Registering a Data Function in Spotfire

A data function is an embedded TERR script that you can save to the library and share with others. Spotfire Analyst includes several out-of-the-box data functions that you can study, edit and save, or run in example data sets. You can use this example task to learn to register a simple data function using a data set provided in the help.

About this task

Perform this task in Spotfire Analyst. Start by opening the data set contained in the help topic Aggregation Data for Spotfire Examples and creating a table visualization of the three-column data set.

Before you begin

You must have a license for advanced analytics in Spotfire Analyst. If you do not have access to the data function dialog box, see your Spotfire administrator.

Procedure

From the menu, click Tools > Register Data Functions.

In the Register Data Function dialog box, provide the data function basic information.

Option	Description
Name	Provide a name that is meaningful for the data function's intended functionality. For the example, name the data function aggregate.
Type	select the default, R script - Spotfire Enterprise Runtime for R. This selection specifies the type of statistical engine to use.
Packages	For this example, leave this text box blank. This exercise uses functionality in packages that are loaded at startup in TERR, so you do not need to install or load any additional packages.
Description	If you intend to share this data function for future use, you and other users can find additional information about the data function useful.
Allow caching	For the exercise, select the check box. (Clear this check box for a data function that evokes a random procedure, where you want the results to change each time it is run.)
Script	You can type the data function script directly in this text box, or you can copy and paste an R script you developed in RStudio or another development environment. See Step 3 for more detail about creating the script for the example. Alternatively, see one of the built-in data functions that ship with the TERR library examples of writing R code for a data function.

For the example, type the following script.

if (nrow(x) > 0) {
y <- aggregate(x[, c("Group", "x1", "x2")], by=list(x[, "Group"]), FUN=median)
} else {
y <- x
}

This example script body, including the output, the function, and the function arguments, includes the following.


`if... else`	Provided for error handling, the `if`/`else` statement ensures that if no rows are selected, the data function does not report an error.
`y`	The object containing the output of the function.
`aggregate`	The TERR function to run.
`x`	A `data.frame` (in TERR) that represents a data table in Spotfire Analyst. This object functions as the input paramter for the data function.
`"Group", "x1", "x2"`	The columns to aggregate.
`by`	An argument of the `aggregate` function that is specified as a list, which represents the vectors that we group by (in this case, the single vector, which is the `"Group"` column in the data set.)
`FUN`	An anonymous or in-line defined function, or a function available to use from one of the available packages in TERR, such as the base or stats package. This example specifies the `median` function from the stats package, which calculates the median of the input.

Click the Input Parameter tab, and then click Add.
The Input Parameters dialog box is displayed.
For the Input parameter name, assign x.
A data function can have any number of input parameters. This example has only one: the table named x.
In the Type drop-down list, select Table.
Remember in the script, you specified x as a data frame. The other choices are as follows.

Option Corresponding type in TERR
Value A vector of length 1.
Column A vector.
Table A data frame. (Select this option if you are working through the example.)
Select the Allowed data types for the script.
For the example, select String and all numeric data types: Integer, Real, SingleReal, and Currency.
Tip: Click Numeric to select all of the numeric data types.
Click OK to save the input parameter.
The Input Parameters tab displays the single parameter.
Click the tab Output Parameter, and then click Add.
The Output Parameter dialog box is displayed.
For the Result parameter name, designate y, and specify its Type as Table.
For anything you create in the script that you then pass into Spotfire, you must designate as an output parameter.
Click OK to save the output parameter.
The Output Parameters tab displays the single parameter.

Option	Corresponding type in TERR
Value	A vector of length 1.
Column	A vector.
Table	A data frame. (Select this option if you are working through the example.)

What to do next

Edit the parameters for the data function.