Analysis EVRIGUI Object

These are the methods defined for Analysis GUI when accessed through an EVRIGUI object. The following methods are called by referring to the given EVRIGUI object, followed by the method to be accessed. For example, given an EVRIGUI object in the workspace called "obj", the following call sets the Calibration X-block data to a given DataSet object called "data":

  obj.setXblock(data);

And this would retrieve the currently loaded Calibration X-block data:

  data = obj.getXblock;

See Complex Example for another example of using these methods.

The specific methods available are described in the sections below.

Loading and Retrieving Data and Models

Loading Data

These methods can be used to set (i.e. "load") the specified data. Note that all take a single parameter as input and this parameter must be a DataSet object. If the object is not a valid DataSet object, an error will be thrown.

.setXblock(dataset)	Sets the Calibration X-block
.setXblockVal(dataset)	Sets the Validation X-block
.setYblock(dataset)	Sets the Calibration Y-block
.setYblockVal(dataset)	Sets the Validation Y-block

Retrieving Data

These methods can be used to retrieve the specified data as a DataSet object:

.getXblock	Returns Calibration X-block
.getXblockVal	Returns Validation X-block
.getYblock	Returns Calibration Y-block
.getYblockVal	Returns Validation Y-block

Loading and Retrieving Models

Models can be set (loaded) or retrieved using the following two methods:

.getModel	Returns the currently calibrated model (if any)
.setModel(model)	Loads the given model into the Analysis GUI and switches the analysis method to that specified by the model. See the .apply method to apply the model to validation or test data.

Loading and Retrieving Predictions

Similarly, predictions can be loaded or retrieved using these methods:

.getPrediction	Returns the current prediction structure. This is the result of applying the loaded model to the validation (a.k.a. test) data.
.setPrediction(prediction)	Loads the given prediction structure into Analysis GUI. This method is often used to load previous predictions following by one of the plotting commands.

Drop method

The "drop" method is a simplified loading method. Any valid data, model or prediction can be "dropped" on a valid Analysis EVRIGUI object and the GUI will attempt to load the given data into the most logical location based on the GUI's current status. Since this may be ambiguious to the script or program accessing the EVRIGUI object where the data will be loaded, it is often recommended that an explict .set____ command (see above) be used in most cases.

.drop(dataset)	Attempt to load the specified DataSet into the most logical data location in the GUI
.drop(model)	Attemp to load the specified model into the GUI (see also .setModel above)

Clearing Data and Models

Clearing of data, models, and predictions can be achieved using these methods. In all cases, if the given data or model is already cleared, no error occurs.

.clearAll	Clears all data, models, options, and predictions (return to initial startup state)
.clearBothCal	Clears both X and Y Calibration Data
.clearBothVal	Clears both X and Y Validation Data
.clearModel	Clears current model
.clearXblock	Clears Calibration X-block
.clearXblockVal	Clears Validation X-block
.clearYblock	Clears Calibration Y-block
.clearYblockVal	Clears Validation Y-block

Model Creation and Method Settings

These methods allow creation of models and manipulation of the basic modeling parameters.

Creating Models

.calibrate	Calculates or recalculates a model if the model is non-existant or out of date with the current settings, and/or applies the current model to the validation data, if loaded. This is equivalent to clicking on the "Calibrate" (gears) button on the Analysis GUI.
.apply	Identical to the .calibrate method.

Analysis Methods and Settings

These methods work with the current analysis method (i.e. modeling method) of the Analysis GUI. This is any of the modeling techniques available in the Analysis GUI Analysis_Menu.

.getMethod	Returns a string specifying the Analysis method (e.g. 'pca', 'pls', 'parafac').
.setMethod('method')	Sets the Analysis method to 'method' (e.g. 'pca', 'pls', 'parafac'). If the requested method is not the currently selected method, any existing model and prediction are cleared.

The .getComponents and .setComponents methods allow reviewing and changing of the number of components used in a factor-based model. Changing this property will cause the model to be cleared (requiring the use of the .calibrate method described above.) Note that some analysis methods (e.g. 'mlr' and 'cluster') do not use the Components settings and any values returned or set using these methods will be ignored.

.getComponents

Returns the number of components currently selected.

.setComponents(n)

Sets the number of components to use in a model. After this value is changed, the .calibrate method should be called to request an update of the model. Any value set here will not be reflected in the model until the after .calibrate method is called. Note: If n is an empty value [] or is omitted entirely, Analysis GUI will clear the model and attempt to recalibrate the model with an automatically selected number of factors. Not all analysis methods support this operation and those methods will simply recalculate with the default components (usually 1).

Preprocessing

