Creating Your Own Narratives – Table-Type Studio Projects


Documentation for Arria NLG’s Add-in for Tableau Desktop


This documentation is organized as follows:

About projects

Creating a custom narrative

  1. Open the sample Tableau dashboard and import Arria’s custom visual
  2. Add a narrative to describe the visuals
  3. Create a project in Arria NLG Studio
  4. Modify the starter project
  5. Publish the NLG Studio sample project
  6. Link your published NLG Studio project to your Tableau dashboard

Using mapping scripts

Optimizing the narrative to handle filters

Contextualizing the narrative

Going further

Other documentation for Arria’s extension to Tableau

 

About Projects

NLG Studio offers the ability to work with different data types in different ways. You select your project type based on the type of data you have and the functions you need to use on the data. Each project type provides a slightly different experience. The two categories of data that NLG Studio allows you to work with are tabular data and JSON data.

Tabular Data

For tabular data—that is, spreadsheet data—you can choose from the project types that follow.

Describe Each Row. Each row in your input data is used to generate a separate story. Your Composer scripts and variable definitions can only refer to data elements within a single row.

Describe the Table. An entire multi-row spreadsheet is used to generate a single story. Your Composer scripts and variable definitions can refer to data elements across rows.

Describe Each Row in Context. Each row in your input data is used to generate a separate story, and data in the other rows provides context. Your Composer scripts and variable definitions can refer to data elements across rows.

JSON Data

For JSON data, NLG Studio provides a project type that allows working with all facets of data in JSON format:

Describe a JSON Object. An entire JSON object is used to generate a single story. Your Composer scripts and variable definitions can refer to data elements within the object.

Project Types Supported with BI Integration

Arria’s add-in for Tableau supports JSON-type projects and Describe the Table projects. This documentation is about BI integration with the Describe the Table project type. For more information on the Describe the Table project type, see Describing a Whole Table. If you are working with JSON data, see this topic that explains creating narratives based on JSON data.

 

Creating a Custom Narrative

This guide explains how to get and use Arria NLG’s add-in for Tableau Desktop.

You’ll begin by downloading a sample Tableau dashboard. Next, you’ll import Arria’s custom visual into the report. After that, you’ll provide some information about your data and the kind of things you would like to say about it in a narrative.

Using Arria’s custom visual, you’ll add a narrative widget to the report. Then, using NLG Studio, you’ll create a very simple NLG project, which you’ll publish to the cloud. Then, you’ll link the published Studio project to the narrative widget to bring its NLG into the report.

By moving through the steps of creating a very simple NLG project, you’ll get a glimpse of the amazing things you can do when you extend Tableau with Arria’s NLG technology.

Prerequisites:
Audience:

BI analysts, BI developers

Open the sample Tableau dashboard and import Arria’s custom visual

1. Download this sample Tableau workbook.
2. In Tableau Desktop, open the workbook.

3. In the Objects section, double-click Extension.

 

 

 

4. In the dialog, click My Extensions.

5. Open the .TREX file provided by Arria. You should now see the Arria extension in your dashboard. Move it to a location that suits you.

Add a narrative to describe the visuals

1. In the Arria extension widget, click Create Custom Narrative.
2. In the Narrative for dropdown, select Underlying Data.

3. Click Show Data Fields.

4. Use the scroll bar to move through the data fields, and with the checkboxes, select the following data fields: Product, Segment, Year, Profit, Sales. (Make sure to select Sales, not Gross Sales.)

5. Scroll back up and click Hide Data Fields. Now that you’ve selected the data you’re working with in Tableau (the fields Product, Segment, Year, Profit, and Sales), you’re ready to bring that specific set of data into NLG Studio.
6. In the Arria NLG widget, make sure the Simple/Advanced toggle is set to Simple.
7. Make sure the Studio Project Type is set to Describe a Table. (This is because the NLG Studio starter project you are going to download is a table-type Studio project. If the Studio project you associate with your dashboard is based on JSON data, you would choose Describe a JSON Object here.)

8. Click in the title text for the View Dataset in CSV section and explore the data.
9. Click in the title text for the View CSV Payload section, and look at the data objects you are sending as part of the API call (described below).

Note: Describe the Table-type projects in NLG Studio require you to have a unique field as the first column. To accommodate this requirement, the Arria add-in by default adds an auto-increment field to the data as the first field. If your data already has an ID column and you want to use that instead of the default auto-increment field, de-select Add auto increment ID. If you do use your own ID column, make sure that in the Fields pane, it is the first column you select so the unique column is in the first position of the table data brought into NLG Studio.

10. In the View Dataset in CSV section, at the top right, click the download icon to download the data.

11. In the Open Browser dialog, click OK.

12. Check your machine’s Download folder for the file called data.json. In the next section, you’ll import this into the BI Starter project in NLG Studio.

Create a project in Arria NLG Studio

You are going to create a very simple sample project in NLG Studio in order to get a basic understanding of how you can use NLG Studio to augment your analytics. (For instructions that show how to create a more elaborate narrative, see the NLG Studio documentation.)

1. Download the BI Starter project for NLG Studio. The BI Starter project contains some helper functions that you’ll see as sub-scripts under the Main script in the Compose view. These helper functions are user-defined functions created specifically for working with BI data.
2. Check your machine’s Download folder for the file called BI+Starter+Project+-+Table+Type+Data.zip and extract its contents.
3. Log in to NLG Studio.
4. In NLG Studio, in your dashboard, click the Import a Project icon to import the unzipped BI Starter Project file.

5. In the NLG Studio dashboard, click the starter project to open it.

 

 

 

 

 


