# recursiveARMA

Online parameter estimation of ARMA model

## Description

Use the `recursiveARMA` System object™ for parameter estimation with real-time data using an ARMA model structure. If all the data you need for estimation is available at once and you are estimating a time-invariant model, use the offline estimation function `ar`.

To perform parameter estimation with real-time data:

1. Create the `recursiveARMA` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``armaobj = recursiveARMA``
``armaobj = recursiveARMA([na,nc])``
``armaobj = recursiveARMA([na,nc],A0,C0)``
``armaobj = recursiveARMA(___,Name=Value)``

### Description

example

````armaobj = recursiveARMA` creates a System object for online parameter estimation of a default single-output ARMA model. The default model structure has a polynomial of order 1 and initial polynomial coefficient values `eps`.```

example

````armaobj = recursiveARMA([na,nc])` sets the orders of polynomials `A` and `C` to `na` and `nc`, respectively.```

example

````armaobj = recursiveARMA([na,nc],A0,C0)` specifies the initial coefficient values of polynomials `A` and `C` by setting the `InitialA` property to `A0` and the `InitialC` property to `C0`. 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, specify a smaller `InitialParameterCovariance`.```

example

````armaobj = recursiveARMA(___,Name=Value)` specifies one or more properties of the model structure or recursive estimation algorithm using name-value arguments. For example, `armaobj = recursiveARMA(2,EstimationMethod="NormalizedGradient")` creates an estimation object that uses a normalized gradient estimation method.Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes. For example, ```armaobj = recursiveARMA(2,"EstimationMethod","NormalizedGradient")``` creates an estimation object that uses a normalized gradient estimation method.```

### Input Arguments

expand all

Order of polynomial A(q), specified as a nonnegative integer.

Order of polynomial C(q), specified as a nonnegative integer.

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Estimated coefficients of the polynomial A(q), returned as a row vector. The elements of this vector appear in order of ascending powers of q-1.

`A` is initially empty when you create the object and is populated after you run the online parameter estimation.

Estimated coefficients of polynomial C(q), returned as a vector. The elements of this vector appear in order of ascending powers of q-1.

`C` is initially empty when you create the object and is populated after you run the online parameter estimation.

Initial coefficients of the polynomial A(q), specified as a row vector. The length of this vector must be `na` + 1, where `na` is the order of A(q). The first element of this vector must be `1`. Specify the coefficients in ascending powers of q-1.

If the initial guesses are much smaller than the default `InitialParameterCovariance` value of 10000, the software accords less importance to the initial guesses during estimation. In that case, specify a smaller initial parameter covariance.

Tunable: Yes

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.

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.

Estimated covariance `P` of the parameters, stored as an Np-by-Np symmetric positive-definite matrix, where Np 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.

The interpretation of `P` depends on the estimation method. When `EstimationMethod` is:

• `'ForgettingFactor'`R2 * P is approximately equal to twice the covariance matrix of the estimated parameters, where R2 is the true variance of the residuals.

• `'KalmanFilter'`R2 * P is the covariance matrix of the estimated parameters, and R1 /R2 is the covariance matrix of the parameter changes. Here, R1 is the covariance matrix that you specify in `ProcessNoiseCovariance`.

`ParameterCovariance` is initially empty when you create the object and is populated after you run the online parameter estimation.

#### Dependencies

To enable this property, set `EstimationMethod` to either `'ForgettingFactor'` or `'KalmanFilter'`.

Covariance of the initial parameter estimates, specified as one of these values:

• Real positive scalar α — Covariance matrix is an N-by-N diagonal matrix in which α is each diagonal element. N is the number of parameters to be estimated.

• Vector of real positive scalars [α1,...,αN] — Covariance matrix is an N-by-N diagonal matrix in which α1 through αN] are the diagonal elements.

• N-by-N symmetric positive-definite matrix.

`InitialParameterCovariance` represents the uncertainty in the initial parameter estimates. For large values of `InitialParameterCovariance`, the software accords less importance to the initial parameter values and more importance to the measured data during the beginning of estimation.

Tunable: Yes

#### Dependency

To enable this property, set `EstimationMethod` to either `'ForgettingFactor'` or `'KalmanFilter'`.

Recursive estimation algorithm used for online estimation of model parameters, specified as one of the following values:

• `'ForgettingFactor'` — Use forgetting factor algorithm for parameter estimation.

