Model Exporter Interpreter and EVRIModel Objects: Difference between pages

From Eigenvector Research Documentation Wiki
(Difference between pages)
Jump to navigation Jump to search
imported>Jeremy
No edit summary
 
imported>Jeremy
 
Line 1: Line 1:
The Model_Exporter Interpreter implements several classes which can be used in Microsoft .NET environments to apply Model_Exporter models to new data. The following describes the classes implemented and their use. The classes include the ModelInterpreter, Workspace, and Matrix classes. The source code for these classes is supplied and can be used, compiled, and redistributed without restriction. Note that such redistribution permission does '''not''' permit the user to redistribute the Model_Exporter product itself - only the interpreter.
==Introduction==


__TOC__
EVRIModel Objects provide access to the [[Standard Model Structure]] content of all models and provide some easy-to-use methods and properties for building, manipulating, and reviewing models from Matlab's command line, scripts, and functions. In addition, these properties and methods are available from [[Solo_Predictor_Script_Construction|Solo Scripting]] when using [[Solo_Predictor_User_Guide|Solo_Predictor]] and Solo_Server. This page describes the various modes, methods, and properties of EVRIModel objects, here shortened to just "model objects".


==ModelInterpreter Class==
Model objects have three distinct states:


The primary class in the Model_Exporter C# Interpreter is a '''ModelInterpreter''' object. The object's interface implements the ability to assign input data, specify a model to interpret and apply, and retrieve results from the application. Input data and results are all stored using the Matrix class described below.
# '''Empty Models''' - Empty models can be populated with data to analyze, "meta parameters" (model building settings), and other modeling options, then models can be calibrated or built from those settings.
# '''Calibrated Models''' - Calibrated models contain all the model results and parameters necessary to apply that model to new data. Plots and other information can be obtained from calibrated models.
# '''Applied Models''' - When a calibrated model is applied to new data, the result is a prediction or "applied model". This object contains all the results from applying the model to the new data. Plots and other information can be obtained from applied models.


===Constructors===
==Working with Model Objects in Matlab and Solo Scripting==


{| border="1" cellpadding="5" cellspacing="0" align="left"
EVRIModels are standard Matlab objects which are manipulated using the dot notation to access properties and methods. For example, to retrieve the "model type" (modeltype) property from a model, you give the object (a.k.a. variable) name followed by .modeltype. All examples here will assume that the model is stored in a variable named "model".
|-
 
|valign="top" |
<pre>model.modeltype</pre>
<tt>ModelInterpreter(String filename)</tt>  
 
| This form of the constructor method allows passing a filename of a Model_Exporter XML file which should be read and parsed for application.
Most object methods can be accessed in the same way:
 
<pre>model.plotscores</pre>
 
Some methods (<tt>.apply</tt> and <tt>.crossvalidate</tt>, for example) also require for additional inputs. These are passed in parenthesis after naming the method:
 
<pre>model.apply(newdata)</pre>
 
===Displaying Contents===
 
At the Matlab command line (but not in Solo Scripting), you can view the contents of a model object by simply typing its name or by using the <tt>.disp</tt> method. When viewing content, there are several ways to view the model:
# By Description (Desc.) : this view shows you a text description of the type of model, how it was built, and a summary of its results.
# By Contents : this view contains the raw field information from the model. Users of previous versions of PLS_Toolbox will recognize this as the previous standard display.
 
At the Matlab command window, you can turn either one of these sections on or off by clicking the [on] or [off] hyperlinks in the top display line (shown in blue below)
 
<tt>  PCA Model Object (Desc. ON/<font color="#0000ee"><u>[off]</u></font>  Contents ON/<font color="#0000ee"><u>[off]</u></font>)</tt>
 
 
==Building from Empty Model Objects==
 
When a model object has been initially created, it contains no data and no results. Many model objects' properties can then be populated with data, meta-parameters, and other settings (options) which can then be used with the <tt>.calibrate</tt> method to build a calibrated model. The <tt>.inputs</tt> property lists the specific properties that can be set for a given model type.
 
:'''NOTE:''' Some model types do NOT support calibration in this manner. In these cases, the <tt>.cancalibrate</tt> property to determine if it allows calibration directly or if it requires a call to the function named in ''modeltype''. In addition, the model will clearly show the state in its display at the command line with a statement to "See _____ function to calibrate." In these cases, the only way to create a calibrated model is to access the named function directly.
 
===Properties===
 
The properties of an uncalibrated model depend on the model type. Typically, a value can be provided for the data to model, plus some number of "meta-parameters" which define aspects of how the model will be built. The list of values available is indicated by the .inputs property.
 
{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em" |-
|-
|-
|valign="top" |
|valign="top" |
<tt>ModelInterpreter(XmlDocument xdoc)</tt>  
<tt>.inputs</tt>
| This form of the constructor method allows passing a XmlDocument object which contains the contents of a Model_Exporter XML file. This method may be preferred when the content of an exported model has been previously read and stored in another location like a database. In such cases, the alternative ways to create XmlDocuments (see the XmlDocument documentation) which can be used to pass the parsed XML contents directly to the ModelInterpreter class.
| Returns a cell array of strings indicating which properties can be set for the model in its current state. Most often this is used when a model is in an uncalibrated state and this property will indicate what parameters and data fields are available to the user to assign before calibrating the model.
|}
|}
&nbsp;


