Spotfire data inputs and outputs for MATLAB
For general information regarding scripting using MATLAB, refer to your MATLAB software documentation.
The common MATLAB data structures are somewhat different than the rectangular data sets Spotfire supports, so it is necessary to convert them when sending data inputs to MATLAB, or when reading outputs from a MATLAB script. In particular:
- The basic MATLAB engine does not include a table data type with named columns. A
Spotfire data set is represented in MATLAB as a MATLAB struct with named elements, where each name is the name of a table column, and each element is a column vector containing the values in the column.
A vector of arbitrary-length string values is represented as a MATLAB cell array (1 column, N rows) containing N string objects.
It is not represented as a MATLAB char array, because this type of array requires all of the strings to have the same length.
- A list of raw (binary) vectors is represented as a MATLAB cell array (1 column, N rows) containing N UINT8 vectors.
An input to a Spotfire data function can have a type of Table (a whole data set), Column (a single column), or Value (a single scalar). A Table input is sent into MATLAB as a variable (with the same name as the data function input) containing a MATLAB struct with named elements. A Column input is sent into MATLAB as a variable containing a column array. A Value input is sent into MATLAB as a variable containing a scalar value (which is the same as an 1x1 array in MATLAB).
For example, suppose that Spotfire sends an input table variable named in with one numeric column and one string column:
Num Str
1.2 aa
3.4 bbb
This would be available in MATLAB as the following structure:
>> in = struct('Num', [1.2;3.4], 'Str', {{'aa';'bbb'}});
>> in
in =
Num: [2x1 double]
Str: {2x1 cell}
>> in.Num
ans =
1.2000
3.4000
>> in.Str
ans =
'aa'
'bbb'
>>
All outputs from Spotfire data functions are retrieved from MATLAB variables with the names of the data function outputs. If one of these variables is not found (because the script did not set it), an error is generated. If Spotfire expects an output to contain a column or a scalar value, it generates an error if the actual data has multiple columns (for a column output) or multiple rows and columns (for a scalar value output).
If an output is a MATLAB struct, it is turned into a multi-column data set, with column names from the names of the struct elements. If one element is of a different size than the others, it will be replicated as necessary to produce a rectangular data set.
Output data types other than struct are converted into rectangular
Spotfire data sets, with column names derived from the output variable name. For example, if an output variable
aa is a single-column array, it generates a single column named
“aa”
. If an output variable
bb is a multiple-column matrix, it generates columns named
“bb.1”
,
“bb.2”
, and so on. If the exact column names are important, it is best to set the output variable to a struct with specified column names.
The following MATLAB script takes an input data table named
myinput
, adds two new columns (rnum
and
cnum
), and produces an output data set named
myoutput
. It starts with a few useful utility functions for handling input tables represented as structs.
% fns to get the number of rows and columns of a table
dfrows = @(s) max(structfun(@length, s));
dfcols = @(s) length(fieldnames(s));
% fn to convert a table to a matrix
% (error if all columns are not of same type)
df2mat = @(s) reshape(cell2mat(struct2cell(s)),dfrows(s),dfcols(s));
% copy input to output variable
myoutput=myinput;
% add rnum column, with random numbers
myoutput.rnum=randn(dfrows(myinput),1);
% add cnum column, with 10,20,...
myoutput.cnum=transpose(10*(1:dfrows(myinput)));