Displaying a Sankey chart in Spotfire using Spotfire Enterprise Runtime for R and JSViz

JSViz is a framework for creating JavaScript-enabled visualizations in Spotfire^®. This article walks through using the framework with Spotfire^® Enterprise Runtime for R (a/k/a TERR), Spotfire's open-source R-compatible statistical engine, to create visualizations not currently natively available in Spotfire.

You can see detailed information on JSViz and review its documentation in a downloadable zip, which you can find elsewhere on the Spotfire Community Site. The documentation contains examples, tutorials, and an extensive User Guide.

Important Announcement

As of Spotfire 11.0, the core product now features visualization mods that overlaps to a large degree with JSViz. More on this here:

• Spotfire® Mods

• How to transition existing visualizations from JSViz to Mods

Users upgrading to or installing Spotfire 7.12 or later will need to download and install the latest version of JSViz.  See the "Known Issues" section for more details.

This article focuses on creating JavaScript graphics for display in Spotfire. If you want to create a JavaScript graphic directly from TERR for use outside of Spotfire, see the section Graphics in Spotfire Enterprise Runtime for R in the Spotfire® Enterprise Runtime for R Technical Documentation.

Prerequisites

Make sure you have all of the following components to run this example in Spotfire.

It is also useful to have a basic understanding of how to construct Spotfire data functions. For readers new to the data function feature, we explain the steps as simply as possible in this example. For more information about data functions, see the Spotfire Analyst help, included with your installation.

Overview

In this walkthrough, you can perform the following tasks to create a JavaScript visualization that uses TERR inside of Spotfire.

1. Open the sample DXP file and create the document property.
2. Create a Spotfire data function to call the TERR code.
3. Return the output as a document property with all the required HTML code embedded.
4. Create a JavaScript visualization that contains the embedded HTML.

Spotfire setup

To get started:

1. Open a session of Spotfire Analyst that is connected to a Spotfire Server with the JSViz extension installed.
2. Open the Spotfire sample Expense Analyzer Dashboard.dxp. This sample DXP is installed by default and is displayed under the Sample Analyses on the Spotfire start flyout. If you do not see the Samples DXPs, ask your Spotfire Server administrator to install the samples.

Installing the required packages

If you have not yet installed the required packages, then follow these steps.

1. In Spotfire Analyst, from the menu, click Tools > TERR Tools.
2. In the TERR Tools dialog box, click the Package Management tab.
3. In the CRAN Package Repository drop-down list, select your favorite repository, and then click Load to populate the Available Packages list.
4. From the list, select networkD3 and htmlwidgets, and then click Install.
5. Close the dialog box.

Creating the document property

Create the document property to hold the HTML data returned by the data function. Be sure to use the specified name and data type. 

1. In Spotfire Analyst, from the menu, click Edit > Document Properties.
2. In the Document Properties dialog box, click New.
3. In the New Properties dialog box, provide the following property values, and then click OK to save the document property.

You are now ready to create the data function that uses these packages.

Creating the data function script

The script contained in step 6 of this section uses functions in the installed packages plus TERR code to analyze the data specified by the input parameter. The script returns the results in an HTML string, which is then stored in the output parameter.

1. From the Spotfire Analyst menu, click Tools > Register Data Functions.

   The Register Data Functions dialog box is displayed.

2. Provide a Name.

   We used Create Sankey chart.

