Main Content

compareOptions

Option set for compare

collapse all in page

Syntax

opt = compareOptions
opt = compareOptions(Name,Value)

Description

opt = compareOptions creates the default options set for compare.

opt = compareOptions(Name,Value) creates an option set with the options specified by one or more Name,Value pair arguments.

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Samples

Data for which compare calculates fit values.

Specify Samples as a vector containing the data sample indices. For multiexperiment data, use a cell array of Ne vectors, where Ne is the number of experiments.

InitialCondition

Handling of initial conditions.

Specify InitialCondition as one of the following:

  • 'z' — Zero initial conditions.

  • 'e' — Estimate initial conditions such that the prediction error for observed output is minimized.

    For nonlinear grey-box models, only those initial states i that are designated as free in the model (sys.InitialStates(i).Fixed = false) are estimated. To estimate all the states of the model, first specify all the Nx states of the idnlgrey model sys as free.

    for i = 1:Nx
sys.InitialStates(i).Fixed = false;
end

    Similarly, to fix all the initial states to values specified in sys.InitialStates, first specify all the states as fixed in the sys.InitialStates property of the nonlinear grey-box model.

  • 'd' — Similar to 'e', but absorbs nonzero delays into the model coefficients. The delays are first converted to explicit model states, and the initial values of those states are also estimated and returned.

    Use this option for linear models only.

  • Vector or Matrix — Initial guess for state values, specified as a numerical column vector of length equal to the number of states. For multiexperiment data, specify a matrix with Ne columns, where Ne is the number of experiments. Otherwise, use a column vector to specify the same initial conditions for all experiments. Use this option for state-space (idss and idgrey) and nonlinear models (idnlarx, idnlhw, and idnlgrey) only.

  • initialCondition object — initialCondition object that represents a model of the free response of the system to initial conditions. For multiexperiment data, specify a 1-by-Ne array of objects, where Ne is the number of experiments.

    Use this option for individual linear models only. If you are analyzing more than one model and want to specify an initialCondition object for each model, you must specify the object and use compare for each model separately.

  • Structure with the following fields, which contain the historical input and output values for a time interval immediately before the start time of the data used by compare:

    FieldDescription
    InputInput history, specified as a matrix with Nu columns, where Nu is the number of input channels. For time series models, use []. The number of rows must be greater than or equal to the model order.
    OutputOutput history, specified as a matrix with Ny columns, where Ny is the number of output channels. The number of rows must be greater than or equal to the model order.

    For multiexperiment data, configure the initial conditions separately for each experiment by specifying InitialCondition as a structure array with Ne elements. To specify the same initial conditions for all experiments, use a single structure.

    The software uses data2state to map the historical data to states. If your model is not idss, idgrey, idnlgrey, or idnlarx, the software first converts the model to its state-space representation and then maps the data to states. If conversion of your model to idss is not possible, the estimated states are returned empty.

  • x0obj — Specification object created using idpar. Use this object for discrete-time state-space (idss and idgrey) and nonlinear grey-box (idnlgrey) models only. Use x0obj to impose constraints on the initial states by fixing their value or specifying minimum or maximum bounds.

Default: 'e'

InputInterSample

Input-channel intersample behavior

Input-channel intersample behavior for transformations between discrete time and continuous time, specified as 'auto', 'zoh','foh', or 'bl'.

The definitions of the three behavior values are as follows:

  • 'zoh' — Zero-order hold maintains a piecewise-constant input signal between samples.

  • 'foh' — First-order hold maintains a piecewise-linear input signal between samples.

  • 'bl' — Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

iddata objects have a similar property, data.InterSample, that contains the same behavior value options. When the InputInterSample value is 'auto' and the estimation data is in an iddata object data, the software uses the data.InterSample value. When the estimation data is instead contained in a timetable or a matrix pair, with the 'auto' option, the software uses 'zoh'.

The software applies the same option value to all channels and all experiments.

InputOffset

Removes offset from time domain input data for model response computation.

Specify as a column vector of length Nu, where Nu is the number of inputs.

Use [] to indicate no offset.

For multiexperiment data, specify InputOffset as a Nu-by-Ne matrix. Nu is the number of inputs and Ne is the number of experiments.

Each entry specified by InputOffset is subtracted from the corresponding input data.

Default: []

OutputOffset

Removes offset from time-domain output data for model response prediction.

Specify as a column vector of length Ny, where Ny is the number of outputs.

Use [] to indicate no offset.

For multiexperiment data, specify OutputOffset as a Ny-by-Ne matrix. Ny is the number of outputs and Ne is the number of experiments.

Each entry specified by OutputOffset is subtracted from the corresponding output data before computing the model response. After computing the model response, the software adds the offset to the response to give the final model response.

Default: []

OutputWeight

Weight of output for initial condition estimation.

OutputWeight requires one of the following values:

  • [] — No weighting is used. This option is the same as using eye(Ny) for the output weight. Ny is the number of outputs.

  • 'noise' — Inverse of the noise variance stored with the model.

  • Matrix of doubles — A positive semi-definite matrix of dimension Ny-by-Ny. Ny is the number of outputs.

Default: []

Output Arguments

opt

Option set containing the specified options for compare.

Examples

collapse all

Open Live Script

Create a default options set for compare. 

opt = compareOptions;
Open Live Script

Create an options set for compare using zero initial conditions. Set the input offset to 5. 

opt = compareOptions('InitialCondition','z','InputOffset',5);

Alternatively, use dot notation to set the values of opt. 

opt = compareOptions;
opt.InitialCondition = 'z';
opt.InputOffset = 5;

Version History

Introduced in R2012a

expand all

See Also