recursiveARMAX

Create System object for online parameter estimation of ARMAX model

Syntax

obj = recursiveARMAX obj = recursiveARMAX(Orders) obj = recursiveARMAX(Orders,A0,B0,C0) obj = recursiveARMAX(___,Name,Value)

Description

Use recursiveARMAX command for parameter estimation with real-time data. If all data necessary for estimation is available at once, and you are estimating a time-invariant model, use the offline estimation command, armax.

obj = recursiveARMAX creates a System object™ for online parameter estimation of default single-input single-output (SISO) ARMAX model structure. The default model structure has polynomials of order 1 and initial polynomial coefficient values eps.

After creating the object, use the step command to update model parameter estimates using recursive estimation algorithms and real-time data.

obj = recursiveARMAX(Orders) specifies the polynomial orders of the ARMAX model to be estimated.

obj = recursiveARMAX(Orders,A0,B0,C0) specifies the polynomial orders and initial values of the polynomial coefficients. Specify initial values to potentially avoid local minima during estimation. If the initial values are small compared to the default InitialParameterCovariance property value, and you have confidence in your initial values, also specify a smaller InitialParameterCovariance.

obj = recursiveARMAX(___,Name,Value) specifies additional attributes of the ARMAX model structure and recursive estimation algorithm using one or more Name,Value pair arguments.

Object Description

recursiveARMAX creates a System object for online parameter estimation of SISO ARMAX models using a recursive estimation algorithm.

A System object is a specialized MATLAB^® object designed specifically for implementing and simulating dynamic systems with inputs that change over time. System objects use internal states to store past behavior, which is used in the next computational step.

After you create a System object, you use commands to process data or obtain information from or about the object. System objects use a minimum of two commands to process data — a constructor to create the object and the step command to update object parameters using real-time data. This separation of declaration from execution lets you create multiple, persistent, reusable objects, each with different settings.

You can use the following commands with the online estimation System objects in System Identification Toolbox™:

Command	Description
`step`	Update model parameter estimates using recursive estimation algorithms and real-time data. `step` puts the object into a locked state. In a locked state, you cannot change any nontunable properties or input specifications, such as model order, data type, or estimation algorithm. During execution, you can only change tunable properties.
`release`	Unlock the System object. Use this command to enable setting of nontunable parameters.
`reset`	Reset the internal states of a locked System object to the initial values, and leave the object locked.
`clone`	Create another System object with the same object property values. Do not create additional objects using syntax `obj2 = obj`. Any changes made to the properties of the new object created this way (`obj2`) also change the properties of the original object (`obj`).
`isLocked`	Query locked status for input attributes and nontunable properties of the System object.

Use the recursiveARMAX command to create an online estimation System object. Then estimate the ARMAX model parameters (A, B, and C) and output using the step command with incoming input and output data, u, and y.

[A,B,C,EstimatedOutput] = step(obj,y,u)

For recursiveARMAX object properties, see Properties.

Examples

collapse all

Estimate an ARMAX Model Online

Open Live Script

Create a System object for online parameter estimation of an ARMAX model.

obj = recursiveARMAX;

The ARMAX model has a default structure with polynomials of order 1 and initial polynomial coefficient values, eps.

Load the estimation data. In this example, use a static data set for illustration.

load iddata1 z1;
output = z1.y;
input = z1.u;

Estimate ARMAX model parameters online using step.

for i = 1:numel(input)
[A,B,C,EstimatedOutput] = step(obj,output(i),input(i));
end

View the current estimated values of polynomial A coefficients.

obj.A

ans = 1×2

    1.0000   -0.8298

View the current covariance estimate of the parameters.

obj.ParameterCovariance

ans = 3×3

    0.0001    0.0001    0.0001
    0.0001    0.0032    0.0000
    0.0001    0.0000    0.0001

View the current estimated output.

EstimatedOutput

EstimatedOutput = -4.5595

Create System Object for ARMAX Model With Known Polynomial Orders

Open Live Script

Specify ARMAX model orders and delays.

na = 1;
nb = 2;
nc = 1;
nk = 1;

Create a System object for online estimation of ARMAX model with the specified orders and delays.

obj = recursiveARMAX([na nb nc nk]);

