EVRIModel Objects

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])

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

 

Building Model from Empty Model Object

When an EVRIModel object has been initially created, it contains no data and no results. Many model objects 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.

• Note the .inputs property

NOTE: Some model types do NOT support calibration in this manner. In these cases, 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. A model can be interrogated with the .cancalibrate property to determine if it allows calibration directly or if it requires a call to the function named in modeltype.

calibrate crossvalidate

Properties

blabla datasource date detail loadings ncomp parent prediction q scores t2 time x xhat y yhat

We need to define all these properties and make sure they are clear what they do.

 

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

Describe how to use them

Properties

blabla datasource date detail loadings ncomp parent prediction q scores t2 time x xhat y yhat

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

 

Methods

blalba apply ploteigen plotloads plotscores

blabla

 

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