Vintage data (Revision history)

This feature requires Macrobond Data+ license. 

Overview

This feature requires Macrobond Data+ license. 

If you have Data+ license you can download vintage versions of time series with Python/R API or through Macrobond main-app. Note that not all time series may have vintage data or they do not have data, from the period you want.

Series with and without vintage data

For various reasons (i.e., contract agreements, source not keeping historical information) not all series have revisions. Those who has will have next to them a three-violet-lines sign and when you hover over the sign you will see a flag with 'This series has revision history available' confirmation and a dates for first and last revision.

Viewing available revision history

In data-tree you can right-click on a series and select Show revision history. New window will pop up where you can see all historical releases we have in our database. Any change in values will be highlighted in beige color.

What does Start column mean?

Consider the Start event as the point in time when the time series was created, as it represents the initial appearance of the series. For newer series it might mean there was no earlier revision before but for older ones it simply is the last available to us recorded state of series.

Set Vintage request for all series in document

Select date in the Vintage field on Series list. This setting will be applied to all series on Series list - program will try to get the revision for all series at this point in time.

How to set time in Vintage field?

The calendar date and time is show in your local time according to your Windows time zone setting.

For example, if you selected the vintage 1st December 2001, and your Windows time zone is UTC+1 , the absolute time is 2001-12-01 09:30+1.

Set Vintage request for one series

Revision history works together with { } brackets. To see historical data for one series, use in Expression field code with date for which you want data:

segdp{2001-12-01 09:30+1}

The format must be {YYYY-MM-DD HH:MM+offset}.

You can also add vintage time series directly from data-tree.

Formula editor hints

This feature is available in Macrobond 1.29 and later.

Since version 1.29 when you end typing series code you will see general hints about the possibilities of vintage data (revision history). If you type a { after code you will see all the specific vintages for that series.

How to add vintage time series from data-tree?

Go to Analytics tab > Series browser panel. Right-click on a series which have vintage data and select one of the possibilities:

How to set relative vintage time?

This feature is available in Macrobond 1.29 and later.

If you don't want to use exact date but want to go back/forth from certain point in time instead you can now use relative formulas to get the right series.

Relative to 'now':

atbopa0003{now} The last vintage (headline version), regardless of the document vintage timestamp.
atbopa0003{now,-1} The previous vintage relative to head version, regardless of the document vintage.

Relative to vintage date set in document on Series list:

atbopa0003{doc,-1} The previous vintage relative to any document vintage.
atbopa0003{doc,-2} The vintage before the previous relative to any document vintage.
atbopa0003{doc,+1} The next vintage relative to any document vintage.

Relative to timestamp:

atbopa0003{2023-12-22 09:07+1,-1} The previous vintage relative to the timestamp.
atbopa0003{2023-12-22 09:07+1,+1} The next vintage relative to the timestamp.

How to set time in vintage formula?

Revision history's time is expressed in UTC, therefore you always need to specify a time zone offset. Offset is always needed in formula for vintage data.

Applying document-wide vintage date on Series list will not affect vintage formula.

Using offset

Update for series segdp was released on 27th August 2021 9:30 Swedish local time. Sweden is in time zone UTC+2 so formula should be:

segdp{2021-08-27 09:30+2}

Most probably you know the release time in your local time. For example, if you are in Hong Kong formula should be:

segdp{2021-08-27 15:30+8}

In effect you can call same vintage data in many ways:

segdp{1999-12-01 09:30+1}
segdp{1999-12-01 15:30+7}
segdp{1999-11-30 23:30-9}
segdp{1999-12-01 08:30z}
segdp{1999-12-01 08:30+0}

UTC+0 time zone

If you want to have UTC time you can write it in two ways:

segdp{1999-12-01 08:30z}
segdp{1999-12-01 08:30+0}

Omitting time

You can omit the time, program will then assume time 00:00. Examples below show same result:

segdp{1999-12-01+0} 
segdp{1999-12-01 00:00+0}

Vintage (revision history) in Excel

This feature requires Macrobond Data+ license. 

You can download vintage data directly in Excel. Under All series panel use ‘Vintage’ field to select the date. it will set vintage date for all series in the list.

If you want to set vintage only for one series right-click on a series and select revision.

After converting object to document data set vintage information will be written as a formula (i.e., clnaac0143{2022-05-18 12:31+0} ).

Downloading values by release order (initial release)

To get first value (initial release) for each point in time type in code:

segdp{0}

In this example (colors won't appear in program):

  • Segdp{0} will return the initial release, the values marked in green
  • Segdp{1} will return the first revision, the values marked in blue

Note that the number means the nth time that value was changed. If the values weren't changed with each release it might look like this (colors won't appear in program):

  • usfcst4775{0} will return the initial release, the values marked in green
  • usfcst4775{1} will return the first revision, the values marked in blue. The last two values marked in pink are filled due to 'Conversion settings' > 'Missing value method'. If you do not want to have them select there 'Do not fill in'.

Questions

Can I sort by First/Last available revision date?

Yes. Go to data browser (for example in Search tab), right-click on a main bar, choose Select column. In the new window check box next to First revision and Last revision.  

How to check if revision was applied to a series?

On a chart's legend you will see analysis text for each expression that uses revision history informing you what was used.

What happens after applying revision if series doesn't have any?

There will appear a yellow bar with general information 'One or more series does not have revision history for the specified vintage.' When you got Series information tab and hover over highlighted series you will see why, there is no revision for this series.

On Series information tab you can check also which series has what revision in Vintage column. Right-click on a main bar, press Select columns and add Vintage.
If there is no revision data for selected point in time, program will display the first available data, highlight series on Series Information tab and in Vintage column will not show any date.

Why current series is so much different than in vintage release?

Series are presented as they were shown by the source at that point in time. The source could decide to shorten series, rebase it, or add more historical values.

Tags: historical datarevisionsvintage