Create Online Estimation System Object for ARMAX Model With Known Initial Parameters

Open Live Script

Specify ARMAX model orders and delays.

na = 1;
nb = 2;
nc = 1;
nk = 1;

Create a System object for online estimation of ARMAX model with known initial polynomial coefficients.

A0 = [1 0.5];
B0 = [0 1 1];
C0 = [1 0.5];
obj = recursiveARMAX([na nb nc nk],A0,B0,C0);

Specify the initial parameter covariance.

obj.InitialParameterCovariance = 0.1;

InitialParameterCovariance represents the uncertainty in your guess for the initial parameters. Typically, the default InitialParameterCovariance (10000) is too large relative to the parameter values. This results in initial guesses being given less importance during estimation. If you have confidence in the initial parameter guesses, specify a smaller initial parameter covariance.

Specify Estimation Method for Online Estimation of ARMAX Model

Open Live Script

Create a System object that uses the Kalman filter algorithm for online parameter estimation of an ARMAX model.

obj = recursiveARMAX([1 2 1 1],'EstimationMethod','KalmanFilter');
obj.ProcessNoiseCovariance = 0.01;

The ProcessNoiseCovariance property of obj is applicable only when the Kalman filter algorithm is used for estimation.

Input Arguments

collapse all

`Orders` — Model orders and delays
1-by-4 vector of integers

Model orders and delays of an ARMAX model, specified as a 1-by-4 vector of integers, [na nb nc nk].

na — Order of the polynomial A(q), specified as a nonnegative integer. na represents the number of poles in your system.
nb — Order of the polynomial B(q) + 1, specified as a positive integer. nb represents the number of zeroes in your system plus 1.
nc — Order of the polynomial C(q), specified as a nonnegative integer.
nk — Input-output delay, specified as a nonnegative integer. nk is number of input samples that occur before the input affects the output. nk is expressed as fixed leading zeros of the B polynomial.

`A0,B0,C0` — Initial value of polynomial coefficients
row vectors of real values | `[]`

Initial value of polynomial coefficients, specified as row vectors of real values with elements in order of ascending powers of q^-1.

A0 — Initial guess for the coefficients of the polynomial A(q), specified as a 1-by-(na+1) vector with 1 as the first element.
B0 — Initial guess for the coefficients of the polynomial B(q), specified as a 1-by-(nb+nk) vector with nk leading zeros.
C0 — Initial guess for the coefficients of the polynomial C(q), specified as a 1-by-(nc+1) vector with 1 as the first element.
The coefficients in C0 must define a stable discrete-time polynomial with roots within a unit disk. For example,
```
C0 = [1 0.5 0.5];
all(abs(roots(C0))<1)
```
```
ans =

     1
```

Specifying as [], uses the default value of eps for the polynomial coefficients.

Note

If the initial guesses are much smaller than the default InitialParameterCovariance, 10000, the initial guesses are given less importance during estimation. In that case, specify a smaller initial parameter covariance.

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.

Use Name,Value arguments to specify writable properties of recursiveARMAX System object during object creation. For example, obj = recursiveARMAX([2 2 1 1],'EstimationMethod','Gradient') creates a System object to estimate an ARMAX model using the 'Gradient' recursive estimation algorithm.

Properties

recursiveARMAX System object properties consist of read-only and writable properties. The writable properties are tunable and nontunable properties. The nontunable properties cannot be changed when the object is locked, that is, after you use the step command.

Use Name,Value arguments to specify writable properties of recursiveARMAX objects during object creation. After object creation, use dot notation to modify the tunable properties.

obj = recursiveARMAX;
obj.ForgettingFactor = 0.99;

