Skip to main content

Working with rows and columns

A "Describe the Table" project generates a single narrative that corresponds to your whole data table. This is significant because the other table project types — "Describe Each Row" and "Describe Row in Context" — generate a separate narrative for each table row.

Because "Describe the Table" projects lack a focus row — that is, a specific row for which a narrative is generated — accessing row and column data works slightly differently. The first stage of this tutorial will highlight these differences.

Important

This tutorial uses the same dataset used for the "Describe Each Row" tutorial. If you don’t have the CSV data file saved to your local drive, you can download it again by clicking HERE.

  1. Import the data file (AustralianStates.csv) into your project.

    In this tutorial, we'll focus on land mass and population statistics and ignore the information about heads of government.

  2. Click Compose to access the Compose view.

    We'll now start writing a narrative that will describe Australia as a whole.

  3. Type this in the script editor: Australia consists of N states and territories: A, B, C…

    Rows and Columns 1 NEW.png

    This sentence has placeholders for the data that we'll retrieve from the table using variables. N will be the number of states and territories, while A, B, C... will be a list of those states and territories. Let's start with the latter.

  4. Select A, B, C.. in your script, click the Insert Variable button, and select RowNames from the drop-down.

    Rows and Columns 2 NEW.png

    Your script should now look like this:

    Rows and Columns 3 NEW.png

    The first column in this project type is special because its cell contents are treated as row names, and each value in the column must be unique. The first column in our table contains the names of states and territories, which are the very items we need. We have used the special variable RowNames to access these.

    Important

    In "Describe Each Row" projects (see previous tutorial), Studio creates a variable for each column in your dataset. These variables are named using the column headers and are visible in the Insert Variable drop-down.

    The same happens in "Describe the Table" projects but with one exception: the variable for accessing the first column is called RowNames — its name is not taken from the column header. Note that the first column in our dataset is named "Jurisdiction" but no Jurisdiction variable is available from the drop-down.

  5. Click Preview. Your narrative should appear as:

    Australia consists of N states and territories: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory.

    Note that the data retrieved using RowNames is already displayed in a punctuated list. In general, variables or functions that return a list of data values try to do the most sensible thing when presenting that data.

  6. Return to the Compose view.

    We now need to replace N with the number of states or territories.

  7. Select the N in your script, click the Insert Variable button, and select RowNames from the drop-down.

    As we know from steps 4–5, this will return a punctuated list of all states and territories. To get the number of items in that list, we must apply the len function to the variable.

  8. Select the inserted RowNames variable, then click Insert Function > text > len. This will open the Function Builder with len already selected in the FUNCTION field and [[RowNames]] already selected in the VARIABLE field.

  9. Click Save.

    Rows and Columns 4 NEW.png

  10. Click Preview. Your narrative should appear as:

    Australia consists of 8 states and territories: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory.

    Looks good, but let's make a subtle change. Most style guides recommend that, in contexts like this, you should use words rather than digits for values less than 10. We can achieve this by using the numToWords function.

  11. Select the inserted function call, then click Insert Function > language > numToWords. This will open the Function Builder with numToWords already selected in the FUNCTION field and [[len(RowNames)]] already specified in the NUMBER field. The other fields can be be left blank.

  12. Click Save, then check that your output narrative looks like this:

    Australia consists of eight states and territories: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory.

    Now we'll add a second sentence that gives the total population and total land mass of the country.

  13. Add this sentence: It has a total population of X and a total land mass of Y square kilometers.

    To get the values for X and Y we need to sum the values in two columns: StatePop2016 and StateLandArea. We can access the data in these columns by using the corresponding variables StatePop2016 and StateLandArea.

    Important

    In "Describe Each Row" projects (see the previous tutorial) column variables such as StatePop2016 and StateLandArea return the column value for the focus row only.

    Column variables work differently in "Describe the Table" projects because there is no focus row. Column variables correspond to entire columns of data. This will be seen in subsequent steps.

  14. Insert the variables StatePop2016 and StateLandArea in place of X and Y respectively.

  15. Click Preview. Your narrative should appear as:

    Australia consists of eight states and territories: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory. It has a total population of 7,618,200, 5,938,100, 4,779,400, 2,591,600, 1,698,600, 516,600, 395,200 and 244,600 and a total land mass of 800,641, 227,416, 1,730,647, 2,529,875, 983,482, 68,401, 2,358 and 1,349,129 square kilometers.

    The StatePop2016 and StateLandArea variables have returned a list of all data values for their corresponding columns. Next, we need to sum-total these lists using the totalVal function.

  16. Select the StatePop2016 variable, then click Insert Function > math > totalVal. This will open the Function Builder with totalVal already selected in the FUNCTION field and [[StatePop2016]] selected in the first parameter. The other parameter can be left blank.

  17. Click Save, then repeat step 16 for the StateLandArea variable.

    Your script should look like this:

    Rows and Columns 5 NEW.png

  18. Click Preview. Your narrative should appear as:

    Australia consists of eight states and territories: New South Wales, Victoria, Queensland, Western Australia, South Australia, Tasmania, the Australian Capital Territory and the Northern Territory. It has a total population of 23,782,300 and a total land mass of 7,691,949 square kilometers.

Key points

The key points from this part of the tutorial are:

  • "Describe the Table" projects generate a single narrative and therefore do not have a focus row.

  • The first column is special because its cell contents are treated as row names.

  • Each value in the first column (i.e. the row names column) must be unique.

  • You must use the RowNames variable to access data in the first column.

  • Column variables in "Describe the Table" projects return all data values for that column in the form of a punctuated list. You can reduce the list to a single value by applying functions such as totalVal to the variable.

The next part of the tutorial focuses on retrieving minimum and maximum values from your dataset.

Working with minimum and maximum values

© Arria Data2Text Limited