Working With Function Options

Working With Function Options

Many PLS_Toolbox functions make use of two kinds of inputs, 'meta-parameters' which are inputs to a function that are required as inputs any time you call a given function and 'options' which are optional inputs to a function. This page describes how to work with these inputs. When working within the PLS_Toolbox or Solo graphical user interface, the Common Application Features: Options Dialog Box page may be of interest.

Meta-Parameters

Meta-parameters are standard inputs to a function. In general, they are always required and the value passed is frequently different from one call to the next. An example is the number of components (ncomp) input to the PCA function.

 model = pca(x,ncomp);

In some cases, meta-parameters can be omitted and a default value will be used instead, but this is the exception and is noted in the help for any function that permits this kind of shortcut.

Options

Inputs that are less-frequently changed, or that are more complicated in their format, are defined as 'options' and are input to a function as a standard Matlab structure and are often called 'options structures'. An options structure is usually the last item in the list of inputs to a function.

Options structures allow you to modify how a function behaves, but also provide default values which will work in most cases. If you want to change one or more options, there are several ways to do this.

Example 1: Getting Options from the Function

You can pass to the function a setting for all options by first retrieving all the options for the function, then changing only those you wish to change:

>> options = pls('options')
 options =
             name: 'options'
          display: 'on'
            plots: 'final'
    outputversion: 3
    preprocessing: {[]  []}
        algorithm: 'sim'
     blockdetails: 'standard'
>> options.plots = 'none';
>> options.display = 'off';
>> model = pls(x,y,ncomp,options)

In the above example, we start by retrieving the default values for all options of the PLS function (any function with options allows this type of call). We then change the "plots" option to be 'none' (no plots) and "display" option to be 'off' (no command-line output). Finally, we call the PLS function with these options, along with our data.

Example 2: Building the Options by Field Assignment

Although example 1 shows retrieving all options, this isn't completely necessary. Functions which use options structures will automatically fill in the default values for any missing fields if a partially completed options structure is supplied. This means that the following two examples are equivalent to Example 1:

>> clear options
>> options.plots = 'none';
>> options.display = 'off';
>> model = pls(x,y,ncomp,options)

Example 3: Using the Struct Command

>> options = struct('plots','none','display','off');
>> model = pls(x,y,ncomp,options);

The above example uses the "struct" Matlab command to create a structure, see the Mathworks documentation for struct (or type "help struct" in Matlab) for more information.)

Example 4: Passing the Options In-Line via Struct

The struct command can also be used directly as an input to a function. The following is again identical to the previous operations:

>> model = pls(x,y,ncomp,struct('plots','none','display','off');

This example combines everything into a single line. The only situation in which the above example will NOT work is when one of the options requires a cell { } input such as the preprocessing option for PLS. In these cases, the field MUST be defined using the standard options.field = {value} notation.

Setting New Defaults for Options

You can change the default value for any option in any function using setplspref.

By specifying a new default options value, the desired behavior can be achieved with a function without passing any options structure. These settings are remembered from one Matlab session to another. This is very useful to semi-permanently change the default behavior of any function without having to continually specify an options structure each time the function is called.

One example would be to turn off the default plotting or display functionality of a function. The following command will disable the plots which are automatically provided by PCA:

>> setplspref('pca','plots','none')

We can test that the option is changed by retrieving the options from PCA.

>> options=pca('options')
options =
           name: 'options'
        display: 'on'
          plots: 'none'
  outputversion: 3
  preprocessing: {[]}
   blockdetails: 'standard'

To reset one option to its factory default, use the keyword 'factory' as the value for the given option:

>> setplspref('pca','plots','factory')  %reset 'plots' option for PCA

To reset all options values for a given function to the factory defaults, call setplspref with the function name and the keyword 'factory'.

>> setplspref('pca','factory')   %reset all options for PCA

To reset all options values for all functions to the factory defaults, call setplspref with keyword 'factory' alone. Warning: this will erase ALL user-defined defaults.

>> setplspref('factory')

Checking for Bad Options

Normally, the options that are input to a function are not checked for strict validity. If you include any unexpected options in the options structure, they are simply ignored. This allows for easy combination of multiple options from different functions, and using the same options structure for input to similar functions. However, if you mistype an option's name, you will generally not be informed of your mistake. Thus, creating the option:

 options.preprocessinf = myprepro;

when you meant to type:

 options.preprocessing = myprepro;

will simply lead to the default preprocessing being used instead of your myprepro settings.

This behavior can be changed through the reconopts settings. The action taken when an unexpected option is passed can be modified by changing the 'missingaction' preference for reconopts using the setplspref command:

setplspref('reconopts','missingaction','action')

where 'action' can be any of the following:

'error'  : throw an error

'warning' : display a warning message

'display' : display a message in the command window (does not trigger warning flag)

'none'  : do nothing (no errors ever thrown or display given.)

Thus, by using

setplspref('reconopts','missingaction','error')

any mistyped options will be flagged for you by having your command give an error:

>> pca(x,3,struct('preprocessinf',myprepro))
??? Error using ==> reconopts at 154
Invalid option "preprocessinf" passed to function: pca

To disable the error checking, reset missingaction to the value 'none'

setplspref('reconopts','missingaction','none')