Extending Spotfire with R
Top 10 Tricks for TERR Data Functions
For more details on these techniques, take online course SP144: Extending Spotfire with R:
•
TIBCO customers: http://learn.spotfire.tibco.com/course/info.php?id=86
•
TIBCO employees: http://spottrain.tibco.com/sep/course/view.php?id=224
1. Quickly add input and output parameters
There is a shortcut for adding input and output parameters to data
functions. In the Script tab of the Register Data Functions dialog,
use the cursor to select a variable in the R script to use as an input
parameter. Then right-click, and click Input Parameter… This opens
the Input Parameter dialog, and populates the Input parameter
name field with the name of the selected variable. Fill in the
remaining fields and click OK to add the input parameter. You can
do the same for output parameters.
2. Debug data functions in RStudio
You may encounter problems when running an R script in a TERR data function that did not
occur when running the same R script outside of Spotfire. To troubleshoot these problems,
add a line of code to the top of the R script to save the input parameters to an RData file.
save(list=ls(), file="C:/debug.RData", RFormat=TRUE)
Select an appropriate location for the file. Then in RStudio, load the RData file and run the R
script, so that the same inputs are used as when the R script ran in the TERR data function.
load(file="C:/debug.RData")
3. Hide warnings and messages
You may wish to suppress uninformative warnings and messages that are generated in TERR
so they are not displayed in Spotfire. This can be done using the R functions
suppressWarnings and suppressMessages. Wrap calls to these functions around expressions
in your R code that generate warnings or messages. A common practice is to apply these
functions when loading R packages. Use the variant suppressPackageStartupMessages to
suppress only messages that are generated when loading R packages.
suppressWarnings(suppressPackageStartupMessages(library(package)))
learn.spotfire.tibco.com
© TIBCO Software Inc.
Extending Spotfire with R
4. Get and set column properties
When a table or column is passed as an input parameter to a TERR data function, you can
access its column properties in the R script. To get the value of the column property foo for a
vector x that is an input parameter of type Column, use the R code:
attr(x, "SpotfireColumnMetaData")$foo
When a table or column is passed as an output parameter from a TERR data function, you can
set its column properties in the R script. To set the value of the column property foo to the
value “bar” for a vector x that is an output parameter of type Column, use the R code:
attr(x, "SpotfireColumnMetaData")$foo <- "bar"
5. Input all columns in a data table
To pass all columns in a data table as an input parameter to
a data function, use the Search expression option of the
Columns input handler, and enter the asterisk wildcard
character *. This ensures that columns added to the data
table later will be passed to the data function.
Or, to pass all columns having a specific data type, use the Expression input handler, and
apply the $map and $csearch functions to select multiple columns using a search expression:
$map("[Data].[$csearch([Data], "DataType:Real")]", ",")
6. Input list-type document properties
Document properties can be passed as input parameters of type Value to a TERR data
function using the Document property input handler. But there is a special kind of document
property, of type List, that must be handled using the Expression input handler. In the
expression, use the $map function to map the list to a single string value, with the values
separated by a delimiter of your choice. For example, to pass the string list document
property ListDocumentProperty as an input parameter of type Value, use the expression:
"$map("${ListDocumentProperty}", ",")"
Then in TERR, the resulting variable is a character string containing the string values in the list
document property, separated with commas. Use the strsplit function in your R script to split
this into a vector of character strings. Use this technique to input selections from multiple
select list boxes to a TERR data function.
learn.spotfire.tibco.com
© TIBCO Software Inc.
Extending Spotfire with R
7. Map an output parameter to filtered or marked input rows
Columns inputted to data functions can be limited by filtering
or marking. But when corresponding columns are outputted
from a data function and are added back to the same data
table that contains the input columns, then Spotfire may
display the message ”Adapting output columns to result
table row count.” This often indicates that there are
mismatches between the rows of the input and output columns.
To resolve this, use the Map to input rows option, and select
an input column that has been limited by filtering or marking.
8. Run a data function when an analysis is opened
To configure a data function to run automatically when the Spotfire analysis is opened:
•
Check the Refresh function automatically checkbox in the Edit Parameters dialog.
•
Configure data tables that were outputted from the data function to be Linked to
source, not Embedded in analysis, in the Data Table Properties dialog.
9. Run a data function synchronously
By default, data functions run asynchronously. Other actions may be performed while the
data function executes. A data function can however be executed synchronously within an
IronPython script by using the method DataFunction.ExecuteSynchronously(). Execution of
the remainder of the IronPython script is then blocked until the data function completes.
for df in Document.Data.DataFunctions:
if df.Name == "K-means clustering":
df.ExecuteSynchronously()
10.
Insert a data function from a file (new in Spotfire 7.5)
In Spotfire 7.5, data functions can be inserted directly from Script Function Definition (.sfd)
files by going to Insert > Data Function > From File…
learn.spotfire.tibco.com
© TIBCO Software Inc.