• Introduction
• Requirements
• Getting started
• Working with MATLAB API
  • Time series
  • Handling of dates
  • Interfaces
  • IConnection
  • IDatabase
    • Downloading series
    • Download one series
    • Download several series
    • Download and transform series
    • Create a monthly series
    • Create a daily series
    • Delete a series
    • Search for series using a 'concept'
    • Find the 'concept' from a time series
  • ISeries
    • Get the values of a series
  • IEntity
    • Get the next release time
  • IMetadata
    • Get the currency of a time series
    • Create a series and specify the currency
  • ISeriesRequest
    • Download and set start year
    • Download and convert currency
  • ISeriesExpression
    • Download and convert without filling in missing values
  • IMetadataInformation
    • Get the presentation text for a region code
  • IMetadataValueInformation
    • Get a list of all currencies
  • ISearchQuery
  • ISearchResult
  • ISeriesWithRevisions
    • Get all available revisions
    • Get revision history for original and first release
    • Get series for selected timestamp
  • SeriesFrequency
  • SeriesWeekdays
  • CalendarMergeMode
  • CalendarDateMode
  • SeriesMissingValueMethod
  • SeriesToLowerFrequencyMethod
  • SeriesToHigherFrequencyMethod
  • SeriesPartialPeriodsMethod
  • MetadataValueType

Introduction

With the API for MATLAB you can load series from the Macrobond database, and you can store series to the Macrobond account in-house database from MATLAB.

Requirements

The Macrobond API in MATLAB works with MATLAB R2012B or later. If you are running the 64-bit version of MATLAB, you need to use the 64-bit version of Macrobond. This is a COM API and uses the support for COM in MATLAB.

This API can be used only with Legacy or Data+ license.

Getting started

To successfully use the API, you might want to learn more about the Commonly used  metadata.

Working with Matlab API

Time series

A time series is represented by the ISeries interface, described below. A time series consists of a vector of values, a calendar, and a set of metadata.

The vector of values consists of floating-point values. A missing value is represented by a NaN. To test if a value is a NaN in MATLAB use the method isnan(value). To represent a NaN you can use the constant NaN. Note! You must never use the constant to compare if a value is NaN; always use isnan(value) to test if a value is NaN.

A missing value typically means that a value was expected, but it is missing for some reason. When you do a unified series request, you have the option of specifying what method, if any, that should be used to fill in missing values.

The calendar is exposed as lists of dates as well as a couple of methods to go between index in the list of values and a date. Each time series has a frequency and a start date. Daily series also have information about what weekdays that are covered. In addition to this, certain dates can be skipped.  This is mostly used for daily series when there is a holiday or other day when the market is closed. It is not common, but you may find skipped dates in series of other frequencies too. For instance, some Chinese monthly data is not reported for February and this month is then skipped.

Handling of dates

There is no data type for dates in MATLAB. Instead MATLAB uses a convention to store dates as a number calculated from start date. When passing a value to and from COM, which has a specific type for dates, there is no way for MATLAB to know if the number is just a number or should be interpreted as a date. For this purpose, there is a helper object in MATLAB called COM.date.

When passing data to the Macrobond API and the API expects a date, but gets a number instead, this is interpreted as a MATLAB date. This means that you can pass a date created by any of these two methods:

startDate = COM.date(1980, 11, 30)
startDate = datenum(1980, 11, 30)

However, when a date is returned from the API the date must be converted to a MATLAB date number by using the datenum method and the date format pattern defined in Windows regional settings on your computer. In this sample, it is assumed Windows is configured with the date format 'yyyy-mm-dd'. Other common formats are 'mm/dd/yyyy' and 'dd/mm/yyyy'.

matlabDate = datenum(s.StartDate, 'yyyy-mm-dd')

Note! If you do not convert dates passed from COM in this manner, MATLAB will convert them to strings. However, the string format used by MATLAB in this case, is for some reason based on your Windows date format settings, which is not always compatible with the format accepted by MATLAB functions such as datenum(string).

Interfaces

IConnection

