What are Data Functions?


Data functions are calculations based on S-PLUS, open-source R, SAS®,  MATLAB® scripts*, or R scripts running under TIBCO Enterprise Runtime for R for Spotfire, which you make available in the TIBCO Spotfire environment. Once a data function has been defined and saved in the Spotfire library using the Register Data Functions dialog, it can be applied at many different places in an analysis. For example, it can be used as a transformation step when you add or replace data tables. It can also be a separate tool that is run from the Insert menu.

S-PLUS or open-source R data functions can be defined from either an existing function in the corresponding Spotfire Statistics Services package repository, or by writing a script directly in the Register Data Functions dialog, and then running in the appropriate engine (either in the S-PLUS engine for S-PLUS functions, or in the TIBCO Enterprise Runtime for R engine or open-source R engine for R functions).  SAS or MATLAB engines can only be accessed using scripts, and only when you have a working installation of the selected software available. See http://support.spotfire.com/sr.asp for information about the TIBCO Spotfire Statistics Services system requirements.

During the set-up of a data function, a number of input and output parameters can be specified.

It is a best practice to avoid sending very large data sets from Spotfire to a statistical engine, or to invoke complex, long-running calculations. This ensures a rapid response and a good user experience.

 

Concerning R:

To use open-source R functionality with TIBCO Spotfire, you must configure TIBCO Spotfire® Statistics Services with a TIBCO Enterprise Runtime for R engine or with an open-source R engine. For more information on setting up Spotfire Statistics Services or your Spotfire Statistics Services Local Adapter using R, please read the TIBCO Spotfire Statistics Services Installation and Administration Guide or the README file included with the Statistics Services Local Adapter. (Statistics Services Local Adapter does not support the TIBCO Enterprise Runtime for R engine. Other third-party calculation tools can be added using the TIBCO Spotfire API.)

Open-source R is available under separate open source software license terms and is not part of TIBCO Spotfire.  As such, open-source R is not within the scope of your license for TIBCO Spotfire. Open-source R is not supported, maintained, or warranted in any way by TIBCO Software Inc.  Download and use of open-source R is solely at your own discretion and subject to the free open source license terms applicable to open-source R.

Example 1:

A simple conversion of the values in a column from degrees Celsius to degrees Fahrenheit. This is of course just as easy to accomplish using the Insert Calculated Column tool, but it serves as an example simple enough to show input and output parameter handling in more detail.

  1. Assume that the data table in TIBCO Spotfire contains a column with temperatures expressed in degrees Celsius.

  2. First, select Tools > Register Data Functions....

  3. Choose the Type R script - TIBCO Enterprise Runtime for R from the drop-down list and define the script that will perform the conversion on the Script tab:
    # Define the convertTemperature function:
    convertTemperature <- function(x)
    {
      x*(9/5) + 32
    }
    # Run the function to produce the output:
    out <- convertTemperature(x);

  4. Define the Input parameter x as a column with the allowed data types Integer and Real.
    df_example_input.png

    Tip: You can select the parameter in the Script tab and use the pop-up menu option Input Parameter... to reach the Input Parameter dialog directly.

  5. Define the Output parameter out as a column.
    df_example_output.png

    Tip: You can select the parameter in the Script tab and use the pop-up menu option Output Parameter... to reach the Output Parameter dialog directly.
    Note that the output display name will not be propagated to the output column name. The column name is always the output specified by the R script.

  6. Save the data function to the library, as Temperature converter.

  7. To connect the input and output parameters to your current data in TIBCO Spotfire and run the calculation, select Insert > Data Function....

    Comment: You need to have some data loaded in TIBCO Spotfire to use this functionality.

  8. Click on the Temperature converter data function and click OK.

  9. In the Data Functions - Parameters dialog, specify that the input parameter x should be a column and select the data table and column to convert.
    df_example_input_parameters.png

  10. Click on the Output tab and specify that the output parameter out should be handled as a column.
    df_example_output_parameters.png

  11. Click OK.

The data function calculation is performed and a new column is added to the data table. You can change the parameter settings or refresh the calculation later by selecting Edit > Document Properties, Data Functions tab.

Example 2:

If the function to use is a Principal Component Analysis (PCA) calculation, the input would be a number of numerical data columns retrieved from the current data in TIBCO Spotfire and, optionally, a parameter specifying the percent variation to be preserved by the principal components. The output would include three new data tables (scores, loadings and eigenvalue/explained variance table) and a scalar indicating the number of principal components generated.

See also:

How to Use Data Functions

Details on Register Data Functions

 

* SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration.

MATLAB is a trademark or registered trademark of The MathWorks, Inc.