# ssregestOptions

Option set for `ssregest`

## Description

## Examples

### Create Default Option Set for State-Space Estimation Using Reduction of Regularized ARX Model

options = ssregestOptions;

### Specify Options for State-Space Estimation Using Reduction of Regularized ARX Model

Create an option set for `ssregest`

that fixes the value of the initial states to `'zero'`

. Also, set the `Display`

to `'on'`

.

opt = ssregestOptions('InitialState','zero','Display','on');

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

.

opt = ssregestOptions; opt.InitialState = 'zero'; opt.Display = 'on';

## 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: **`opt = ssregestOptions('InitialState','zero')`

fixes
the value of the initial states to zero.

`InitialState`

— Handling of initial states

`'estimate'`

(default) | `'zero'`

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

`'zero'`

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

— The initial state is treated as an independent estimation parameter.

`ARXOrder`

— ARX model orders

`'auto'`

(default) | matrix of nonnegative integers

ARX model orders, specified as a matrix of nonnegative integers ```
[na
nb nk]
```

. The `max(ARXOrder)+1`

must be greater
than the desired state-space model order (number of states). If you
specify a value, it is recommended that you use a large value for `nb`

order.
To learn more about ARX model orders, see `arx`

.

`RegularizationKernel`

— Regularizing kernel

`'TC'`

(default) | `'SE'`

| `'SS'`

| `'HF'`

| `'DI'`

| `'DC'`

Regularizing kernel used for regularized estimates of the underlying ARX model, specified as one of the following values:

`'TC'`

— Tuned and correlated kernel`'SE'`

— Squared exponential kernel`'SS'`

— Stable spline kernel`'HF'`

— High frequency stable spline kernel`'DI'`

— Diagonal kernel`'DC'`

— Diagonal and correlated kernel

For more information, see [1].

`Reduction`

— Options for model order reduction

structure

Options for model order reduction, specified as a structure with the following fields:

`StateElimMethod`

State elimination method. Specifies how to eliminate the weakly coupled states (states with smallest Hankel singular values). Specified as one of the following values:

`'MatchDC'`

Discards the specified states and alters the remaining states to preserve the DC gain. `'Truncate'`

Discards the specified states without altering the remaining states. This method tends to product a better approximation in the frequency domain, but the DC gains are not guaranteed to match. **Default:**`'Truncate'`

`AbsTol, RelTol`

Absolute and relative error tolerance for stable/unstable decomposition. Positive scalar values. For an input model

*G*with unstable poles, the reduction algorithm of`ssregest`

first extracts the stable dynamics by computing the stable/unstable decomposition*G*→*GS*+*GU*. The`AbsTol`

and`RelTol`

tolerances control the accuracy of this decomposition by ensuring that the frequency responses of*G*and*GS*+*GU*differ by no more than`AbsTol`

+`RelTol`

*abs(*G*). Increasing these tolerances helps separate nearby stable and unstable modes at the expense of accuracy. See`stabsep`

(Control System Toolbox) for more information.**Default:**`AbsTol = 0; RelTol = 1e-8`

`Offset`

Offset for the stable/unstable boundary. Positive scalar value. In the stable/unstable decomposition, the stable term includes only poles satisfying

`Re(s) < -Offset * max(1,|Im(s)|)`

(Continuous time)`|z| < 1 - Offset`

(Discrete time)

Increase the value of

`Offset`

to treat poles close to the stability boundary as unstable.**Default:**`1e-8`

`Focus`

— Error to be minimized

`'prediction'`

(default) | `'simulation'`

Error to be minimized in the loss function during estimation,
specified as the comma-separated pair consisting of `'Focus'`

and
one of the following values:

`'prediction'`

— The one-step ahead prediction error between measured and predicted outputs is minimized during estimation. As a result, the estimation focuses on producing a good predictor model.`'simulation'`

— The simulation error between measured and simulated outputs is minimized during estimation. As a result, the estimation focuses on making a good fit for simulation of model response with the current inputs.

The `Focus`

