TIBCO Spotfire: Extending Narratives


Documentation for Arria NLG’s Add-in for TIBCO Spotfire Analyst


 

This documentation is organized as follows:

Overview of extending narratives

Extending out-of-the-box narratives

Get and view the sample Spotfire analysis
Get and modify the NLG Studio project
Publish the NLG Studio Project
Configure the Arria add-in to use the published NLG Studio project

Other documentation for Arria’s add-in to TIBCO Spotfire Analyst

 

 

Overview of extending narratives

Arria NLG’s add-in for TIBCO Spotfire Analyst allows you to not only use the out-of-the-box narratives generated from Core Insights, but also extend or modify those narratives to fit your domain’s terminology and any preferences you may have for phrasing, ordering of information, formatting, and so on. The Arria add-in takes the data behind your dashboard and sends a request to Arria’s Insights API, which then delivers messages to the Custom Narrative service for use in NLG Studio, as shown above. The messages are the interface between data-side and language-side processing. Messages are derived from the data analysis and interpretation stage of Arria’s insights APIs and used in the narrative services. Put another way, the messages are enhanced information, containing insights, for Studio to work with in its generation of narratives.

 

Extending an out-of-the-box narrative

To extend Arria’s out-of-the box narratives, you configure the Spotfire analysis to use Arria’s Insight APIs and corresponding NLG Studio projects.

In this example, you’ll begin by downloading a sample Spotfire analysis with an out-of-the-box narrative already configured (as described in Configuring a narrative). Next, you’ll download and modify a sample NLG Studio project containing the code for that narrative, then publish the project. Finally, you’ll configure the Arria add-in to use your published project and to view the changes in the new, extended narrative.

Prerequisites
 

Get and view the sample TIBCO Spotfire analysis

1. Download the Extending Narratives sample Spotfire analysis (.DXP file).

2. In Spotfire, open the sample analysis, which has the custom visualization already added to it.

You should see a narrative like the one below, generated from Arria’s out-of-the-box BI option (Configure Narrative in the UI). Since the narrative generated by this option is configured to use random variation, the text you see may differ.

3. Interact with different areas of the chart and filters to see how the narrative responds.

 

Get and modify the sample NLG Studio project

Now let’s assume you want to change the narrative slightly. In this example, you’ll customize the title of the narrative. (This is just a small change that demonstrates how to modify the narrative in a way that is immediately obvious. In most instances, you would probably want to make more extensive changes.)

1. Download the Extending Narratives sample NLG Studio project and extract the contents of the .ZIP file to find the .JSON file inside.

2. Log in to NLG Studio.

3. In NLG Studio, in the Project Portal, click the Import Project icon to import the Descriptive Statistics JSON file.

4. Rename the project if required.


NOTE: This project may become the starting point for all BI projects you create in NLG Studio in future. You may wish to rename the project to something generic, or to give it a name that matches the name of the corresponding Spotfire analysis file. To change the name of the project, just click in the name field and start typing.

5. Click the sample project to open it.

6. In the left navigation ribbon, click Compose to go to the Compose view.

7. In the list of scripts, click the MeasureOverview sub-script.

8. Change the “MeasureOverview” script to modify the title, adding “- ABC Co. Ltd.”, as shown below:

[[measure.measure_name]] – ABC Co. Ltd.

9. Go back to the Main script, and click Preview to preview the modified narrative.

Next, you’ll publish your modified Studio project.

 

Publish the NLG Studio project

Once you’ve built your Arria NLG Studio project and tested it with your sample data, you can publish it as an application. Before it is published, you can only run the application via the Preview mode in the NLG Studio interface. After it is published, it becomes a real application accessible in the cloud. You can continue to refine your application within NLG Studio, but the published version is fixed until you republish a new version.

To call your published project from outside Studio you will need to create an API endpoint (URL) and an API key (authentication key), as shown in the steps below.

See the NLG Studio documentation if you would like to learn more about deploying NLG Studio applications and using the NLG Studio applications API. However, it is not necessary to have an in-depth understanding in order to use the Arria add-in for Spotfire.

Publish the NLG Studio project and generate an API key

1. In your NLG Studio project, click Publish in the left navigation ribbon to go to the Publish view.

2. In the Publish > API tab, click the Publish button.

3. Make a note of the project URL. (From inside the URL box, you can click the copy icon to copy the URL to your clipboard. Paste it to a notepad.)

4. In the API Key section, click the Generate API Key button.

5. 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.)

NOTE: The NLG Service URL and API key provided here are only examples; they will not work in practice. You must use your own Studio project URL and API key.

 

Configure the Arria add-in to use your published Studio project

Now you’re ready to configure the Arria add-in to use your newly published NLG Studio project. Because you are extending the out-of-the-box narratives, you must call the relevant Insights API. You must also configure mapping scripts to provide the necessary metadata to carry out the analysis and to leverage the Studio project.

1. In Spotfire, in the sample analysis you downloaded previously, click the cog icon in the Arria add-in.

2. Click Create Custom Narrative.

3. In the Simple/Advanced toggle, select Advanced.

4. In the section labeled Call your NLG Service, do the following:

a) In the field labeled Enter NLG Service URL, paste the URL of your published Studio project.
b) In the field labeled API Key, paste the API key of your published Studio project.

Your Create Custom Narrative tab should now look like this:

5. Select the appropriate Studio Project Type for your published Studio project (in this case, Describe a JSON Object).

6.  Configure the mapping script. In the top-right corner, click the Maximize visualization icon to expand the wizard.

Click Edit Mapping Script and paste the following:

var data=getData();setDefaultNarrativeConfig(data);
updateDimensionOrMeasure(data,’Sales’,’entityType’,’currency’);
updateDimensionOrMeasure(data,’Sales’,’unit’,’USD’);
updateDescriptiveStats(data,1,”data”,true);
updateVerbosity(data,’everything’);
setData(data);

7. Configure the Insights API URL you obtained from Arria. For this example, copy/paste the following:

https://jxczzc66qa.execute-api.us-east-1.amazonaws.com/prod/descriptivestats

8. Configure the authorization key (x-api-key) and value (WPj9iYDMvI4thvgSQwv121Xm0h7d1RaR2fpLZpwj).

NOTE: This API and the authorization key are only for learning purposes; they cannot be used in production.

When you have completed the steps above, the Insights URL window should look like this:

9. Minimize the Arria add-in.

10. Click Generate Text. Now you should see the text with the modified title.