impulseestOptions

Options set for impulseest

Description

Use an impulseestOptions object to specify options for estimating nonparametric impulse responses through the impulseest function. You can specify options such as the regularization kernel or input offset to be used in estimation.

Creation

Syntax

options = impulseestOptions

options = impulseestOptions(Name,Value)

Description

options = impulseestOptions creates a default options set for impulseest.

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

Properties

RegularizationKernel — Used for regularized estimates of impulse response for all input-output channels

'TC' (default) | 'none' | 'CS' | 'SE' | 'SS' | 'HF' | 'DI' | 'DC'

Regularizing kernel, used for regularized estimates of impulse response for all input-output channels. Regularization reduces variance of estimated model coefficients and produces a smoother response by trading variance for bias. For more information, see [1].

Regularization is specified as one of the following values:

• 'TC' — Tuned and correlated kernel

• 'none' — No regularization is used

• 'CS' — Cubic spline kernel

• 'SE' — Squared exponential kernel

• 'SS' — Stable spline kernel

• 'HF' — High frequency stable spline kernel

• 'DI' — Diagonal kernel

• 'DC' — Diagonal and correlated kernel

PW — Order of input prewhitening filter

'auto' (default) | nonnegative integer

Order of the input prewhitening filter. Must be one of the following:

• 'auto' — Uses a filter of order 10 when RegularizationKernel is 'none'; otherwise, 0.

• Nonnegative integer

Use a nonzero value of prewhitening only for unregularized estimation (RegularizationKernel is 'none').

InputOffset — Input signal offset level of time-domain estimation data

[] (default) | column vector

Input signal offset level of time-domain estimation data. Must be one of the following:

• An Nu-element column vector, where Nu is the number of inputs. For multi-experiment data, specify a Nu-by-Ne matrix, where Ne is the number of experiments. The offset value InputOffset(i,j) is subtracted from the i^th input signal of the j^th experiment.

• [] — No offsets.

OutputOffset — Output signal offset level of time-domain estimation data

[] (default) | column vector

Output signal offset level of time-domain estimation data. Must be one of the following:

• An Ny-element column vector, where Ny is the number of outputs. For multi-experiment data, specify a Ny-by-Ne matrix, where Ne is the number of experiments. The offset value OputOffset(i,j) is subtracted from the i^th output signal of the j^th experiment.

• [] — No offsets.

Advanced — Used during regularized estimation

struct

Structure, used during regularized estimation, with the following fields:

• MaxSize — Maximum allowable size of Jacobian matrices formed during estimation. Specify a large positive number.

  Default: 250e3

• SearchMethod — Search method for estimating regularization parameters, specified as one of the following values:

  • '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.

  • 'gn': Quasi-Newton line search.

  SearchMethod is used only when RegularizationKernel is not 'none'.

  Default: 'fmincon'

• AROrder — Order of the AR-part in the model from input to output. Specify as a positive integer.

  An order>0 allows more accurate models of the impulse response in case of feedback and non-white output disturbances.

  Default: 5

• FeedthroughInSys — Specify whether the impulse response value at zero lag must be attributed to feedthrough in the system (true) or to feedback effects (false). Applies only when you compute the response values for negative lags.

  Default: false

Examples

Create Default Options Set for Impulse Response Estimation

Create a default options set for impulseest.

options = impulseestOptions;

Specify Regularizing Kernel and Prewhitening Options for Impulse Response Estimation

Specify 'HF' regularizing kernel and order of prewhitening filter for impulseest.

options = impulseestOptions('RegularizationKernel','HF','PW',5);

Alternatively, use dot notation to specify these options.

options = impulseestOptions;
options.RegularizationKernel = 'HF';
options.PW = 5;

Tips

• A linear model cannot describe arbitrary input-output offsets. Therefore, before using the data, you must either detrend it or remove the levels using InputOffset and OutputOffset. You can reintroduce the removed data during simulations by using the InputOffset and OutputOffset simulation options. For more information, see simOptions.

• Estimating the impulse response by specifying either InputOffset, OutputOffset or both is equivalent to detrending the data using getTrend and detrend. For example:

  opt = impulseestOptions('InputOffset',in_off,'OutputOffset',out_off);
  impulseest(data,opt);

  is the same as:

  Tr = getTrend(data),
  Tr.InputOffset = in_off
  TR.OutputOffset = out_off
  dataT = detrend(data,Tr)
  impulseest(dataT)

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 R2012b

R2018a: Renaming of Estimation and Analysis Options

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