The preprocessing methods allow getting and setting the current X and Y-block preprocessing methods. Currently, these set methods require complex preprocessing structure inputs and require knowledge and use of the Preprocess functionality in PLS_Toolbox.

.getXPreprocessing	Return the current X-block preprocessing structure
.getYPreprocessing	Return the current Y-block preprocessing structure
.setXPreprocessing(p)	Sets the X-block preprocessing to the structure passed as p
.setYPreprocessing(p)	Sets the Y-block preprocessing to the structure passed as p

Toolbar Buttons

These methods allow the automatic "pressing" of any of the Toolbar buttons. The .getButtons method returns a list of all the current toolbar buttons as a list of their "tags" (unique names). The .pressButton method can then be used with any one of these tags to simulate the clicking of the given button. By using these methods, an outside program can automatically bring up plots like scores and loadings plots, or start up "helper GUIs" like the PLSDA_Class_Groups_Interface.

.getButtons	Returns a cell array of strings indicating the tags for each of the current toolbar buttons.
.pressButton(tag)	Equivalent to the user clicking the toolbar button specified by the given tag.

Generic GUI Methods

These methods provide simple access to simple GUI actions such as controlling the visibility of the GUI and closing or creating the GUI

.getVisibility	Returns 1 (one) if the GUI is currently visible (not hidden) and 0 (zero) otherwise
.setVisibility(vis)	When input is 1 (one), the GUI is made visible. When input is 0 (zero), the GUI is hidden from view and from the task bar (when relevent). Note that some methods may make a hidden GUI visible again even if this value has been set to zero.
.close	Forces the GUI to close
.create	Used to create a new Analysis GUI - NOTE: This method is called automatically by the main EVRIGUI object and should not be called directly by the user (an error will always be thrown in that situation)

Advanced Methods

Analysis Method Options

These methods allows access and manipulation of the low-level "Analysis Method" options. These options are specific to each method and often change very fundamental aspects of how the modeling algorithms operate. It is possible to cause a complete failure to model or get unexpected models using these options so their use is only recommended for expert users. The options being set here are equivalent to the options which are passed to the specific modeling functions (in Matlab: pls.m, pca.m, parafac.m) and the individual function for the currently selected method (see .setMethod above) should be consulted in setting these options. The one field that is required when setting options is the functionname field which must be set to the string equivalent to the method name (e.g. functionname = 'pca' ).

.getOptions	Returns the current options for the given analysis method. Note that, if the user or an outside program has not modified the options, this will be returned as an empty matrix. In that case, the default function options are generally used
.setOptions(opts)	Sets the current options for the given analysis method to the options structure passed as "opts". Note that some options are always overridden (e.g. the automatic generation of plots controlled in many functions through the .plots option is always ignored, even if set here to be "on")

Shared Data Object Access

These methods can be used to access a Shared Data object which gives direct, dynamic access to the data and model being used in the GUI. This allows an advanced user to view and/or modify the used data directly. Changes to the object are automatically acted on by the GUI (e.g. clearing of models and updating of plots when Data changes.) However, the use of Shared Data objects is for advanced users only and describing their use is beyond the scope of this document. See the Shared Data object documentation for more information on using Shared Data.

.getXblockId	Returns Shared Data object to Calibration X-block
.getXblockValId	Returns Shared Data object to Validation X-block
.getYblockId	Returns Shared Data object to Calibration Y-block
.getYblockValId	Returns Shared Data object to Validation Y-block
.getModelId	Returns Shared Data object to Model
.getPredictionId	Returns Shared Data object to Predictions

Generic Object Access

The generic .getObject method returns the object specified using a keyword string from Analysis GUI. This is the actual DataSet, model, or other object itself (not the shared data object) Valid keywords are internal and may be subject to chage. As a result this function is not recommended for most uses. Instead, the user is directed to the general .get____ commands described earlier in this document. This method does, however, provide access to objects which may not be accessible through the other .get____ methods.

.getObject('object_keyword')

Returns specified object from GUI

Complex Example

The following sequence of operations would create an Analysis GUI EVRIGUI object called "obj", load the data "data", set the analysis method to PCA, set the number of components at 5, calibrate a model, bring up a scores plot, and grab the model object:

  obj = evrigui('analysis');       % open a new Analysis GUI and create an attached EVRIGUI object
  obj.setXblock(data);             % load "data" into GUI
  obj.setMethod('pca');            % set PCA as analysis method
  obj.setComponents(5);            % set 5 PCs as number of components
  obj.calibrate;                   % calibrate the model
  obj.pressButton('plotscores');   % bring up a scores plot
  model = obj.getModel;            % retreive the model as a variable called "model"

Note that text following the % is comment text only. When passing commands like these into Solo, this text can be omitted.