n4sidOptions

Option set for `n4sid`

Syntax

`opt = n4sidOptionsopt = n4sidOptions(Name,Value)`

Description

`opt = n4sidOptions` creates the default options set for `n4sid`.

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

Input Arguments

collapse all

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 single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

`'InitialState'` — Handling of initial states`'estimate'` (default) | `'zero'`

Handling of initial states during estimation, specified as one of the following strings:

• `'zero'` — The initial state is set to zero.

• `'estimate'` — The initial state is treated as an independent estimation parameter.

`'N4Weight'` — Weighting scheme used for singular-value decomposition by the `N4SID` algorithm`'auto'` (default) | `'MOESP'` | `'CVA'` | `'SSARX'`

Weighting scheme used for singular-value decomposition by the N4SID algorithm, specified as one of the following strings:

• `'MOESP'` — Uses the MOESP algorithm by Verhaegen [2].

• `'CVA'` — Uses the Canonical Variable Algorithm by Larimore [1].

Estimation using frequency-domain data always uses `'CVA'`.

• `'SSARX'` — A subspace identification method that uses an ARX estimation based algorithm to compute the weighting.

Specifying this option allows unbiased estimates when using data that is collected in closed-loop operation. For more information about the algorithm, see [4].

• `'auto'` — The estimating function chooses between the `MOESP`, `CVA` and `SSARX` algorithms.

`'N4Horizon'` — Forward- and backward-prediction horizons used by the `N4SID` algorithm`'auto'` (default) | vector `[r sy su]` | `k`-by-3 matrix

Forward- and backward-prediction horizons used by the N4SID algorithm, specified as one of the following values:

• A row vector with three elements — ` [r sy su]`, where `r` is the maximum forward prediction horizon, using up to `r` step-ahead predictors. `sy` is the number of past outputs, and `su` is the number of past inputs that are used for the predictions. See pages 209 and 210 in [3] for more information. These numbers can have a substantial influence on the quality of the resulting model, and there are no simple rules for choosing them. Making `'N4Horizon'` a `k`-by-3 matrix means that each row of `'N4Horizon'` is tried, and the value that gives the best (prediction) fit to data is selected. `k` is the number of guesses of ` [r sy su]` combinations. If you specify N4Horizon as a single column, `r = sy = su` is used.

• `'auto'` — The software uses an Akaike Information Criterion (AIC) for the selection of `sy` and `su`.

`'Focus'` — Estimation focus`'prediction'` (default) | `'simulation'` | `'stability'` | vector | matrix | linear system

Estimation focus that defines how the errors e between the measured and the modeled outputs are weighed at specific frequencies during the minimization of the prediction error, specified as one of the following values:

• `'prediction'` — Automatically calculates the weighting function as a product of the input spectrum and the inverse of the noise spectrum. The weighting function minimizes the one-step-ahead prediction. This approach typically favors fitting small time intervals (higher frequency range). From a statistical-variance point of view, this weighting function is optimal. However, this method neglects the approximation aspects (bias) of the fit.

This option focuses on producing a good predictor and does not enforce model stability. Use `'stability'` when you want to ensure a stable model.

• `'simulation'` — Estimates the model using the frequency weighting of the transfer function that is given by the input spectrum. Typically, this method favors the frequency range where the input spectrum has the most power. This method provides a stable model.

• `'stability'` — Same as `'prediction'`, but with model stability enforced.

• Passbands — Row vector or matrix containing frequency values that define desired passbands. For example:

```[wl,wh] [w1l,w1h;w2l,w2h;w3l,w3h;...]```

where `wl` and `wh` represent lower and upper limits of a passband. For a matrix with several rows defining frequency passbands, the algorithm uses union of frequency ranges to define the estimation passband.

Passbands are expressed in `rad/TimeUnit` for time-domain data and in `FrequencyUnit` for frequency-domain data, where `TimeUnit` and `FrequencyUnit` are the time and frequency units of the estimation data.