`A`	Estimated coefficients of polynomial A(q), returned as a row vector of real values specified in order of ascending powers of q^-1. `A` is a read-only property and is initially empty after you create the object. It is populated after you use the `step` command for online parameter estimation.
`B`	Estimated coefficients of polynomial B(q), returned as a vector of real values specified in order of ascending powers of q^-1. `B` is a read-only property and is initially empty after you create the object. It is populated after you use the `step` command for online parameter estimation.
`C`	Estimated coefficients of polynomial C(q), returned as a vector of real values specified in order of ascending powers of q^-1. `C` is a read-only property and is initially empty after you create the object. It is populated after you use the `step` command for online parameter estimation.
`InitialA`	Initial values for the coefficients of polynomial A(q) of order `na`, specified as a row vector of length `na+1`, with 1 as the first element. Specify the coefficients in order of ascending powers of q^-1. If the initial guesses are much smaller than the default `InitialParameterCovariance`, 10000, the initial guesses are given less importance during estimation. In that case, specify a smaller initial parameter covariance. `InitialA` is a tunable property. You can change it when the object is in a locked state. Default: `[1 eps]`
`InitialB`	Initial values for the coefficients of polynomial B(q) of order `nb-1`, specified as a row vector of length `nb+nk`, with `nk` leading zeros. `nk` is the input-output delay. Specify the coefficients in order of ascending powers of q^-1. If the initial guesses are much smaller than the default `InitialParameterCovariance`, 10000, the initial guesses are given less importance during estimation. In that case, specify a smaller initial parameter covariance. `InitialB` is a tunable property. You can change it when the object is in a locked state. Default: `[0 eps]`
`InitialC`	Initial values for the coefficients of polynomial C(q) of order `nc`, specified as a row vector of length `nc+1`, with 1 as the first element. Specify the coefficients in order of ascending powers of q^-1. The coefficients in `InitialC` must define a stable discrete-time polynomial with roots within a unit circle. For example, InitialC = [1 0.5 0.5]; all(abs(roots(InitialC))<1) ans = 1 If the initial guesses are much smaller than the default `InitialParameterCovariance`, 10000, the initial guesses are given less importance during estimation. In that case, specify a smaller initial parameter covariance. `InitialC` is a tunable property. You can change it when the object is in a locked state. Default: `[1 eps]`
`ParameterCovariance`	Estimated covariance `P` of the parameters, returned as an N-by-N symmetric positive-definite matrix. N is the number of parameters to be estimated. The software computes `P` assuming that the residuals (difference between estimated and measured outputs) are white noise, and the variance of these residuals is 1. `ParameterCovariance` is applicable only when `EstimationMethod` is `'ForgettingFactor'` or `'KalmanFilter'`. The interpretation of `P` depends on the estimation method: `'ForgettingFactor'` — R₂`/2` * `P` is approximately equal to the covariance matrix of the estimated parameters, where R₂ is the true variance of the residuals. `'KalmanFilter'` — R₂* `P` is the covariance matrix of the estimated parameters, and R₁ /R₂ is the covariance matrix of the parameter changes. Where, R₁ is the covariance matrix that you specify in `ProcessNoiseCovariance`. `ParameterCovariance` is a read-only property and is initially empty after you create the object. It is populated after you use the `step` command for online parameter estimation.
`InitialParameterCovariance`	Covariance of the initial parameter estimates, specified as one of the following: Real positive scalar, α — Covariance matrix is an N-by-N diagonal matrix, with α as the diagonal elements. N is the number of parameters to be estimated. Vector of real positive scalars, [α₁,...,α_N] — Covariance matrix is an N-by-N diagonal matrix, with [α₁,...,α_N] as the diagonal elements. N-by-N symmetric positive-definite matrix. `InitialParameterCovariance` represents the uncertainty in the initial parameter estimates. For large values of `InitialParameterCovariance`, less importance is placed on the initial parameter values and more on the measured data during beginning of estimation using `step`. Use only when `EstimationMethod` is `'ForgettingFactor'` or `'KalmanFilter'`. `InitialParameterCovariance` is a tunable property. You can change it when the object is in a locked state. Default: `10000`
`EstimationMethod`	Recursive estimation algorithm used for online estimation of model parameters, specified as one of the following values: `'ForgettingFactor'` — Algorithm used for parameter estimation `'KalmanFilter'` — Algorithm used for parameter estimation `'NormalizedGradient'` — Algorithm used for parameter estimation `'Gradient'` — Unnormalized gradient algorithm used for parameter estimation Forgetting factor and Kalman filter algorithms are more computationally intensive than gradient and unnormalized gradient methods. However, they have better convergence properties. For information about these algorithms, see Recursive Algorithms for Online Parameter Estimation. `EstimationMethod` is a nontunable property. You cannot change it during execution, that is after the object is locked using the `step` command. If you want to deploy code using MATLAB Coder™, `EstimationMethod` can only be assigned once. Default: `'ForgettingFactor'`
`ForgettingFactor`	Forgetting factor, λ, relevant for parameter estimation, specified as a scalar in the range (0,1]. Suppose that the system remains approximately constant over T₀ samples. You can choose λ such that: $T_{0} = \frac{1}{1 - λ}$ Setting λ = 1 corresponds to “no forgetting” and estimating constant coefficients. Setting λ < 1 implies that past measurements are less significant for parameter estimation and can be “forgotten”. Set λ < 1 to estimate time-varying coefficients. Typical choices of λ are in the range `[0.98 0.995]`. Use only when `EstimationMethod` is `'ForgettingFactor'`. `ForgettingFactor` is a tunable property. You can change it when the object is in a locked state. Default: `1`
`EnableAdapation`	Enable or disable parameter estimation, specified as one of the following: `true` or `1`— The `step` command estimates the parameter values for that time step and updates the parameter values. `false` or `0` — The `step` command does not update the parameters for that time step and instead outputs the last estimated value. You can use this option when your system enters a mode where the parameter values do not vary with time. Note If you set `EnableAdapation` to `false`, you must still execute the `step` command. Do not skip `step` to keep parameter values constant, because parameter estimation depends on current and past I/O measurements. `step` ensures past I/O data is stored, even when it does not update the parameters. `EnableAdapation` is a tunable property. You can change it when the object is in a locked state. Default: `true`
`DataType`	Floating point precision of parameters, specified as one of the following values: `'double'` — Double-precision floating point `'single'` — Single-precision floating point Setting `DataType` to `'single'` saves memory, but leads to loss of precision. Specify `DataType` based on the precision required by the target processor where you will deploy generated code. `DataType` is a nontunable property. It can only be set during object construction using `Name,Value` arguments and cannot be changed afterward. Default: `'double'`
`ProcessNoiseCovariance`	Covariance matrix of parameter variations, specified as one of the following: Real nonnegative scalar, α — Covariance matrix is an N-by-N diagonal matrix, with α as the diagonal elements. Vector of real nonnegative scalars, [α₁,...,α_N] — Covariance matrix is an N-by-N diagonal matrix, with [α₁,...,α_N] as the diagonal elements. N-by-N symmetric positive semidefinite matrix. N is the number of parameters to be estimated. `ProcessNoiseCovariance` is applicable when `EstimationMethod` is `'KalmanFilter'`. Kalman filter algorithm treats the parameters as states of a dynamic system and estimates these parameters using a Kalman filter. `ProcessNoiseCovariance` is the covariance of the process noise acting on these parameters. Zero values in the noise covariance matrix correspond to estimating constant coefficients. Values larger than 0 correspond to time-varying parameters. Use large values for rapidly changing parameters. However, the larger values result in noisier parameter estimates. `ProcessNoiseCovariance` is a tunable property. You can change it when the object is in a locked state. Default: `0.1`
`AdaptationGain`	Adaptation gain, γ, used in gradient recursive estimation algorithms, specified as a positive scalar. `AdaptationGain` is applicable when `EstimationMethod` is `'Gradient'` or `'NormalizedGradient'`. Specify a large value for `AdaptationGain` when your measurements have a high signal-to-noise ratio. `AdaptationGain` is a tunable property. You can change it when the object is in a locked state. Default: `1`
`NormalizationBias`	Bias in adaptation gain scaling used in the `'NormalizedGradient'` method, specified as a nonnegative scalar. `NormalizationBias` is applicable when `EstimationMethod` is `'NormalizedGradient'`. The normalized gradient algorithm divides the adaptation gain at each step by the square of the two-norm of the gradient vector. If the gradient is close to zero, this can cause jumps in the estimated parameters. `NormalizationBias` is the term introduced in the denominator to prevent these jumps. Increase `NormalizationBias` if you observe jumps in estimated parameters. `NormalizationBias` is a tunable property. You can change it when the object is in a locked state. Default: `eps`

