Welcome to the NLG Studio Documentation

Index of ATL Functions

Key for the table

Function Name = The name of the function (click on a function name to see examples of usage).

Parameters = A list of parameters for each function: string, string means the function has two string parameters, string… means one or more strings, string/list means a string or a list.

In Function Builder = Whether a function is supported in Arria NLG Studio’s Function Builder in Compose view. If a function is marked , it is widely available in the function builder in most project types (a few marked are not in the function builder in JSON projects). Functions that are not available in the Function Builder in any project type are marked x; these functions can, of course, be constructed by hand.

Row, Table, Context, JSON = ‘Describe Each Row‘, ‘Describe the Table‘, ‘Describe Each Row in Context‘ and ‘Describe a JSON Object’ (project types). In these columns, a function marked is available in the project type and a function marked x is not available.

Function Name

Parameters

In Function Builder

Description

Row

Table

Context

JSON

abs

number

Returns the absolute value (without the sign) of a number.

absDiff

number, number

Finds the absolute difference between two numbers: |x – y|.

addToDateTime

datetime/string

Adds a duration in seconds to a datetime object, or a datetime string.

asBoolean

string/number

Converts the input value to a Boolean.

asDateTime

string/table cell

Transforms the input string or table cell into a datetime object.

asDays

number

Converts a duration from seconds to days. The parameter is the duration in seconds.

asHours

number

Converts a duration from seconds to hours. The parameter is the duration in seconds.

asJson

string

x

Transforms a JSON string into a JSON object.

asList

tableRegion

Converts the input region to a data list.

asMilliseconds

number

Converts a duration from seconds to milliseconds. The parameter is the duration in seconds.

asMinutes

number

Converts a duration from seconds to minutes. The parameter is the duration in seconds.

asMonths

number, datetime/string, datetime/string

Converts a duration from seconds to months. The parameters are the duration in seconds, an optional start time and an optional end time.

asNumber

string

Converts the input value to a number.

asString

any

Converts the input value to a string.

asTable

subScript

Transforms the output of a sub-script into a table object.

x

x

asWeeks

number

Converts a duration from seconds to weeks. The parameter is the duration in seconds.

asYears

number, datetime/string, datetime/string

Converts a duration from seconds to years. The parameters are the duration in seconds, an optional start time and an optional end time.

averageVal (Deprecated)

list/tableRegion, number, Boolean

Finds the average value in a table region (e.g. a column) or a list. See mean.

cell

string, string

Selects a cell from a table or table region. The first parameter is the row name and the second is the column name.

x

x

cellInRegion

tableRegion, string, string

Selects a cell from a table or table region. The second parameter is the row name and the third is the column name.

x

x

charAt

string, number

Returns the character value at the specified index. An index ranges from 0 to length -1.The first character value of the sequence is at index 0, the next at index 1, and so on.

chooseAtRandom

string, string…

Takes input strings and selects one at random.

columnNames

tableRegion

Returns a data list of all column names within a table region.

x

x

columns

string…

Selects columns from your table. The parameters are column names.

x

x

columnsInRegion

tableRegion, string…

Selects columns from a table region. The parameters are the table region and one or more column name(s).

x

x

concat

any…

Concatenates items or lists into a list.

contains

list/string/tableColumn/tableRow/JSONarray, list/string/number/JSONobject

Tests if a string or a list contains a specified substring, item, or items in a sub-list. The first parameter is the input; the second is the test item.

count

list/tableRegion, number/string, function

Returns a count of how many times a given item appears in a list or table region of items.

The first parameter is the input list or table region, and the second is the item to be counted. The third parameter (optional) allows you to apply another function to the list/region prior to counting.

countable

number/string, string/list, string, string/number, string

Generates a noun phrase with a number in grammatically correct form, e.g. “four just men”. The parameters are: the count, the an optional modifier or modifiers, the noun, an optional number format, and an optional word/phrase to use for zero.

countryAdjective

string

Returns the corresponding adjective for a given country name (e.g. "Chinese" for "China").

countryDeterminer

string

Determines if a country name should be preceded by the determiner "the" and returns the country name with or without the determiner.

currency

number, string, string, string, string, string, string

Formats a number as a currency expression. The parameters are: the amount, the unit (an optional ISO currency code), format (an optional ISO currency format), thousands, millions, billions (optional K, M and B formats), and an optional string for formatting negative values.

