Functions
Functions compute values from existing variables or constants. ATL functions are very similar to the functions used in, say, Microsoft Excel; if you are familiar with using functions there, you’ll quickly understand how to use functions in Arria NLG Studio.
Studio's built-in functions are organized into nine categories:
Data access functions — for access to values in table and JSON data.
Datetime functions — for calculations on and manipulation of dates, times, and timezones.
Formatting functions — for controlling how text or numbers appear in your narrative.
Language functions — for linguistic operations on variables and constants.
Mathematical functions — for arithmetic and mathematical computations.
Statistics functions — for advanced statistical analysis.
Text functions — for manipulating the contents of strings as sequences of characters.
Tools functions — developer tools that produce an output in the Console Log area.
Advanced functions — for advanced users (these are not available in the Function Builder).
Tip
See Index of ATL functions for a comprehensive list of built-in functions.
Functions can accept any legal ATL expression as an argument. In the example below, three functions — percentageChange, div, and product — are underlined in orange. The variables CapitalPop2010 and CapitalPop2016 store the populations of a capital city in 2010 and 2016, and StatePop2010 and StatePop2016 the populations of a state in 2010 and 2016:
As can be seen above, functions may be nested (one function wrapped in another function). This can be done to arbitrary depth. The script above calculates the capital population as a percentage of the state population; that is, the product function multiplies CapitalPop2016 by 100, and the div function divides the result by StatePop2016.
The result would be something like:
New South Wales has a land mass of 800,641 square kilometers and a population in 2016 of 7,618,200, up 5.2% from 2010’s figure of 7,238,800. The capital city, Sydney, has a population of 4,526,479, which is up 8.2% from 2010’s count of 4,183,471. Today the capital is home to 59.42% of the state’s population.
Working with functions
Most functions are supported in the Function Builder. To insert one of these functions into your script, click the Insert Function button and select a function from the dropdown menu:
Clicking on a function's name opens the Function Builder dialog with the function pre-selected. The displayed fields vary depending on how many parameters the function takes. Some functions have a fixed number of parameters. Others take an arbitrary number of parameters. For example, the chooseAtRandom function randomly selects from any number of parameters, as shown below.
In these cases, when you first open the Function Builder dialog, fields for only two or three parameters are shown. If you provide values for these, a new empty parameter field appears in the dialog.
To build a complex function, start by inserting the innermost function into your script. Next, select the function call and invoke the Function Builder to wrap a new function around it. You can keep wrapping functions around other functions as necessary to achieve your desired result.
User-defined functions
Although there are over 150 built-in functions in Studio, there might not be an individual function (or nested combination of multiple functions) that performs the operation you need. In such cases, you can use ATL to define your own function.
Tip
Please refer to ATL Guide > User-defined functions for guidance.
