# dsp.KalmanFilter

(To be removed) Estimate system measurements and states using Kalman filter

`dsp.KalmanFilter` will be removed in a future release. Use the Kalman filter functionality in Sensor Fusion and Tracking Toolbox™ instead.

## Description

The `dsp.KalmanFilter` System object™ is an estimator used to recursively obtain a solution for linear optimal filtering. This estimation is made without precise knowledge of the underlying dynamic system. The Kalman filter implements the following linear discrete-time process with state, x, at the kth time-step: $x\left(k\right)=Ax\left(k-1\right)+Bu\left(k-1\right)+w\left(k-1\right)$ (state equation). This measurement, z, is given as: $z\left(k\right)=Hx\left(k\right)+v\left(k\right)$ (measurement equation).

The Kalman filter algorithm computes the following two steps recursively:

• Prediction: Process parameters x (state) and P (state error covariance) are estimated using the previous state.

• Correction: The state and error covariance are corrected using the current measurement.

To filter each channel of the input:

1. Create the `dsp.KalmanFilter` object and set its properties.

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

## Creation

### Syntax

``kalman = dsp.KalmanFilter``
``````kalman = dsp.KalmanFilter(STMatrix, MMatrix, PNCovariance, MNCovariance, CIMatrix)``````
``kalman = dsp.KalmanFilter(Name,Value)``

### Description

````kalman = dsp.KalmanFilter` returns the Kalman filter System object, `kalman`, with default values for the parameters.```

example

``````kalman = dsp.KalmanFilter(STMatrix, MMatrix, PNCovariance, MNCovariance, CIMatrix)``` returns a Kalman filter System object, `kalman`. The `StateTransitionMatrix` property is set to `STMatrix`, the `MeasurementMatrix` property is set to `MMatrix`, the `ProcessNoiseCovariance` property is set to `PNCovariance`, the `MeasurementNoiseCovariance` property is set to `MNCovariance`, and the `ControlInputMatrix` property is set to `CIMatrix`.```
````kalman = dsp.KalmanFilter(Name,Value)` returns an Kalman filter System object, `kalman`, with each property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.```

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

Specify A in the state equation that relates the state at the previous time step to the state at current time step. A is a square matrix with each dimension equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify B in the state equation that relates the control input to the state. B is a column vector with a number of rows equal to the number of states.

#### Dependencies

This property is activated only when the `ControlInputPort` property value is `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify H in the measurement equation that relates the states to the measurements. H is a row vector with a number of columns equal to the number of measurements.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify Q as a square matrix with each dimension equal to the number of states. Q is the covariance of the white Gaussian process noise, w, in the state equation.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify R as a square matrix with each dimension equal to the number of states. R is the covariance of the white Gaussian process noise, v, in the measurement equation.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify an initial estimate of the states of the model as a column vector with length equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify an initial estimate for covariance of the state error, as a square matrix with each dimension equal to the number of states.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify as a scalar logical value, disabling System object filters from performing the correction step after the prediction step in the Kalman filter algorithm.

Specify if the control input is present, using a scalar logical value. The default value is `true`.

## Usage

### Syntax

``[zEst, xEst, MSE_Est, zPred, xPred, MSE_Pred] = kalman(z,u)``

### Description

example

````[zEst, xEst, MSE_Est, zPred, xPred, MSE_Pred] = kalman(z,u)` carries out the iterative Kalman filter algorithm over measurements `z` and control inputs `u`. The columns in `z` and `u` are treated as inputs to separate parallel filters, whose correction (or update) step can be disabled by the `DisableCorrection` property. The values returned are estimated measurements `zEst`, estimated states `xEst`, MSE of estimated states `MSE_Est`, predicted measurements `zPred`, predicted states `xPred`, and MSE of predicted states `MSE_Pred`.```

### Input Arguments

expand all

Measurement input, specified as a vector or a matrix.

The ratio of the number of rows of the measurement input to the number of rows of the `MeasurementMatrix` property must be equal to the ratio of the number of rows of the control input to the number of columns of the `ControlInputMatrix` property.

The measurement signal can be a variable-size input. Once the object is locked, you can change the size of each input channel, but the number of channels cannot change.

Data Types: `single` | `double`

Control input, specified as a vector or a matrix.

The ratio of the number of rows of the control input to the number of columns of the `ControlInputMatrix` property must be equal to the ratio of the number of rows of the measurement input to the number of rows of the `MeasurementMatrix` property.

The control signal can be a variable-size input. Once the object is locked, you can change the size of each input channel, but the number of channels cannot change.

Data Types: `single` | `double`

### Output Arguments

expand all

Estimated measurements, returned as a vector or matrix.

Data Types: `single` | `double`

Estimated state, returned as a vector or matrix.

Data Types: `single` | `double`

Mean-squared error of estimated states, returned as a scalar or column vector. If the input is a row vector, the MSE of the estimated states is a scalar.

Data Types: `single` | `double`

Predicted measurements, returned as a vector or a matrix.

Data Types: `single` | `double`

Predicted states, returned as a vector or a matrix.

Data Types: `single` | `double`

Mean-squared error of predicted states, returned as a scalar or a column vector. If the input is a row vector, the MSE of the estimated states is a scalar.

Data Types: `single` | `double`

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

## Examples

collapse all

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, `obj(x)` becomes `step(obj,x)`.

Create the System objects for the changing scalar input, the Kalman filter, and the scope (for plotting).

```numSamples = 4000; R = 0.02; src = dsp.SignalSource; src.Signal = [ones(numSamples/4,1);-3*ones(numSamples/4,1);... 4*ones(numSamples/4,1); -0.5*ones(numSamples/4,1)]; tScope = timescope('NumInputPorts',3,... 'TimeSpanSource','Property','TimeSpan',numSamples, ... 'TimeUnits','Seconds','YLimits',[-5 5], ... 'ShowLegend',true); % Create the Time Scope kalman = dsp.KalmanFilter('ProcessNoiseCovariance', 0.0001,... 'MeasurementNoiseCovariance',R,... 'InitialStateEstimate',5,... 'InitialErrorCovarianceEstimate',1,... 'ControlInputPort',false); %Create Kalman filter ```

Add noise to the scalar, and pass the result to the Kalman filter. Stream the data, and plot the filtered signal.

```while(~isDone(src)) trueVal = src(); noisyVal = trueVal + sqrt(R)*randn; estVal = kalman(noisyVal); tScope(noisyVal,trueVal,estVal); end ```

## Algorithms

This object implements the algorithm, inputs, and outputs described on the Kalman Filter block reference page. The object properties correspond to the block parameters.

## Compatibility Considerations

expand all

Not recommended starting in R2021a

## References

[1] Greg Welch and Gary Bishop, An Introduction to the Kalman Filter, Technical Report TR95 041. University of North Carolina at Chapel Hill: Chapel Hill, NC., 1995.