# recursiveLS

Create System object for online parameter estimation using recursive least squares algorithm

## Syntax

```obj = recursiveLS obj = recursiveLS(Np) obj = recursiveLS(Np,theta0) obj = recursiveLS(___,Name,Value) ```

## Description

Use the `recursiveLS` 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 `mldivide, \`.

`obj = recursiveLS` creates a System object™ for online parameter estimation of a default single output system that is linear in estimated parameters. Such a system can be represented as:

y(t) = H(t)θ(t)+e(t).

Here, y is the output, θ are the parameters, H are the regressors, and e is the white-noise disturbance. The default system has one parameter with initial parameter value `1`.

After creating the object, use the `step` command to update model parameter estimates using recursive least squares algorithms and real-time data. Alternatively, you can call the object directly. For more information, see Tips.

`obj = recursiveLS(Np)` also specifies the number of parameters to be estimated.

`obj = recursiveLS(Np,theta0)` also specifies the number of parameters and initial values of the parameters.

`obj = recursiveLS(___,Name,Value)` specifies additional attributes of the system and recursive estimation algorithm using one or more `Name,Value` pair arguments.

## Object Description

`recursiveLS` creates a System object for online parameter estimation of a single output system that is linear in its parameters.

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™:

CommandDescription
`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 `recursiveLS` command to create an online estimation System object. Then estimate the system parameters (`theta`) and output using the `step` command with regressors and incoming output data, `H` and `y`.

`[theta,EstimatedOutput] = step(obj,y,H)`

For `recursiveLS` object properties, see Properties.

## Examples

collapse all

`obj = recursiveLS`
```obj = recursiveLS with properties: NumberOfParameters: 1 Parameters: [] InitialParameters: 1 ParameterCovariance: [] InitialParameterCovariance: 10000 EstimationMethod: 'ForgettingFactor' ForgettingFactor: 1 EnableAdaptation: true History: 'Infinite' InputProcessing: 'Sample-based' DataType: 'double' ```

The system has two parameters and is represented as:

`$\mathit{y}\left(\mathit{t}\right)={\mathit{a}}_{1}\mathit{u}\left(\mathit{t}\right)+{\mathit{a}}_{2}\mathit{u}\left(\mathit{t}-1\right)$`

Here,

• $\mathit{u}$ and $y$ are the real-time input and output data, respectively.

• $\mathit{u}\left(\mathit{t}\right)$ and $\mathit{u}\left(\mathit{t}-1\right)$ are the regressors, `H`, of the system.

• ${\mathit{a}}_{1}$ and ${\mathit{a}}_{2}$ are the parameters, `theta`, of the system.

Create a System object for online estimation using the recursive least squares algorithm.

`obj = recursiveLS(2);`

Load the estimation data, which for this example is a static data set.

```load iddata3 input = z3.u; output = z3.y;```

Create a variable to store `u(t-1)`. This variable is updated at each time step.

`oldInput = 0;`

Estimate the parameters and output using `step` and input-output data, maintaining the current regressor pair in `H`. Invoke the `step` function implicitly by calling the `obj` system object with input arguments.

```for i = 1:numel(input) H = [input(i) oldInput]; [theta, EstimatedOutput] = obj(output(i),H); estimatedOut(i)= EstimatedOutput; theta_est(i,:) = theta; oldInput = input(i); end```

Plot the measured and estimated output data.

```numSample = 1:numel(input); plot(numSample,output,'b',numSample,estimatedOut,'r--'); legend('Measured Output','Estimated Output');```

Plot the parameters.

```plot(numSample,theta_est(:,1),numSample,theta_est(:,2)) title('Parameter Estimates for Recursive Least Squares Estimation') legend("theta1","theta2")```

View the final estimates.

`theta_final = theta`
```theta_final = 2×1 -1.5322 -0.0235 ```

Use frame-based signals with the `recursiveLS` command. Machine interfaces often provide sensor data in frames containing multiple samples, rather than in individual samples. The `recursiveLS` object accepts these frames directly when you set `InputProcessing` to `Frame-based`.

The object uses the same estimation algorithms for sample-based and frame-based input processing. The estimation results are identical. There are some special considerations, however, for working with frame-based inputs.

This example is the frame-based version of the sample-based `recursiveLS` example in Estimate Parameters of System Using Recursive Least Squares Algorithm.

The system has two parameters and is represented as:

`$\mathit{y}\left(\mathit{t}\right)={\mathit{a}}_{1}^{}\mathit{u}\left(\mathit{t}\right)+{\mathit{a}}_{2}^{}\mathit{u}\left(\mathit{t}-1\right)$`