All interaction with the Macrobond starts with an instance of the Connection object which is access through the IConnection interface. You create an instance of the object like this:

c = actxserver('Macrobond.Connection')

The interface contains the following methods and properties:

IDatabase Database	This property returns a reference to the database interface.
Close()	Call this method if you want to free all resources used by the Macrobond API. Opening and closing sessions can be slow, so it is usually not a good idea to open and close them for each request.

IDatabase

This interface allows you to interact with the Macrobond database.

ISeries FetchOneSeries(string seriesName)	Download one series from the database.
ISeries[] FetchSeries(VARIANT seriesNames)	Download one or more series from the database. The parameter can be a string, a vector of series names or an object created by CreateUnifiedSeriesRequest(). The result is a vector of series in the same order as requested.
IEntity FetchOneEntity(string entityName)	Download an entity, such as a Release.
IEntity[] FetchEntities(VARIANT entityNames)	Download one or more entities from the database. The parameter can be a string or a list of entity names. The result is a vector of entities in the same order as requested.
ISeriesRequest CreateUnifiedSeriesRequest()	Create a request of one or more series where the resulting time series will be converted to a common length and calendar. You can specify frequency, currency, date range, missing value, and frequency conversion methods
ISeries CreateSeriesObject(string name, string description, string region, string category, SeriesFrequency frequency, SeriesWeekdays dayMask, VARIANT startDateOrDates, VARIANT values, IMetadata metadata)	Create a series object that can be uploaded to the server using the UploadOneOrMoreSeries method. The startDateOrDates can either be just one start date or one date for each value. The values should be an array of numbers. The metadata parameter is optional. The region is a value of the Region metadata which is based on the 2 letter ISO for countries. See list here. The name should be of the form 'ih:storage:id', where storage is 'priv', 'dept' or 'com' corresponding to the private, department and company storages. It must be a unique identifier per storage
ISeries CreateSeriesObjectWithForecastFlags(string name, string description, string region, string category, SeriesFrequency frequency, SeriesWeekdays dayMask, VARIANT startDateOrDates, VARIANT values, VARIANT forecastFlags, IMetadata metadata)	Create a series object that can be uploaded to the server using the UploadOneOrMoreSeries method.The startDateOrDates can either be just one start date or one date for each value. The values should be an array of numbers. The forecastFlags should be an array of boolean values where true means that the corresponding value is a forecast. The metadata parameter is optional. The region is a value of the Region metadata which is based on the 2 letter ISO for countries. See list here. The name should be of the form 'ih:storage:id', where storage is 'priv', 'dept' or 'com' corresponding to the private, department and company storages. Id should must be a unique identifier per storage.
UploadOneOrMoreSeries(VARIANT series)	Upload one or more series created by the CreateSeriesObject method. The parameter can be a single series or a list of series. It is more efficient to upload more series at once than one by one.
DeleteOneOrMoreSeries(VARIANT nameOrNames)	Delete one or more series. The parameter can be a single series name or a list of names. It is more efficient to delete more than one series at once than one by one.
IMetadata CreateEmptyMetadata()	Create an empty set of metadata. The content can be changed until it is used in a series.
IMetadata CreateDerivedMetadata(IMetadata metadata)	Create a set of metadata derived from another set. The content can be changed until it is used in a series.
IMetadataInformation GetMetadataInformation(string name)	Get information about a type of metadata.
ISearchQuery CreateSearchQuery()	Create a search query object. Set properties on this object and pass it to the Search function in order to search for series and other entities. (Requires Data+ license.)
ISearchResult Search(ISearchQuery query)	Execute a search for series and other entities. (Requires Data+ license.)
ISeriesWithRevisions FetchOneSeriesWithRevisions(string name)	Download one revision history for one series. (Requires Data+ license.)
ISeriesWithRevisions[] FetchSeriesWithRevisions(VARIANT seriesNames)	Download one or more series from the database. The parameter can be a string or a vector of series names. The result is a vector of revision history objects in the same order as requested. (Requires Data+ license.)

Downloading series

You can select from two modes when downloading series:

• Download raw data. All available data will be made available without any conversion. You do this by calling FetchOneSeries or FetchSeries with one or more series names (strings).
• Download unified data. You can specify frequency, currency, date range, missing value, and frequency conversion methods. When more than one series is downloaded, they will all have the same calendar. This means that they will have equal length, the same frequency and that a specific index in the vector or values corresponds to the same point in time for all the series. This type of download is made by creating a request object by calling CreateUnifiedSeriesRequest().

Download one series

This will download the entire time series usgdp without any transformations.

c = actxserver('Macrobond.Connection')
d = c.Database
s = d.FetchOneSeries('usgdp')

You can also use one of the ratio expressions to when downloading series. Here the usgdp series is expressed per capita.

c = actxserver('Macrobond.Connection')
d = c.Database
s = d.FetchOneSeries('#PerCapita(usgdp)')

After any of the above you should use its Values property to retrieve the values with:

values = s.Values
dates = datenum(s.DatesAtStartOfPeriod, 'yyyy-mm-dd')

Download several series

This will download the entire time series usgdp and uscpi without any transformations. It is faster to download several series in one call rather than one by one.

c = actxserver('Macrobond.Connection')
d = c.Database
listOfSeries = d.FetchSeries({'usgdp', 'uscpi'})
seriesUsgdp = listOfSeries{1}
seriesUscpi = listOfSeries{2}

Download and transform series

This will download the entire time series usgdp and uscpi transform them to a common length and calendar. By default, the highest frequency of the series and the union on the ranges will be used. For more examples, see the documentation about the ISeriesRequest interface.

c = actxserver('Macrobond.Connection')
d = c.Database
r = d.CreateUnifiedSeriesRequest()
r.AddSeries('usgdp')
r.AddSeries('uscpi')
listOfSeries = d.FetchSeries(r)

Create and upload a monthly series

This creates a monthly time series. Since just one data is specified, this will be the start date of the series and the rest of the dates will be implicitly calculated based on the frequency.

c = actxserver('Macrobond.Connection')
d = c.Database
m = d.CreateEmptyMetadata()
startDate = COM.date(1980, 1, 1)
values = { 12.2, 12.7, 12.8, 13.0 }
s = d.CreateSeriesObject('ih:mb:priv:s1', 'My forecast', 'us', 'Forecasts', 'SeriesFrequency_Monthly', 'SeriesWeekdays_MondayToFriday', startDate, values, m)
d.UploadOneOrMoreSeries(s)

Create and upload a daily series

This will create a daily time series. In this case we have chosen to specify the date for each observation. Please note that the 5th and 6th of January 1980 are Saturday and Sunday and will not be included in the series since it is set to use Monday-Friday. The 7th is not included in the list of dates, so this date will be skipped in the calendar.

c = actxserver('Macrobond.Connection')
d = c.Database
m = d.CreateEmptyMetadata()
dates = { COM.date(1980, 1, 2), COM.date(1980, 1, 3), COM.date(1980, 1, 4), COM.date(1980, 1, 8) }
values = { 12.2, 12.7, 12.8, 13.0 }
s = d.CreateSeriesObject('ih:mb:priv:s1', 'My forecast', 'us', 'Forecasts', 'SeriesFrequency_Daily', 'SeriesWeekdays_MondayToFriday', dates, values, m)
d.UploadOneOrMoreSeries(s)

Delete a series

c = actxserver('Macrobond.Connection')
d = c.Database
d.DeleteOneOrMoreSeries('ih:mb:priv:s1')

Search for series using a 'concept'

This example only works with Data+ license.

This example searches for time series that are defined by Macrobond as the GDP series for the regions 'us', 'gb' and 'cn'. The RegionKey attribute defines what is called a 'concept' and is used to build the 'Concept & Category' database view in Macrobond Application. It is a powerful way to identify corresponding series for many regions. For the GDP series, the RegionKey is 'gdp_total.'

