Solo Predictor Script Construction

Solo_Predictor and Solo provide a simple, flexible scripting language with which clients can send instructions to load data, apply a model to that data ("make a prediction"), and retrieve results. A typical exchange follows this sequence:

1. load data
2. load model
3. apply model to data (make a prediction)
4. return prediction results

This section describes the details of how to format a script, what commands are available and how the commands are used. The next section gives several quick-start example scripts which can be used as templates to perform some standard analyses.

Some familiarity with multivariate analyses and modeling are presumed by this chapter. The user is directed to the PLS_Toolbox and Solo Manual and Tutorial to learn more about specific modeling methods and multivariate analysis in general.

It may also be useful to review the Solo Predictor Script Commands Summary as a starting point for familiarizing yourself with the scripting language.

Workspace Objects

Each command in a script creates or operates on objects stored by Solo_Predictor for the client. Objects include:

DataSet Objects – contain data to be used in predictions.

Preprocessing Objects – contain instructions for how to apply preprocessing to a DataSet.

Calibration Model Objects – contain details on a calibration model from PLS_Toolbox or Solo.

Calibration Transfer Model Objects – contain details on a calibration transfer model from PLS_Toolbox or Solo.

Prediction Objects – contain results from applying a calibration.

Some other object types can be created and modified using the Advanced Scripting with Objects methods.

When created, each object must be given a unique name (up to 64 characters in length) using only letters, numbers, and the underscore character ( _ ). Object names may not contain spaces and may not start with a number ("a1" is allowed, "1" is not), but are otherwise unlimited. Giving a new object the same name as a previously existing object overwrites the original object.

All objects exist in a persistent "workspace" – it remains intact from one request call to another. In addition, this workspace is usually unique to the individual client so that no two clients can access the objects in another's workspace (however, see the privateworkspace option in the Installation and Configuration section.)

Script Commands

Script commands fall into these categories:

1. Importing commands – bring data or objects into Solo_Predictor

obj_data = 'content'

2. Object creation commands - create advanced object types (see Advanced Scripting with Objects)

obj = @objecttype(properties)

3. Model and Preprocessing Application commands – apply an object to data

obj_result = obj_data | obj_model

4. Return Value Request commands – request the value contained in an object.

obj_result

5. Response Message Format commands – set the output format for returned results and errors

:format

6. Write To File and Export commands – creates an output file containing results

:writefile

7. Other commands

:command

8. Comments – not processed by Solo_Predictor.

//comment

#comment

%comment

Each script can contain one or more commands, so more than one operation can be performed in a single call. Multiple commands are separated by semicolons. For example:

 command; command; command

White-space characters in a command (i.e. spaces, tabs, line-feeds) are generally ignored. They can be included for readability but are not generally required. The exceptions to this rule are noted below (for example, in some of the data importing formats where white-space may be required.)

All script commands are also summarized Solo_Predictor Script Commands Summary.

Importing Commands

Nearly all scripts start with one or more importing commands. To perform a prediction, a client must request the import of data and a model (at a minimum). Importing commands create data, models, or preprocessing objects in the client's workspace. These can be created from:

1. Reading the object from one of a number of supported file types, or
2. Creating the object directly from text in the script.

In either case, the format of the command is the new object's name, followed by an equal sign and the content for the object in single quotes:

 obj_1 = 'content'

The content takes various forms depending on the source of the object. Note that if the content needs to include a single quote, it should be escaped by adding a backslash in front of the quote: \' This is most often necessary when importing an XML object (see below)

Importing From a File

Any of the objects used by Solo_Predictor can be loaded from a disk file. This is the most common form of import command when a client program can only save data to disk, and is also the most common command used to load a model. A file that is stored either locally on the server's computer or on a network-mounted drive can be loaded by providing the path and filename (including extension) of the file enclosed in single quotes.

obj_1 = 'C:/full/path/filename.ext'

or accessing from a network drive using its UNC path:

obj_1 = '//network-drive/modelfolder/filename.ext'

Note that the path to the file is always relative to the server, not the client.

Solo_Predictor will automatically recognize the filetype and use the appropriate file reader to import the file.