Here,

• $\mathit{u}$ and $y$ are the real-time input and output data, respectively.

• $\mathit{u}\left(\mathit{t}\right)$ and $\mathit{u}\left(\mathit{t}-1\right)$ are the regressors, `H`, of the system.

• ${\mathit{a}}_{1}^{}$ and ${\mathit{a}}_{2}^{}$ are the parameters,$\theta$, of the system.

Create a System object for online estimation using the recursive least squares algorithm.

`obj_f = recursiveLS(2,'InputProcessing','Frame-Based');`

Load the data, which contains input and output time series signals. Each signal consists of 30 frames and each frame contains ten individual time samples.

```load iddata3_frames input_sig_frame output_sig_frame input = input_sig_frame.data; output = output_sig_frame.data; numframes = size(input,3)```
```numframes = 30 ```
`mframe = size(input,1)`
```mframe = 10 ```

Initialize the regressor frame, which for a given frame, is of the form

${H}_{f}=\left[\begin{array}{cc}{u}_{1}& {u}_{0}\\ {u}_{2}& {u}_{1}\\ ⋮& ⋮\\ {u}_{10}& {u}_{9}\end{array}\right]$,

where the most recent point in the frame is ${\mathit{u}}_{10}^{}$.

`Hframe = zeros(10,2);`

For this first-order example, the regressor frame includes one point from the previous frame. Initialize this point.

`oldInput = 0;`

Estimate the parameters and output using `step` and input-output data, maintaining the current regressor frame in `Hframe`.

• The input and output arrays have three dimensions. The third dimension is the frame index, and the first two dimensions represent the contents of individual frames.

• Use the `circshift` function to populate the second column of `Hframe` with the past `input` value for each regressor pair by shifting the input vector by one position.

• Populate the `Hframe `element holding the oldest value, `Hframe(1,2),` with the regressor value stored from the previous frame.

• Invoke the `step` function implicitly by calling the `obj` system object with input arguments. The `step` function is compatible with frames, so no loop function within the frame is necessary.

• Save the most recent input value to use for the next frame calculation.

```EstimatedOutput = zeros(10,1,30); theta = zeros(2,30); for i = 1:numframes Hframe = [input(:,:,i) circshift(input(:,:,i),1)]; Hframe(1,2) = oldInput; [theta(:,i), EstimatedOutput(:,:,i)] = obj_f(output(:,:,i),Hframe); oldInput = input(10,:,i); end```

Plot the parameters.

```theta1 = theta(1,:); theta2 = theta(2,:); iframe = 1:numframes; plot(iframe,theta1,iframe,theta2) title('Frame-Based Recursive Least Squares Estimation') legend('theta1','theta2','location','best')```

View the final estimates.

`theta_final = theta(:,numframes)`
```theta_final = 2×1 -1.5322 -0.0235 ```

The final estimates are identical to the sample-based estimation.

Create System object for online parameter estimation using recursive least squares algorithm of a system with two parameters and known initial parameter values.

`obj = recursiveLS(2,[0.8 1],'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.

## Input Arguments

collapse all

Number of parameters in the system, specified as a positive integer.

Initial value of parameters, specified as one of the following:

• Scalar — All the parameters have the same initial value.

• Vector of real values of length `Np`— The ith parameter has initial value `theta0(i)`.

The default initial value for all parameters is `1`.

### Note

If the initial parameter values are much smaller than `InitialParameterCovariance`, these initial values are given less importance during estimation. Specify a smaller initial parameter covariance if you have high confidence in the initial parameter values. This statement applies only for infinite-history estimation. Finite-history estimation does not use `InitialParameterCovariance`.

### 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 `recursiveLS` System object during object creation. For example, `obj = recursiveLS(2,'EstimationMethod','Gradient')` creates a System object to estimate the system parameters using the `'Gradient'` recursive estimation algorithm.

## Properties

`recursiveLS` 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 `recursiveLS` objects during object creation. After object creation, use dot notation to modify the tunable properties.

```obj = recursiveLS; obj.ForgettingFactor = 0.99;```

`NumberOfParameters`

Number of parameters to be estimated, returned as a positive integer.

`NumberOfParameters` is a read-only property. If `Np` is specified during object construction, `NumberOfParameters` takes the value assigned to `Np`.

Default: `1`

`Parameters`

Estimated parameters, returned as a column vector of real values.

`Parameters` 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.

`InitialParameters`

Initial values of parameters, specified as one of the following:

• Scalar — All the parameters have the same initial value.

• Vector of real values of length `Np`— The ith parameter has initial value `InitialParameters(i)`.

If the initial parameter values are much smaller than `InitialParameterCovariance`, these initial values are given less importance during estimation. Specify a smaller initial parameter covariance if you have high confidence in initial parameter values. This statement applies only for infinite-history estimation. Finite-history estimation does not use `InitialParameterCovariance`.

`InitialParameters` is a tunable property. You can change `InitialParameters` when the object is in a locked state.

Default: `1`

`InitialOutputs`

Initial values of the outputs buffer in finite-history estimation, specified as `0` or as a W-by-1 vector, where W is the window length.

The `InitialOutputs` property provides a means of controlling the initial behavior of the algorithm.

When `InitialOutputs` is set 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.

Specify `InitialOutputs` only when `History` is `Finite`.

`InitialOutputs` is a tunable property. You can change `InitialOutputs` when the object is in a locked state.

Default: `0`

`InitialRegressors`

Initial values of the regressors buffer in finite-history estimation, specified as `0` or as a W-by-`Np` matrix, where W is the window length and `Np` is the number of parameters.

The `InitialRegressors` property provides a means of controlling the initial behavior of the algorithm.

When the `InitialRegressors` is set 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.

Specify `InitialRegressors` only when `History` is `Finite`.

`InitialRegressors` is a tunable property. You can change `InitialRegressors` when the object is in a locked state.

Default: `0`

`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'` or when `History` is `Finite`.