dateTimeDifference

datetime/string, datetime/string

Returns the absolute difference in seconds between two datetime objects or strings.

day

datetime/string

Returns a number that is the day part of the input datetime object or string.

decodeHtml

string

Interprets a given string as HTML.

diff

number, number

Calculates the difference between two numbers.

direction

tableRegion/list

Determines whether the last value in a table region (typically a column), or in a list increases or decreases relative to the first value in the region.

div

number, number

Performs division.

durationAsList

number, string, datetime/string, datetime/string

Converts the first parameter (duration in seconds) into a list of 7 time units, [years, months, weeks, days, hours, minutes and seconds]. The optional second parameter is a string of time units, the default is 'yMdhms' ('weeks' is not selected). The optional 3rd and 4th parameters are the start and end dates.

encodeHtml

string

Encodes HTML tags in a string so they are rendered verbatim rather than interpreted as HTML.

endsWith

string, string

Tests whether the input string ends with the specified suffix. The first parameter is the input string; the second is the test string

filter

list, function

x

Filters items in a list using a Boolean test function. Returns a list of the items that pass the test.

filterRows

tableRegion, tableColumn/list, function

x

Filters table rows using column names and a lambda expression to define the filter conditions. Returns all rows matching the filter conditions.

x

x

forAll

list, function

x

Iterates through a list applying a function to each item. Returns a string.

forAllCellsByColumn

tableColumn, function

x

Iterates through each cell in a table column applying a function to each item in the column. Returns a string.

x

x

forAllCellsByRow

tableRow, function

x

Iterates through each cell in a table row applying a function to each item in the row. Returns a string.

x

x

forAllColumns

table, function

x

Iterates through all columns in a table applying a function to each one. Returns a string.

x

x

forAllRows

table, function

x

Iterates through all rows in a table applying a function to each one. Returns a string.

x

x

formatDateTime

datetime/string

Formats a datetime object, or a datetime string, as text.

formatDuration

number, string, Boolean, Boolean datetime/string, datetime/string

Formats a duration (in seconds) as a string. The first parameter is the duration in seconds, the optional second parameter is a string of time units, the optional 3rd parameter is whether to include zero values, the optional 4th parameter is whether to include a conjunction and the optional 5th and 6th parameters are the start and end dates.

formatNumber

number, string

Formats a number using the specified format string. The first parameter is the input number; the second is the format string.

frequency

list/tableRegion, list, Boolean

Returns a list of counts showing how many items from a list (or table region) of numbers fall within a series of defined bounds.

The first parameter is the input list or table region, and the second is the bounds list. The third parameter (optional) allows you to choose whether to ignore null/empty values or count them as a zero.

gender

string

Outputs the gender (male, female) for a given name, e.g. Lily or Nick.

getCurrentTime

string

Returns a datetime object representing the current date and time, either in the default GMT timezone or in the optional input timezone.

getTimeZone

datetime/string

Returns the timezone ID or the offset (depending on which has been set) of the input datetime object or string.

groupByJson

JSONarray, number, number, function

Takes a two-dimensional array and groups the inner arrays that have identical values in one or more grouping fields. For each group of inner arrays, the function then aggregates one or more fields using aggregation functions.

x

x

x

groupByJsonObject

JSONobject, string, string, function

Takes an array of JSON objects and groups the objects that have identical values in one of more grouping fields. For each group of objects, the function then aggregates one or more fields using aggregation functions.

x

x

x

groupByTable

tableRegion, tableColumn, tableColumn, function

Takes an input table region and groups the rows that have identical values in one or more grouping columns. For each group of rows, the function then aggregates one or more columns using aggregation functions.

x

x

hasKey

object, string

Checks whether a JSON object (or ATL object, see Advanced Functionality) has the specified String as a key. If it has it returns True, otherwise it returns False.

hour

datetime/string

Returns a number that is the hour part of the input datetime object or string.

indexOf

string/list/table, string/list, number, string

Returns the index within this string or list or table of the first occurrence of the specified substring or sub-list or item searching in the direction of the specified offset and returns -1 if not found. The parameters are: the input string, list or table, the sub-string or sub-list, the offset, and the search direction.

inflectNoun

string, string/number

Inflect a noun, e.g. tree/trees. The first parameter is the input word; the second is the count.