===Methods===
===Methods===


{| border="1" cellpadding="5" cellspacing="0"
Both of the methods below return a model object. In Matlab, when no output is requested, the model object is stored back into the same object invoked. In Solo Scripting, these methods require an output variable, usually the same model object being built from. For example: <tt>m = m.calibrate</tt>
 
{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em" |-
|-
|valign="top" |
<tt>.calibrate</tt>
| Build the model based on the current meta-parameters and options.
|-
|-
|valign="top" |
|valign="top" |
<tt>apply()</tt>  
<tt>.crossvalidate(''cvi'',''ncomp'')</tt>
| Applies the model to the ''inputdata'' and stores results in the ''results'' property. This method has no return value itself. An error is thrown if ''inputdata'' has not already been assigned.
| Build the model and cross-validate with the supplied conditions. ''cvi'' is the cross-validation splitting as described for cvi in [[crossval]] (default = venetian blinds with square-root of the number of samples as splits). ''ncomp'' is the number of components (default = maximum number available).
|}
|}
&nbsp;
==Working With Calibrated Models==
Once calibrated, a model object contains all the results (relevant to the model type) derived from the modeled data. The object also has all the information necessary to apply that model to new data. For many models, methods exist for plotting parts of the model (scores, loadings, eigenvalues, etc.)


===Properties===
===Properties===


{| border="1" cellpadding="5" cellspacing="0"
The following properties are available for most models once they have been calibrated.
 
{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em"
|-
|valign="top" |
<tt>datasource</tt>
|
|-
|valign="top" |
<tt>date</tt>
|
 
|-
|valign="top" |
<tt>detail</tt>
|
|-
|-
|valign="top" colspan="2"|
|valign="top" |
'''Read-Only Properties'''
<tt>loadings</tt>
|
|-
|valign="top" |
<tt>ncomp</tt>
|
|-
|valign="top" |
<tt>parent</tt>
|
|-
|valign="top" |
<tt>prediction</tt>
|
|-
|valign="top" |
<tt>q</tt>
|
|-
|valign="top" |
<tt>scores</tt>
|
|-
|valign="top" |
<tt>t2</tt>
|
|-
|-
|valign="top" |
|valign="top" |
<tt>inputDataSize</tt>
<tt>time</tt>
| (Int32) The number of columns expected for the inputdata matrix.
|
|-
|-
|valign="top" |
|valign="top" |
<tt>modeltype</tt>        
<tt>x</tt>
| (String) The model type of the model. One of the supported model types such as: "PCA" "PLS" "PCR" "CLS" or "PLSDA" (or other supported model types) This often helps identify what variables are of interest in the ''results'' workspace after application of the model.
|
|-
|-
|valign="top" |
|valign="top" |
<tt>information</tt>        
<tt>x</tt>
| (XmlDocument) The raw, unparsed XML contained in the information section of the model. This may be of interest to help identify where the model came from, what the model is predicting, how many outputs to expect, etc. See the exported model's &lt;information&gt; tag for details included.
|
|-
|-
|valign="top" |
|valign="top" |
<tt>results</tt>        
<tt>xhat</tt>
| (Workspace) The workspace object that contains all the results after applying the model. This contains all the variables (see Workspace class below) that were used during model application as well as the variables which hold the results of interest such as ''yhat'', ''T2'', or ''Q''.
|
|-
|-
|valign="top" colspan="2"|
|valign="top" |
'''Read/Write Properties'''
<tt>y</tt>
|
|-
|-
|valign="top" |
|valign="top" |
<tt>inputdata</tt>
<tt>yhat</tt>
| (Matrix) Specifies the data to which the model should be applied. Type is ''Matrix'' as defined using the Matrix class described below. This field is not modified by applying the model. Assigning a new value this field erases the results from a previous model application.
|
|}
|}