• `'KalmanFilter'` — Use Kalman filter algorithm for parameter estimation.

• `'NormalizedGradient'` — Use normalized gradient algorithm for parameter estimation.

• `'Gradient'` — Use unnormalized gradient algorithm for parameter estimation.

Forgetting factor and Kalman filter algorithms are more computationally intensive than gradient and unnormalized gradient methods. However, the former algorithms have better convergence properties. For information about these algorithms, see Recursive Algorithms for Online Parameter Estimation.

If you want to deploy code using MATLAB® Coder™, `EstimationMethod` can only be assigned once.

Forgetting factor λ for parameter estimation, specified as a scalar in the range (0, 1].

Suppose that the system remains approximately constant over T0 samples. You can choose λ to satisfy this condition:

`${T}_{0}=\frac{1}{1-\lambda }$`
• Setting λ to 1 corresponds to "no forgetting" and estimating constant coefficients.

• Setting λ to a value less than 1 implies that past measurements are less significant for parameter estimation and can be "forgotten". Set λ to a value less than 1 to estimate time-varying coefficients.

Typical choices of λ are in the range [0.98, 0.995].

Tunable: Yes

#### Dependencies

To enable this property, set `EstimationMethod` to `'ForgettingFactor'`.

Option to enable or disable parameter estimation, specified as one of the following:

• `true` — The `step` function estimates the parameter values for that time step and updates the parameter values.

• `false` — The `step` function 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.

Tunable: Yes

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.

You must set `DataType` during object creation using a name-value argument.

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, [α1,...,αN] — Covariance matrix is an N-by-N diagonal matrix, with [α1,...,αN] as the diagonal elements.

• N-by-N symmetric positive semidefinite matrix.

N is the number of parameters to be estimated.

The 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.

Tunable: Yes

#### Dependencies

To enable this property, set `History` to `'Infinite'` and set `EstimationMethod` to `'KalmanFilter'`.

Adaptation gain, γ, used in gradient recursive estimation algorithms, specified as a positive scalar.

Specify a large value for `AdaptationGain` when your measurements have a high signal-to-noise ratio.

Tunable: Yes

#### Dependencies

To enable this property, set `EstimationMethod` to either `'Gradient'` or `'NormalizedGradient'`.

Bias in adaptation gain scaling used in the `'NormalizedGradient'` method, specified as a nonnegative scalar.

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 division can cause jumps in the estimated parameters. `NormalizationBias` is the term introduced in the denominator to prevent such jumps. If you observe jumps in estimated parameters, increase `NormalizationBias`.

Tunable: Yes

#### Dependencies

To enable this property, set `EstimationMethod` to `'NormalizedGradient'`.

## Usage

### Syntax

``[A,C,estimatedOutput] = armaobj(y)``

### Description

````[A,C,estimatedOutput] = armaobj(y)` updates and returns the coefficients and output of `recursiveARMA` model `armaobj` based on real-time output data `y`.```

### Input Arguments

expand all

Output data acquired in real time, specified as a real scalar.

### Output Arguments

expand all

Estimated output, returned as a real scalar. The output is estimated using input-output estimation data, current parameter values, and the recursive estimation algorithm specified in the `recursiveARMA` System object.

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

expand all

 `clone` Create duplicate System object `isLocked` Determine if System object is in use

## Examples

collapse all

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

`obj = recursiveARMA;`

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

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

```load iddata9 z9; output = z9.y;```

Estimate ARMA model parameters online using `step`.

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

View the current estimated values of polynomial `C` coefficients.

`obj.C`
```ans = 1×2 1.0000 0.2315 ```

View the current covariance estimate of the parameters.

`obj.ParameterCovariance`
```ans = 2×2 10-3 × 0.6372 -0.0257 -0.0257 0.0017 ```

View the current estimated output.

`EstimatedOutput`
```EstimatedOutput = 11.8121 ```

Specify ARMA model orders.

```na = 2; nc = 1;```

Create a System object for online estimation of an ARMA model with the specified orders.

`obj = recursiveARMA([na nc]);`

Specify ARMA model orders.

```na = 2; nc = 1;```

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

```A0 = [1 0.5 0.3]; C0 = [1 0.7]; obj = recursiveARMA([na nc],A0,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.

Create a System object that uses the unnormalized gradient algorithm for online parameter estimation of an ARMA model.

`obj = recursiveARMA([2 1],'EstimationMethod','Gradient');`