• SISO filter — Specify a SISO linear filter in one of the following ways:

• A single-input-single-output (SISO) linear system

• `{A,B,C,D}` format, which specifies the state-space matrices of the filter

• `{numerator, denominator}` format, which specifies the numerator and denominator of the filter transfer function

This option calculates the weighting function as a product of the filter and the input spectrum to estimate the transfer function. To obtain a good model fit for a specific frequency range, you must choose the filter with a passband in this range. The estimation result is the same if you first prefilter the data using `idfilt`.

• Weighting vector — For frequency-domain data only, specify a column vector of weights. This vector must have the same length as the frequency vector of the data set, `Data.Frequency`. Each input and output response in the data is multiplied by the corresponding weight at that frequency.

`'EstCovar'` — Control whether to generate parameter covariance data`true` (default) | `false`

Controls whether parameter covariance data is generated, specified as `true` or `false`.

If `EstCovar` is `true`, then use `getcov` to fetch the covariance matrix from the estimated model.

`'Display'` — Specify whether to display the estimation progress`'off'` (default) | `'on'`

Specify whether to display the estimation progress, specified as one of the following strings:

• `'on'` — Information on model structure and estimation results are displayed in a progress-viewer window.

• `'off'` — No progress or results information is displayed.

`'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'` — Weighting of prediction errors in multi-output estimations`[]` (default) | `'noise'` | positive semidefinite symmetric matrix

Weighting of prediction errors in multi-output estimations, specified as one of the following values:

• `'noise'` — Minimize $\mathrm{det}\left(E\text{'}*E/N\right)$, where E represents the prediction error and `N` is the number of data samples. This choice is optimal in a statistical sense and leads to the maximum likelihood estimates in case no data is available about the variance of the noise. This option uses the inverse of the estimated noise variance as the weighting function.

• Positive semidefinite symmetric matrix (`W`) — Minimize the trace of the weighted prediction error matrix `trace(E'*E*W/N)` where:

• `E` is the matrix of prediction errors, with one column for each output. `W` is the positive semidefinite symmetric matrix of size equal to the number of outputs. Use `W` to specify the relative importance of outputs in multiple-input, multiple-output models, or the reliability of corresponding data.

• `N` is the number of data samples.

This option is relevant only for multi-input, multi-output models.

• `[]` — The software chooses between the `'noise'` or using the identity matrix for `W`.

`'Advanced'` — Additional advanced optionsstructure

Additional advanced options, specified as a structure with the field `MaxSize`. `MaxSize` specifies the maximum number of elements in a segment when input-output data is split into segments.

`MaxSize` must be a positive integer.

Default: 250000

Output Arguments

collapse all

`opt` — Option set for `n4sid``n4sidOptions` option set

Option set for `n4sid`, returned as an `n4sidOptions` option set.

Examples

collapse all

Create Default Options Set for State-Space Estimation Using Subspace Method

```opt = n4sidOptions; ```

Specify Options for State-Space Estimation Using Subspace Method

Create an options set for `n4sid` using the `'zero'` option to initialize the state. Set the `Display` to `'on'`.

```opt = n4sidOptions('InitialState','zero','Display','on'); ```

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

```opt = n4sidOptions; opt.InitialState = 'zero'; opt.Display = 'on'; ```

References

[1] Larimore, W.E. "Canonical variate analysis in identification, filtering and adaptive control." Proceedings of the 29th IEEE Conference on Decision and Control, pp. 596–604, 1990.

[2] Verhaegen, M. "Identification of the deterministic part of MIMO state space models." Automatica, Vol. 30, 1994, pp. 61–74.

[3] Ljung, L. System Identification: Theory for the User. Upper Saddle River, NJ: Prentice-Hall PTR, 1999.

[4] Jansson, M. "Subspace identification and ARX modeling." 13th IFAC Symposium on System Identification , Rotterdam, The Netherlands, 2003.