c = actxserver('Macrobond.Connection')
d = c.Database
query = d.CreateSearchQuery()
query.SetEntityTypeFilter('TimeSeries')
query.AddAttributeValueFilter('RegionKey', 'gdp_total')
query.AddAttributeValueFilter('Region', {'us', 'gb', 'cn'})
result = d.Search(query).Entities

Find the 'concept' from a time series

This example shows how you can find out what 'concept' or RegionKey a series is associated with. Far from all series have this classification, but we know that the uscpi series has . This is a good way to find out the names of RegionKeys to use when searching for data.

c = actxserver('Macrobond.Connection')
d = c.Database
query = d.CreateSearchQuery()
query.SetEntityTypeFilter('TimeSeries')
query.AddAttributeValueFilter('RegionKey', 'gdp_total')
query.AddAttributeValueFilter('Region', {'us', 'gb', 'cn'})
result = d.Search(query).Entities

ISeries

This interface represents a Macrobond time series.

string Name	The name of the series.
bool IsError	If True, then the series request resulted in an error and the ErrorMessage property contains an error message. If there is an error, only these two properties are valid.
string ErrorMessage	Contains an error message if IsError is True.
string Title	The title of the series.
IMetadata Metadata	Metadata information for the time series.
double[] Values	A list of all values in the time series. The COM data type is SAFEARRAY(VT_R8)
VARIANT[] DatesAtStartOfPeriod	A list of dates. There is one date for the start of the period for each value in Values. The COM data type is VT_SAFEARRAY|VT_DATE.
VARIANT[] DatesAtEndOfPeriod	A list of dates. There is one date for the end of the period for each value in Values. The COM data type is VT_SAFEARRAY|VT_DATE.
bool[] ForecastFlags	A list flags where a value is True if the corresponding value in Values is a forecast.
date StartDate	The date of the first observation of the time series.
date EndDate	The date of the last observation of the time series.
SeriesFrequency Frequency	The series frequency.
SeriesWeekdays Weekdays	A bit field of weekdays to use for daily time series.
double GetValueAtDate(date d)	Get the value at or preceding a specific date.
int GetIndexAtDate(date d)	Get the zero-based index of the value at or preceding the specified date in the Value list.
double TypicalObservationCountPerYear	The typical number of observations per year based on the frequency of the series.

Get the values of a series

This will download the time series usgdp and the list of values as well as a list of MATLAB 'datenums'. Please note that the date format pattern passed as an argument to datenum function must match the regional settings in Windows.

c = actxserver('Macrobond.Connection')
d = c.Database
s = d.FetchOneSeries('usgdp')
values = s.Values
dates = datenum(s.DatesAtStartOfPeriod, 'yyyy-mm-dd')

IEntity

This interface represents a Macrobond entity. There are many types of entities in the Macrobond database. Examples are Source, Release, Company and Security. Time series are also entities.

The reason you might want to download an entity, is to obtain some metadata.

string Name	The name of the entity.
bool IsError	If True, then the entity request resulted in an error and the ErrorMessage property contains an error message. If there is an error, only these two properties are valid.
string ErrorMessage	Contains an error message if IsError is True.
string Title	The title of the entity.
IMetadata Metadata	Metadata information for the entity.

Get the next release time

This will download the time series usgdp and then download the corresponding release entity. The release entity can contain metadata about the when time series associated with this release is scheduled to be updated.

c = actxserver('Macrobond.Connection')
d = c.Database
s = d.FetchOneSeries('usgdp')
releaseName = s.Metadata.GetFirstValue('Release')
if (not(isnan(releaseName)))
 r = d.FetchOneEntity(releaseName)
 nextReleaseTime = datenum(r.Metadata.GetFirstValue('NextReleaseEventTime'), 'yyyy-mm-dd')
end

IMetadata

This interface represents a set of metadata for a time series or entity.

Metadata is represented by a name and a value. The type of the value can be a string, a boolean, an integer or a date. An examples of a metadata names are 'Region' and 'Currency.' Some metadata can have multiple values, like Region, but others, Currency, can have only one value.