option can be interpreted as a
weighting filter in the loss function. For more information, see Loss Function and Model Quality Metrics.

`WeightingFilter`

— Weighting prefilter

`[]`

(default) | vector | matrix | cell array | linear system

Weighting prefilter applied to the loss function to be minimized
during estimation. To understand the effect of `WeightingFilter`

on
the loss function, see Loss Function and Model Quality Metrics.

Specify `WeightingFilter`

as one of the following
values:

`[]`

— No weighting prefilter is used.Passbands — Specify a row vector or matrix containing frequency values that define desired passbands. You select a frequency band where the fit between estimated model and estimation data is optimized. For example,

`[wl,wh]`

where`wl`

and`wh`

represent lower and upper limits of a passband. For a matrix with several rows defining frequency passbands,`[w1l,w1h;w2l,w2h;w3l,w3h;...]`

, the estimation algorithm uses the union of the 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 single-input-single-output (SISO) linear filter in one of the following ways:

A SISO LTI model

`{A,B,C,D}`

format, which specifies the state-space matrices of a filter with the same sample time as estimation data.`{numerator,denominator}`

format, which specifies the numerator and denominator of the filter as a transfer function with same sample time as estimation data.This option calculates the weighting function as a product of the filter and the input spectrum to estimate the transfer function.

Weighting vector — Applicable 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.

`EstimateCovariance`

— Option to generate parameter covariance data

`true`

(default) | `false`

Option to generate parameter covariance data, specified as `true`

or
`false`

.

If `EstimateCovariance`

is `true`

, then use
`getcov`

to fetch the covariance matrix
from the estimated model.

`Display`

— Option to display estimation progress

`'off'`

(default) | `'on'`

Option to display the estimation progress, specified as one of the following values:

`'on'`

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

— No progress or results information is displayed.

`InputInterSample`

— Input-channel intersample behavior

`'auto'`

| `'zoh'`

| `'foh'`

| `'bl'`

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`

— 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 prediction errors in multi-output estimation

`[]`

(default) | positive semidefinite, symmetric matrix

Weight of prediction errors in multi-output estimation, specified as one of the following values:

Positive semidefinite, symmetric matrix (

`W`

). The software minimizes 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, and`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-output models, or the reliability of corresponding data.`N`

is the number of data samples.

`[]`

— No weighting is used. Specifying as`[]`

is the same as`eye(Ny)`

, where`Ny`

is the number of outputs.

This option is relevant only for multi-output models.

`Advanced`

— Advanced estimation options

structure

Advanced options for regularized estimation, specified as a structure with the following fields:

`MaxSize`

— Maximum allowable size of Jacobian matrices formed during estimation, specified as a large positive number.**Default:**`250e3`

`SearchMethod`

— Search method for estimating regularization parameters, specified as one of the following values:`'gn'`

: Quasi-Newton line search.`'fmincon'`

: Trust-region-reflective constrained minimizer. In general,`'fmincon'`

is better than`'gn'`

for handling bounds on regularization parameters that are imposed automatically during estimation.

**Default:**`'fmincon'`

## Output Arguments

`options`

— Option set for `ssregest`

`ssregestOptions`

options set

Estimation options for `ssregest`

, returned as an
`ssregestoptions`

option set.

## References

[1] T. Chen, H. Ohlsson, and L. Ljung. “On
the Estimation of Transfer Functions, Regularizations and Gaussian
Processes - Revisited”, *Automatica*,
Volume 48, August 2012.

## Version History

**Introduced in R2014a**

### R2022b: `InputInterSample`

option allows intersample behavior specification for continuous models estimated from timetables or matrices.

`iddata`

objects contain an `InterSample`

property that
describes the behavior of the signal between sample points. The
`InputInterSample`

option implements a version of that property in
`ssregestOptions`

so that intersample behavior can be specified also when
estimation data is stored in timetables or matrices.

### R2018a: Renaming of Estimation and Analysis Options

The names of some estimation and analysis options were changed in R2018a. Prior names still work.

## 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)