Data access in table projects

This project type uses what we call one-dimensional table access, meaning you can only access a single row of data at any one time.

The variables that Studio automatically creates for this project type refer directly to the cell values in the focus row, and they take their names from the column headers in your table data.

Suppose you create a Describe Each Row project and upload this data.

Studio creates four variables for accessing the data:

You can use these variables in a script:

[[City]] has a population of [[Population_2015]]. That's [[percentageChange(Population_2015,Population_2014)]]% up on last year's count of [[Population_2014]], and [[percentageChange(Population_2015,Population_2010)]]% up on 2010's figure of [[Population_2010]].

The output for Row 1 is:

The output for Row 2 is:

KEY POINT: The variables created by "Describe Each Row" projects return column values for the focus row.

This project types uses what we call two-dimensional data access. When you generate just one narrative describing the whole table, there is no focus row, which means Studio only provides variables that refer to whole columns, not to individual cells.

To reference the value of a particular cell, you must use a data access function. To enable this, the table rows need names too. Studio assumes that the first column in your data table contains the row names. The special variable used to access this column is called RowNames. In the table above, this is the City column, making each city name the key for accessing a row. The items in the key column must be unique or row access is not possible.

For the remaining three table columns, the same three variables are created as in the one-dimensional case, but each refers to the entire column. So a reference to the Population_2010 variable returns all data in the Population 2010 column. If column or row name variables are called in a script, Studio prints all values in the column or row as a punctuated list.

Using the data given above, you could write the following ATL script:

The five most populous cities in Australia are [[RowNames]]. In 2015, their respective population figures were [[Population_2015]], averaging at [[precision(mean(Population_2015),0)]]. This average was [[pecentageChange(mean(Population_2015), mean(Population_2014))]]% higher than in 2014. The most populous city was [[rowNames(max(Population_2015))]].

The output narrative would be:

If you know which row names will appear in the script, you can refer to them by their exact string when using one of our Data Access Functions. For example:

In 2015, Sydney had [[cell("Sydney",Population_2015)]] inhabitants.

produces the following narrative output.

"Describe Row in Context" projects combine aspects of the two previous project types. Like the one-dimensional project type, it has the concept of a focus row, but it also allows two-dimensional data access. It generates one narrative per row, but the values for the row can be compared to the values of other rows, table-wide averages, maximums, and so on. Suppose you want to say how the current city being described compares to the average city. This project type allows you to do this.

To make this possible, Studio creates both cell variables and column variables, in addition to the WholeTable variable. Similar to the "Describe Each Row" project type, variables referring to cells in the focus row take their names from the column headers. The names of variables referring to entire columns are formed by appending the word "Column" to the header names.

Assume a "Describe Row in Context" project with this data:

For this dataset, Studio creates these cell and column variables:

You might use these variables in the following ATL script:

In 2015, [[FocusRowName]] had [[Population_2015]] inhabitants, meaning its population was [[if(Population_2015 > mean(Population_2015Column)){larger}else{smaller}]] than the average across the 5 most populous cities in Australia ([[RowNames]]).

The narrative output for Row 1 would be:

Note how the script references both the cell variable Population_2015 and the corresponding column variable Population_2015Column. It uses both variable types to make a comparison between each city's 2015 population and the average across the whole 2015 column.

There are a lot more things you can do with two-dimensional data. See Data access functions.