VARIANT GetFirstValue(string name)	Get the first metadata value with the specified name.
VARIANT[] GetValues(string name)	Get a list of the values for metadata of the specified name.
VARIANT[,] ListNames()	Get a list of all the metadata specified together with a description for each name.
bool IsReadonly	Indicating whether new values can be added or hidden in this instance. Typically, only newly created instances of the metadata objects can be edited and only until they have been used in a series.
AddValue(string name, VARIANT value)	Add a value to the metadata instance. The value can be a single value or a list of values.
HideValue(string name)	Hide a value inherited from a parent metadata collection.

You can find more information on this page: Commonly used metadata.

Get the currency of a time series

c = actxserver('Macrobond.Connection')
d = c.Database
s = d.FetchOneSeries('usgdp')
m = s.Metadata
currencyCode = m.GetFirstValue('Currency')

Create and upload a series and specify the currency

c = actxserver('Macrobond.Connection')
d = c.Database
m = d.CreateEmptyMetadata()
m.AddValue('Currency', 'sek')
startDate = COM.date(1980, 1, 1)
values = { 12.2, 12.7, 12.8, 13.0 }
s = d.CreateSeriesObject('ih:mb:priv:s1', 'My forecast', 'us', 'Forecasts', 'SeriesFrequency_Daily', 'SeriesWeekdays_MondayToFriday', startDate, values, m)
d.UploadOneOrMoreSeries(s)

ISeriesRequest

Use this interface to set up a request of unified series. You create objects with this interface by calling IDatabase.CreateUnifiedSeriesRequest(). Then you configure the object and pass it as a parameter to IDatabase.FetchSeries().

ISeriesExpression AddSeries(string name)	Add a series to the list of series to request. You can optionally use the returned interface to do further configurations, such as methods for missing value, and frequency conversion.
ISeriesExpression [] AddedSeries	A list of the added series.
SeriesFrequency Frequency	The frequency that all series will be converted to. The default value is ‘Highest’, which means that all series will be converted to the same frequency as the series with the highest frequency.
CalendarMergeMode CalendarMergeMode	Determines how to handle points in time that are not available in one or more series. The default value is ‘AvailibleInAny’
SeriesWeekdays Weekdays	This determines what days of the week that are used when the resulting frequency is Daily and the CalendarMergeMode is ‘FullCalendar’.
string Currency	The currency code based on the three letter IS 4217 codes that will be used to convert any series expressed in currency units. The default is an empty string, which means that no currency conversion will be done. There is a list of the supported currencies on a Currencies List web page.
CalendarDateMode StartDateMode	Determines if the automatic start of the series is at the first point when there is data in any series or the first point where there is data in all series. The default is ‘DataInAnySeries’. This setting is not used when the StartDate property is set to an absolute point in time.
VARIANT StartDate	This specifies the start date used for all the series in the request. The value can be empty, a specific date or a string representing a point in time as described below. If it is empty or a relative reference, the StartDateMode will be used to determine the start.
CalendarDateMode EndDateMode	Determines if the automatic end of the series is at the last point when there is data in any series or the last point where there is data in all series. The default is ‘DataInAnySeries’. This setting is not used when the EndDate property is set to an absolute point in time.
VARIANT EndDate	This specifies the end date used for all the series in the request. The value can be empty, a specific date or a string representing a point in time as described below. If it is empty or a relative reference, the EndDateMode will be used to determine the end.

For the StartDate and EndDate properties, you can specify a string representing a point in time. This can either be an absolute reference on the form 'yyyy,' 'yyyy-mm' or 'yyyy-mm-dd' or a reference relative the last observation of the series based on these examples:

-50	Fifty observations before the last available observation.
+40	Forty observations after the last available observation.
-2y	Two years before the last available observation.
-1q	One quarter before the last available observation.
-4m	Four months before the last available observation.
-3w	Three weeks before the last available observation.
-5d	Five days before the last available observation.

Download and set start year

This will download two series and convert them to the higher frequency. The data range is set to start year 1980 and continue until the last observation that has data in both series.