If the file extension is not unique, or is misleading (e.g. a file in "XY" format that doesn't use the ".xy" extension or Opus files, which can have numerical extensions), a specific importer can be forced for use by prefixing the filename with a colon and the keyword associated with the importer to use plus a space followed by the filename. For example:

obj_1 = ':opusreadr C:/full/path/filename.ext'

would force the use of the Opus file reader on the specified filename. See the Data Importing Formats page to get a list of keywords that can be used to import the corresponding file types.

Importing From Matlab MAT Files

If reading from a MATLAB .mat file containing more than one variable, a specific variable to load must be specified in the import command. This is done by appending a question mark followed by the variable name, all inside the single quotes.

obj_1 = 'C:/full/path/filename.mat?variable'

This is only necessary when the .mat file contains more than one variable. If only one variable is present, that variable will be loaded without a specific variable name being specified.

The Features and Supported Methods section discusses valid file types, and other types may be available. In general, the list of file types supported by the Analysis GUI and Workspace Browser in Solo and PLS_Toolbox are also supported by Solo_Predictor.

Creating Data From Script Text

Data can be created from a list of comma-separated values by simply passing those values as text between the quotation marks:

obj_1 = '1,2,3,4'

This would create an object that contains the values 1 through 4. Note that this form of input provides no means to assign labels or axis values corresponding to these values. As a result, no variable alignment or correction for missing or extra variables can be performed. It is assumed that the number of variables passed is appropriate for use with the model of interest.

Creating Literal String Constants

For some object properties and methods, literal strings (a.k.a. string constants) are needed. To generate such strings, double-quotes can be used in place of the single quotes:

str_1 = "A String Here"

In this example, the object str_1 will be assigned the literal string between the double-quotes. Note that in older version of solo scripting, single quotes were required around the double quotes, indicating you were importing the string: '"this string"' but this approach is no longer necessary.

Creating Objects from XML

Any of the objects used by Solo_Predictor can be created from an XML format that is supported by both PLS_Toolbox and Solo. In this form, the content of the import command is an object's XML description.

obj_1 = '<obj>(XML formatted content)</obj>'

Although XML input is more complex, it enables the widest range of features supported by Solo_Predictor, including variable replacement and alignment. To simplify its use, a template XML file showing the tags necessary to create a DataSet object is discussed in DataSet XML Format. This template can be used to create and pass appropriate XML for these objects.

Any xml object that has been exported from Solo or PLS_Toolbox (including DataSet, Model, and Preprocessing objects) can be stored and passed into Solo_Predictor to re-create the given object.

Advanced Object Creation and Modification

Objects can be created from an empty object definition using the "at" symbol prefix before an object type and its properties in parenthesis:

obj = @objecttype(properties)

The exact objects available depend on the product being used, but most support DataSet objects and EVRIScript objects. In addition, the inputs required by these objects differ.

Creating and working with objects is discussed on the Advanced Scripting with Objects page.

Application of Models and Preprocessing Commands

Once a calibration model, calibration transfer model, or preprocessing object has been imported into Solo_Predictor, it can be applied to a DataSet object using the application command. This command consists of an output object name, an equal sign, a DataSet object's name, the bar character, and the model or preprocessing object to apply. The output of the application command depends on the type of object being applied.

 modifieddata = data_obj | preprocessing_obj
 modifieddata = data_obj | caltransfer_obj
 prediction_obj = data_obj | model_obj

When applying a preprocessing object to a DataSet object, the result is always another DataSet which contains the modified data. This DataSet can then be used in subsequent application commands or retrieved using a Return Value Request command, described below.

When applying a calibration transfer model to data, the result is a modified version of the original DataSet object that can be used in a subsequent command (much like with preprocessing objects.)

A calibration model applied to data outputs a prediction object. Prediction objects are similar in content to a model, but contain results specific to the application results. It is most often the fields of this prediction object which a client will want to retrieve as the final result of a model application.

Requesting Return Values

The eventual goal of most scripts is to return one or more values to the client. A large number of different statistics, results, and information are available. These are all stored as properties of the objects in the client's workspace. The specific value or values an individual client will need to retrieve depends largely on the model being applied and the intended use of the model. Some typical requests will be discussed later.

A script can specify the values to return by sending a return request command. This command specifies an object's name followed by a period and the name of the property (also known as "field") to return.

 Obj.property

The specified object's property will be returned to the client when the script finishes. Properties may contain strings, single numeric values, numeric vectors, numeric arrays or complex objects. The format of the contents will be based on the Response Message Format described later in this section.

Note that the returned value will be the value of the object and property at the point in the script where the statement occurs. Changing or clearing the object or property after the request statement will not affect the returned value.

Retrieving Multiple Values

A given script can only return a single set of values. This can be from a single return request command or multiple "compatible" return request commands. Commands are compatible if the specified values can be concatenated horizontally into a row vector or matrix. To retrieve multiple compatible values, the script can simply include several return request commands within the body of the script (with terminating semicolons as is always necessary between commands.) For example:

Obj_A.property1;
Obj_A.property2;
Obj_B.property1;

If the commands refer to objects or data tables which cannot be combined in this manner (e.g. different number of rows or incompatible objects), Solo_Predictor will return a script error.

If multiple incompatible properties need to be retrieved by a script, multiple connections will need to be made to Solo_Predictor retrieving the desired properties one at a time. Remember that because objects are persistent from call to call, the objects created by one call to Solo_Predictor remain available for subsequent calls. See the Scripting Examples for an example of retrieving multiple values. Another option to retrieve multiple outputs is the Write to File command discussed later in this section.

Common Return Properties

Model and prediction objects can be queried for a description of the properties which are typically used in predictions from the given model type. Sending the command:

 Model_Obj.help.predictions

will return an XML description of properties of Model_Obj which the client program might want to make available to the user. This description is comprised of a single tag enclosing multiple tags, each containing the description of an available property in the model including the following tags:

• <label> contains a text description of the property's contents
• <field> contains the full property name which should be used to access the given value. Add the contents of this field onto the string name of the prediction or model object followed by a period: pred.field
• <dimension> contains a string describing the type of return value provided in this property for the prediction of a single sample. This will be "scalar" (single value), "vector", or "matrix" and can be used by the client to ignore return value types which it cannot manage. "vector" means a single row of numbers. "matrix" means a table of values.

For example, the following XML fragment describes two fields available from a PCA model:

<tr>
  <td>
    <label class="string">Scores</label>
    <field class="string">loads{1}</field>
    <dimension class="string">vector</dimension>
  </td>
  <td>
    <label class="string">Hotelling's T^2</label>
    <field class="string">tsqs{1}</field>
    <dimension class="string">scalar</dimension>
  </td>
</tr>

The first tag describes the Model_Obj.loads{1} property which contains Scores and will be returned as a vector. The second tag describes the Model_Obj.tsqs{1} property which contains the Hotelling's T^2 (T-squared) value which will be returned as a scalar (single value).

The client can use this list to populate a table (or other GUI) with outputs available from the predictions using a given model. Note that the help.predictions list is the same from a model object and any prediction objects made from it.

Because only model and prediction objects provide self-description of useful properties, the following the following tables, organized by object type, are provided to guide the user to some of the standard properties which clients may be interested in retrieving. Note that some properties may contain additional indexing information in either "curly" braces { } or in standard parenthesis ( ) and that this indexing must be included as shown.

Table 1. Commonly used properties for DataSet objects

Description / Content	Property
Numerical data	.data
Labels for the variables	.label{2}
Numerical axis scale for the variables	.axisscale{2}

Table 2. Commonly used properties for Prediction and Model objects

General Properties
Description / Content	Property	Notes
Model Type	.modeltype	String keyword describing the type of model
Author	.author	Model's author. Usually defined by user's login name and computer name.
Date Created	.date	Date only in text format (for time information, see Timestamp)
Time Stamp	.time	Date/Time as vector of numbers: [Year Month Day Hour Minute Second] (seconds includes fractional portion describing miliseconds) When combined with author, this is considered a unique identifier for the model.
# of X variables total	.datasource{1}.size(2)	Total number of x-variables (included and excluded)
# of X variables used	.datasource{1}.include_size(2)	Number of x-variables used by model
# of Y values	.datasource{2}.include_size(2)	Number of y-values being predicted by model
Preprocessing Step(s)	.detail.preprocessing{1}	An XML structure with all preprocessing information (can be very large)
Preprocessing Step Descriptions	model.detail.preprocessing{1}(n).description	String description of the n-th preprocessing step (returns error if n>number of preprocessing steps; it is safe to iterate until error)
Numeric Results
Description / Content	Property	Notes
Scores	.scores	The numeric scores of a model
Hotelling's T2	.t2	These values will generally be "reduced" so that a value of 1 is at the pre-defined confidence limit. See .detail.options.confidencelimit property to retrieve the confidence limit used for the reduced value.
Sum-squared residuals (Q)	.q	Q residuals (a.k.a. SPE) These values will generally be "reduced" so that a value of 1 is at the pre-defined confidence limit.
Y Predictions, Classes or Scores	.prediction	For regression models, this is the y prediction(s) (may be multiple columns). For Classification models, this is an array of strings indicating the class for which the sample(s) are "in class". For other models, this is typically the scores. See .predictionlabel below.
T-contributions	.tcon	The Hotelling's T-squared contributions.
Q-conributions	.qcon	The Q contributions (X-block residuals).
Labels, Axis Scales, and Include Flags
Description / Content	Property	Notes
Prediction Lables	.predictionlabel	A string array of labels corresponding to each column of .prediction (see above). This field will always match the size of the .prediction output no matter what the model type or data source.
Y value labels	.detail.label{2,2}	Labels for all columns of y (included and excluded). Note that this may include labels for columns which the model is not predicting. The .detail.includ{2,2} vector will indicate which of these label(s) are actually being predicted. String may be empty if no labels exist.
X-block axisscale	.detail.axisscale{2,1}	Vector of any axisscale (e.g. frequency, wavelength) expected for the X-block variables. Note that Solo_Predictor will usually automatically handle mismatches in the axisscale if you provide the measured axisscale in the input DataSet object.
X-block labels	.detail.label{2,1}	String array of any labels expected for the X-block variables. Note that Solo_Predictor will usually automatically handle missing or mis-ordered variables if you include the labels in the input DataSet object.
X-block included variables	.detail.includ{2,1}	Vector indicating which of the original X-block variables are actually used by the model (also see "# of X variables used" above)

Response Message Format

All results returned by Solo_Predictor are text-based but the exact format of the text can be selected to best match the client program's ability to parse text. The format is selected using a format command which consists of a colon followed by a format keyword. A format command can be located anywhere within your script, before or after a return request command. As always, each command must be separated from other commands by semicolons. The following are valid output formats:

:xml

Selects the XML format. This consists of three tags: result, error, date.

result : Contains any output produced by a "return value" command. The class of the returned value is given in the class attribute of this tag. Standard classes are "string" and "numeric" but other complex objects may be returned. Numeric values are given in comma- and semicolon-delimited format where commas delimit row-wise elements in vectors and arrays and semicolons delimit column-wise elements in vectors and arrays. For example, an array with two rows of 5 numbers would be returned as:

 1,2,3,4,5;6,7,8,9,10

In addition, the result tag will have a size attribute included with any string or numeric value. It will give the expected result's size in rows and columns. This can be used by the client to prepare an appropriately-sized matrix for the parsed result and for error checking on the parsed result.

error : Contains a text description of any errors which occurred during the script execution. If no errors occurred, the error tag will be empty.

date : Contains the date and time the request was received by the server.

In XML format, a response with no errors and no results will return as an XML structure with result and error tags empty. Date will contain the relevant date information as usual.

Example:

<response>
<result     class="numeric" size="[2,5]">
1,2,3,4,5;6,7,8,9,10
</result>
<error     class="string"/>
<date     class="string">Thu 06 Sep 2007 14:21:08</date>
</response>

:plain

Selects the plain-text format. If any errors occurred, this will be an error message starting with the text: "ERROR:" and will supersede any results.

When no errors occurred, the content of any return values will be given in a space- and linefeed-delimited format where spaces delimit row-wise elements in vectors and arrays and linefeeds delimit column-wise elements in vectors or arrays. For example, an array with two rows of 5 numbers would appear as:

1     2     3     4     5
6     7     8     9    10

Note that multiple spaces will almost always be used between row-wise elements.

In plain-text format, a response with no errors and no results will return as an empty (null) message.

:html

Selects an HTML-friendly format. This output is appropriate for display by any standard HTML-parser such as a web browser; All text is enclosed in preformatted text tags (<pre>). If any errors occurred, they will be displayed much like the plain format. Otherwise, the result will be included in an XML format (same as the result field in the xml format.)

If more than one format command is included in a script, only the last-encountered format command will be used.

The default format for the response is set by the default_format option. See the Installation and Configuration section for more information.

:json

Selects JavaScript Object Notation output format. This format is useful when the output needs to be parsed by a JavaScript application. Fields of DataSet objects will be returned as fields of a JavaScript object. Multi-row arrays will be returned as nested row-wise arrays. For example, an array with two rows of 5 numbers would appear as:

[[1,2,3,4,5],[6,7,8,9,10]]

Most objects (models, predictions) can NOT be encoded in JSON format and will be returned as a simple string saying:

"Unencodable Object"

In these cases, individual fields must be extracted before returning the value.

Write To File Command

Another method of returning results to a client is the write-to-file command. This command provides a simple way to create a specifically-named output file based on a user-created "template" file. This command is particularly useful when the client is unable to parse returned strings, when passing particularly complicated return values, or when Solo_Predictor is being used by legacy systems which expect a file response. See the example scripts section for an example of their use.

NOTE: By default, the writefilefolder option in the configuration file, default.xml, is blank. This disables the writefile command. This option must be configured before using the writefile command in any script.

The general format of the command is:

:writefile 'subpath/output.ext' 'path/template.tem' -append

When encountered in a script, this command specifies the output filename and extension (for example, 'subpath/output.ext', see note below regarding paths), the name of the template file ('path/template.tem', see note below regarding paths) and a flag indicating if the results should be appended to the end of the output file rather than replacing the file ("-append"). All values except the output filename are optional. If the -append flag is omitted, any existing output file is overwritten.

If the template filename is omitted, a template file named as the output file but with extension '.tem', for example, 'output.tem' is expected in the same folder as the output file. In this case, if this .tem file is not found then writing output will fail. Note that the only acceptable template file type is ".tem". Also, the output file suffix, '.ext' is typically .txt, or .csv, but is unrestricted

The paths on the output and template filenames are optional and but specified paths behave slightly differently between the two:

• output : any path on this filename will be appended to the writefilefolder path and must refer to a folder below the writefilefolder. It may not include any references to higher-level folders ( .. ). Thus, if no path is specified on this file, it will simply refer to the writefilefolder.
• template : if no path is included on this filename, it is assumed to be in the writefilefolder. Otherwise, it is assumed to be a fully qualified folder name and the writefilefolder is not prepended.

The template file is a user-created text file containing one or more lines of text which contain static text and replacement keys. Static text is written to the output file exactly as it appears in the template file (including linefeeds, spaces, tabs and all other text characters). Replacement keys consist of any return request command, described earlier, inside square brackets [ ]. When the output file is written, replacement keys are replaced with the value(s) indicated by the contained return request command. For example, consider the following template text, which expects a prediction object 'pred' and a 'conc' variable exist in the workspace:

1, "residuals", [pred.q]
2, "tsquared", [pred.t2]
3, "y-prediction [[conc]]", [pred.prediction]

This template would create an output file like:

1, "residuals", 0.3225352
2, "tsquared", 0.1212351
3, "y-prediction [conc]", 12.25252

Note the following:

• The <writefilefolder> option in the default.xml file configures the folder into which files can be written and template files may be read. If this option is set to empty (blank string), then no :writefile commands will be permitted.
• An optional formatting instruction can be included inside the replacement key brackets. This instruction consists of a simple fprintf instruction (%_._f) followed by a comma and the usual return request command. :For example:

[%i,pred.prediction]

The percent sign can be followed by optional precision indicators _._ but must be followed by a format character (usually i, f, g, or e). For more information on formatting commands see: SPRINTF Documentation] )

