residOptions

Option set for resid

Syntax

opt = residOptions

opt = residOptions(Name,Value)

Description

opt = residOptions creates the default option set for resid. Use dot notation to customize the option set, if needed.

opt = residOptions(Name,Value) creates an option set with options specified by one or more Name,Value pair arguments. The options that you do not specify retain their default value.

Examples

Create and Modify Default Option Set for Residual Analysis

Create a default option set for resid.

opt = residOptions;

Specify the maximum lag for residual correlation calculations.

opt.MaxLag = 35;

Specify Options for Residual Analysis

Create an option set for resid that specifies initial condition as zero.

opt = residOptions('InitialCondition','z');

Input Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: residOptions('InitialCondition','e')

'MaxLag' — Maximum positive lag

25 (default) | positive integer

Maximum positive lag for residual correlation and impulse response calculations, specified as the comma-separated pair consisting of 'MaxLag' and a positive integer.

'InitialCondition' — Handling of initial conditions

'e' (default) | 'z' | 'd' | column vector | matrix | initialCondition object | object array | structure | idpar object x0Obj

Handling of initial conditions, specified as the comma-separated pair consisting of 'InitialCondition' and one of the following values:

• '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 multi-experiment 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-N_e array of objects, where N_e is the number of experiments.

  Use this option for linear models only.

• 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 resid:

  Field	Description
  Input	Input 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.
  Output	Output 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 multi-experiment 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.

'InputOffset' — Removal of offset from time-domain input data during estimation

[] (default) | vector of positive integers | matrix

Removal of offset from time-domain input data during estimation, specified as the comma-separated pair consisting of 'InputOffset' and one of the following:

• A column vector of positive integers of length Nu, where Nu is the number of inputs.

• [] — Indicates no offset.

• Nu-by-Ne matrix — For multi-experiment data, specify InputOffset as an 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.

'OutputOffset' — Removal of offset from time-domain output data during estimation

[] (default) | vector | matrix

Removal of offset from time-domain output data during estimation, specified as the comma-separated pair consisting of 'OutputOffset' and one of the following:

• A column vector of length Ny, where Ny is the number of outputs.

• [] — Indicates no offset.

• Ny-by-Ne matrix — For multi-experiment 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.

'OutputWeight' — Weight of output for initial condition estimation

[] (default) | 'noise' | matrix

Weight of output for initial condition estimation, specified as the comma-separated pair consisting of 'OutputWeight' and one of the following:

• [] — 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 semidefinite matrix of dimension Ny-by-Ny. Ny is the number of outputs.

Output Arguments

opt — Option set for resid

residOptions option set

Option set for resid, returned as an residOptions option set.