inflectVerb

string, string/number, number, string, Boolean, Boolean

Inflect a verb, e.g. take / takes / has taken / took. The parameters are: the input verb, the count, the person, tense, perfect, and progressive.

initCap

string

Capitalizes the first letter of a given sentence or word.

isDateTime

string, string

Tests whether an input string can be parsed as a datetime object and returns True or False. The parameters are an input string and an optional input format string.

isEmpty

text

x

Tests whether a string, list, table cell or JSON object is empty and returns a Boolean a value of true (empty) or false (not empty).

isNotEmpty

text

x

Tests whether a string, list, table cell or JSON object is not empty and returns a Boolean a value of true (not empty) or false (empty).

isNumber:

number/string

Tests whether a value is a number and returns True or False.

joinStrings

string/list, strings/lists…

Concatenates the specified strings or lists.

keys

object

Returns the key or keys in a JSON object or ATL object (see Advanced Functionality).

len

string/list/tableRow/tableColumn

Finds the length of a variable. The variable can either be a String, where len(string) is equal to the number of characters in the string, or a List, where len(list) is equal to the number of items in the list.

list

string, Boolean, string, string/list, string/list…

Presents a set of input items as a punctuated list and returns a string, e.g. 'cats, dogs and fish'. The parameters are: optional conjunction, optional oxford comma, optional separator, and one or more strings or lists.

lower

string

Converts all letters in the input string to lowercase.

makeList

string/list…

x

Constructs a list data structure from zero or more elements. The input parameters are optional, so you can create an empty list.

map

list, function

x

Takes a list or a list-like object and produces a new list by applying a function to each item in the input list.

max

tableRegion

Finds the cells containing the maximum value in a table region (e.g. a column).

x

x

maxVal

tableRegion/list/number…

Finds the maximum value in one or more numbers, or table regions (e.g. columns) or lists containing numeric values.

mean

list/tableRegion, Boolean

Returns the mean (average value) for an input list or table region of numbers. The second parameter (optional) indicates whether to ignore null/empty values or count them as a zero.

median

list/tableRegion, Boolean

Returns the median of an input list or table region of numbers, i.e. the middle number in the list/region after sorting. The second parameter (optional) indicates whether to ignore null/empty values or count them as a zero.

min

tableRegion

Finds the cells containing the minimum value in a table region (e.g. a column).

x

x

minute

datetime/string

Returns a number that is the minutes part of the input datetime object or string.

minVal

tableRegion/list/number…

Finds the minimum value in one or more numbers, or table regions (e.g. columns) or lists containing numeric values.

mode

list/tableRegion, Boolean

Returns the most frequently occurring item(s) in a list or table region of items.

The first parameter is the input list or table region. The second parameter (optional) allows you to choose whether to ignore null/empty values or count them as a zero.

month

datetime/string

Returns a number, the month part of the input datetime object or string.

monthAsNumber

string, string

Returns the month number (1 to 12) for a given month name.

now (Deprecated)

string

Outputs the time in the specified timezone. See also getCurrentTime.

numberAsMonth

number, string

Takes an integer between 1 and 12 and returns the corresponding month name.

numberAsWeekday

number, string

Takes an integer between 1 and 7 and returns the corresponding weekday name.

numColumns

none

x

Returns the number of columns in the current project data table.

x

x

numRows

none

x

Returns the number of rows in the current project data table.

x

x

numToWords

number, string, number, string

Outputs a number in words, e.g. 4 as four or 5.5 as five point five. Optionally, it may be shown as an ordinal, e.g. fourth. The parameters are: the number, an optional type, an optional threshold, and optional wording for zero.

pairwiseMap

list, list

x

Takes two input lists and produces a new list by applying a function to pairs of elements with the same index from the two lists.

parseDateTime

string, string

Parses an input string and creates a datetime object. The parameters are an input string and an optional input format string.

parseDuration

string, string, string/datetime, string/datetime, Boolean

Takes a string representing a duration and returns a number representing that duration in seconds. The parameters are the input string, the units to parse, optional start time, optional end time, and optional right-to-left parsing.

percentage

number, number, number, Boolean

Finds the percentage of the portion from the whole value in a variable: portionValue / wholeValue * 100. The parameters are: the part value, the whole value, optional decimal places, and optionally strip trailing zeros.