• When the return request command inside of a replacement key consists of more than one value, all values will be returned as comma separated list. To return in any other format, the template file must be hard-coded to access each value individually: [pred.prediction(1)] [pred.prediction(2)]
• To include square brackets as static text in a template, use double brackets [[ and ]].
• When using the -append mode, make certain to include any linefeed characters required. Without linefeed characters, each subsequent output will be appended to the same line.
• A common request is to have the :writefile command add a new row to the output file for each processed sample file. This can be accomplished by manually initializing the output file, for example output.txt, with any desired header text lines. Next, use the :writefile command with the "-append" flag and a template file specifying the desired fields to write out. It is important that the last line in the template file is a blank line as this inserts a newline character which is needed to have the output from successive processed files appear on separate lines in the output.txt file.

As an example, a template .tem file which contains the following two lines (second line is blank):

[pred.time]    [pred.prediction]    [pred.t2]    [pred.q]    [data.label{1}]    [data.date]

when used with :writefile and the '-append' flag will output something like the following it the output .txt file after three files have been processed, each files output written to its own line:

"Model_Date"             "Pred[mol%]"   "T2"    "Q"    "data_name"    "data_date"
2017,4,12,20,56,38.154    0.623374    6.68099    611.281    basil2_1_1317    2017,4,12,20,56,36.786
2017,4,12,20,56,38.664    0.59356    5.54621    521.627    basil2_2_1317    2017,4,12,20,56,38.494
2017,4,12,21,46,32.798    0.3965    0.387434    158.553    basil3_1_1302    2017,4,12,21,46,31.671