===Examples===
:&nbsp;
 
===Methods===


The following C# example shows use of the ModelInterpreter class along with the Matrix and Workspace classes (described below). It start by creating a new ModelInterpreter object loading the model contained in plsexample.xml. It then creates a Matrix object with a vector of value from 1 to the number of variables expected by the model, stores this matrix in the inputdata, and applies the model. Finally, it retrieves the results from that model by listing ALL workspace contents. Alternatively, the commented-out code shows how the typical PLS (or other regression model) results would be retrieved specifically.
The following methods are available when a model has been calibrated.


  ModelInterpreter test = new ModelInterpreter("plsexample.xml");
  //display some of the common model information
  Console.WriteLine("Model type: " + test.modeltype);
  Console.WriteLine("Expected Data Size:" + test.inputDataSize);
  //create data to pass to the model
  Matrix inmatrix = new Matrix(1, test.inputDataSize);
  for (int i = 0; i < inmatrix.NoCols; i++) { inmatrix[0, i] = i + 1; };
  test.inputdata = inmatrix;
  //set data and apply model         
  test.inputdata = inmatrix;    //assign input data to object
  test.apply();  //apply model
  //Typical outputs for a PLS or other regression model:
  //Console.WriteLine("yhat = " + test.results.getVar("yhat"));
  //Console.WriteLine("T2 = " + test.results.getVar("T2"));
  //Console.WriteLine("Q = " + test.results.getVar("Q"));
               
  //List ALL contents of workspace     
  foreach (String name in test.results.varList)
  {
    Console.WriteLine(name + " = \n" + test.results.getVar(name));
  }


{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em"
|-
|valign="top" |
<tt>.apply()</tt>       
||
|-
|valign="top" |
<tt>.crossvalidate()</tt>       
||
|-
|valign="top" |
<tt>.ploteigen</tt>   
||
|-
|valign="top" |
<tt>.plotloads</tt>   
||
|-
|valign="top" |
<tt>.plotscores</tt>   
|| We will populate this table once we've got the others done.
|}


==Workspace Class==
:&nbsp;


The Workspace class serves as a way to store any number of matrices (Matrix objects) each associated with a name. These names and their corresponding matrix are referred to as a "variable". A variable is stored in the workspace using the setVar() method and retrieved using the getVar() method.


Note that although variables names can contain upper- and lower-case characters, the case is ignored when retrieving. Thus, a variable set using the name "Pred" can be set or retrieved using "Pred", "pred", or any other combination of upper- and lower-case. Since these two would be considered the same variable, you cannot set two different variables which are identical except for the case of the variable name.
==General Model Properties and Methods==


===Constructors===
The following properties and methods are always available in a model independent of the model state or model type:


