# residOptions

Option set for `resid`

## Description

creates
the default option set for `opt`

= residOptions`resid`

. Use dot notation
to customize the option set, if needed.

creates
an option set with options specified by one or more `opt`

= residOptions(`Name,Value`

)`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 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.*

**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*array of objects, where_{e}*N*is the number of experiments._{e}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 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 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.

## Version History

**Introduced in R2016a**

## See Also

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)