The first line of this output.txt file was inserted manually by the user before Solo_Predictor was started.

The quantity pred.time is the timestamp of the prediction being created, while data.date is the timestamp of the data being loaded into Solo_Predictor.

<DATE> Token

If the writefile command's output file 'subpath/output.ext' contains the special 6-character string '<DATE>' then it will be automatically modified so that '<DATE>' is replaced by today's date, for example '28-Aug-2017' in the output file. If this file or path does not exist then it will be automatically created and the output written to it. This feature is convenient if you want to organize the writefile output from Solo_Predictor into separate files or folders for each day. An example usage is:

':writefile 'projA/my<DATE>/output.txt' 'template.tem' -append'

If Solo_Predictor's default.xml configuration file specified writefilefolder = 'C:\tmp\', then this writefile would output to a file at 'C:\tmp\projA\my28-Aug-2017\output.txt' on August 28th, where the values written are controlled by 'C:\tmp\template.tem'. Output would be appended to this file until midnight when the new file 'C:\tmp\projA\my29-Aug-2017\output.txt' would begin accumulating the writefile output, and so on.

Export command

Any object can be exported to one of several filetypes using the command:

   :export 'output.ext' object

The extension on output filename 'output.ext' defines the filetype and must be one of the following:

.xml = XML encoding of the object