Output Arguments

collapse all

`obj` — System object for online parameter estimation of ARMAX model
`recursiveARMAX` System object

System object for online parameter estimation of ARMAX model, returned as a recursiveARMAX System object. This object is created using the specified model orders and properties. Use step command to estimate the coefficients of the ARMAX model polynomials. You can then access the estimated coefficients and parameter covariance using dot notation. For example, type obj.A to view the estimated A polynomial coefficients.

More About

collapse all

ARMAX Model Structure

The ARMAX (Autoregressive Moving Average with Extra Input) model structure is:

$\begin{array}{l} y (t) + a_{1} y (t - 1) + \dots + a_{n_{a}} y (t - n_{a}) = \\ b_{1} u (t - n_{k}) + \dots + b_{n_{b}} u (t - n_{k} - n_{b} + 1) + \\ c_{1} e (t - 1) + \dots + c_{n_{c}} e (t - n_{c}) + e (t) \end{array}$

A more compact way to write the difference equation is

$A (q) y (t) = B (q) u (t - n_{k}) + C (q) e (t)$

where

$y (t)$ — Output at time $t$
$n_{a}$ — Number of poles
$n_{b}$ — Number of zeroes plus 1
$n_{c}$ — Number of C coefficients
$n_{k}$ — Number of input samples that occur before the input affects the output, also called the dead time in the system
$y (t - 1) \dots y (t - n_{a})$ — Previous outputs on which the current output depends
$u (t - n_{k}) \dots u (t - n_{k} - n_{b} + 1)$ — Previous and delayed inputs on which the current output depends
$e (t - 1) \dots e (t - n_{c})$ — White-noise disturbance value

