Modelselector

Purpose

Create or apply a Model Selector model.

Synopsis

model = modelselector(triggermodel,target_1,target_2,...,target_default);

[target_model,applymodel] = modelselector(data,model)

modelselector % Launches the modelselector tool

Please note that the recommended way to build a Model Selector model from the command line is to use the Model Object. Please see this wiki page on building models using the Model Object.

Description

A Model Selector Model is a special model type which, when applied to new data, selects between two or more "target" models or outputs (a.k.a. end-point nodes) based on a "trigger" model (a.k.a. rule or decision node). These models are used to implement discrete local models when a single global model is not sufficient for all possible scenarios.

For example, if a single PCA or PLS model does not perform sufficiently for all operating conditions but the operating conditions can be split into two or more easier-to-model subsets, a selector model can be used to choose between these subset models when applying the models to new data.

Selector models consist of a trigger model (trigger) which can be a classification model or a set of one or more logical test strings to test the raw data or output of a regression or decomposition model and a set of two or more target models (target_1, target_2, etc) which can be any type of standard model structure, any standard object, or an empty array [ ] to indicate a null model.

Model Selector models can also be created using the graphical Hierarchical Model Builder interface.

Trigger Models

Trigger models define the decision/rule nodes. Guidelines and rules for trigger models:

• (A) A classification trigger model can be created using the standard classification modeling functions (PLSDA, KNN, SIMCA, SVMDA.) The model should be built with data representative of the sample types to which each target model can be applied. The number of classes separated by the model dictates the number of target models which can be selected from. The target models should be in the same order as the numerical class numbers used when building the model (e.g. if classes 1, 2 and 3 are used in PLSDA, the target models should be ordered so that target_1 is appropriate if the PLSDA model finds that a sample is class 1, target_2 is for class 2, and target_3 is for class 3.) A special case for PLSDA is that an "otherwise" model can be included which will be selected if the Q and T^2 values of the prediction are not within the limits specified by the qtestlimit and t2testlimit options.

• (B) Logical test strings are specified as a trigger model by passing a cell containing one or more strings which perform a logical test on a variable from the data set. Variables are specified using either a label in double quotes (e.g. "flowrate"), or a axisscale value in quotes and square brackets (e.g. "[1530]"). The varaible can be used in any interpretable Matlab expression (including function calls) that returns a logical result. The simplest test could involve one of the Matlab logical comparison operators ( < > <= >= == and \~= ) and a value to which the given variable should be compared. For example, the target model:

{'"Fe">1100' '"Fe"<500'}

tests if the variable named "Fe" is greater than 1100. If true, the target_1 model is applied, if not true, "Fe" is tested for being less than 500, and if so, target_2 is selected. If neither test is true, the "default" target model (i.e. target_3) is selected.

Example 2:

{'"[1745.3]"<=500'}

tests if variable 1745.3 (on the variable axiscale) is less than or equal to 500. If true, target_1 is selected, if not true, default target model is selected. If variable 1745.3 does not exist, it is interpolated from the provided data.

• (C) Logical test strings to be applied to the prediction from a simple regression (e.g. PLS, MLR, etc) or decomposition (e.g. PCA) model. When passed in this format, the first item in the cell array is a model to be applied to the data followed by a sequence of one or more logical tests to be performed on the predictions from the model application. The format of the logical tests is the same as in case (B) above EXCEPT any axisscale reference will be used to index into either the predicted values (for regression models) or the scores (for a decomposition model). For example, a test string of '"[2]">0.3' for a PLS trigger model would indicate that the second predicted y-value should be tested for being > 0.3. The tests will be performed on the predictions from the model.

Example 1:

{ regmodel '"[1]"<10' '"[1]"<100' }

applies "regmodel" to the data then tests the predicted values against the tests <10 and <100 for a total of three classes. If the predicted value is <10, the first target model is selected. If it is <100, the second target model is selected. Otherwise, the third (default) model is selected. Note that this method can not generally be used on classification models. Instead, the (A) form of trigger models should be used.

Normally, the "label" form of the test strings is not valid for prediction and decomposition trigger models. However, two special cases are "Q" and "T2" which, if used in a test string, will test the Q and Hotelling's T^2 values output by the model. Note that, if the model type does not have Q or T^2 values (SVM model, for example) a test including Q or T2 will throw an error.

Target Models and Objects