.mat = MAT file containing the object

.m = m-file encoding of the object (Matlab m-code which, when executed, will recreate the object)

.csv = CSV encoding of the object (only valid for dataset objects or numeric arrays)

.spc = SPC encoding of the object (only valid for dataset objects or numeric arrays)

.smat = SMAT file containing the object (only available if secureMAT file feature is installed)

Note: This command requires the writefilefolder configuration property be assigned.

Other Commands

Several other commands exist for various operations. Each consists of a colon followed by the command name and can generally be used anywhere within a script.

:include 'path/script.txt'

Include the contents of the specified file in the current script. The indicated text file (which can have any file name and extension but must include the full path to the file) will be executed by Solo_Predictor as if it had been passed explicitly in the current script.

This command permits a client to pass a simple :include command to invoke a possibly complicated script. The included script is always executed in the same workspace as the calling script and the calling script has access to any objects created by the included script.

:clear

Clears all objects from the client's workspace. An error will result if a script clears all objects from the workspace, then subsequently attempts to refer to a cleared object.

:list

Returns a list of the names of all objects in the client's workspace. This is generally only useful as the last instruction in a given script as subsequent return value requests will overwrite the output of this command.

Scripting Examples

The following sections show examples of basic scripts which might be used by a client calling into Solo_Predictor. To better understand how to connect to Solo_Predictor see the Solo_Predictor Socket Connection Examples. (For Solo_Predictor version 4.2, or earlier, see also: EigenvectorTools Programming Examples ).

