Variables
There are two basic types of variables: automatic variables, which the system creates for you from your data; and user-defined variables, which you create yourself.
Index
Automatic variables in table projects
Automatic variables are created by Studio when you upload your data. In table projects, most automatic variables correspond to the columns in your data table. For example, suppose your table includes a column with the header Sales. At the point of data upload, Studio automatically creates a variable with the same name. You can then use this variable to access the data values in that column.
Generally, the names given to automatic variables reflect the column headers in the data. The exception is when the column header text violates one of the rules for naming variables. For example, if your data table contains a column with the header Profit Margin, Studio names the corresponding variable Profit_Margin. This is because variables cannot contain spaces.
Automatic variables vary by project type. This is explained further below.
Describe Each Row
Studio automatically creates a variable for each column in your table. These return the column data for the focus row only. This is because this project type generates a narrative for each table row, using only data from that row.
Suppose your table contains a column with the header Income. Studio automatically creates a corresponding variable named Income. This variable returns the Income column data for the focus row only (i.e. the row for which you're generating the narrative).
Automatic variables in this project type do not provide access to whole columns or the whole table.
Describe the Table
Studio automatically creates a variable for each column in your data table. Unlike in "Describe Each Row" projects, these variables provide access to all data in the corresponding column.
Suppose your data table contains a column with the header Profit. Studio automatically creates a corresponding variable named Profit. This variable returns a column of all values in the Profit column. You might apply an ATL function to the column to sum the values within or find the maximum value.
Another difference between "Describe Each Row" and "Describe the Table" concerns the first column. In "Describe the Table" projects, there is an automatic variable corresponding to the first column, but its name is not taken from the column header. To access data in the first column, you use the automatic variable RowNames.
You can access the whole data table via an automatic variable called WholeTable.
Describe Row in Context
This project type automatically creates two variables from each column in your data table.
The first type — known as a value variable — works like the automatic variables in "Describe Each Row" projects: they return the column's data for the focus row only. The second type — known as a column variable — works like the automatic variables in "Describe the Table" projects: they return a whole column of values.
The image below shows a table in which you can see five column headers: StatePop2010, StatePop2016, Capital, CapitalPop2010, and CapitalPop2016. You can also see three rows of data:
Below is a screenshot of the Variables view (accessed by clicking Variables in the vertical navigation bar). This shows some of the automatic variables created from the data.
Studio creates two variables for the Capital column. The first, Capital, is a value variable and returns the column data for the focus row only. The second, CapitalColumn, is a column variable and returns a whole column of values.
As in "Describe the Table" projects, this project type treats the first column differently. Studio automatically creates two variables from the first column, but their names are not taken from the column header text. They are named RowNames and FocusRowName.
You can access the whole data table via an automatic variable called WholeTable.
Automatic variables in JSON projects
Studio automatically creates a single variable from your uploaded JSON data.
This variable, called WholeJSON, allows you to access the entire JSON object.
Note
It's not possible to change the name of WholeJSON.
Changing an automatic variable's name
You can change the name of most automatic variables. The exceptions are:
WholeTable
WholeJSON
RowNames
FocusRow
FocusRowName
If the variable is editable, changing its name is easy. Go to the Variables view, click on the variable, and change the value in the Variable Name field. The change won't occur until you click Done.
User-defined variables
You can also define your own variables — known as user-defined variables — in the Variables view.
Why define your own variables?
Many valuable insights cannot be gained using automatic variables alone. Automatic variables are great for retrieving values from your dataset (e.g. returning all numbers in a Sales column), but gaining further insights from that data (e.g. calculating the mean or the sum total) requires an ATL function.
It is common practice in Studio to apply functions to variables. If you find yourself repeatedly applying the same functions to the same variable, that's a sign that you should define the operation as a user-defined variable. Once defined, you can call the variable whenever you need to perform the operation.
In the image below, MedianPriceCurrency is a user-defined variable that uses currencyFormat to turn the data value returned from MedianPrice (an automatic variable) into a formatted currency expression.
MedianPriceCurrency is a variable of NUMERIC type, and its data source is [[currencyFormat(MedianPrice)]].
If the value returned by [[currencyFormat(MedianPrice)]] is needed repeatedly in your script, it's neater and easier to make the ATL a user-defined variable — MedianPriceCurrency — and call the variable instead.
Adding a user-defined variable
To add a user-defined variable, click the New Variable button. The New Variable dialog opens.
Here, you specify the variable’s name and type. You’ll see a warning that there is no data source; to fix that, specify either the data source or how to compute the variable. Once you have fully specified your variable, click Done. If you want to change the definition of the variable, you can always come back to this view to edit it.
Tip
You can declare variables directly inside a script — see Script variables for guidance.
Working with variables
When you’re in the Variables view, you can click on a variable’s name to access its properties and edit its definition. Here you can:
Delete the variable.
Change its name.
Change its type.
Change its source. The source can be a data item, a variable, a function, or a constant.
Note
To duplicate a variable, go to the list of variables, find the one you want to copy, and click the Duplicate Variable icon at the right edge of the variable’s row.
Variable types
Currently, Studio supports the following types of variables:
TYPE | DESCRIPTION |
|---|---|
NUMERIC | Returns an integer or decimal number. |
STRING | Returns a sequence of characters. |
LIST | Returns a list of values. |
BOOLEAN | Returns a value of true or false. |
ROW | Returns a table row of data. |
COLUMN | Returns a table column of data. |
JSON | Provides access to a specific part of your JSON data structure. |
DATETIME | Returns a date value, a time value, or a datetime value. |
Variable names
While there are no restrictions on the names of data values in table data, there are restrictions on the names of variables. For an ATL variable name to be valid, it must meet the following conditions:
It must be no more than 40 characters in length.
It must begin with an alphabetic character.
It must not contain spaces or punctuation marks other than the underscore character.
It must not be the same as an existing variable name, script name, folder name, or reserved word.
Important
You can give a variable the same name as an ATL function, but we advise against this.
If your variable has the same name as an ATL function (e.g. product) and you accidentally call the function without parameters (e.g. [[product()]]), Studio treats this as a call to the variable.
Variable names are case-sensitive — so, for example, VAR1 and Var1 refer to distinct variables. If a source data item has a name that is not a valid variable name (e.g. an automatic variable whose source is a column name with a space in it), Studio uses the following algorithm to transform the invalid name into a valid variable name:
Spaces are replaced by underscore characters.
Any other non-alphanumeric characters are replaced by an underscore.
If the name begins with a number, the prefix 'v_' is inserted in front of the number (e.g. 'v_2017').
If the name is the same as a reserved word, the prefix 'v_' is inserted in front of the name.
If the name is longer than 40 characters, it is truncated.
If the name is the same as an existing variable name, one or more digits are added to the end of both names to make them unique.
If the name is the same as an existing script name, one or more digits are added to the end of the variable name to make it unique.
