Analysis EVRIGUI Object
- 1 Loading and Retrieving Data and Models
- 2 Model Creation and Method Settings
- 3 Generic GUI Methods
- 4 Advanced Methods
- 5 Complex Example
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":
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
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|
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.|
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.
|.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).
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|
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)|
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")|
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|
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.