Target models and objects define end-point nodes for each branch of the modelselector tree. When creating a selector model, there must be at least as many targets passed as there are classes (when trigger is a classification model) or strings (when trigger is a cell of logical test strings). There may also be an additional target (i.e. the "default") which is used if none of the classes or tests were positive.

Note that target objects may be any standard model including another selector model (thus allowing multi-layer selector trees) or standard object including strings, numerical arrays, DataSet objects or even structures or cells.

If a target is a model, the output of modelselector will be the result of applying the model to the input data (see also the 'applytarget' option which disables this behavior). If the target is not a model, the target object itself will be returned.

One special target object is the "error" object. This object consists of a simple structure with one field named "error" which contains a string which should be used to throw an error. If the given target is selected, modelselector will throw a runtime error with the given string. This is useful in conjunction with on-line systems which should cease execution and send an alarm to a control system when the given situation occurs. This behavior can be changed by modifying the "errors" option (see below.)

Applying Models

When a single row of new data is passed as a dataset along with the selector model itself. the output is the result of applying the selected target model (target_model) or the target object, along with a unique description of the "branch(s)" taken to select the target model as a vector of branch numbers (applymodel). For example, given a multi-layer selector model containing:

selector_model  -> target_1 = PCA_model_A1
                   target_2 = Selector_model -> target_1 = PCA_model_B1
                                                target_2 = PCA_model_B2 
                   target_3 = PCA_model_A2

a returned value for applymodel of [2 1] implies that the second target model was selected from the first layer of target models, and this model was another selector model. From that second selector model, the first target model (PCA_model_B1) was selected and that is what was returned.

If more than one row of new data is passed to modelselector, each row will be predicted and the output will be either a cell array of objects (prediction structures, strings) or a dataset with one row for each input row (when numerical values are output or numerical prediction results are extracted using outputfilters option)

Note that if there are multiple "branches" (trigger models) the data passed to modelselector must contain all the data necessary for all trigger models within the selector model. If some of those variables are not used by a given model, modelselector will automatically discard unneeded variables before applying each trigger model.

Options

options = a structure array with the following fields:

• multiple : [{'otherwise'} | 'mostprobable' | 'fail' ] Governs behavior when more than one class of a classification model is assigned. 'fail' will throw an error. 'mostprobable' will choose the target that corresponds to the most probable class. 'otherwise' will use the last target (otherwise.)
• outputfilters : {} Provides information on how to filter output results after selection of a target. The value of this option is stored in the model indicating how the output of each corresponding target should be indexed. It is a cell array equal in length to the number of targets. Each cell element can contain another cell array with one or more of the following:

(A) a standard subscript indexing as defined by the Matlab "substruct" command

(B) a 2-element cell array containing a string label in the first cell and a standard substruct indexing structure in the second cell (as with A above)

(C) a string or numerical constant to be included verbatim Each content of the cell(to be concatenated row-wise). If any top-level cell elements are missing or the corresponding element is empty, no filtering is done.

         EXAMPLE:
         {
           { {'my prediction' substruct('.','prediction')} {'Q residuals' substruct('.','Q')} }
           { {'my prediction' substruct('.','prediction')} {'Q residuals' [0] }
           { }
         }

Would grab the "prediction" and "Q" outputs from a model for the first target and would grab only the "prediction" field for the second target and add a 0 (zero) to that. No filtering would be done on the third target. The odd use of [0] in row 2 is useful because some models may not output Q residuals, but you might still want to always output a second value so predictions from the first model and the second model are extracted to form an identical output (two columns.)

• applytarget : [ 'off' |{'on'}] When 'on' any target that is a model is automatically applied to the data. Note that modelselector models are ALWAYS automatically applied to the data.
• errors : [{'throw'}| 'struct' | 'string' ] Governs handling of error targets (structure with field "error" and a string). If 'throw', the content of the error field is thrown as an error. If 'string' the string content of the error field is returned with a prefix of "ERROR: ". If 'struct' the entire error structure is returned.
• qtestlimit : [3] Governs Q limit testing for PLSDA models (over this reduced value = otherwise branch is used)
• t2testlimit : [3] Governs T2 limit testing for PLSDA models (over this reduced value = otherwise branch is used)
• addtrigmodels : [{'trendtool'}] Specifies which models (other than standard) are allowed as trigger models. This option is mostly for future use as new methods are added which may be usable as trigger models.

• waitbar : [{'off'} | 'on'] Governs display of waitbar while processing.

See Also

Hierarchical Model Builder, knn, lwrpred, plsda, simca, svmda, EVRIModel_Objects