c = actxserver('Macrobond.Connection')
d = c.Database
r = d.CreateUnifiedSeriesRequest()
r.AddSeries('usgdp')
r.AddSeries('uscpi')
r.StartDate = '1980'
r.EndDateMode = 'CalendarDateMode_DataInAllSeries'
listOfSeries = d.FetchSeries(r)

Download and convert currency

This will download two series and convert them to USD. The data range is set to cover the range where there is data in both series.

c = actxserver('Macrobond.Connection')
d = c.Database
r = d.CreateUnifiedSeriesRequest()
r.AddSeries('usgdp')
r.AddSeries('gbgdp')
r.Currency = 'USD'
r.StartDateMode = 'CalendarDateMode_DataInAllSeries'
r.EndDateMode = 'CalendarDateMode_DataInAllSeries'
listOfSeries = d.FetchSeries(r)

ISeriesExpression

Use this interface to set properties for a series requested by calling ISeriesRequest.AddSeries().

string Name	The name of the series
SeriesMissingValueMethod MissingValueMethod	The method to use when filling in any missing values in this series. The default is ‘Auto’.
SeriesToLowerFrequencyMethod ToLowerFrequencyMethod	The method to use when converting this series to a lower frequency. The default is ‘Auto’.
SeriesToHigherFrequencyMethod ToHigherFrequencyMethod	The method to use when converting this series to a higher frequency. The default is ‘Auto’.
SeriesPartialPeriodsMethod PartialPeriodsMethod	The method to use for partial periods at the ends of the series when converting to a lower frequency. The default is None.

Download and convert without filling in missing values

This will download two series and convert them to the same calendar, but do not fill in any missing values.

c = actxserver('Macrobond.Connection')
d = c.Database
r = d.CreateUnifiedSeriesRequest()
r.AddSeries('usgdp').MissingValueMethod = 'SeriesMissingValueMethod_None'
r.AddSeries('gbgdp').MissingValueMethod = 'SeriesMissingValueMethod_None'
listOfSeries = d.FetchSeries(r)

IMetadataInformation

Use this interface to get information about a type of metadata.

string Name	The name of the metadata type
string Description	A description of the metadata type.
string Comment	A comment about the metadata type.
bool UsesValueList	If True, then this type of metadata uses a list of possible values and only values from that list can be used. The list can be obtained from ListAllValues. Information about a specific value can be found by calling GetValueInformation().
MetadataValueType ValueType	Get the datatype of the values for this type of metadata.
bool CanHaveMultipleValues	If True, then a metadata collection can have several values of this type.
bool IsDatabaseEntity	If True, then this value corresponds to an entity in the database that can be retrieved by IDatabase.FetchOneEntity().
string GetValuePresentationText(VARIANT value)	Format a value as a presentable text.
IMetadataValueInformation GetValueInformation(VARIANT value)	Get information about a metadata value. This information is only available for metadata types that uses value lists
IMetadataValueInformation[] ListAllValues()	Get a list of all possible values for a metadata type that uses a value list.
bool CanListValues	If True, then the possible values can be listed using the ListAllValues function.

Get the presentation text for a region code

This will get information about the metadata type called ‘Region’ and then get the presentation text for the region called ‘us’. The result will be the string ‘United States’.

c = actxserver('Macrobond.Connection')
d = c.Database
m = d.GetMetadataInformation('Region')
description = m.GetValuePresentationText('us')

IMetadataValueInformation

Use this interface to get information about a value of metadata.

VARIANT Value	The value of the metadata
string Description	The description of the value.
string Comment	A comment about the value.

Get a list of all currencies

This will get information about the metadata type called 'Region' and then get the presentation text for the region called 'us'. The result will be the string 'United States'.

c = actxserver('Macrobond.Connection')
d = c.Database
m = d.GetMetadataInformation('Currency')
v = m.ListAllValues()
currencies = cellfun(@(x) x.Value, v, 'UniformOutput', 0)

ISearchQuery

This example only works with Data+ license.

Use this interface to set up a search query. You create objects with this interface by calling IDatabase.CreateSearchQuery(). Then you configure the object and pass it as a parameter to IDatabase.Search().