{| border="1" cellpadding="5" cellspacing="0"
===Informational Properties (Read-Only)===
{| border="1" cellpadding="5" cellspacing="0" align="left"  style="margin-left:3em"  |-
|valign="top" |
<tt>.author</tt>
| String describing the author and computer on which this model was created. Usually ''user@computername''. Given a system with assigned usernames and computer names, this is equivalent to an electronic signature on a model.
|-
|-
|valign="top" |
|valign="top" |
<tt>Workspace()</tt>  
<tt>.content</tt>
|Creates an instance of the Workspace class.
| Returns the "raw" model information in a form that is most similar to the model structures from previous versions of PLS_Toolbox and Solo. Generally, users need not access this field directly except to provide a model in a form more similar to old models.
 
|}
 
===Methods===
 
The following methods are defined for the Workspace class. These are the primary means for assigning and retrieving values from a Workspace.
 
{| border="1" cellpadding="5" cellspacing="0"
|-
|-
|valign="top" |
|valign="top" |
<tt>setVar(String name, Matrix value)</tt>  
<tt>.downgradeinfo</tt>
|Sets the variable specified by ''name'' with the matrix ''value''. If ''name'' already exists in the workspace, the previous value is overwritten without any warning. This method returns nothing. ''void setVar(String name, Matrix value)''
| Informational string explaining the purpose of the <tt>.content</tt> field.
|-
|-
|valign="top" |
|valign="top" |
<tt>setVar(Workspace toadd)</tt>  
<tt>.evrimodelversion</tt><br>
|Copies all variables in the ''toadd'' workspace into the workspace being addressed by the method. Any variables in the current workspace which have the same name as a variable in the ''toadd'' workspace are overwritten without warning. This method returns nothing. ''void setVar(Workspace toadd)''
<tt>.modelversion</tt>
| Returns a string containing the model version description. The model version is almost always linked to the version of PLS_Toolbox or Solo that created the given model. The two field names here are synonymous.
|-
|-
|valign="top" |
|valign="top" |
<tt>getVar(String name)</tt>  
<tt>.info</tt>
|(Matrix) Retrieves the specified variable ''name'' from the workspace. Returned value is a Matrix object. ''Matrix getVar(String name)''
| Returns (or displays with no outputs) the text description of the model. This is the same description shown at the Matlab command line when the model is viewed with content "on". With an output, the results are returned as a cell array of strings.
|-
|-
|valign="top" |
|valign="top" |
<tt>isSet(String name)</tt>  
<tt>.uniqueid</tt>
|(Boolean) Returns boolean ''TRUE'' if the given variable ''name'' is currently set in the workspace. ''Boolean isSet(String name)''   
| Returns a string which uniquely identifies this model including the author, author's computer, and a date/time stamp. This uniqueid can be used to safely discriminate between different models.
|-
|-
|valign="top" |
|valign="top" |
<tt>clearAll()</tt>  
<tt>.validmodeltypes</tt>
|Clears all values from the workspace. This method returns nothing. ''void clearAll()'' 
| Returns a cell array of strings listing the model types which are currently valid for assignment to the <tt>.modeltype</tt> field.
|}
|}


===Properties===
&nbsp;


{| border="1" cellpadding="5" cellspacing="0"
===Model Status Properties (Read-Only)===
{| border="1" cellpadding="5" cellspacing="0" align="left"  style="margin-left:3em" |-
|valign="top" |
<tt>.cancalibrate</tt>
| Returns (1) if the model contains a modeling building definition (see Empty Model description, below), or (0) if the model does not contain a definition and must be calibrated using the function defined in the modeltype property.
|-
|-
|valign="top" |
|valign="top" |
<tt>varList</tt>  
<tt>.iscalibrated</tt>
|(List<String>) Returns the alphabetically sorted list of names for all variables currently set in the Workspace as a List<String> type. These names can be used with the getVar method to retrieve the values.
| Returns (1) if the model has been calibrated or applied and (0) if the model is in the "empty" state and has not been calibrated.
|-
|valign="top" |
<tt>.isclassification</tt>
| Returns (1) if the model is a classification model that returns class assignments for unknowns or (0) if it is a decomposition or regression model type
|-
|valign="top" |
<tt>.isprediction</tt>
| Returns (1) if the model contains a prediction from applying a calibrated model to new data and (0) if the model is just "calibrated" or "empty".
|}
|}


&nbsp;


===Examples===
===Modifiable Properties===
 