Reading data and model from file and retrieve results

This example sets the output format to be a simple plain-text format, then reads data from an SPC-format file, reads a PLS model from a .mat file, and applies the model to the data. Finally, it returns the y-block predictions.

:plain;
data = 'C:/datacollector/datafolder/spectrum1.spc';
model = 'C:/modelfolder/mymodel.mat';
pred = data | model;
pred.prediction;

Recall that spaces and linefeeds are not necessary (only the semicolons are necessary) but they are included in the above script to help readability. The last line of the above script retrieves the y-block predictions from the applied model. In the case where the PLS model is predicting only one value (typical), the output string would be that single value. For example:

 14.23424

The application which made the call above would parse the result as a numerical value in order to use it.

Usually, two subsequent calls would then be used to retrieve the the T² and Q (sum squared residuals) values. First T²:

 :plain;
 pred.t2;

Note that the command starts with the :plain; instruction stating that the output should be in plain-text. Then the second call for the Q value:

:plain;
pred.q

Note that all three of these values could be retrieved in one call if the three "retrieve values" commands were all included in the first script:

:plain;
(other lines here)
pred.prediction;
pred.t2;
pred.q;

This would return a space-separated output of the three values. For example:

14.23423  0.852324  0.242445

Reading data from passed CSV

This example starts by pre-reading a PCA model (when the client first starts), then makes predictions using that model by passing directly to the server in a comma-separated values format. The Q contributions and Hotelling's T² contributions are then retrieved.