string Text	An optional text to search for. The search will be made by matching each word.
SetEntityTypeFilter(VARIANT types)	A single string or a vector of strings identifying what type of entities to search for. The options are TimeSeries, Release, Source, Index, Security, Region, RegionKey, Exchange and Issuer. Typically you want to set this to TimeSeries. If not specified, the search will be made for several entity types.
AddAttributeFilter(string attributeName, bool include = true)	Add a name of an attribute that must or must not be set on entities returned by the search. The 'include' parameter determines if the search should include or exclude entities that have the attribute. For example, if you do AddAttributeFilter("SeasonAdj"), only series that are seasonally adjusted will be included.You can call this method several times to add more filters.
AddAttributeValueFilter(string attributeName, VARIANT attributeValues, bool include = true)	Add attribute values that must or must not be set on entities returned by the search. You can specify one value or a list of values. The 'include' parameter determines if the search should include or exclude entities that have the attribute values. For example, if you do AddAttributeValueFilter("Region", ["us", "gb", "cn"]) only entities that have the Region attribute set to any of "us", "gb" or "cn" will be included. You can call this method several times to add more filters.
bool IncludeDiscontinued	Set to True to include discontinued series in the search. The default is False.

ISearchResult

This example only works with Data+ license.

This interface represents a search result returned by a call to IDatabase.Search(query).

IEntity[] Entities	The list of entities returned by the search.
bool IsTruncated	This is True if the result is not exhaustive. There is a limit on the number of entities that can be returned. It is possible to get at least 2000 entities before the result is truncated.

ISeriesWithRevisions

These examples only works with Data+ license.

This interface represents a time series with revision history.

The series returned by Head, GetNthRelease, GetVintage and GetCompleteHistory will all be of equal length and share the same calendar. In this way they can easily be used in a data frame.

bool IsError	If True, then the series request resulted in an error and the ErrorMessage property contains an error message. If there is an error, only these two properties are valid.
string ErrorMessage	Contains an error message if IsError is True.
bool HasRevisions	If True, then the series has one or more revisions.
bool StoresRevisions	If True, then the series stores revision history. This can be True while HasRevisions is False if no revisions have yet been recorded.
datetime TimeOfLastRevision	The timestamp of the last revision.
ISeries Head	The current revision of the time series.
ISeries GetNthRelease(int n)	Get then nth revision of each value. GetNthRelease(0) will return the first release of each value. Values that have not been revised the number of times specified and value for which the complete revision history is not known will be represented by NaN.The series ValuesMetadata will contain the metadata attribute RevisionTimeStamp with the timestamp when the revision was made to that value.
ISeries GetVintage(datetime time)	Get the series as it looked at the time specified. The metadata attribute RevisionTimeStamp will contain the timestamp of when this revision was recorded.In order to make this series of the same length as the Head series, it may be padded with NaN.
ISeries GetObservationHistory(date d)	Get a daily series with the revision history of the value specified by the date.
ISeries[] GetCompleteHistory()	Get list of all revisions. Each time series has the metadata attribute RevisionTimeStamp with the timestamp the revision. The first series typically has date 1899-12-30 which means that the timestamp of the original data is not known. Please note that this can potentially be a lot of data and use a large amount of memory.
datetime[] GetVintageDates()	Get a list of timestamps representing when revisions were recorded.

Get all available revisions

c = actxserver('Macrobond.Connection');
d = c.Database;
s = d.FetchOneSeriesWithRevisions("uscpi");
history = s.GetCompleteHistory();

Get revision history for original and first release

c = actxserver('Macrobond.Connection');
d = c.Database;
s = d.FetchOneSeriesWithRevisions("uscpi");
firstRevisionSeries = s.GetNthRelease(0);
secondRevisionSeries = s.GetNthRelease(1);

Get series for selected timestamp

c = actxserver('Macrobond.Connection');
d = c.Database;
seriesWithRevisions = d.FetchOneSeriesWithRevisions('usgdp');
s = seriesWithRevisions.GetVintage('2021-04-02 00:00:00');

SeriesFrequency

This enumeration contains the supported time series frequencies.