{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em" |-
The following example creates a new empty Workspace called "ws", a new Matrix (in this case, a vector with 1 row and 5 columns) called "myvalue", then stores myvalue into ws under the variable named "x". It then looks
|-
 
|valign="top" |
  Workspace ws = New Workspace();    //create new workspace
<tt>.modeltype</tt>
  Matrix myvalue = New Matrix(1,5);  //create all-zeros matrix "myvalue" as exmple
| Returns the short "keyword" model type of the current model (or empty if the model type has not been set). This keyword most often is linked to the PLS_Toolbox function that created the given model. Can be assigned (within the limits defined by the <tt>.validmodeltypes</tt> property)
  ws.setVar("x",myvalue);            //assign variable "x" the value myvalue in workspace
 
Example of retrieving a variable from a workspace "ws"
 
  if (ws.isSet("y"))                //is the variable "y" assigned?
  {
    retrieved = ws.getVar("y");      //get value assigned in y
  }
  else
  {
    retrieved = New Matrix(0,0);    //no "y" was set? use empty matrix instead
  }
 
==Matrix Class==
 
The Matrix class is defined through a public-domain class implemented in the cMatrixLib. This class allows storing and retrieval of data in a simple two-dimensional matrix as well as performing various matrix calculations on that data. For the purposes of the Model_Exporter Interpreter, the main use is to provide a convenient method to exchange data between the client and the interpreter. Thus, the details of the class are not given here, but only the main creation and access information. This class is used for the ''inputdata'' property and the variables stored in the ''results'' Workspace of the '''ModelInterpreter'''.
 
===Constructors===
 
Constructor for a new Matrix object is by either specifying the size (in rows and columns) for the new Matrix, or by passing an array of Double to the constructor:
 
{| border="1" cellpadding="5" cellspacing="0"
|-
|-
|valign="top" |
|valign="top" |
<tt>Matrix(int rows, int columns)</tt>  
<tt>.display</tt>
|Create a Matrix with the specified number of rows and columns. Matrix is initialized to all zeros. Note that rows = 0 and columns = 0 can be used to create an "empty" matrix. <tt>Matrix mymatrix = new Matrix(int rows, int columns)</tt>
| String property indicating 'on' if command-line display should be given when calibrating or applying a model and 'off' if no display should be given.
* ''''on'''' : Display command-line output
* ''''off'''' : Do not display any output
|-
|-
|valign="top" |
|valign="top" |
<tt>Matrix(Double[,] data)</tt>  
<tt>.plots</tt>
|Create a Matrix from the Double array ''data'' using the sizes of that array. <tt>Matrix mymatrix = new Matrix(Double[,] data)</tt>
| String property indicating 'final' if plots should be displayed after calibrating or applying a model and 'none' if no plots should be displayed.
* ''''final'''' : Generate plots (if possible)
* ''''none'''' : Do not generate any plots
|}
|}


===Methods===
&nbsp;
Changing and accessing values in a matrix can be accomplished using standard (zero-based) indexing.
===General Methods===
 
