How to Use Data Functions

You can use data functions to enhance the functionality of TIBCO Spotfire. Below are a few examples of where and how data functions can be defined and applied. Note that you can use the local TIBCO Enterprise Runtime for R engine. Alternatively, you can send requests to a TIBCO Spotfire Statistics Services server. (See your admin about setting the address to TIBCO Spotfire Statistics Services). If you are using open-source R or S-PLUS,  you can send requests to the  TIBCO Spotfire Statistics Services Local Adapter as explained below. See also What are Data Functions?

• To register a TIBCO Enterprise Runtime for R function in Spotfire:

1. In TIBCO Spotfire, select Tools > Register Data Functions.

Response: The Register Data Functions dialog is displayed.

2. From the Type drop-down list, select R script - TIBCO Enterprise Runtime for R.

3. In the Packages field, type the exact name of the package where the function is located in the Spotfire Statistics Services package repository. (This is only necessary if there is more than one function bearing the same name in the repository, or the packages are not loaded automatically.)

4. In the Name field, type the exact name of the function of interest, as it was defined in the Spotfire Statistics Services package repository.

   Comment: TIBCO Spotfire will not be able to locate the function in the Spotfire Statistics Services package repository unless the name is exactly the same.

5. Optionally, provide a Description of the function.

6. On the Input Parameters tab, add all required input parameters.

   Comment: How the input parameters should be handled is defined upon execution of the data function.

7. If necessary, move the input parameters so that the order in the list reflects the order in which the input parameters should be retrieved.

8. On the Output Parameters tab, add all required output parameters.

   Comment: How the output parameters should be handled is defined upon execution of the data function.

9. Save the data function.

   Comment: You can specify keywords upon saving that will help in locating the function in the library at a later stage.

   Response: The registered data function is saved in the library.

10. Click Close.

    Comment: The data function can now be added to an analysis by running it from the Insert menu (see below).

• To register an S-PLUS function in Spotfire:

1. When a function that you want to use from within TIBCO Spotfire has been defined and saved to your package repository in Spotfire Statistics Services, you need to write down or remember its name, together with the names of all required input and output parameters.

2. In TIBCO Spotfire, select Tools > Register Data Functions....

   Response: The Register Data Functions dialog is displayed.

3. From the Type drop-down list, select S-PLUS function.

4. In the Packages field, type the exact name of the package where the function is located in the Spotfire Statistics Services package repository. (This is only necessary if there is more than one function bearing the same name in the repository, or the packages are not loaded automatically.)

5. In the Function name field, type the exact name of the function of interest, as it was defined in the Spotfire Statistics Services package repository.

   Comment: TIBCO Spotfire will not be able to locate the function in the Spotfire Statistics Services package repository unless the name is exactly the same.

6. If desired, type a new Description of the function.

7. On the Input Parameters tab, add all required input parameters.

   Comment: How the input parameters should be handled is defined upon execution of the data function.

8. If necessary, move the input parameters so that the order in the list reflects the order in which the input parameters should be retrieved.

9. On the Output Parameters tab, add all required output parameters.

   Comment: How the output parameters should be handled is defined upon execution of the data function.

10. Save the data function.

    Comment: You can specify keywords upon saving that will help in locating the function in the library at a later stage.

    Response: The registered data function is saved in the library.

11. Click Close.

    Comment: The data function can now be added to an analysis by running it from the Insert menu (see below).

The same steps would be used if the function was created using open-source R.

When open-source R scripts are used to register the data function, for step 3, you must specify the engine that you want your function to run in. Specify either the TIBCO Enterprise Runtime for R engine or the open-source R engine.

When S-PLUS or open-source R scripts are used to register the data function, step 5 is omitted.

For SAS and MATLAB scripts, step 4 is also unapplicable.

• To map and execute a previously registered data function from the Insert menu:

1. In TIBCO Spotfire, select Insert > Data Function....

   Response: The Data Functions - Select Function dialog is displayed.

2. Optionally, click on a Keyword or use the search field to limit the number of shown functions in the dialog.

   Comment: For more information about search expressions, see Searching in TIBCO Spotfire.

   Response: Only the functions whose names match the keyword or search expression are shown in the dialog.

3. Click to select the desired function.

4. Click OK.

   Response: The Data Functions - Parameters dialog is displayed.

5. Specify whether to Refresh function automatically.

   Comment: If the check box is selected a new calculation is performed each time the input parameters change. If the check box is cleared, you must refresh the data function manually.

