dsp.KalmanFilter

(Removed) Estimate system measurements and states using Kalman filter

dsp.KalmanFilter has been removed. 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 k^th time-step: $$x(k)=Ax(k-1)+Bu(k-1)+w(k-1)$$ (state equation). This measurement, z, is given as: $$z(k)=Hx(k)+v(k)$$ (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.

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

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.

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

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.

StateTransitionMatrix — Model of state transition

1 (default) | scalar | square matrix

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

ControlInputMatrix — Model of relation between control input and states

1 (default) | column vector

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

MeasurementMatrix — Model of relation between states and measurement output

1 (default) | row vector

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

ProcessNoiseCovariance — Covariance of process noise

0.1 (default) | scalar | square matrix

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

MeasurementNoiseCovariance — Covariance of measurement noise

0.1 (default) | scalar | square matrix

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

InitialStateEstimate — Initial value for states

0 (default) | scalar | column vector

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

InitialErrorCovarianceEstimate — Initial value for state error covariance

0.1 (default) | scalar | square matrix

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

DisableCorrection — Disable port for filters

false (default) | true

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

ControlInputPort — Presence of a control input

true (default) | false

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

[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

z — Measurement input

vector | matrix

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

u — Control input

vector | matrix

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

zEst — Estimated measurements

vector | matrix

Estimated measurements, returned as a vector or matrix.

Data Types: single | double

xEst — Estimated state

vector | matrix

Estimated state, returned as a vector or matrix.

Data Types: single | double

MSE_Est — MSE of estimated states

scalar | column vector

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

zPred — Predicted measurements

vector | matrix

Predicted measurements, returned as a vector or a matrix.

Data Types: single | double

xPred — Predicted states

vector | matrix

Predicted states, returned as a vector or a matrix.

Data Types: single | double

MSE_Pred — MSE of predicted states

scalar | column vector

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)

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

Examples

Estimate Changing Scalar

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.

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.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2013b

R2023a: dsp.KalmanFilter System object has been removed

The dsp.KalmanFilter System object has been removed. Use the Kalman filter functionality in Sensor Fusion and Tracking Toolbox instead.

R2021b: dsp.KalmanFilter System object will be removed

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