The interpretation of `P` depends on your settings for the `History` and `EstimationMethod` properties.

• If `History` is `Infinite`, then your `EstimationMethod` selection results in one of the following:

• `'ForgettingFactor'` — (R2`/2`)`P` is approximately equal to 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`.

• If `History` is `Finite` (sliding-window estimation) — R2`P` 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 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, [α1,...,αN] — Covariance matrix is an N-by-N diagonal matrix, with [α1,...,α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 least squares 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.

These methods all use an infinite data history, and are available only when `History` is `'Infinite'`.

`EstimationMethod` is a nontunable property. You cannot change it during execution, that is, after the object is locked using the `step` command.

Default: `Forgetting Factor`

`ForgettingFactor`

Forgetting factor, λ, relevant 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 λ such that:

`${T}_{0}=\frac{1}{1-\lambda }$`
• 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, [α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.

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

`History`

Data history type defining which type of recursive algorithm you use, specified as:

• `'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. The object provides multiple algorithms of the `'Infinite'` `History` type. Specifying this option activates the `EstimationMethod` property with which you specify an algorithm.

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 algorithm of the `'Finite'` type. Specifying this option activates the `WindowLength` property that sizes the window.

For more information on recursive estimation methods, see Recursive Algorithms for Online Parameter Estimation.

`History` is a nontunable property. It can be set only during object construction using `Name,Value` arguments and cannot be changed afterward.

Default: `'Infinite'`

`WindowLength`

Window size determining the number of time samples to use for the sliding-window estimation method, specified as a positive integer. Specify `WindowLength` only when `History` is `Finite`.

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. Always specify Window Length in samples, even if you are using frame-based input processing.

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

`WindowLength` is a nontunable property. It can be set only during object construction using `Name,Value` arguments and cannot be changed afterward.

Default: `200`

`InputProcessing`

Option for sample-based or frame-based input processing, specified as a character vector or string.

• `Sample-based` processing operates on signals streamed one sample at a time.

• `Frame-based` processing operates on signals containing 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.

Your `InputProcessing` specification impacts the dimensions for the input and output signals when using the `step` command:

`[theta,EstimatedOutput] = step(obj,y,H)`

• `Sample-based`

• `y` and `EstimatedOutput` are scalars.

• `H` is a 1-by-`Np` vector, where `Np` is the number of parameters.

• `Frame-based` with M samples per frame

• `y` and `EstimatedOutput` are M-by-1 vectors.

• `H` is an M-by-`Np` matrix.

`InputProcessing` is a nontunable property. It can be set only during object construction using `Name,Value` arguments and cannot be changed afterward.

Default: `'Sample-based'`

## Output Arguments

collapse all

System object for online parameter estimation, returned as a `recursiveLS` System object. Use `step` command to estimate the parameters of the system. You can then access the estimated parameters and parameter covariance using dot notation. For example, type `obj.Parameters` to view the estimated parameters.

## 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, ```[theta,EstimatedOutput] = step(obj,y,H)``` and `[theta,EstimatedOutput] = obj(y,H)` perform equivalent operations.

Get trial now