percentageChange

number, number, number, Boolean

Finds the percentage change in a variable: (newValue – oldValue) / oldValue * 100. The parameters are: the new number, the old number, optional decimal places, and optionally strip trailing zeros.

percentageChangeAcrossSeries

tableRegion, number, Boolean

Determines the percentage change between the first and last values in a table region (typically a column). The parameters are: the table region, optional decimal places, and optionally strip trailing zeros.

x

x

percentile

list/tableRegion, number, Boolean

Takes a list of numbers and a target percentile, and returns the value calculated to represent that percentile.

The first parameter is the input list or table region, the second is the target percentile, and the third (optional) indicates whether to ignore null / empty values or count them as a zero.

power

number, number, number, Boolean

Finds the yth power of an argument x. The parameters are: the base number, the exponent, optional decimal places, and optionally strip trailing zeros.

product

number, number…

Calculates the product of two or more numbers.

pronoun

string, string, string, Boolean

Outputs the pronoun for a given gender, or name e.g. you, his, her, their. The parameters are: gender, number, type, person and isPerson.

rank

string/tableRegion, number, Boolean, Boolean, Boolean

Returns the rank of an entry in a list or table region of numbers. The parameters are: the input list/region, the target value, the ranking order, whether to use equal or average ranking, and whether to ignore null values or count them as a zero.

realise

tuple…

Generates from Lex Rules and input data (JSON data or other data types). The parameters are one or more tuples in the form (data, lex-rule-class).

x

x

x

reduce

list, number, function

x

Reduces a list to a single item by applying a function to all list elements (e.g. summing all numbers in a list). The parameters are: the input list, the start value, and a function.

root

number, number, number, Boolean

Finds root of yth degree of an argument x. The parameters are: the number, the number of the root, optional decimal places, and optionally strip trailing zeros.

round

number, number, Boolean

Performs rounding to a specified number of decimal places. The parameters are: the number, optional decimal places, and optionally strip trailing zeros.

rowNames

none/tableRegion

Returns a data list of all row names within a table region.

x

x

rows

string…

Selects rows from your table. The parameters are row names.

x

x

rowsInRegion

tableRegion, string…

Selects rows from a table region. The parameters are: the table region and one or more row name strings.

x

x

second

datetime/string

Returns a number that is the seconds part of the input datetime object or string.

setTimeZone

string/datetime, string

Sets or overwrites the timezone or offset in the input datatime object or string. The second parameters is a valid regional time zone string.

sign

number

Determines the sign of a number, 1 if positive, -1 if negative, 0 if zero.

sort

list/tableColumn/tableRow/object, function

x

Takes items from an input data source (a list, table row, table column or JSON object) and returns a sorted list. The second parameter defines how the items are sorted.

sortByColumn

table, string, function

x

Sorts a table by the items in a specified column (the second parameter) using a comparator function.

x

x

sortByColumnNumbers

table, string

x

Sorts a table by the items in a specified numerical column (the second parameter) with the smallest number at the top and the largest at the bottom.

x

x

sortByColumnNumbersReverse

table, string

x

Sorts a table by the items in a specified numerical column (the second parameter) with the largest number at the top and the smallest at the bottom.

x

x

sortByColumnStrings

table, string

x

Alphabetically sorts a table by the items in a column (the second parameter) containing strings.

x

x

sortByColumnStringsReverse

table, string

x

Reverse-alphabetically sorts a table by the items in a column containing strings (the second parameter).

x

x

sortByRow

tableRegion, string, function

x

Sorts the cells in a table row or part of a table row. The second parameter is the name of the table row.

x

x

sortByRowNumbers

tableRegion, string

x

Sorts numerical cells in a table row or part of a table row. The second parameter is the name of the table row.

x

x

sortByRowNumbersReverse

tableRegion, string

x

Reverse-sorts numerical cells in a table row or part of a table row. The second parameter is the name of the table row.

x

x

sortByRowStrings

tableRegion, string

x

Sorts cells in a table row or part of a table row. The second parameter is the name of the table row.

x

x

sortByRowStringsReverse

tableRegion, string

x

Reverse-sorts cells in a table row or part of a table row. The second parameter is the name of the table row.

x

x

sortDateTimes

list/tableColumn/tableRow

Sorts a list, column or row of datetime objects or strings.

