How to Use Data Functions


Data functions can be used to enhance the functionality of TIBCO Spotfire in many ways. Below are a few examples of where and how data functions can be defined and applied. Note that you or your admin must first set the address to TIBCO Spotfire Statistics Services or TIBCO Spotfire Statistics Services Local Adapter as explained below. See also What are Data Functions?

  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.

  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 or not to Refresh function automatically.

    Comment: If the check box is selected a new calculation will be performed each time the input parameters change. If the check box is cleared, you need to 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. A Details... link with progress information  will be available in the lower left part of the TIBCO Spotfire window. Click on the link for more 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. Columns with the data type Currency cannot be used in data functions.

Once executed in the document, data functions can also be refreshed by clicking on 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.

  1. Create an analysis where the data function can be used and run the data function from the Insert menu as described above.

    Comment: This is done in order to make the current document aware of the data function.

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

  3. Click on the Insert Action Control button, text_icon_action.png.

    Response: The Action Control dialog is displayed.

  4. Click on Data Function in the left-hand pane.

  5. Type a 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 will be available.

  8. Click OK.

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

Data functions can be used to calculate new data which 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 which 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 which 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 on Lines & Curves.

  5. Click Add and select Line from Column Values....

    Comment: This is the option to use 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, and 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.

  1. Select Edit > Document Properties.

    Response: The Document Properties dialog is displayed.

  2. Click on the Data Functions tab.

    Response: All data functions that have been executed in the analysis are shown in the Available data functions list.

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

  4. Click Edit....

    Comment: To simply update the data function using the same settings as last time, click Refresh.

    Comment: Use the Sync button to update the data function with any changes done to the data function in the library.

    Response: The Data Functions - Parameters dialog is displayed.

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

  6. 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.

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.

  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.

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. Click to 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 on the Delete button at the top of the dialog.

    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.

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. Click to 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 on 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.

If you run a data function which creates one or more columns and you then delete one of the result columns from the analysis, the lost column will remain gone when refreshing the data function. In order to recreate the lost column you must run the data function from the Insert menu once again.

See also:

What are Data Functions?