Note:
 In the future, this project may become your starting point for all your BI projects created in NLG Studio. So if you like, you can rename the project to something generic. Or, you might want to give it a name that matches the name of the corresponding .TWBX file. To change the project’s name, just click in the name at the top left of the screen.

You’ll see the data that comes with the starter project. When you’re ready to modify this starter project, you’re going to replace this data with the data from your field selections in Tableau.

6. In the left navigation ribbon, click Compose to access the Compose editor.

In the editor, you’ll see the contents of the Main script, which is empty aside from a reference to a ReadMe sub-script. This ReadMe describes the BI data format used in Tableau projects, and it provides information about the helper functions in the project. The helper functions appear as a list of sub-scripts under the Main script. You can click on the sub-scripts to see their contents (the user-defined helper functions).

7. Make sure you’re in the Main script, then at the top right of the screen, click Preview. Read the ReadMe information.

Modify the starter project

You are going to compose a piece of narrative describing the total sales and total profit for the selected period. To generate the text for that, you’ll add some code in the Compose editor. But first, you need to import the data set that is specific to the fields you have selected in Tableau: Product, Segment, Year, Profit, Sales.

1. In the left navigation ribbon, click Data to go to the Data view.
2. At the top right of the screen, click the import icon to bring in the file called data.json from your Downloads folder.

3. Click Compose to go to the Compose view.
4. Click Main to begin editing the Main script.
5. Remove the text that is already there ([[ReadMe]]).
6. Copy/paste the following:

For the [[inflectNoun('year',len(unique(Year)))]] [[unique(Year)]], the total sales were [[formatCurrency(totalVal(Sales),'USD','#.00')]] and the total [[direction(totalVal(Profit) ,'profit','loss' )]] was [[formatCurrency(abs(totalVal(Profit)),'USD','#.00')]].

7. In the top right of the screen, click Preview.
Your previewed output should look like this: Now add another piece of narrative. You’ll add a sentence reporting on the sectors that contributed the most and least profit. As an exercise, you’ll create some in-script variables that you’ll use to replace some of your existing code.

8. In the left navigation ribbon, click Variables then +NEW VARIABLE to add a variable called “currency” of type STRING and source USD, as shown here:

9. Click Done to save the new variable.

10. In Main, replace the existing script with the following:

For the [[inflectNoun('year',len(unique(Year)))]] [[unique(Year)]], the total sales were [[formatCurrency(totalVal(Sales),currency,'#.00')]] and the total [[direction(totalVal(Profit) ,'profit','loss' )]] was [[formatCurrency(abs(totalVal(Profit)),currency,'#.00')]]. The best-selling product was [[getKey(topNInstancesbyDimension(Product,Sales,1)[0])]] with a total of [[formatCurrency(getValue(topNInstancesbyDimension(Product,Sales,1)[0]),currency,'#.00')]]. The [[getKey(topNInstancesbyDimension(Segment,Profit,1)[0])]] segment reported the most [[direction(getValue(topNInstancesbyDimension(Segment,Profit,1)[0]), 'profit','loss')]] ([[formatCurrency(getValue(topNInstancesbyDimension(Segment,Profit,1)[0]),currency,'#.00')]]).

11. Click Preview. Your previewed output should look like this:

 

Publish the NLG Studio sample project

1. In NLG Studio, in your BI Starter Project, click Publish in the left navigation ribbon.
2. In the Publish view, click the Publish button.
3. At the Congratulations! message, make note of the URL for your project. (From inside the URL box, you can click the copy icon to copy the URL to your clipboard. Paste it to a notepad.)
4. Under Run Project, click API.
5. Scroll down, then click the Generate API Key button.
6. Make note of the API key generated. (Again, you can copy it to your clipboard from inside the box with the key. Paste it to a notepad.)

Link your published NLG Studio project to your Tableau dashboard

1. In the first empty field in the widget, enter the NLG service URL (the URL you made note of after publishing your NLG Studio project).
2. In the second empty field in the widget, paste in your API key.

3.  Click the Generate Text button.

4. Click around on different pieces of the charts to see how the narrative responds. To select multiple bars at the same time, use CTRL+Click.
5. (Optional) You can copy the narrative for pasting elsewhere by clicking the copy icon in the top right of the widget.

 

Note: Above, in Add a Narrative to Describe the Visuals, you selected the data you’re working with in Tableau (the fields Product, Sales, Profit, Segment, Year). The order in which you ticked those checkboxes in the Fields pane is reflected in the dataset you import into NLG Studio. So for example, if you went top-down and first clicked Product, Sales, Segment, and Year, and then went back up and clicked Profit, then in your dataset, Profit would appear after Year, not after Product. This is important to know because if you change the order of your selected fields in Tableau after creating and publishing your Studio project, you must re-download the sample data, bring it into your Studio project again, and republish the Studio project.

Using Mapping Scripts

With Arria’s add-in, you can add custom JavaScript to modify the input variables — right inside the narrative widget. You do this in the Edit Mapping Script section.

About the Methods Used:

getData(): This method returns the underlying JSON data (the data you see in the View Dataset in JSON section and View CSV Payload section).
setData(modifiedData): This method sets the modifiedData variable (the transformed data object). After using this method, the transformed data object is available for posting to the NLG service URL.

The following example shows how you can assign some variable values to the input JSON data object that can be used in the narrative script:

var data=getData();
data.vars['currency']='GBP';
setData(data);

To try out a custom mapping script:
1. Copy the above script and paste it in the Edit Mapping Script section of the narrative widget.

2. Click Generate Text in the Arria widget).

You should see the currencies expressed in sterling (£) instead of dollars (US$).

What you have done here is you have used a new mapping script to overwrite your design-time variable values.