Annual	Once a year.
SemiAnnual	Twice a year.
QuadMonthly	Once in 4 months.
Quarterly	Once in 3 months
BiMonthly	Every second month.
Monthly	Once a month.
Weekly	Once a week
Daily	Once a day.
Lowest	When specified in a series request, this corresponds to the lowest frequency of the series in set.
Highest	When specified in a series request, this corresponds to the highest frequency of the series in the request.

SeriesWeekdays

This enumeration contains flags that are used as bitmasks to determine what weekdays that are used in a daily time series.

Sunday	1
Monday	2
Tuesday	4
Wednesday	8
Thursday	16
Friday	32
Saturday	64
FullWeek	Sun+Mon+Tue+Wed+Thu+Fri+Sat
MondayToFriday	Mon+Tue+Wed+Thu+Fri
SaturdayToThursday	Sun+Mon+Tue+Wed+Thu+Sat
SaturdayToWednesday	Sun+Mon+Tue+Wed+Sat
SundayToThursday	Sun+Mon+Tue+Wed+Thu
MondayToThursdayAndSaturday	Sun+Mon+Tue+Wed+Thu+Sat

CalendarMergeMode

This enumeration defines how calendars are merged into one calendar when there are time periods missing in one or more series. Please note that missing time period is not the same thing as a missing value. A time period is missing in cases when there should be no observation such as on a holiday. A missing value, on the other hand, is a special value in the time series that indicates that there should have been a value, but it is unknown for some reason.

FullCalendar	Use all the time periods as specified by the frequency and weekdays.
AvailableInAll	Use the time periods that are available in all series.
AvailableInAny	Use the time periods that are available in any series.

CalendarDateMode

This enumeration defines how the StartDate and EndDate properties of a unified series request are interpreted when they are set to a relative or empty reference.

DataInAnySeries	Use the first or last time period where there is valid data in any series.
DataInAllSeries	Use the first or last time period where there is valid data in all series.

SeriesMissingValueMethod

This enumeration determines the method for filling in any missing values.

None	Do not fill in missing values. They will remain NaN in the value vector.
Auto	Determine the method based on the series classification.
PreviousValue	Use the previous non-missing value.
ZeroValue	Use the value zero.
LinearInterpolation	Do a linear interpolation between the previous and next non-missing values.

SeriesToLowerFrequencyMethod

This enumeration determines the method for converting a series to a lower frequency.

Auto	Determine the method based on the series classification.
Last	Use the last value of the time period.
First	Use the first value of the time period.
Flow	Aggregate the values of the time period.
PercentageChange	Aggregate the percentage change over the period.
Highest	Use the highest value in the time period.
Lowest	Use the lowest value of the time period.
Average	Use the average value of the period.

SeriesToHigherFrequencyMethod

This enumeration determines the method for converting a series to a higher frequency.

Auto	Determine the method based on the series classification.
Same	Use the same value for the whole period.
Distribute	Use the first value of the time period.
PercentageChange	Distribute the percentage change over the period.
LinearInterpolation	Use a linear interpolation of the values from this to the next period.
Pulse	Use the value for the first value of the period.
QuadraticDistribution	Use quadratic interpolation to distribute the value over the period.
CubicInterpolation	Use a cubic interpolation of the values from this to the next period.

SeriesPartialPeriodsMethod

This enumeration determines the method for converting a series with partial periods.

None	Do not include partial periods.
Auto	Determine the method based on the series meta data.
RepeatLastValue	Fill up the partial period by repeating the last value.
FlowCurrentSum	Fill up the partial period with the average of the incomplete period.
PastRateOfChange	Use the rate of change from the previous year to extend the partial period.
Zero	Fill up the partial period with zeroes.

MetadataValueType

The type of a metadata value. These values correspond to the COM VARIANT data types.

Int	A 32-bit signed integer. VT_I4.
Double	A 64-bit floating point number. VT_R8.
Date	A date. VT_DATE.
String	A unicode string. VT_BSTR.
Bool	A boolean value where -1 is True and 0 is False. VT_BOOL.