Introduction

This feature was introduced in Macrobond 1.13

By using Dynamic text in charts, you can present data from time series as part of any text that you enter. For instance, you can have a textbox with a text like "The last value is 12.72", where the number 12.72 comes from a time series and is automatically updated.

The part of the text that is dynamic is written within curly brackets. The example above might have been written like "The last value is {s .Value}". The text within the brackets will be processed and replaced with the result in the output.
You can have any number of dynamic texts in a text. For example: "The value at {s .Date} is {s .Value}", which could result in something like "The value at 2014 Q1 is 12.72"

The Dynamic text editor helps you to type the dynamic text expressions. You get feedback suggestions as you type. Tooltips helps you examine the expressions. dynamictexteditor

The general format is

{x parameters}

The first letter after the opening bracket, called x determines the type of dynamic text. There are two types of dynamic texts: s for series data and c for chart and document data.

You can, and sometimes need to, put quotes around the parameters. In particular, you need to do this if a parameter contains space characters.

There is detailed documentation below, but here are some examples:

{s .Value}Present the current value from the current time series with automatic formatting.
{s .Value F2}Present the current value with two decimals.
{s .Value  #,,}Divide the value by 1 million and show without decimals.
{s .Value[2012] A3}Format the value of 2012 using three significant digits.
{s .Value[-1Y]}The value one year back.
{s .Date}Present the current date from the current time series with automatic formatting.
{s .Date D}Present the date with the long date format.
{s .Region}Present the region of the current time series.
{s s1.Currency -m}Present the currency of the specified time series. -m means that there will be no error if the series has no currency..
{c DocumentSources –d “\n”}The sources of the document separated with a new line.

If you want to include a bracket as part of your text, you need to write double brackets: {{ will result in { in the output and }} will be }.

Default series and observations

When a dynamic text is processed there is a set of default series and a default observation that depends on the context where the expression is used.

ElementSeriesObservation
Main/sub titleAll series used in the chartThe last observation
Copyright textAll series used in the chartThe last observation
Legend itemThe series used for the graphThe last observation
Y-axis titleThe series plotted against the axisThe last observation
X-axis titleThe series used in the paneThe last observation
Text boxThe series used in the paneThe last observation
Observation labelThe series used for the graphThe observation it points to
Axis value labelThe series it referencesThe last observation

This means that a dynamic text like {s .Value} can sometimes refer to several series and this several values. By default, such a list will be presented as a list separated by comma. For instance when used in the main title and the chart uses two series the text might be 12.34, 56.78. If you just want one of these, you should consider referencing a specific time series or using the index operator.
The .Date property works in the same way and produces a list of dates.
All other properties, like .Region, will remove any duplicates from the list.

Series data

The dynamic text is written on the format

{s series.Data[index] format options}

The options, format, data and index parts are always optional. The series part is optional if there is a default series in the context where the text is used.

There are several options available:

-f formatThe format depends on the data type as covered below.
-d delimiterThe delimiter is used to when there is a list of items. The default delimiter is “, “. For new lines you can use “\n”.
-p textA text that will be prepended to the formatted text.
-s textA text that will be appended to the formatted text.
-m textA text that will be displayed of the specified data property or data point is missing. By specifying –m without a text, there will be no text at all in the case where the property is missing.
-ct textInstead of formatting the value of the data, the specified text will be written if the data is “true”. The value is “true” if it is a Boolean value that is True or a number > 0.5. If the value is “false”, the text specified by –cf will be used if available and otherwise empty.
-cf textInstead of formatting the value of the data, the specified text will be written if the data is “false”. The value is “false” if it is a Boolean value that is False or a number <= 0.5. If the value is “true”, the text specified by –ct will be used if available and otherwise empty.

You can thus specify the format either as the second part of the dynamic text or as an option.

series

The part series is a reference to the series on the format s1, s2, s3 etc.

This will reference the current value of the series s1:

{s s1}

The reference can be omitted if there is a default series in the context where the text is used. In this case the dynamic text can be as short as

{s}

.Data

The part .data specifies what data property to retrieve for the specified series. The default value is .Value, which is the vector of values.

Examples of data:

.ValueThe values of the series. You can specify an index as point in time. If no index is specified, the index of the context will be used, which is often the last value.
.DateThe dates of the series. You can specify an index as point in time. If no index is specified, the index of the context will be used, which is often the last value. This property does not exist for category series.
.ValueLabelThe value labels of the series. You can specify an index as point in time. If no index is specified, the index of the context will be used, which is often the last value.
.OrdinalThe ordinal of the series. You can specify an index as point in time. If no index is specified, the index of the context will be used, which is often the last value. This property only exists for category series.
.GraphTextThe text of the associated graph
.DisplayUnitThe unit
.CurrencyThe currency
.OriginalCurrencyThe currency of the original series before any currency conversion.
.FrequencyThe frequency
.FullDescriptionThe full description of the series.
.RegionThe country or region. There can be several regions. All regions will be included if no index is specified.
.ReleaseThe title of the release associated with this series. This is an entity with additional data.
.Release.LastReleaseEventTimeThe time of the previous release of new data.
.Release.NextReleaseEventTimeThe time of next scheduled release of new data.

Some examples of usage:

{s .Value[2012]}The last value of 2012 of the default series.
{s s2.Value[-1y]}The value one year before the end of the series s2.
{s s2.Date}The last date of the series s2.
{s s2.Date[-1q]}The date one quarter before the end of the series s2.
{s .Region}The regions for the default series.
{s s2.Region[0]}The first region of the series s2.

format

The format is optional and the default format depends on the context and data type.

Formatting numbers

The following predefined number formats are defined:

FnFixed-point notation where n specifies the number of decimal digits. Example: 1234.5678 formatted using "F2" is "1234.56".
EnExponential notation where n specifies the number of decimal digits. Example: 12345678 formatted using "E2" is "1.23E+007".
GnPicks the shortest of the F and E formats with the specified number of significant digits. Example: 12345678 formatted using "G3" is "1.23E+07"
PnPercent notation where n specifies the number of decimal digits. The value is multiplied with 100 and displayed with a % symbol. Example: 0.1234 formatted using "P1" is "12.3 %".
AnAutomatic scaling by using n significant digits and an exponent divisible by 3, excluding -3 and 3. Example 1234567 formatted with "A3" is "1.23 million".

The decimal separator is always localized.

The formatting string can also be composed of the following specifiers:

0The "0" format specifier serves as a zero-placeholder symbol. If the value that is being formatted has a digit in the position where the zero appears in the format string, that digit is copied to the result string; otherwise, a zero appears in the result string. The position of the leftmost zero before the decimal point and the rightmost zero after the decimal point determines the range of digits that are always present in the result string. Example: The number 1.2 formatted using "00.00" is "01.20".
#The "#" format specifier serves as a digit-placeholder symbol. If the value that is being formatted has a digit in the position where the pound sign appears in the format string, that digit is copied to the result string. Otherwise, nothing is stored in that position in the result string. Note that this specifier never displays a zero that is not a significant digit, even if zero is the only digit in the string. It will display zero only if it is a significant digit in the number that is being displayed. The number 1.234 formatted using "#.##" is "1.23".
.The "." format specifier inserts a localized decimal separator into the result string. The first period in the format string determines the location of the decimal separator in the formatted value; any additional periods are ignored. Example: The number 1.234 formatted using "0.00" is "1.23".
%A percent sign (%) in a format string causes a number to be multiplied by 100 before it is formatted. The localized percent symbol is inserted in the number at the location where the % appears in the format string. Example: The number 1.234 formatted using "#%" is "123%".
, The “,” format has two functions:
  1. 1000-separator: If a comma is specified between two digit placeholders (0 or #) that format the integral digits of a number then a group separator character is inserted between each number group in the integral part of the output. Example: using the format “#,#” and US number format settings, the number 1000000 is formatted as “1,000,000”.
  2. Scaling: If one or more commas are specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 for each comma. Example: using the format “#,,”, the number 1000000 is formatted as “1”.

Rounding is always made away from zero.

Instead of the formatting specifiers, you can also specify a formatting group:

@groupName:digits

All numbers that belong to the same group will be formatted with the same number of decimals so that at least the specified number of significant digits are included. If no :digits part is included, a default value of 3 will be used.

There are three special groups: YAxisMain, YAxisAlternate, and XAxis. These will be used as the default group when the default series is used and the context can be associated with an axis.

Some examples of usage:

{s .Value F2}Formats "123.456" with two decimals like "123.46".
{s .Value A4}Formats "123.456" with four significant digits like "123.5".
{s .Value P1}Formats "0.123456" with one decimal digits like "12.3 %".
{s .Value #,,}Formats "123456789" scaled by 1 million and no decimals "123".
{s .Value #,,,.00}Formats "123456789" scaled by 1 billion and two decimals "0.12".
{s .Value -f F2}This is a different way to write the same thing as the first sample.
Formatting dates and time stamps

Predefined date patterns that format according to the current language settings:

QYear and quarter. For example 2008 Q2.
WYear and week. For example 2008 W21.
GA short date with time. Example for US: 4/23/2008 1:45 PM
dA short date. Example for US: 4/23/2008. This is the default.
DA long date. Example for US: Thursday, April 23, 2008
fA long date with time. Example for US: Thursday, April 23, 2008 1:45 PM
MDisplay day and month. Example for US: April 23
YDisplay month and year. Example for US: April, 2008
tThe time. Example for US: 1:45 PM

A format string can also be composed of two or more of the following specifiers:

dThe day from 1 to 31. When used as the only specifier, it must be written as %d.
ddThe day from 01 to 31.
dddThe abbreviated name of the day of the week. Example for US: Mon
ddddThe full name of the day of the week. Example for US: Monday
MThe month from 1 to 12. When used as the only specifier, it must be written as %M.
MMThe month from 01 to 12.
MMMThe abbreviated name of the month. Example for US: Jun
MMMMThe full name of the month. Example for US: June
yyThe year without century. Example: 95
yyyyThe year including the century. Example: 1995
:Time separator. Example for Italy: .
/Date separator. Example for Sweden: -

If you use spaces in the formatting specification, you need to quote the parameter.

Chart data

The dynamic text is written on the format:

{c data format options}

There are two options available:

-f formatThe format depends on the data type as covered below.
-d delimiterThe delimiter is used to when there is a list of items. The default delimiter is “, “. For new lines you can use “\n”.

You can thus specify the format either as the second part of the dynamic text or as an option.

The following data items are available:

DocumentNameThe name of the document.
AutomaticTitleThe automatic title of the chart.
AutomaticUnitYAxisMainThe automatic of the main y-axis.
AutomaticUnitYAxisAlternateThe automatic of the alternate y-axis.
AutomaticUnitXAxisThe automatic of the x-axis.
NowThe today’s date
DocumentSourcesA list of the sources of the time series used in this document.

Some examples of usage:

{c DocumentSources –d “\n”}The sources of the document separated with a new line.
{c Now}The current date.

Sample documents