6. Specify what to do with the input or output parameters, and then click OK.

   Comment: For a description of the available input and output handlers, see Details on Data Functions - Parameters.

   Response: The function is executed. Depending on how the output parameters were set up, you may get a new or updated data table, new columns or rows, or an updated data table or document property, which can be used to control a variety of settings in your analysis. Click the Details link, located in the lower left part of the TIBCO Spotfire window, for more progress information.

Note: Time and Date formats are not directly supported by Spotfire Statistics Services. When sending this type of input to Spotfire Statistics Services you will get the data back in a DateTime (TimeDate) format where a default date or time part has been appended to the original data.

You can use the Currency data type only for data functions intended to use the TIBCO Enterprise Runtime for R engine, but when it is sent to the engine, the data type is converted from Currency to numeric, and when it is returned to Spotfire, it is converted to real. This conversion process can result in a loss of precision for very large values.

• To refresh a data function from a text area:

When data functions are executed in the document, you can refresh the output by clicking an action link or button in a text area. This can be a way to make it easier for other users of the analysis to find and use the data function. For example, if the data function has been set up to work with filtered rows, many people can access the analysis, filter to their special area of interest and click on a button to receive calculation results relevant for them.

Note: If you use this feature, remember that when you publish an analysis to the Spotfire Cloud, the TERR engine is not available to Analysis Client users. Trying to filter or use other controls that attempt to call the TERR engine in the Spotfire Analysis Client results in an error reporting that TIBCO Spotfire Statistics Services is not available. If you want to use TERR in Spotfire applications that you publish to web-based users, we recommend you use Spotfire Cloud Enterprise instead.

1. Create an analysis that uses the data function, and run the data function from the Insert menu, as described above.

   Comment: You must run the data function initially to make the current document aware of the data function.

2. Create a text area, and then enter edit mode by clicking the Toggle Edit Mode button, .

3. Click the Insert Action Control button, .

   Response: The Action Control dialog is displayed.

4. In the left pane, click Data Function.

5. Type the Display text to use on the button or link.

6. Select the Control type to use.

7. Click to select the data function of interest from the Available data functions list.

   Comment: Only those data functions that have been executed from within the current document and do not use automatic refresh are available.

8. Click OK.

   Response: The button or link (or image) is added to the text area.

• To use the result from a data function to draw a line in a visualization:

Data functions can be used to calculate new data that can be used to do such things as drawing a line in a visualization. This can be accomplished in a variety of ways, but the steps below describe an example where the data function result is presented as two new columns containing coordinate values.

1. Define and execute a data function that uses the current data columns as input and performs a calculation before the new resulting columns are added to the data table.

   Response: The data function is added to the document, and the result columns are added to the data table.

2. Create a visualization that can display lines and curves, such as a scatter plot.

   Comment: Line from Column Values cannot draw curves over categorical axes, so make sure that the value columns on both axes are continuous.

3. Right-click in the visualization and select Properties.

   Comment: You can also select Edit > Visualization Properties from the main menu.

   Response: The Visualization Properties dialog is displayed.

4. Click Lines & Curves.

5. Click Add and select Line from Column Values.

   Comment: Use this option if the data results are located in one X-values and one Y-values column. If the results from the data function are presented as curve parameters, you should use Curve from Data Table instead. If a curve equation is calculated, use Curve Draw.

   Response: The Line from Column Values dialog is displayed.

6. Select the Data table with line values.

   Comment: This should be the data table where the result columns were added.

7. Select the X-values column.

8. Select the Y-values column.

9. If desired, select a Sorted by column, to specify a different sort order.

10. Specify whether to Ignore (skip) empty values or to Split curve at empty values.

11. Specify whether to use an Automatic or a Custom curve name.

12. Click OK.

    Response: The curve is added to the visualization.

• To refresh a data function:

If you have inserted a data function in your analysis and the underlying data has been changed you can update the calculation using the same settings as last time without needing to insert the data function again.

1. Select Edit > Data Function Properties.

Response: The Data Function Properties dialog is displayed and all data functions that have been executed in the analysis are shown in the Available data functions list.

2. Click to select the function of interest in the Available data functions list.

3. Click Refresh.

4. Click OK.

• To change settings for a saved data function in an analysis:

1. Select Edit > Data Function Properties.

   Response: The Data Function Properties dialog is displayed and all data functions that have been executed in the analysis are shown in the Available data functions list.