When the client starts, it sends the single-command script

model = 'C:/modelfolder/mymodel.mat';

This model will remain in memory as long as the server is running.

Next, the following script is executed each time the client is ready to make a prediction. It passes the seven values expected by the model and makes a prediction.

:plain;
data = '0,100,1242,2320,14,-50,232';
pred = data | model;

Because this script returns no outputs and uses the "plain" response format, the successful application of the model will be indicated by an empty message returned by Solo_Predictor. The client can easily test for any errors by checking for a non-empty return string from the server.

With a successful model application, the client can retrieve the Q contributions:

:plain; pred.qcon

Again, the script requests a "plain" response format so the Q contributions (which are a row-vector of numbers) are returned in a space-delimited format. Finally, another script is sent to retrieve the T² contributions:

:plain; pred.tcon

The comma-separated return values from this script can also be easily parsed by the client.

Reading data from passed XML

To modify the previous script to pass an XML data structure and include a series of labels with the data, the following script would be used for prediction calls:

:plain;
data = '<obj class="dataset">
<data class="numeric"> 0,100,1242,2320,14,-50,232</data>
  <label>
    <set>
      <mode>2</mode>
      <name>variable labels</name>
      <content>
        <sr>tempA</sr>
        <sr>Aspeed</sr>
        <sr>tempB</sr> 
        <sr>Bspeed</sr> 
        <sr>Rate</sr> 
        <sr>SetPoint</sr> 
        <sr>Time</sr> 
      </content>
    </set>
  </label>
</obj>';
pred = data | model;

For more information on the XML format, see DataSet_XML_Format.

Wait for file and output to results file

Wait for file provides a simple method to interface to programs which do not have the capability to send data through sockets. In this example, we will assume that a client program has been configured to save data files (in .xy format) to a specified "drop folder". Solo_Predictor will monitor this folder and, when a new file appears, it will load the data into an object named "data" (this name is not configurable) and execute an analysis script we will call "analyze.scr" (this name and file extension are also configurable. You could use "myanalyze.txt" instead of "analyze.scr", for example).

For this mode, the following options must be configured:

waitforfile must be "on"

waitfolder must give the full path to the drop folder ("c:/df" in this example)

waitfilespec must be defined as "*.xy" (to ignore all other file types in the folder.)

waitscript must point to the "analyze.scr" (or whatever you named it) with the entire path to the file.

The analyze.scr will contain the steps we want to use to analyze the results, and it will contain the instructions to write the results out to a results file.

analyze.scr

modl = 'C:/path/to/file/mymodel.mat';
pred = data | modl;
:writefile 'proj1/results.txt' 'c:/df/template.tem'

The first line loads the model from a .mat file located on a network drive. The second line applies the model to the data loaded from the dropped file. The final line writes the results out to a file named "results.txt" in a folder named "proj1" (which must already exist) in the "writefilefolder". The template file would be defined to output any of the results needed from this application. For an example, see the :writefile definition in the Script Construction section.

Alternatively, the last command could instead be an :export command to write a simple CSV-style format (for example):

modl = 'C:/path/to/file/mymodel.mat';
pred = data | modl;
results = pred.prediction;
results = results|pred.T2;
results = results|pred.Q;
:export 'results.csv' results