The parameters na, nb, and nc are the orders of the ARMAX model, and nk is the delay. q is the delay operator. Specifically,

$A (q) = 1 + a_{1} q^{- 1} + \dots + a_{n_{a}} q^{- n_{a}}$

$B (q) = b_{1} + b_{2} q^{- 1} + \dots + b_{n_{b}} q^{- n_{b} + 1}$

$C (q) = 1 + c_{1} q^{- 1} + \dots + c_{n_{c}} q^{- n_{c}}$

Tips

Starting in R2016b, instead of using the step command to update model parameter estimates, you can call the System object with input arguments, as if it were a function. For example, [A,B,C,EstimatedOutput] = step(obj,y,u) and [A,B,C,EstimatedOutput] = obj(y,u) perform equivalent operations.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

For Simulink-based workflows, use Recursive Polynomial Model Estimator.
For limitations, see Generate Code for Online Parameter Estimation in MATLAB.

Supports MATLAB Function block: No

Documentation

recursiveARMAX

Syntax

Description

Object Description

Examples

Estimate an ARMAX Model Online

Create System Object for ARMAX Model With Known Polynomial Orders

Create Online Estimation System Object for ARMAX Model With Known Initial Parameters

Specify Estimation Method for Online Estimation of ARMAX Model

Input Arguments

`Orders` — Model orders and delays
1-by-4 vector of integers

`A0,B0,C0` — Initial value of polynomial coefficients
row vectors of real values | `[]`

Name-Value Pair Arguments

Properties

Output Arguments

`obj` — System object for online parameter estimation of ARMAX model
`recursiveARMAX` System object

More About

ARMAX Model Structure

Tips

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

See Also

Topics

System Identification Toolbox Documentation

Support

Documentation

recursiveARMAX

Syntax

Description

Object Description

Examples

Estimate an ARMAX Model Online

Create System Object for ARMAX Model With Known Polynomial Orders

Create Online Estimation System Object for ARMAX Model With Known Initial Parameters

Specify Estimation Method for Online Estimation of ARMAX Model

Input Arguments

Orders — Model orders and delays 1-by-4 vector of integers

A0,B0,C0 — Initial value of polynomial coefficients row vectors of real values | []

Name-Value Pair Arguments

Properties

Output Arguments

obj — System object for online parameter estimation of ARMAX model recursiveARMAX System object

More About

ARMAX Model Structure

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

See Also

Topics

System Identification Toolbox Documentation

Support

`Orders` — Model orders and delays
1-by-4 vector of integers

`A0,B0,C0` — Initial value of polynomial coefficients
row vectors of real values | `[]`

`obj` — System object for online parameter estimation of ARMAX model
`recursiveARMAX` System object

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.