2. Click to select the function of interest in the Available data functions list.

3. Click Edit....

   Response: The Data Functions - Parameters dialog is displayed.

4. If desired, change whether or not to Refresh function automatically.

5. Change the Input parameter settings and click OK.

   Comment: You cannot change the Output parameter settings from here. If this is required, you must execute the data function from the Insert menu again.

   Response: The data function is updated using the new settings.

• To sync a data function with the library:

If a newer version of the data function in the document is available in the library you can click sync to update the data function in the analysis with the changes in the library.

1. Select Edit > Data Function Properties.

2. Click to select the function of interest in the Available data functions list.

3. Click Sync.

4. Click OK.

• To remove a previously inserted data function from the analysis:

1. Select Edit > Data Function Properties.

2. Click on the data function you wish to remove.

3. Click Delete.

4. Click OK.

Response: The data function is removed from the current document but any outputs that were added (columns, data tables, document properties, etc.) will remain until you remove those manually.

• To change the address to Spotfire Statistics Services:

The address to Spotfire Statistics Services is normally specified by the TIBCO Spotfire administrator, on a group level. This step instruction shows how an administrator can change the address for a user group. It is also possible to use a local calculation engine (see below).

1. Login to  TIBCO Spotfire as a user with administration rights.

2. Select Tools > Administration Manager.

   Response: The Administration Manager is displayed.

3. Click on the Preferences tab.

4. Click on the group of interest in the Selected group list.

   Response: The preferences and configuration sets for the selected group are displayed.

5. On the Preferences tab, click on the plus sign next to TIBCO Spotfire Statistics Services to expand that group.

6. Click on StatisticsServices in the TIBCO Spotfire Statistics Services group.

   Response: The currently specified TIBCO Enterprise Runtime for R URL, S-PLUS URL, R URL, SAS URL and MATLAB URL are shown.

7. For the implementation of your choice, click Edit.

   Response: The Edit Preferences dialog is displayed.

8. Type or paste a new URL for Spotfire Statistics Services.

9. Click OK.

10. Click Close.

• To use an alternative calculation engine, e.g., TIBCO Spotfire® Statistics Services Local Adapter:

1. Select Tools > Options.

   Response: The Options dialog is displayed.

2. Go to the Data Functions page.

3. Click the Custom URL radio button.

4. Type the address to the local calculation engine.

5. Click OK.

• To delete a saved data function from the library:

You can delete and edit the name, description, and keywords of a data function using the Library Administration tool.

1. Select Tools > Library Administration.

   Response: The Library Administration dialog is displayed.

2. Browse to and select the data function of interest.

   Comment: You can use the search field at the top right corner of the dialog to help in locating the data function. (Use 'type:datafunction' as the search expression in the search field to find all data functions.) See Searching the Library for more information about search expressions.

3. Click Delete.

   Response: A dialog asking you if you are sure you want to delete the data function is displayed. Click Yes and the data function is removed.

4. Click Close.

• To edit the name, description or keywords of a saved data function in the library:

If you have administrative rights you can delete and edit the name, description and keywords of a data function using the Library Administration tool.

1. Select Tools > Library Administration.

   Response: The Library Administration dialog is displayed.

2. Browse to and select the data function of interest.

   Comment: You can use the search field at the top right corner of the dialog to help in locating the data function. (Use 'type:datafunction' as the search expression in the search field to find all data functions.) See Searching the Library for more information about search expressions.

3. Click the Edit link next to the Selected Item header in the lower part of the dialog.

   Response: The Edit Properties dialog for the selected data function is displayed.

4. Change the properties for the data function and click OK.

5. Click Close.

• To recreate a deleted result column:

If you run a data function that creates one or more columns, and then you delete one of the result columns from the analysis, the lost column remains deleted when you refresh the data function. To recreate the lost column, you must run the data function from the Insert menu again.

• To export a data function definition:

You can export a script/data function definition to disk if you want to share it with others or if you prefer to edit scripts in other script editing environments.

1. Make sure you have the data function script definition you want to export open in the Register Data Functions dialog.

2. Click Export.

3. Browse to the location where you want to save the file and type a File name.

4. Click Save.

• To import a data function definition:

You can import a script function definition which you have previously exported to disk or have written using another script editing tool. The script file should use the extension *.sfd.

1. In TIBCO Spotfire, select Tools > Register Data Functions.

2. Click Import.

3. Browse to locate the script function definition.

4. Click Open.

See also:

What are Data Functions?