sortDateTimesReverse

list/tableColumn/tableRow

Reverse-sorts a list, column or row of datetime objects or strings.

sortedColumns

string…

Selects columns from a whole table and presents them in the order of the input column names.

x

x

sortedColumnsInRegion

tableRegion, string…

Selects columns from a table region and presents them in the order of the input column names.

x

x

sortedRows

string…

Selects rows from a whole table and presents them in the order of the input row names.

x

x

sortedRowsInRegion

tableRegion, string…

Selects rows from a table region and presents them in the order of the input row names.

x

x

sortMonthNames

list/tableColumn/tableRow, string

Sorts a list, column or row of month names in order of calendar month.

sortNumbers

list

x

Sorts numbers in a list of numbers.

sortNumbersReverse

list

x

Reverse-sorts numbers in a list of numbers.

sortStrings

list

x

Sorts the strings in a list of strings.

sortStringsReverse

list

x

Reverse-sorts the strings in a list of strings.

split

string, string, number

Splits the string around matches of the given regular expression. The parameters are: the input string, a regular expression, and an optional number of substrings in the result.

standardDeviation

list/tableRegion, Boolean, Boolean

Returns the standard deviation calculated from a list or table region of numbers. The second parameter (optional) indicates whether to calculate sample standard deviation or population standard deviation.

startsWith

string, string

Tests whether the input string starts with the specified prefix. The first parameter is the input string and the second is the prefix string.

sublist

list/tableColumn/tableRow, number, number

Takes a list, table row, or table column of items and returns a sublist of the input data. The start index and end index points for the sublist are defined using the function's second and third parameters.

substitute

string, string, string, number

Substitutes new text for old text in a string (all or a specific occurrence). The parameters are: the input string, the search string to be replaced, the replacement string, and an optional number of occurrences to replace.

substring

string, number, number

Returns a string that is a substring of this string, starting from the beginning index and extending to end index -1. The parameters are: the input string, the index of the first character to include in the substring, and an optional index of the last character to include.

subtractFromDateTime

datetime/string, number

Subtracts a duration in seconds from the input datetime object or string.

sum

number/list, number/list…

Calculates the sum of two or more numbers or lists of numbers.

titleCase

string, Boolean

Capitalizes every word in a given input string. The optional second parameter determines whether all other letters should be lower case.

today (Deprecated)

string

Outputs the date in the specified timezone. See also getCurrentTime.

top

list/tableRow/tableColumn, number

x

Returns the specified number of items from the beginning or top of the input list, row or column.

x

topColumns

tableRows, number

x

Returns the specified number of columns from the beginning of the specified input rows.

x

x

topRows

tableColumns, number

x

Returns the specified number of rows from the top of the input columns.

x

x

toReachThreshold

list/tableRow/tableColumn, number/string

Takes an input list (or row or column) of numbers and a target threshold value, then returns the number of input items that must be summed to equal or exceed the target threshold.

truncate

number/string

Truncates a number to its integer part.

totalVal

tableRegion/list…

Finds the total value in one or more table regions (e.g. a column) or lists.

translateTimeZone

string/datetime, string, string

The inputs are a datetime object and a timezone. The function translates the input datetime into a new datetime object with the equivalent time in the specified timezone. The first parameter is the input datetime, the second is the output timezone, and the optional third parameter is an input timezone (default GMT).

trim

string, Boolean

Trims leading and trailing whitespace from a string. The first parameter is the input string and the second is whether to trim whitespace.

unique

list/tableColumn/tableRow, function

Remove duplicates from a list, column or row. The second parameter is optional.

upper

upper

Converts all letters to uppercase.

value

tableCell/list

Extracts the value from a table cell or from a list with a single element.

values

object

Accesses the values in a JSON object or ATL object (see Advanced Functionality).

variance

list/tableRegion, Boolean, Boolean

Returns the variance calculated from a list or table region of numbers. The second parameter (optional) indicates whether to calculate sample variance or population variance,

weekdayAsNumber

string, string

Returns the weekday number for a given weekday name.

year

datetime/string

Returns a number that is the year part of the input datetime object or string.

zip

list, list

x

Converts items from two lists into a set of tuples (or pairs).

zipWithIndex

list

x

Converts a list into a set of tuples where the second value in the tuple is the index of an item in the list.