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 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?
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.
In TIBCO Spotfire, select
Tools > Register Data Functions....
Response: The Register
Data Functions dialog is displayed.
From the Type
drop-down list, select S-PLUS function.
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.)
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.
If desired, type a new Description of the function.
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.
If necessary, move the input
parameters so that the order in the list reflects the order in which
the input parameters should be retrieved.
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.
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.
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.
In TIBCO Spotfire, select
Insert > Data Function....
Response: The Data
Functions - Select Function dialog is displayed.
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.
Click to select the desired
function.
Click OK.
Response: The Data Functions - Parameters dialog
is displayed.
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.
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.
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.
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.
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.
Create a text area and enter
edit mode by clicking on the Toggle Edit Mode button, 
.
Click on the Insert Action
Control button, 
.
Response: The Action
Control dialog is displayed.
Click on Data
Function in the left-hand pane.
Type a Display
text to use on the button or link.
Select the Control
type to use.
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.
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.
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.
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.
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.
Click on Lines
& Curves.
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.
Select the Data
table with line values.
Comment: This should be the data table where the
result columns were added.
Select the X-values
column.
Select the Y-values
column.
If desired, select a Sorted by column, to specify a different sort
order.
Specify whether to Ignore
(skip) empty values or to Split curve
at empty values.
Specify whether to use an
Automatic or a Custom
curve name.
Click OK.
Response: The curve is added to the visualization.
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.
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.
Click
to select the function of interest in the Available
data functions list.
Click
Refresh.
Click
OK.
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.
Click to select the function
of interest in the Available data functions
list.
Click Edit....
Response: The Data
Functions - Parameters dialog is displayed.
If desired, change whether
or not to Refresh function automatically.
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.
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.
Select
Edit > Data Function Properties.
Click
to select the function of interest in the Available
data functions list.
Click
Sync.
Click
OK.
Select
Edit > Data Function Properties.
Click
on the data function you wish to remove.
Click
Delete.
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.
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).
Login to TIBCO Spotfire
as a user with administration rights.
Select Tools
> Administration Manager.
Response: The Administration Manager is displayed.
Click on the Preferences
tab.
Click on the group of interest
in the Selected group list.
Response: The preferences and configuration sets
for the selected group are displayed.
On the Preferences tab, click
on the plus sign next to TIBCO Spotfire Statistics
Services to expand that group.
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.
For the implementation of
your choice, click Edit.
Response: The Edit Preferences dialog is displayed.
Type or paste a new URL for
Spotfire Statistics Services.
Click OK.
Click Close.
Select Tools
> Options.
Response: The Options dialog is displayed.
Go to the Data
Functions page.
Click the Custom
URL radio button.
Type the address to the local
calculation engine.
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.
Select Tools
> Library Administration.
Response: The Library Administration dialog is
displayed.
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.
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.
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.
Select Tools
> Library Administration.
Response: The Library Administration dialog is
displayed.
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.
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.
Change the properties for
the data function and click OK.
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?