Introduction
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.
![](https://help.macrobond.com/wp-content/uploads/2024/06/dynamictexteditor_24a.svg)
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 #,0,,} |
Millions with thousand separator and no 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. |
{c DocumentLastDataRevision f -p "Data last updated " -m} |
Shows when data was last updated. Example: Data last updated 28 February 2024 01:30 (Feature is available in Macrobond 1.28 and later.) |
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.
Element |
Series |
Observation |
Main/subtitle |
All series used in the chart |
The last observation |
Copyright text |
All series used in the chart |
The last observation |
Legend item |
The series used for the graph |
The last observation |
Y-axis title |
The series plotted against the axis |
The last observation |
X-axis title |
The series used in the pane |
The last observation |
Text box |
The series used in the pane |
The last observation |
Observation label |
The series used for the graph |
The observation it points to |
Axis value label |
The series it references |
The 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 format |
The format depends on the data type as covered below. |
-d delimiter |
The delimiter is used to when there is a list of items. The default delimiter is ' , '. For new lines you can use '\n'. |
-p text |
A text that will be prepended to the formatted text. |
-s text |
A text that will be appended to the formatted text. |
-m text |
A 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 text |
Instead 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 text |
Instead 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:
.Value |
The 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. |
.Date |
The 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. |
.ValueLabel |
The 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. |
.Ordinal |
The 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. |
.GraphText |
The text of the associated graph. |
.DisplayUnit |
The unit. (in Dynamic text roll search for 'Axis label') |
.Currency |
The currency. |
.OriginalCurrency |
The currency of the original series before any currency conversion. |
.ObservationDate |
When 'Last common' or 'Value at' methods are used in analysis it shows date of the observation. |
.OriginalEndDate |
The 'Original end date', 'Original start date', 'Original frequency' and 'Original currency' refers to the original values before any transformations or calculations. |
.Frequency |
The frequency. |
.FullDescription |
The full description of the series. |
.Region |
The country or region. There can be several regions. All regions will be included if no index is specified. |
.Release |
The title of the release associated with this series. This is an entity with additional data. |
.Release.LastReleaseEventTime |
The time of the previous release of new data. |
.Release.NextReleaseEventTime |
The time of next scheduled release of new data. |
.Database |
The database where the series is stored. For example: 'Macrobond', 'Account in-house' or the name of SQL database. |
Some examples of usage:
{s .Value[2012]} |
The last value of 2012 of the default series. |
{s .Value[-1]} |
Second row of values in a category 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:
Fn |
Fixed-point notation where n specifies the number of decimal digits. Example: 1234.5678 formatted using 'F2' is '1234.56.' |
En |
Exponential notation where n specifies the number of decimal digits. Example: 12345678 formatted using 'E2' is '1.23E+007.' |
Gn |
Picks the shortest of the F and E formats with the specified number of significant digits. Example: 12345678 formatted using 'G3' is '1.23E+07.' |
Pn |
Percent 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 %.' |
An |
Automatic 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.' |
Nn |
Same as Fn, but formats numbers using a thousand separator. |
0,, |
Shows value in millions or billions. |
#,0,, |
Shows value in millions or billions with thousand separator. |
The decimal separator is always localized.
The formatting string can also be composed of the following specifiers:
0 |
The '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:
- Thousand 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'.
- 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'.
The two usages of ' , ' can be combined. Example '#,0,,' scales the number by 1000000 and uses a thousand separator. |
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:
Q |
Year and quarter. For example, 2008 Q2. |
W |
Year and week. For example, 2008 W21. |
G |
A short date with time. Example for US: 4/23/2008 1:45 PM. |
d |
A short date. Example for US: 4/23/2008. This is the default. |
D |
A long date. Example for US: Thursday, April 23, 2008. |
f |
A long date with time. Example for US: Thursday, April 23, 2008 1:45 PM. |
M |
Display day and month. Example for US: April 23. |
Y |
Display month and year. Example for US: April, 2008. |
t |
The time. Example for US: 1:45 PM. |
A format string can also be composed of two or more of the following specifiers:
d |
The day from 1 to 31. When used as the only specifier, it must be written as %d. |
dd |
The day from 01 to 31. |
ddd |
The abbreviated name of the day of the week. Example for US: Mon |
dddd |
The full name of the day of the week. Example for US: Monday |
M |
The month from 1 to 12. When used as the only specifier, it must be written as %M. |
MM |
The month from 01 to 12. |
MMM |
The abbreviated name of the month. Example for US: Jun |
MMMM |
The full name of the month. Example for US: June |
yy |
The year without century. Example: 95 |
yyyy |
The 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 format |
The format depends on the data type as covered below. |
-d delimiter |
The 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:
DocumentName |
The name of the document. |
AutomaticTitle |
The automatic title of the chart. |
AutomaticUnitYAxisMain |
The automatic of the main y-axis. |
AutomaticUnitYAxisAlternate |
The automatic of the alternate y-axis. |
AutomaticUnitXAxis |
The automatic of the x-axis. |
DocumentDatabases |
List of databases from which time series used in given document originate. Values might include Macrobond, names of In-House sources, names of 3rd party connectors like Bloomberg. |
DocumentSources |
A list of the sources of the time series used in this document. |
DocumentSourceAbbreviations |
List of abbreviations for the data sources of the time series used in this document |
DocumentLastDataRevision |
Shows when data was last updated. (Feature is available in Macrobond 1.28 and later.) |
Now |
The today’s date. |
Some examples of usage:
{c DocumentSources –d “\n”} |
The sources of the document separated with a new line. |
{c DocumentLastDataRevision f -p "Data last updated " -m} |
Example: Data last updated 28 February 2024 01:30 (Feature is available in Macrobond 1.28 and later.) |
{c Now} |
The current date. |
Example
Axis value labels