3. For Packages, specify networkD3;htmlwidgets.
4. Optionally, provide a Description.
5. Clear the Allow caching checkbox.
6. Copy and paste the following R script into the Script edit box.

 # Input Parameter: 'data'  
 # A Table with the character string columns 'Department' and 
 # 'Type', and a numeric column, 'Line Amount'. Each row represents 
 # an expense of the given value of the given type by the given  
 # department.   
 # Output Parameter: 'htmlData'  
 # A character string containing the contents of  
 # an HTML file that displays a Sankey chart.   
 # make sure you are using the correct columns.   
 stopifnot("Line Amount" %in% colnames(data), "Department"  %in% colnames(data),  "Type" %in% colnames(data))   
 # aggregate the expenditures by type and department, showing the   
 # amounts flowing from each department to the expense type.  
 summedData <- aggregate(data["Line Amount"], by=data[c("Department", "Type")], FUN=sum)
 categories <- unique(c(summedData$Department, summedData$Type))   
 # create the chart information for the nodes and links  
 # to match the dept, type, and amount.   
 chartInfo <- list(nodes = data.frame(stringsAsFactors = FALSE, name = categories), links = data.frame(dept = match(summedData$Department, categories) - 1L, type = match(summedData$Type, categories) - 1L, amt  = summedData$'Line Amount'))
 # create the chart by calling the networkD3 package function,  
 # sankeyNetwork passing in the information for the nodes and links,     
 # and setting the display properties for fonts and width.   
 chart <- networkD3::sankeyNetwork(Links = chartInfo$links, Source = "dept", Target = "type", Value = "amt", Nodes = chartInfo$nodes, NodeID = "name", units = "USD", fontSize = 12, nodeWidth = 30)   
 # From the resulting files created by the function,  
 # create the single HTML file to display in Spotfire.   
 dir.create(htmlDir <- tempfile())  
 htmlFilename <- file.path(htmlDir, "chart.html")   
 # create a single HTML file of the graphic for any graphic object  
 # that inherits from the class "htmlwidgets" (defined in the  # htmlwidgets package).  
 htmlwidgets::saveWidget(chart, file = htmlFilename, selfcontained = TRUE)  
 htmlData <- readChar(htmlFilename, file.size(htmlFilename))   
 # clean up.   
 unlink(recursive=TRUE, htmlDir)

 The Register Data Functions dialog box now looks like the following. 

Adding the input and output parameters

The input and output parameters that you add to the Spotfire data function must match the inputs and outputs specified in the TERR script (described in the code comments and used in the script). In addition, Spotfire expects the data types given below, so you must specify them as described.

When you run the data function, the TERR engine prompts Spotfire to match the input and output objects specified in the script to the input and output parameters named in Spotfire. Spotfire displays the Edit Parameters dialog box to prompt you to assign the match for the parameters.

Assigning the data function inputs and outputs

In these steps, first you specify which of the data sample's available columns the data function expects to operate. Then you match the HTML output to the document property that can render the long HTML string (called htmlData in the R script, and matched to HTMLData in the document property) created by the TERR code.

1. In the Edit Parameters dialog box, select Refresh function automatically.

   This step is needed if you expect the data passed to the function to change due to streaming or filtering.

2. In the Input tab, for Input handler, select Columns.
3. Click Select Columns.

   The Select Columns dialog box is displayed.

4. From the Available columns list, select Type, Department, and Line Amount, and add them to the Selected columns list, and then click OK to close this dialog box and return to the Edit Parameters dialog box.

   Remember from the script that these are the only columns we specified for the analysis. (Type and Department are type String, and Line Amount is type Currency.)
   
   

5. Scroll down to display the Limit by option, and from the Filtered rows drop-down, select (Active filtering scheme).

6. This step is needed if you plan to apply a filter, which causes the data function to rerun and the visualization to refresh.

7. Click the Output tab, and then assign the output to the document property you created.

   

8. Click OK to close the Edit parameters dialog box.
9. Click Refresh to run the data function and write to the document property the HTML for the visualization.

   (The HTML string created by the data function is too large to display in the Document Properties dialog box; however, if you want to examine the string, you can export it from the TERR console, available from Spotfire, by typing htmlData at the console prompt.)

10. Close the Data Function Properties dialog box.
11. Optionally, save the data function to the Spotfire Server library, or you can embed the data function in the analysis.

Next, set up JSViz to render the visualization.

JSViz Setup

Adding a JSViz Visualization

1. Create a new visualization page.
2. On the toolbar, click the JSViz icon to add an empty JSViz visualization.

Next, add the HTML content from the Document Property HTMLData.

Adding HTML Linked Content

1. Open the properties for the JSViz visualization, and in the left panel, click Library.
2. Add a Linked Content item with the following properties.
3. Save the setting to close the dialog box and create the Linked Content item.
4. In the left pane, click Contents, and then click the arrow to add chart.html to the Used Content list.

The visualization is displayed in the JSViz window.

Summary

We created a simple example of using the networkD3 package in TERR. We have shown how to integrate JSViz into Spotfire, and how to pass in parameters. By using these steps as a starting point, you should be able to create your own interactive visualization inside Spotfire using TERR, JSViz, and your own data.