recursiveBJ

Online parameter estimation of Box-Jenkins model

Description

Use the recursiveBJ System object™ for parameter estimation with real-time data using an Box-Jenkins 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 bj.

To perform parameter estimation with real-time data:

Create the recursiveBJ object and set its properties.
Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

bjobj = recursiveBJ

bjobj = recursiveBJ([nb,nc,nd,nf,nk])

bjobj = recursiveBJ([nb,nc,nd,nf,nk],B0,C0,D0,F0)

bjobj = recursiveBJ(___,Name=Value)

Description

bjobj = recursiveBJ creates a System object for online parameter estimation of a default single-output Box-Jenkins model. The default model structure has a polynomial of order 1 and initial polynomial coefficient values eps.

example

bjobj = recursiveBJ([nb,nc,nd,nf,nk]) sets the orders of polynomials B, C, D, and F to nb, nc, nd, and nf, respectively. This syntax also sets the input-output delay to nk.

example

bjobj = recursiveBJ([nb,nc,nd,nf,nk],B0,C0,D0,F0) specifies the initial coefficient values of polynomials B, C, D, and F by setting the InitialB property to B0, the InitialC property to C0, the InitialD property to D0, and the InitialF property to F0. 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

bjobj = recursiveBJ(___,Name=Value) specifies one or more properties of the model structure or recursive estimation algorithm using name-value arguments. For example, bjobj = recursiveBJ(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, bjobj = recursiveBJ(2,"EstimationMethod","NormalizedGradient") creates an estimation object that uses a normalized gradient estimation method.

example

Input Arguments

expand all

`na` — Order of polynomial A(q)
`1` (default) | nonnegative integer

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

`nb` — Order of polynomial B(q) + 1
`1` (default) | nonnegative integer

Order of polynomial B(q) + 1, specified as a nonnegative integer.

`nc` — Order of polynomial C(q)
`1` (default) | nonnegative integer

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

`nk` — Input-output delay
`1` (default)

Input-output delay, specified as a nonnegative integer. nk is number of input samples that occur before the input affects the output.

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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

`B` — Estimated coefficients of polynomial B(q)
`[]` (default) | row vector

This property is read-only.

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

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

`C` — Estimated coefficients of polynomial C(q)
`[]` (default) | row vector

This property is read-only.

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.

`D` — Estimated coefficients of polynomial A(q)
`[]` (default) | row vector

This property is read-only.

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

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

`F` — Estimated coefficients of polynomial A(q)
`[]` (default) | row vector

This property is read-only.

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

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

`InitialB` — Initial coefficients of polynomial B(q)
`[0 eps]` (default) | row vector

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.

Tunable: Yes

`InitialC` — Initial coefficients of polynomial C(q)
`[1 eps]` (default) | row vector

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.

`InitialD` — Initial coefficients of polynomial D(q)
`[1 eps]` (default) | row vector

Initial values for the coefficients of polynomial D(q) of order nd, specified as a row vector of length nd +1, with 1 as the first element. Specify the coefficients in order of ascending powers of q^-1.

The coefficients in InitialD must define a stable discrete-time polynomial with roots within a unit circle.

`InitialF` — Initial coefficients of polynomial F(q)
`[1 eps]` (default) | row vector

Initial values for the coefficients of polynomial F(q) of order nf, specified as a row vector of length nf +1, with 1 as the first element. Specify the coefficients in order of ascending powers of q^-1.

The coefficients in InitialF must define a stable discrete-time polynomial with roots within a unit circle.

`ParameterCovariance` — Estimated covariance
`[]` (default) | N_p-by-N_p symmetric positive-definite matrix

This property is read-only.

Estimated covariance P of the parameters, stored as an N_p-by-N_p symmetric positive-definite matrix, where N_p 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' — R₂ * P is approximately equal to twice 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. Here, R₁ 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'.

`InitialParameterCovariance` — Covariance of initial parameter estimates
`10000` (default) | positive scalar | vector of positive scalars | symmetric positive-definite matrix

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 [α₁,...,α_N] — Covariance matrix is an N-by-N diagonal matrix in which α₁ 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'.

`EstimationMethod` — Recursive estimation algorithm
`'ForgettingFactor'` (default) | `'KalmanFilter'` | `'NormalizedGradient'` | `'Gradient'`

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.

`ForgettingFactor` — Forgetting factor for parameter estimation
`1` (default) | scalar in the range (0, 1]

Forgetting factor λ 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 λ to satisfy this condition:

$T_{0} = \frac{1}{1 - λ}$

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

`EnableAdapation` — Option to enable or disable parameter estimation
`true` (default) | `false`

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

`DataType` — Floating point precision of parameters
`'double'` (default) | `'single'`

This property is read-only.

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.

`ProcessNoiseCovariance` — Covariance matrix of parameter variations
`0.1` (default) | nonegative scalar | vector of nonegative values | N-by-N symmetric positive semidefinite matrix

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.

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

`AdaptationGain` — Adaptation gain
`1` (default) | positive scalar

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

`NormalizationBias` — Bias in adaptation gain scaling
`eps` (default) | nonegative scalar

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

[B,C,D,F,K,estimatedOutput] = bjobj(y)

Description

[B,C,D,F,K,estimatedOutput] = bjobj(y) updates and returns the parameters and output of recursiveBJ model bjobj online based on real-time output data y and input data u.

Input Arguments

expand all

`y` — Output data
real scalar

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

`u` — Input data
real scalar

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

Output Arguments

expand all

`estimatedOutput` — Estimated output
real scalar

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 recursiveBJ 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

Common to All System Objects

`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

Specific to `recursiveBJ`

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

Examples

collapse all

Estimate Box-Jenkins Polynomial Model Online

Open Live Script

Create a System object for online parameter estimation of a Box-Jenkins polynomial model.

obj = recursiveBJ;

The Box-Jenkins 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 Box-Jenkins model parameters online using step.

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

View the current estimated values of polynomial D coefficients.

obj.D

ans = 1×2

    1.0000   -0.6876

View the current covariance estimate of the parameters.

obj.ParameterCovariance

ans = 4×4

    0.0020   -0.0004   -0.0001    0.0002
   -0.0004    0.0007    0.0006   -0.0001
   -0.0001    0.0006    0.0007   -0.0000
    0.0002   -0.0001   -0.0000    0.0001

View the current estimated output.

EstimatedOutput

EstimatedOutput = 
-4.1905

Create System Object for Box-Jenkins Model with Known Orders and Delays

Open Live Script

Specify Box-Jenkins polynomial model orders and delays.

nb = 1;
nc = 1;
nd = 2;
nf = 1;
nk = 1;

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

obj = recursiveBJ([nb nc nd nf nk]);

Create System Object for Box-Jenkins Model with Known Initial Parameters

Open Live Script

Specify Box-Jenkins polynomial model orders and delays.

nb = 1;
nc = 1;
nd = 1;
nf = 2;
nk = 1;

Create a System object for online estimation of Box-Jenkins model with known initial polynomial coefficients.

B0 = [0 1];
C0 = [1 0.5];
D0 = [1 0.9];
F0 = [1 0.7 0.8];
obj = recursiveBJ([nb nc nd nf nk],B0,C0,D0,F0);

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 Box-Jenkins Model

Open Live Script

Create a System object that uses the normalized gradient algorithm for online parameter estimation of a Box-Jenkins model.

obj = recursiveBJ([1 1 1 2 1],'EstimationMethod','NormalizedGradient');

More About

expand all

Box-Jenkins Polynomial Model Structure

The general Box-Jenkins model structure is:

$y (t) = \sum_{i = 1}^{n u} \frac{B_{i} (q)}{F_{i} (q)} u_{i} (t - n k_{i}) + \frac{C (q)}{D (q)} e (t)$

where nu is the number of input channels.

The orders of Box-Jenkins model are defined as follows:

$\begin{matrix} n b : B (q) = b_{1} + b_{2} q^{- 1} + ... + b_{n b} q^{- n b + 1} \\ n c : C (q) = 1 + c_{1} q^{- 1} + ... + c_{n c} q^{- n c} \\ n d : D (q) = 1 + d_{1} q^{- 1} + ... + d_{n d} q^{- n d} \\ n f : F (q) = 1 + f_{1} q^{- 1} + ... + f_{n f} q^{- n f} \end{matrix}$

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

Version History

Introduced in R2015b

recursiveBJ

Description

Creation

Syntax

Description

Input Arguments

na — Order of polynomial A(q) 1 (default) | nonnegative integer

nb — Order of polynomial B(q) + 1 1 (default) | nonnegative integer

nc — Order of polynomial C(q) 1 (default) | nonnegative integer

nk — Input-output delay 1 (default)

Properties

B — Estimated coefficients of polynomial B(q) [] (default) | row vector

C — Estimated coefficients of polynomial C(q) [] (default) | row vector

D — Estimated coefficients of polynomial A(q) [] (default) | row vector

F — Estimated coefficients of polynomial A(q) [] (default) | row vector

InitialB — Initial coefficients of polynomial B(q) [0 eps] (default) | row vector

InitialC — Initial coefficients of polynomial C(q) [1 eps] (default) | row vector

InitialD — Initial coefficients of polynomial D(q) [1 eps] (default) | row vector

InitialF — Initial coefficients of polynomial F(q) [1 eps] (default) | row vector

ParameterCovariance — Estimated covariance [] (default) | Np-by-Np symmetric positive-definite matrix

Dependencies

InitialParameterCovariance — Covariance of initial parameter estimates 10000 (default) | positive scalar | vector of positive scalars | symmetric positive-definite matrix

Dependency

EstimationMethod — Recursive estimation algorithm 'ForgettingFactor' (default) | 'KalmanFilter' | 'NormalizedGradient' | 'Gradient'

ForgettingFactor — Forgetting factor for parameter estimation 1 (default) | scalar in the range (0, 1]

Dependencies

EnableAdapation — Option to enable or disable parameter estimation true (default) | false

DataType — Floating point precision of parameters 'double' (default) | 'single'

ProcessNoiseCovariance — Covariance matrix of parameter variations 0.1 (default) | nonegative scalar | vector of nonegative values | N-by-N symmetric positive semidefinite matrix

Dependencies

AdaptationGain — Adaptation gain 1 (default) | positive scalar

Dependencies

NormalizationBias — Bias in adaptation gain scaling eps (default) | nonegative scalar

Dependencies

Usage

Syntax

Description

Input Arguments

y — Output data real scalar

u — Input data real scalar

Output Arguments

estimatedOutput — Estimated output real scalar

Object Functions

Common to All System Objects

Specific to recursiveBJ

Examples

Estimate Box-Jenkins Polynomial Model Online

Create System Object for Box-Jenkins Model with Known Orders and Delays

Create System Object for Box-Jenkins Model with Known Initial Parameters

Specify Estimation Method for Online Estimation of Box-Jenkins Model

More About

Box-Jenkins Polynomial Model Structure

Extended Capabilities

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

Version History

See Also

Functions

Objects

Blocks

Topics

`na` — Order of polynomial A(q)
`1` (default) | nonnegative integer

`nb` — Order of polynomial B(q) + 1
`1` (default) | nonnegative integer

`nc` — Order of polynomial C(q)
`1` (default) | nonnegative integer

`nk` — Input-output delay
`1` (default)

`B` — Estimated coefficients of polynomial B(q)
`[]` (default) | row vector

`C` — Estimated coefficients of polynomial C(q)
`[]` (default) | row vector

`D` — Estimated coefficients of polynomial A(q)
`[]` (default) | row vector

`F` — Estimated coefficients of polynomial A(q)
`[]` (default) | row vector

`InitialB` — Initial coefficients of polynomial B(q)
`[0 eps]` (default) | row vector

`InitialC` — Initial coefficients of polynomial C(q)
`[1 eps]` (default) | row vector

`InitialD` — Initial coefficients of polynomial D(q)
`[1 eps]` (default) | row vector

`InitialF` — Initial coefficients of polynomial F(q)
`[1 eps]` (default) | row vector

`ParameterCovariance` — Estimated covariance
`[]` (default) | N_p-by-N_p symmetric positive-definite matrix

`InitialParameterCovariance` — Covariance of initial parameter estimates
`10000` (default) | positive scalar | vector of positive scalars | symmetric positive-definite matrix

`EstimationMethod` — Recursive estimation algorithm
`'ForgettingFactor'` (default) | `'KalmanFilter'` | `'NormalizedGradient'` | `'Gradient'`

`ForgettingFactor` — Forgetting factor for parameter estimation
`1` (default) | scalar in the range (0, 1]

`EnableAdapation` — Option to enable or disable parameter estimation
`true` (default) | `false`

`DataType` — Floating point precision of parameters
`'double'` (default) | `'single'`

`ProcessNoiseCovariance` — Covariance matrix of parameter variations
`0.1` (default) | nonegative scalar | vector of nonegative values | N-by-N symmetric positive semidefinite matrix

`AdaptationGain` — Adaptation gain
`1` (default) | positive scalar

`NormalizationBias` — Bias in adaptation gain scaling
`eps` (default) | nonegative scalar

`y` — Output data
real scalar

`u` — Input data
real scalar

`estimatedOutput` — Estimated output
real scalar

Specific to `recursiveBJ`

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