{| border="1" cellpadding="5" cellspacing="0" align="left" style="margin-left:3em" |-
  mymatrix[0,0] = value;  //replace element 0,0 with specified Double "value"
  value = mymatrix[0,0];   //retrieve value at element 0,0
 
===Properties===
To determine the size of a given matrix, use the ''NoRows'' and ''NoCols'' properties:
 
{| border="1" cellpadding="5" cellspacing="0"
|-
|-
|valign="top" |
|valign="top" |
<tt>NoRows</tt>  
<tt>.disp</tt>
|(int) Returns the total number of rows the matrix object is currently dimensioned to contain.
| Displays the contents of the model. There is no output variable from this method, it only displays the information. For access to the content, see the <tt>.info</tt> method.
|-
|-
|valign="top" |
|valign="top" |
<tt>NoCols</tt>  
<tt>.help</tt>
|(int) Returns the total number of columns the matrix object is currently dimensioned to contain.
| Alone without any additional sub-indexing, this method brings up the help which is most relevant for the particular model type. With the <tt>.predictions</tt> sub-field, this method returns [[Solo_Predictor_Script_Construction#Common_Return_Properties|a structure array of possible sub-fields]] that may be requested for certain properties of the current model.
|}
|}


===Examples===


Below are some general examples of using the constructors, methods, and properties specified above. Other methods exist which are not indicated in this documentation. See also the examples given for the Workspace class above.
&nbsp;
==Alphabetical List of General Properties and Methods==


Create a matrix and populate it with some numbers:
===Properties===


   Matrix mat = New Matrix(3,5);
<pre>
   For (int row=0; row<3; row++)
author       
   {
cancalibrate    
     For (int col=0; col<5; col++)
content       
    {
datasource   
       mat[row,col] = row*10 + col;  //assigns values to indicated row/column
date         
     }
detail       
  }
display       
downgradeinfo 
evrimodelversion
info         
iscalibrated    
isclassification
isprediction    
loadings     
modeltype     
ncomp         
parent       
plots         
prediction      
q             
scores       
settings     
t2           
time         
uniqueid        
validmodeltypes
x             
xhat         
y             
yhat      
</pre>


Retrieve value from row 2 column 4:
===Methods===
 
  Double value = mat[1,3];    //remember this is zero indexed
 
Display all elements of the first row of a matrix on the console:


  int ncols = mat.NoCols;
<pre>
  For (int col=0; col<ncols; col++) Console.Write(mat[0,col] + "  ");
apply         
calibrate     
crossvalidate 
help         
ploteigen     
plotloads     
plotscores   
</pre>

Revision as of 03:59, 10 September 2012

Introduction

EVRIModel Objects provide access to the Standard Model Structure content of all models and provide some easy-to-use methods and properties for building, manipulating, and reviewing models from Matlab's command line, scripts, and functions. In addition, these properties and methods are available from Solo Scripting when using Solo_Predictor and Solo_Server. This page describes the various modes, methods, and properties of EVRIModel objects, here shortened to just "model objects".

Model objects have three distinct states:

  1. Empty Models - Empty models can be populated with data to analyze, "meta parameters" (model building settings), and other modeling options, then models can be calibrated or built from those settings.
  2. Calibrated Models - Calibrated models contain all the model results and parameters necessary to apply that model to new data. Plots and other information can be obtained from calibrated models.
  3. Applied Models - When a calibrated model is applied to new data, the result is a prediction or "applied model". This object contains all the results from applying the model to the new data. Plots and other information can be obtained from applied models.

Working with Model Objects in Matlab and Solo Scripting

EVRIModels are standard Matlab objects which are manipulated using the dot notation to access properties and methods. For example, to retrieve the "model type" (modeltype) property from a model, you give the object (a.k.a. variable) name followed by .modeltype. All examples here will assume that the model is stored in a variable named "model".

model.modeltype

Most object methods can be accessed in the same way:

model.plotscores

Some methods (.apply and .crossvalidate, for example) also require for additional inputs. These are passed in parenthesis after naming the method:

model.apply(newdata)

Displaying Contents

At the Matlab command line (but not in Solo Scripting), you can view the contents of a model object by simply typing its name or by using the .disp method. When viewing content, there are several ways to view the model:

  1. By Description (Desc.) : this view shows you a text description of the type of model, how it was built, and a summary of its results.
  2. By Contents : this view contains the raw field information from the model. Users of previous versions of PLS_Toolbox will recognize this as the previous standard display.

At the Matlab command window, you can turn either one of these sections on or off by clicking the [on] or [off] hyperlinks in the top display line (shown in blue below)

PCA Model Object (Desc. ON/[off] Contents ON/[off])


Building from Empty Model Objects

When a model object has been initially created, it contains no data and no results. Many model objects' properties can then be populated with data, meta-parameters, and other settings (options) which can then be used with the .calibrate method to build a calibrated model. The .inputs property lists the specific properties that can be set for a given model type.

NOTE: Some model types do NOT support calibration in this manner. In these cases, the .cancalibrate property to determine if it allows calibration directly or if it requires a call to the function named in modeltype. In addition, the model will clearly show the state in its display at the command line with a statement to "See _____ function to calibrate." In these cases, the only way to create a calibrated model is to access the named function directly.

Properties

The properties of an uncalibrated model depend on the model type. Typically, a value can be provided for the data to model, plus some number of "meta-parameters" which define aspects of how the model will be built. The list of values available is indicated by the .inputs property.

.inputs

Returns a cell array of strings indicating which properties can be set for the model in its current state. Most often this is used when a model is in an uncalibrated state and this property will indicate what parameters and data fields are available to the user to assign before calibrating the model.

 

Methods

Both of the methods below return a model object. In Matlab, when no output is requested, the model object is stored back into the same object invoked. In Solo Scripting, these methods require an output variable, usually the same model object being built from. For example: m = m.calibrate

.calibrate

Build the model based on the current meta-parameters and options.

.crossvalidate(cvi,ncomp)

Build the model and cross-validate with the supplied conditions. cvi is the cross-validation splitting as described for cvi in crossval (default = venetian blinds with square-root of the number of samples as splits). ncomp is the number of components (default = maximum number available).

 

Working With Calibrated Models

Once calibrated, a model object contains all the results (relevant to the model type) derived from the modeled data. The object also has all the information necessary to apply that model to new data. For many models, methods exist for plotting parts of the model (scores, loadings, eigenvalues, etc.)

Properties

The following properties are available for most models once they have been calibrated.

datasource

date

detail

loadings

ncomp

parent

prediction

q

scores

t2

time

x

x

xhat

y

yhat

 

Methods

The following methods are available when a model has been calibrated.


.apply()

.crossvalidate()

.ploteigen

.plotloads

.plotscores

We will populate this table once we've got the others done.
 


General Model Properties and Methods

The following properties and methods are always available in a model independent of the model state or model type:

Informational Properties (Read-Only)

.author

String describing the author and computer on which this model was created. Usually user@computername. Given a system with assigned usernames and computer names, this is equivalent to an electronic signature on a model.

.content

Returns the "raw" model information in a form that is most similar to the model structures from previous versions of PLS_Toolbox and Solo. Generally, users need not access this field directly except to provide a model in a form more similar to old models.

.downgradeinfo

Informational string explaining the purpose of the .content field.

.evrimodelversion
.modelversion

Returns a string containing the model version description. The model version is almost always linked to the version of PLS_Toolbox or Solo that created the given model. The two field names here are synonymous.

.info

Returns (or displays with no outputs) the text description of the model. This is the same description shown at the Matlab command line when the model is viewed with content "on". With an output, the results are returned as a cell array of strings.

.uniqueid

Returns a string which uniquely identifies this model including the author, author's computer, and a date/time stamp. This uniqueid can be used to safely discriminate between different models.

.validmodeltypes

Returns a cell array of strings listing the model types which are currently valid for assignment to the .modeltype field.

 

Model Status Properties (Read-Only)

.cancalibrate

Returns (1) if the model contains a modeling building definition (see Empty Model description, below), or (0) if the model does not contain a definition and must be calibrated using the function defined in the modeltype property.

.iscalibrated

Returns (1) if the model has been calibrated or applied and (0) if the model is in the "empty" state and has not been calibrated.

.isclassification

Returns (1) if the model is a classification model that returns class assignments for unknowns or (0) if it is a decomposition or regression model type

.isprediction

Returns (1) if the model contains a prediction from applying a calibrated model to new data and (0) if the model is just "calibrated" or "empty".

 

Modifiable Properties

.modeltype

Returns the short "keyword" model type of the current model (or empty if the model type has not been set). This keyword most often is linked to the PLS_Toolbox function that created the given model. Can be assigned (within the limits defined by the .validmodeltypes property)

.display

String property indicating 'on' if command-line display should be given when calibrating or applying a model and 'off' if no display should be given.
  • 'on' : Display command-line output
  • 'off' : Do not display any output

.plots

String property indicating 'final' if plots should be displayed after calibrating or applying a model and 'none' if no plots should be displayed.
  • 'final' : Generate plots (if possible)
  • 'none' : Do not generate any plots

 

General Methods

.disp

Displays the contents of the model. There is no output variable from this method, it only displays the information. For access to the content, see the .info method.

.help

Alone without any additional sub-indexing, this method brings up the help which is most relevant for the particular model type. With the .predictions sub-field, this method returns a structure array of possible sub-fields that may be requested for certain properties of the current model.


 

Alphabetical List of General Properties and Methods

Properties

author         
cancalibrate   
content        
datasource     
date           
detail         
display        
downgradeinfo  
evrimodelversion
info           
iscalibrated   
isclassification
isprediction   
loadings       
modeltype      
ncomp          
parent         
plots          
prediction     
q              
scores         
settings       
t2             
time           
uniqueid       
validmodeltypes
x              
xhat           
y              
yhat     

Methods

apply          
calibrate      
crossvalidate  
help           
ploteigen      
plotloads      
plotscores