recursiveOE
Online parameter estimation of output-error polynomial model
Description
Use the recursiveOE
System object™ for parameter estimation with real-time data using an output-error 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 oe
.
To perform parameter estimation with real-time data:
Create the
recursiveOE
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
Description
creates a System object for online parameter estimation of a default single-output output-error
model. The default model structure has a polynomial of order 1 and initial polynomial
coefficient values oeobj
= recursiveOEeps
.
specifies the initial coefficient values of polynomials oeobj
= recursiveOE([na
,nb
,nf
],B0
,F0
)B
and
F
by setting the InitialB
property to
B0
, 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
.
specifies one or more properties of the model
structure or recursive estimation algorithm using name-value arguments. For example,
oeobj
= recursiveOE(___,Name=Value
)oeobj = recursiveOE(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, oeobj =
recursiveOE(2,"EstimationMethod","NormalizedGradient")
creates an estimation
object that uses a normalized gradient estimation method.
Input Arguments
nb
— Order of polynomial B(q) + 1
1
(default) | nonnegative integer
Order of polynomial B(q) + 1, specified as a nonnegative integer.
nf
— 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
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.
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
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.
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.
InitialOutputs
— Initial values of output buffer in finite-history estimation
0
(default) | column vector of real values
Initial values of the output buffer in finite-history estimation, specified as
0
or a (W + nf
)-by-1
vector, W is equal to WindowLength
.
Use this property to control the initial behavior of the algorithm.
When you set InitialOutputs
to 0
, the object
populates the buffer with zeros.
If you set the initial buffer to 0
or if the buffer does not
contain enough information, you see a warning message during the initial phase of your
estimation. The warning usually clears after a few cycles. The number of cycles required
to buffer sufficient information depends on the order of your polynomials and your input
delays. If the warning persists, evaluate the content of your signals.
Tunable: Yes
Dependencies
To enable this property, set History
to
'Finite'
.
InitialInputs
— Initial values of input buffer in finite-history estimation
0
(default) | column vector of real values
Initial values of the inputs in the finite history window, specified as
0
or as a
(W-1+max(nb
)+max(nk
))-by-Nuu
matrix, where W is equal to WindowLength
and
Nu is the number of inputs.
Use this property to control the initial behavior of the algorithm.
When you set InitialInputs
to 0
, the object
populates the buffer with zeros.
If the initial buffer is set to 0
or does not contain enough
information, you see a warning message during the initial phase of your estimation. The
warning should clear after a few cycles. The number of cycles it takes for sufficient
information to be buffered depends upon the order of your polynomials and your input
delays. If the warning persists, you should evaluate the content of your signals.
Dependencies
To enable this property, set History
to
'Finite'
.
ParameterCovariance
— Estimated covariance
[]
(default) | Np-by-Np symmetric positive-definite matrix
This property is read-only.
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 your settings for the History
and EstimationMethod
properties.
If you set
History
to'Infinite'
andEstimationMethod
to:'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 inProcessNoiseCovariance
.
If
History
is'Finite'
(sliding-window estimation) — R2P is the covariance of the estimated parameters. The sliding-window algorithm does not use this covariance in the parameter-estimation process. However, the algorithm does compute the covariance for output so that you can use it for statistical evaluation.
ParameterCovariance
is initially empty when you create the object and is populated after you run the online parameter estimation.
Dependencies
To enable this property, use one of the following configurations:
Set
History
to'Finite'
.Set
History
to'Infinite'
and setEstimationMethod
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 [α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, use one of the following configurations:
Set
History
to'Finite'
.Set
History
to'Infinite'
and setEstimationMethod
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:
'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.
Dependencies
To enable this property, set History
to
'Infinite'
.
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 T0 samples. You can choose λ to satisfy this condition:
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 History
to
'Infinite'
and 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
— Thestep
function estimates the parameter values for that time step and updates the parameter values.false
— Thestep
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
tofalse
, you must still execute thestep
command. Do not skipstep
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, [α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'
.
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 History
to
'Infinite'
and 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 History
to
'Infinite'
and set EstimationMethod
to
'NormalizedGradient'
.
History
— Data history type
'Infinite'
(default) | 'Finite'
This property is read-only.
Data history type, which defines the type of recursive algorithm to use, specified as one of the following:
'Infinite'
— Use an algorithm that aims to minimize the error between the observed and predicted outputs for all time steps from the beginning of the simulation.'Finite'
— Use an algorithm that aims to minimize the error between the observed and predicted outputs for a finite number of past time steps.
Algorithms with infinite history aim to produce parameter estimates that explain all data since the start of the simulation. These algorithms still use a fixed amount of memory that does not grow over time. To select an infinite-history algorithm, use EstimationMethod
.
Algorithms with finite history aim to produce parameter estimates that explain only a finite number of past data samples. This method is also called sliding-window estimation. The object provides one finite-history algorithm. To define the window size, specify the WindowLength
property.
For more information on recursive estimation methods, see Recursive Algorithms for Online Parameter Estimation.
You must set History
during object creation using a name-value argument.
WindowLength
— Window size
200
(default) | positive integer
This property is read-only.
Window size for finite-history estimation, specified as a positive integer indicating the number of samples.
Choose a window size that balances estimation performance with computational and memory burden. Sizing factors include the number and time variance of the parameters in your model. WindowLength
must be greater than or equal to the number of estimated parameters.
Suitable window length is independent of whether you are using sample-based or frame-based input processing (see InputProcessing
). However, when using frame-based processing, your window length must be greater than or equal to the number of samples (time steps) contained in the frame.
You must set WindowLength
during object creation using a name-value argument.
Dependencies
To enable this property, set History
to 'Finite'
.
InputProcessing
— Input processing method
'Sample-based'
(default) | 'Frame-based'
This property is read-only.
Input processing method, specified as one of the following:
'Sample-based'
— Process streamed signals one sample at a time.'Frame-based'
— Process streamed signals in frames that contain samples from multiple time steps. Many machine sensor interfaces package multiple samples and transmit these samples together in frames.'Frame-based'
processing allows you to input this data directly without having to first unpack it.
The InputProcessing
property impacts the dimensions for the
input and output signals when using the recursive estimator object.
Sample-based
y
,u
, andestimatedOutput
are scalars.
Frame-based
with M samples per framey
,u
, andestimatedOutput
are M-by-1 vectors.
You must set InputProcessing
during object creation using a
name-value argument.
Usage
Description
[
updates and returns the parameters and output of B
,F
,estimatedOutput
] = oeobj(y
)recursiveOE
model
oeobj
online based on real-time output data y
and input data u
.
Input Arguments
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
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 recursiveOE
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)
Examples
Estimate Output-Error Polynomial Model Online
Create a System object for online parameter estimation of a Output-Error polynomial model using recursive estimation algorithms.
obj = recursiveOE;
The Output-Error 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 Output-Error model parameters online using step
.
for i = 1:numel(input) [B,F,EstimatedOutput] = step(obj,output(i),input(i)); end
View the current estimated values of polynomial F
coefficients.
obj.F
ans = 1×2
1.0000 -0.7618
View the current covariance estimate of the parameters.
obj.ParameterCovariance
ans = 2×2
0.0024 0.0002
0.0002 0.0001
View the current estimated output.
EstimatedOutput
EstimatedOutput = -4.1866
Create System Object for Output-Error Model with Known Orders and Delays
Specify Output-Error polynomial model orders and delays.
nb = 1; nf = 2; nk = 1;
Create a System object for online estimation of Output-Error polynomial model with the specified orders and delays.
obj = recursiveOE([nb nf nk]);
Create System Object for Output-Error Model with Known Initial Parameters
Specify Output-Error polynomial model orders and delays.
nb = 1; nf = 2; nk = 1;
Create a System object for online estimation of Output-Error model with known initial polynomial coefficients.
B0 = [0 1]; F0 = [1 0.7 0.8]; obj = recursiveOE([nb nf nk],B0,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 Output-Error Model
Create a System object that uses the unnormalized gradient algorithm for online parameter estimation of an Output-Error model.
obj = recursiveOE([1 2 1],'EstimationMethod','Gradient');
More About
Output-Error Model Structure
The general output-error model structure is:
The orders of the output-error model are:
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
See Also
Functions
Objects
Blocks
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)