Updaters
- class stonesoup.updater.base.Updater(measurement_model: MeasurementModel)[source]
Bases:
Base
Updater base class
An updater is used to update the predicted state, utilising a measurement and a
MeasurementModel
. The general observation model is\[\mathbf{z} = h(\mathbf{x}, \mathbf{\sigma})\]where \(\mathbf{x}\) is the state, \(\mathbf{\sigma}\), the measurement noise and \(\mathbf{z}\) the resulting measurement.
- Parameters
measurement_model (
MeasurementModel
) – measurement model
- measurement_model: MeasurementModel
measurement model
- abstract predict_measurement(state_prediction, measurement_model=None, **kwargs)[source]
Get measurement prediction from state prediction
- Parameters
state_prediction (
StatePrediction
) – The state predictionmeasurement_model (
MeasurementModel
, optional) – The measurement model used to generate the measurement prediction. Should be used in cases where the measurement model is dependent on the received measurement. The default is None, in which case the updater will use the measurement model specified on initialisation
- Returns
The predicted measurement
- Return type
- abstract update(hypothesis, **kwargs)[source]
Update state using prediction and measurement.
- Parameters
hypothesis (
Hypothesis
) – Hypothesis with predicted state and associated detection used for updating.- Returns
The state posterior
- Return type
Kalman
- class stonesoup.updater.kalman.KalmanUpdater(measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False)[source]
Bases:
Updater
A class which embodies Kalman-type updaters; also a class which performs measurement update step as in the standard Kalman Filter.
The Kalman updaters assume \(h(\mathbf{x}) = H \mathbf{x}\) with additive noise \(\sigma = \mathcal{N}(0,R)\). Daughter classes can overwrite to specify a more general measurement model \(h(\mathbf{x})\).
update()
first callspredict_measurement()
function which proceeds by calculating the predicted measurement, innovation covariance and measurement cross-covariance,\[ \begin{align}\begin{aligned}\mathbf{z}_{k|k-1} = H_k \mathbf{x}_{k|k-1}\\S_k = H_k P_{k|k-1} H_k^T + R_k\\\Upsilon_k = P_{k|k-1} H_k^T\end{aligned}\end{align} \]where \(P_{k|k-1}\) is the predicted state covariance.
predict_measurement()
returns aGaussianMeasurementPrediction
. The Kalman gain is then calculated as,\[K_k = \Upsilon_k S_k^{-1}\]and the posterior state mean and covariance are,
\[ \begin{align}\begin{aligned}\mathbf{x}_{k|k} = \mathbf{x}_{k|k-1} + K_k (\mathbf{z}_k - H_k \mathbf{x}_{k|k-1})\\P_{k|k} = P_{k|k-1} - K_k S_k K_k^T\end{aligned}\end{align} \]These are returned as a
GaussianStateUpdate
object.- Parameters
measurement_model (
LinearGaussian
, optional) – A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- measurement_model: LinearGaussian
A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.
- force_symmetric_covariance: bool
A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- predict_measurement(predicted_state, measurement_model=None, **kwargs)[source]
Predict the measurement implied by the predicted state mean
- Parameters
predicted_state (
GaussianState
) – The predicted state \(\mathbf{x}_{k|k-1}\), \(P_{k|k-1}\)measurement_model (
MeasurementModel
) – The measurement model. If omitted, the model in the updater object is used**kwargs (various) – These are passed to
function()
andmatrix()
- Returns
The measurement prediction, \(\mathbf{z}_{k|k-1}\)
- Return type
GaussianMeasurementPrediction
- update(hypothesis, **kwargs)[source]
The Kalman update method. Given a hypothesised association between a predicted state or predicted measurement and an actual measurement, calculate the posterior state.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a predicted measurement, or a predicted state. In the latter case a predicted measurement will be calculated.**kwargs (various) – These are passed to
predict_measurement()
- Returns
The posterior state Gaussian with mean \(\mathbf{x}_{k|k}\) and covariance \(P_{x|x}\)
- Return type
- class stonesoup.updater.kalman.ExtendedKalmanUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False)[source]
Bases:
KalmanUpdater
The Extended Kalman Filter version of the Kalman Updater. Inherits most of the functionality from
KalmanUpdater
.The difference is that the measurement model may now be non-linear, though must be differentiable to return the linearisation of \(h(\mathbf{x})\) via the matrix \(H\) accessible via
jacobian()
.- Parameters
measurement_model (
MeasurementModel
, optional) – A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown. Must be linear or capable or implement thejacobian()
.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- measurement_model: MeasurementModel
A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown. Must be linear or capable or implement the
jacobian()
.
- class stonesoup.updater.kalman.UnscentedKalmanUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False, alpha: float = 0.5, beta: float = 2, kappa: float = 0)[source]
Bases:
KalmanUpdater
The Unscented Kalman Filter version of the Kalman Updater. Inherits most of the functionality from
KalmanUpdater
.In this case the
predict_measurement()
function uses theunscented_transform()
function to estimate a (Gaussian) predicted measurement. This is then updated via the standard Kalman update equations.- Parameters
measurement_model (
MeasurementModel
, optional) – The measurement model to be used. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.alpha (
float
, optional) – Primary sigma point spread scaling parameter. Default is 0.5.beta (
float
, optional) – Used to incorporate prior knowledge of the distribution. If the true distribution is Gaussian, the value of 2 is optimal. Default is 2kappa (
float
, optional) – Secondary spread scaling parameter. Default is calculated as 3-Ns
- measurement_model: MeasurementModel
The measurement model to be used. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.
- beta: float
Used to incorporate prior knowledge of the distribution. If the true distribution is Gaussian, the value of 2 is optimal. Default is 2
- predict_measurement(predicted_state, measurement_model=None)[source]
Unscented Kalman Filter measurement prediction step. Uses the unscented transform to estimate a Gauss-distributed predicted measurement.
- Parameters
predicted_state (
GaussianStatePrediction
) – A predicted statemeasurement_model (
MeasurementModel
, optional) – The measurement model used to generate the measurement prediction. This should be used in cases where the measurement model is dependent on the received measurement (the default is None, in which case the updater will use the measurement model specified on initialisation)
- Returns
The measurement prediction
- Return type
- class stonesoup.updater.kalman.SqrtKalmanUpdater(measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False, qr_method: bool = False)[source]
Bases:
KalmanUpdater
The Square root version of the Kalman Updater.
The input
State
is aSqrtGaussianState
which means that the covariance of the predicted state is stored in square root form. This can be achieved by keepingcovar
attribute as \(L\) where the ‘full’ covariance matrix \(P_{k|k-1} = L_{k|k-1} L^T_{k|k-1}\) [Eq1].In its basic form \(L\) is the lower triangular matrix returned via Cholesky factorisation. There’s no reason why other forms that satisfy Eq 1 above can’t be used.
References
Schmidt, S.F. 1970, Computational techniques in Kalman filtering, NATO advisory group for aerospace research and development, London 1970
Andrews, A. 1968, A square root formulation of the Kalman covariance equations, AIAA Journal, 6:6, 1165-1166
- Parameters
measurement_model (
LinearGaussian
, optional) – A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.qr_method (
bool
, optional) – A switch to do the update via a QR decomposition, rather than using the (vector form of) the Potter method.
- class stonesoup.updater.kalman.IteratedKalmanUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False, tolerance: float = 1e-06, measure: Measure = Euclidean(mapping=None, mapping2=None), max_iterations: int = 1000)[source]
Bases:
ExtendedKalmanUpdater
This version of the Kalman updater runs an iteration over the linearisation of the sensor function in order to refine the posterior state estimate. Specifically,
\[ \begin{align}\begin{aligned}x_{k,i+1} &= x_{k|k-1} + K_i [z - h(x_{k,i}) - H_i (x_{k|k-1} - x_{k,i}) ]\\P_{k,i+1} &= (I - K_i H_i) P_{k|k-1}\end{aligned}\end{align} \]where,
\[ \begin{align}\begin{aligned}H_i &= h^{\prime}(x_{k,i}),\\K_i &= P_{k|k-1} H_i^T (H_i P_{k|k-1} H_i^T + R)^{-1}\end{aligned}\end{align} \]and
\[ \begin{align}\begin{aligned}x_{k,0} &= x_{k|k-1}\\P_{k,0} &= P_{k|k-1}\end{aligned}\end{align} \]It inherits from the ExtendedKalmanUpdater as it uses the same linearisation of the sensor function via the
_measurement_matrix()
function.- Parameters
measurement_model (
MeasurementModel
, optional) – A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown. Must be linear or capable or implement thejacobian()
.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.tolerance (
float
, optional) – The value of the difference in the measure used as a stopping criterion.measure (
Measure
, optional) – The measure to use to test the iteration stopping criterion. Defaults to the Euclidean distance between current and prior posterior state estimate.max_iterations (
int
, optional) – Number of iterations before while loop is exited and a non-convergence warning is returned
- measure: Measure
The measure to use to test the iteration stopping criterion. Defaults to the Euclidean distance between current and prior posterior state estimate.
- max_iterations: int
Number of iterations before while loop is exited and a non-convergence warning is returned
- update(hypothesis, **kwargs)[source]
The iterated Kalman update method. Given a hypothesised association between a predicted state or predicted measurement and an actual measurement, calculate the posterior state.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a predicted measurement, or a predicted state. In the latter case a predicted measurement will be calculated.**kwargs (various) – These are passed to the measurement model function
- Returns
The posterior state Gaussian with mean \(\mathbf{x}_{k|k}\) and covariance \(P_{k|k}\)
- Return type
Particle
- class stonesoup.updater.particle.ParticleUpdater(measurement_model: MeasurementModel, resampler: Resampler = None)[source]
Bases:
Updater
Particle Updater
Perform an update by multiplying particle weights by PDF of measurement model (either
measurement_model
ormeasurement_model
), and normalising the weights. If provided, aresampler
will be used to take a new sample of particles (this is called every time, and it’s up to the resampler to decide if resampling is required).- Parameters
measurement_model (
MeasurementModel
) – measurement modelresampler (
Resampler
, optional) – Resampler to prevent particle degeneracy
- update(hypothesis, **kwargs)[source]
Particle Filter update step
- Parameters
hypothesis (
Hypothesis
) – Hypothesis with predicted state and associated detection used for updating.- Returns
The state posterior
- Return type
- predict_measurement(state_prediction, measurement_model=None, **kwargs)[source]
Get measurement prediction from state prediction
- Parameters
state_prediction (
StatePrediction
) – The state predictionmeasurement_model (
MeasurementModel
, optional) – The measurement model used to generate the measurement prediction. Should be used in cases where the measurement model is dependent on the received measurement. The default is None, in which case the updater will use the measurement model specified on initialisation
- Returns
The predicted measurement
- Return type
- class stonesoup.updater.particle.GromovFlowParticleUpdater(measurement_model: MeasurementModel)[source]
Bases:
Updater
Gromov Flow Particle Updater
This is implementation of Gromov method for stochastic particle flow filters 1. The Euler Maruyama method is used for integration, over 20 steps using an exponentially increase step size.
- Parameters
measurement_model (
MeasurementModel
) – measurement model
References
- 1
Daum, Fred & Huang, Jim & Noushin, Arjang. “Generalized Gromov method for stochastic particle flow filters.” 2017
- update(hypothesis, **kwargs)[source]
Update state using prediction and measurement.
- Parameters
hypothesis (
Hypothesis
) – Hypothesis with predicted state and associated detection used for updating.- Returns
The state posterior
- Return type
- predict_measurement(state_prediction, measurement_model=None, **kwargs)
Get measurement prediction from state prediction
- Parameters
state_prediction (
StatePrediction
) – The state predictionmeasurement_model (
MeasurementModel
, optional) – The measurement model used to generate the measurement prediction. Should be used in cases where the measurement model is dependent on the received measurement. The default is None, in which case the updater will use the measurement model specified on initialisation
- Returns
The predicted measurement
- Return type
- class stonesoup.updater.particle.GromovFlowKalmanParticleUpdater(measurement_model: MeasurementModel, kalman_updater: KalmanUpdater = None)[source]
Bases:
GromovFlowParticleUpdater
Gromov Flow Parallel Kalman Particle Updater
This is a wrapper around the
GromovFlowParticleUpdater
which can use aExtendedKalmanUpdater
orUnscentedKalmanUpdater
in parallel in order to maintain a state covariance, as proposed in 2. In this implementation, the mean of theParticleState
is used the EKF/UKF update.This should be used in conjunction with the
ParticleFlowKalmanPredictor
.- Parameters
measurement_model (
MeasurementModel
) – measurement modelkalman_updater (
KalmanUpdater
, optional) – Kalman updater to use. Default None where a new instance of:class:~.ExtendedKalmanUpdater will be created utilising thesame measurement model.
References
- 2
Ding, Tao & Coates, Mark J., “Implementation of the Daum-Huang Exact-Flow Particle Filter” 2012
- kalman_updater: KalmanUpdater
Kalman updater to use. Default None where a new instance of:class:~.ExtendedKalmanUpdater will be created utilising thesame measurement model.
- update(hypothesis, **kwargs)[source]
Update state using prediction and measurement.
- Parameters
hypothesis (
Hypothesis
) – Hypothesis with predicted state and associated detection used for updating.- Returns
The state posterior
- Return type
- predict_measurement(state_prediction, *args, **kwargs)[source]
Get measurement prediction from state prediction
- Parameters
state_prediction (
StatePrediction
) – The state predictionmeasurement_model (
MeasurementModel
, optional) – The measurement model used to generate the measurement prediction. Should be used in cases where the measurement model is dependent on the received measurement. The default is None, in which case the updater will use the measurement model specified on initialisation
- Returns
The predicted measurement
- Return type
Ensemble
- class stonesoup.updater.ensemble.EnsembleUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False)[source]
Bases:
KalmanUpdater
Ensemble Kalman Filter Updater class The EnKF is a hybrid of the Kalman updating scheme and the Monte Carlo aproach of the the particle filter.
Deliberately structured to resemble the Vanilla Kalman Filter,
update()
first callspredict_measurement()
function which proceeds by calculating the predicted measurement, innovation covariance and measurement cross-covariance. Note however, these are not propagated explicitly, they are derived from the sample covariance of the ensemble itself.Note that the EnKF equations are simpler when written in the following formalism. Note that h is not neccisarily a matrix, but could be a nonlinear measurement function.
\[\mathbf{A}_k = \hat{X} - E(X) \mathbf{HA}_k = h(\hat{X} - E(X))\]The cross covariance and measurement covariance are given by:
\[P_{xz} = \frac{1}{M-1} \mathbf{A}_k \mathbf{HA}_k^T P_{zz} = \frac{1}{M-1} A_k \mathbf{HA}_k^T + R\]The Kalman gain is then calculated via:
\[K_{k} = P_{xz} P_{zz}^{-1}\]and the posterior state mean and covariance are,
\[\mathbf{x}_{k|k} = \mathbf{x}_{k|k-1} + K_k (\mathbf{z}_k - H_k \mathbf{x}_{k|k-1})\]This is returned as a
EnsembleStateUpdate
object.References
1. J. Hiles, S. M. O’Rourke, R. Niu and E. P. Blasch, “Implementation of Ensemble Kalman Filters in Stone-Soup,” International Conference on Information Fusion, (2021)
2. Mandel, Jan. “A brief tutorial on the ensemble Kalman filter.” arXiv preprint arXiv:0901.3725 (2009).
- Parameters
measurement_model (
MeasurementModel
, optional) – A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- measurement_model: MeasurementModel
A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.
- predict_measurement(predicted_state, measurement_model=None, **kwargs)[source]
Predict the measurement implied by the predicted state mean
- Parameters
pred_state (
State
) – The predicted state \(\mathbf{x}_{k|k-1}\)measurement_model (
MeasurementModel
) – The measurement model. If omitted, the model in the updater object is used
- Returns
The measurement prediction, \(\mathbf{z}_{k|k-1}\)
- update(hypothesis, **kwargs)[source]
The Ensemble Kalman update method. The Ensemble Kalman filter simply uses the Kalman Update scheme to evolve a set or Ensemble of state vectors as a group. This ensemble of vectors contains all the information on the system state.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a predicted measurement, or a predicted state. In the latter case a predicted measurement will be calculated.- Returns
The posterior state which contains an ensemble of state vectors and a timestamp.
- Return type
- class stonesoup.updater.ensemble.EnsembleSqrtUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False)[source]
Bases:
EnsembleUpdater
The Ensemble Square Root filter propagates the mean and square root covariance through time, and samples a new ensemble. This has the advantage of not requiring perturbation of the measurement which reduces sampling error. The posterior mean is calculated via:
\[\mathbf{x}_{k|k} = \mathbf{x}_{k|k-1} + K_k (\mathbf{z}_k - H_k \mathbf{x}_{k|k-1})\]The Kalman gain is calculated via:
\[K_{k} = P_{xz} P_{zz}^{-1}\]The cross covariance and measurement covariance respectivley are approximated via the sample square root covariances:
\[ \begin{align}\begin{aligned}P_{xz} \approx \tilde{P}_k (\tilde{Z}_k)^T\\P_{zz} \approx \tilde{Z}_k (\tilde{Z}_k)^T + R_k\end{aligned}\end{align} \]and the posterior covariance is propaged through time via:
\[\mathbf{P}_{k|k} = \tilde{P}^- B (\tilde{P}^- B)^T\]Where \(\tilde{P}^-\) represents the prediction square root covariance and B is the matrix square root of:
\[B = \mathbf{I} - (\tilde{Z}_k)^T [P_{zz}]^{-1} \tilde{Z}_k\]The posterior mean and covariance are used to sample a new ensemble. The resulting state is returned via a
EnsembleStateUpdate
object.References
1. J. Hiles, S. M. O’Rourke, R. Niu and E. P. Blasch, “Implementation of Ensemble Kalman Filters in Stone-Soup”, International Conference on Information Fusion, (2021)
2. Livings, Dance, S. L., & Nichols, N. K. “Unbiased ensemble square root filters.” Physica. D, 237(8), 1021–1028. (2008)
- Parameters
measurement_model (
MeasurementModel
, optional) – A measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- update(hypothesis, **kwargs)[source]
The Ensemble Square Root Kalman update method. The Ensemble Square Root filter propagates the mean and square root covariance through time, and samples a new ensemble. This has the advantage of not peturbing the measurement with statistical noise, and thus is less prone to sampling error for small ensembles.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a predicted measurement, or a predicted state. In the latter case a predicted measurement will be calculated.- Returns
The posterior state which contains an ensemble of state vectors and a timestamp.
- Return type
Information
- class stonesoup.updater.information.InformationKalmanUpdater(measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False)[source]
Bases:
KalmanUpdater
A class which implements the update of information form of the Kalman filter. This is conceptually very simple. The update proceeds as:
\[ \begin{align}\begin{aligned}Y_{k|k} = Y_{k|k-1} + H^{T}_k R^{-1}_k H_k\\\mathbf{y}_{k|k} = \mathbf{y}_{k|k-1} + H^{T}_k R^{-1}_k \mathbf{z}_{k}\end{aligned}\end{align} \]where \(\mathbf{y}_{k|k-1}\) is the predicted information state and \(Y_{k|k-1}\) the predicted information matrix which form the
InformationStatePrediction
object. The measurement matrix \(H_k\) and measurement covariance \(R_k\) are those in the Kalman filter (see tutorial 1). AnInformationStateUpdate
object is returned.Note
Analogously with the
InformationKalmanPredictor
, the measurement model is queried for the existence of aninverse_covar()
property. If absent, thecovar()
is inverted.- Parameters
measurement_model (
LinearGaussian
, optional) – A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- measurement_model: LinearGaussian
A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.
- predict_measurement(predicted_state, measurement_model=None, **kwargs)[source]
There’s no direct analogue of a predicted measurement in the information form. This method is therefore provided to return the predicted measurement as would the standard Kalman updater. This is mainly for compatibility as it’s not anticipated that it would be used in the usual operation of the information filter.
- Parameters
predicted_information_state (
State
) – The predicted state in information form \(\mathbf{y}_{k|k-1}\)measurement_model (
MeasurementModel
) – The measurement model. If omitted, the model in the updater object is used**kwargs (various) – These are passed to
matrix()
- Returns
The measurement prediction, \(H \mathbf{x}_{k|k-1}\)
- Return type
- update(hypothesis, **kwargs)[source]
The Information filter update (corrector) method. Given a hypothesised association between a predicted information state and an actual measurement, calculate the posterior information state.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis carries a predicted information state.**kwargs (various) – These are passed to
predict_measurement()
- Returns
The posterior information state with information state \(\mathbf{y}_{k|k}\) and precision \(Y_{k|k}\)
- Return type
Point Process
- class stonesoup.updater.pointprocess.PointProcessUpdater(updater: KalmanUpdater, clutter_spatial_density: float = 1e-26, normalisation: bool = True, prob_detection: Probability = 1, prob_survival: Probability = 1)[source]
Bases:
Base
Base updater class for the implementation of any Gaussian Mixture (GM) point process derived multi target filters such as the Probability Hypothesis Density (PHD), Cardinalised Probability Hypothesis Density (CPHD) or Linear Complexity with Cumulants (LCC) filters
- Parameters
updater (
KalmanUpdater
) – Underlying updater used to perform the single target Kalman Update.clutter_spatial_density (
float
, optional) – Spatial density of the clutter process uniformly distributed across the state space.normalisation (
bool
, optional) – Flag for normalisationprob_detection (
Probability
, optional) – Probability of a target being detected at the current timestepprob_survival (
Probability
, optional) – Probability of a target surviving until the next timestep
- updater: KalmanUpdater
Underlying updater used to perform the single target Kalman Update.
- clutter_spatial_density: float
Spatial density of the clutter process uniformly distributed across the state space.
- prob_detection: Probability
Probability of a target being detected at the current timestep
- prob_survival: Probability
Probability of a target surviving until the next timestep
- update(hypotheses)[source]
Updates the current components in a
GaussianMixture
by applying the underlyingKalmanUpdater
updater to each component with the supplied measurements.- Parameters
hypotheses (list of
MultipleHypothesis
) – Measurements obtained at time \(k+1\)- Returns
updated_components – GaussianMixtureMultiTargetTracker with updated components at time \(k+1\)
- Return type
GaussianMixtureUpdate
- class stonesoup.updater.pointprocess.PHDUpdater(updater: KalmanUpdater, clutter_spatial_density: float = 1e-26, normalisation: bool = True, prob_detection: Probability = 1, prob_survival: Probability = 1)[source]
Bases:
PointProcessUpdater
A implementation of the Gaussian Mixture Probability Hypothesis Density (GM-PHD) multi-target filter
References
[1] B.-N. Vo and W.-K. Ma, “The Gaussian Mixture Probability Hypothesis Density Filter,” Signal Processing,IEEE Transactions on, vol. 54, no. 11, pp. 4091–4104, 2006. https://ieeexplore.ieee.org/document/1710358.
[2] D. E. Clark, K. Panta and B. Vo, “The GM-PHD Filter Multiple Target Tracker,” 2006 9th International Conference on Information Fusion, 2006, pp. 1-8, doi: 10.1109/ICIF.2006.301809. https://ieeexplore.ieee.org/document/4086095.
- Parameters
updater (
KalmanUpdater
) – Underlying updater used to perform the single target Kalman Update.clutter_spatial_density (
float
, optional) – Spatial density of the clutter process uniformly distributed across the state space.normalisation (
bool
, optional) – Flag for normalisationprob_detection (
Probability
, optional) – Probability of a target being detected at the current timestepprob_survival (
Probability
, optional) – Probability of a target surviving until the next timestep
- class stonesoup.updater.pointprocess.LCCUpdater(updater: KalmanUpdater, clutter_spatial_density: float = 1e-26, normalisation: bool = True, prob_detection: Probability = 1, prob_survival: Probability = 1, mean_number_of_false_alarms: float = 1, variance_of_false_alarms: float = 1)[source]
Bases:
PointProcessUpdater
A implementation of the Gaussian Mixture Linear Complexity with Cumulants (GM-LCC) multi-target filter
References
- [1] D. E. Clark and F. De Melo. “A Linear-Complexity Second-Order
Multi-Object Filter via Factorial Cumulants”. In: 2018 21st International Conference on Information Fusion (FUSION). 2018. DOI: 10. 23919/ICIF.2018.8455331. https://ieeexplore.ieee.org/document/8455331..
- Parameters
updater (
KalmanUpdater
) – Underlying updater used to perform the single target Kalman Update.clutter_spatial_density (
float
, optional) – Spatial density of the clutter process uniformly distributed across the state space.normalisation (
bool
, optional) – Flag for normalisationprob_detection (
Probability
, optional) – Probability of a target being detected at the current timestepprob_survival (
Probability
, optional) – Probability of a target surviving until the next timestepmean_number_of_false_alarms (
float
, optional) – Mean number of false alarms (clutter) expected per timestepvariance_of_false_alarms (
float
, optional) – Variance on the number of false alarms (clutter) expected per timestep
AlphaBeta
- class stonesoup.updater.alphabeta.AlphaBetaUpdater(measurement_model: MeasurementModel, alpha: float, beta: float, vmap: ndarray = None)[source]
Bases:
Updater
Conceptually, the \(\alpha-\beta\) filter is similar to its Kalman cousins in that it operates recursively over predict and update steps. It assumes that a state vector is decomposable into quantities and the rates of change of those quantities. We refer to these as position \(p\) and velocity \(v\) respectively, though they aren’t confined to locations in space. If the interval from \(t_{k-1} \rightarrow t_k\) is \(\Delta T\), and at \(k\), we can gain a (noisy) measurement of the position, \(p^z_k\).
The recursion proceeds as:
Predict
\[ \begin{align}\begin{aligned}p_{k|k-1} &= p_{k-1} + \Delta T v_{k-1}\\v_{k|k-1} &= v_{k-1}\end{aligned}\end{align} \]Update
\[ \begin{align}\begin{aligned}s_k &= p^z_k - p_{k|k-1} \: (\mathrm{innovation})\\p_k &= p_{k|k-1} + \alpha s_k\\v_k &= v_{k|k-1} + \frac{\beta}{\Delta T} s_k\end{aligned}\end{align} \]The \(\alpha\) and \(\beta\) parameters which give the filter its name are small, \(0 < \alpha < 1\) and \(0 < \beta \leq 2\). Colloquially, the larger the values of the parameters, the more influence the measurements have over the transition model; \(\beta\) is usually much smaller than \(\alpha\).
As the prediction is just the application of a constant velocity model, there is no \(\alpha-\beta\) predictor provided in Stone Soup. It is assumed that the predictions passed to the hypothesis have been generated by a constant velocity model. Any application of a control model is also assumed to have taken place during the prediction stage.
This class assumes the velocity is in units of the length per second. If different units are required, scale the prior appropriately.
The measurement model used should be linear and a measurement model such that it provides a ‘mapping’ to \(p\) via the
mapping
tuple and a binary measurement matrix which returns \(p\). This isn’t checked.- Parameters
measurement_model (
MeasurementModel
) – measurement modelalpha (
float
) – The alpha parameter. Controls the weight given to the measurements over the transition model.beta (
float
) – The beta parameter. Controls the amount of variation allowed in the velocity component.vmap (
numpy.ndarray
, optional) – Binary map of the velocity elements in the state vector. If left default, the class will assume that the velocity elements interleave the position elements in the state vector.
- alpha: float
The alpha parameter. Controls the weight given to the measurements over the transition model.
- beta: float
The beta parameter. Controls the amount of variation allowed in the velocity component.
- vmap: ndarray
Binary map of the velocity elements in the state vector. If left default, the class will assume that the velocity elements interleave the position elements in the state vector.
- predict_measurement(prediction, measurement_model=None, **kwargs)[source]
Return the predicted measurement
- Parameters
prediction (
StatePrediction
) – The state prediction- Returns
The predicted measurement
- Return type
- update(hypothesis, time_interval, **kwargs)[source]
Calculate the inferred state following update
- Parameters
hypothesis (
Hypothesis
) – A hypothesis associates a measurement with a predictiontime_interval (
timedelta
) – The time interval over which the prediction has been made.
- Returns
The updated state
- Return type
Sliding Innovation Filter
- class stonesoup.updater.slidinginnovation.SlidingInnovationUpdater(layer_width: ndarray, measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False)[source]
Bases:
KalmanUpdater
Sliding Innovation Filter Updater
The Sliding Innovation Filter (SIF) is a sub-optimal filter (in comparison to Kalman filter) which uses a switching gain to provide robustness to estimation problems that may be ill-conditioned or contain modeling uncertainties or disturbances.
The main difference from Kalman filter is the calculation of the gain:
\[K_k = H_k^+ \overline{sat}(|\mathbf{z}_{k|k-1}|/\mathbf{\delta})\]where \(\mathbf{\delta}\) is the sliding boundary layer width.
References
S. A. Gadsden and M. Al-Shabi, “The Sliding Innovation Filter,” in IEEE Access, vol. 8, pp. 96129-96138, 2020, doi: 10.1109/ACCESS.2020.2995345.
- Parameters
layer_width (
numpy.ndarray
) – Sliding boundary layer width \(\mathbf{\delta}\). A tunable parameter in measurement space. An example initial value provided in original paper is \(10 \times \text{diag}(R)\)measurement_model (
LinearGaussian
, optional) – A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- class stonesoup.updater.slidinginnovation.ExtendedSlidingInnovationUpdater(layer_width: ndarray, measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False)[source]
Bases:
SlidingInnovationUpdater
,ExtendedKalmanUpdater
Extended Sliding Innovation Filter Updater
This is the Extended version of the
SlidingInnovationUpdater
for non-linear measurement models.References
S. A. Gadsden and M. Al-Shabi, “The Sliding Innovation Filter,” in IEEE Access, vol. 8, pp. 96129-96138, 2020, doi: 10.1109/ACCESS.2020.2995345.
- Parameters
layer_width (
numpy.ndarray
) – Sliding boundary layer width \(\mathbf{\delta}\). A tunable parameter in measurement space. An example initial value provided in original paper is \(10 \times \text{diag}(R)\)measurement_model (
LinearGaussian
, optional) – A linear Gaussian measurement model. This need not be defined if a measurement model is provided in the measurement. If no model specified on construction, or in the measurement, then error will be thrown.force_symmetric_covariance (
bool
, optional) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
Categorical
- class stonesoup.updater.categorical.HMMUpdater(measurement_model: MarkovianMeasurementModel = None)[source]
Bases:
Updater
Hidden Markov model updater
- Parameters
measurement_model (
MarkovianMeasurementModel
, optional) – The measurement model used to predict measurement vectors. If no model is specified on construction, or in a measurement, then an error will be thrown.
- measurement_model: MarkovianMeasurementModel
The measurement model used to predict measurement vectors. If no model is specified on construction, or in a measurement, then an error will be thrown.
- update(hypothesis, **kwargs)[source]
The update method. Given a hypothesised association between a predicted state or predicted measurement and an actual measurement, calculate the posterior state.
\[\alpha_t^i = E^{ki}(F\alpha_{t-1})^i\]Measurements are assumed to be discrete categories from a finite set of measurement categories \(Z = \{\zeta^n|n\in \mathbf{N}, n\le N\}\) (for some finite \(N\)). A measurement should be equivalent to a basis vector \(e^k\), (the N-tuple with all components equal to 0, except the k-th (indices starting at 0), which is 1). This indicates that the measured category is \(\zeta^k\).
The equation above can be simplified to:
\[\alpha_t = E^Ty_t \circ F\alpha_{t-1}\]where \(\circ\) denotes element-wise (Hadamard) product.
- Parameters
hypothesis (
SingleHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a predicted measurement, or a predicted state. In the latter case a predicted measurement will be calculated.**kwargs (various) – These are passed to
predict_measurement()
.
- Returns
The posterior categorical state.
- Return type
- predict_measurement(predicted_state, measurement_model, **kwargs)[source]
Predict the measurement implied by the predicted state.
- Parameters
predicted_state (
CategoricalState
) – The predicted state.measurement_model (
MeasurementModel
) – The measurement model. If omitted, the model in the updater object is used.measurement (
CategoricalState
.) – The measurement.**kwargs (various) – These are passed to
function()
.
- Returns
The measurement prediction.
- Return type
Composite
- class stonesoup.updater.composite.CompositeUpdater(sub_updaters: Sequence[Updater])[source]
Bases:
Updater
Composite updater type
A composition of sub-updaters (
Updater
).- Parameters
sub_updaters (
Sequence[Updater]
) – Sequence of sub-updaters comprising the composite updater. Must not be empty.
- sub_updaters: Sequence[Updater]
Sequence of sub-updaters comprising the composite updater. Must not be empty.
- property measurement_model
measurement model
- predict_measurement(*args, **kwargs)[source]
To attain measurement predictions, the composite updater will use it’s sub-updaters’ predict_measurement methods and leave combining these to the
CompositeHypothesis
type.
- update(hypothesis: CompositeHypothesis, **kwargs)[source]
Given a hypothesised association between a composite predicted state or composite predicted measurement and a composite measurement, calculate the composite posterior state.
- Parameters
hypothesis (
CompositeHypothesis
) – the prediction-measurement association hypothesis. This hypothesis may carry a composite predicted measurement, or a composite predicted state. In the latter case a measurement prediction is calculated for each sub-state of the composite hypothesis, which will then create its own composite measurement prediction.**kwargs (various) – These are passed to the
predict_measurement()
method of each sub-updater
- Returns
The posterior composite state update
- Return type
Chernoff
- class stonesoup.updater.chernoff.ChernoffUpdater(measurement_model: MeasurementModel, omega: float = 0.5)[source]
Bases:
Updater
A class which performs state updates using the Chernoff fusion rule. In this context, measurements come in the form of states with a mean and covariance (compared to traditional measurements which contain solely a mean). The measurements are expected to come as
GaussianDetection
objects.The Chernoff fusion rule is written as 3
\[p_{\omega}(x_{k}) = \frac{p_{1}(x_{k})^{\omega}p_{2}(x_{k})^{1-\omega}} {\int p_{1}(x)^{\omega}p_{2}(x)^{1-\omega} \mathrm{d} x}\]where \(\omega\) is a weighting parameter in the range \((0,1]\), which can be found using an optimization algorithm.
In situations where \(p_1(x)\) and \(p_2(x)\) are multivariate Gaussian distributions, the above formula is equal to the Covariance Intersection Algorithm from Julier et al 4. Let \((a,A)\) and \((b,B)\) be the means and covariances of the measurement and prediction respectively. The Covariance Intersection Algorithm was reformulated for use in Bayesian state estimation by Clark and Campbell 5, yielding formulas for the updated covariance and mean, \(D\) and \(d\), and the innovation covariance matrix, \(V\), as follows:
\[\begin{split}D &= \left ( \omega A^{-1} + (1-\omega)B^{-1} \right )\\ d &= D \left ( \omega A^{-1}a + (1-\omega)B^{-1}b \right )\\ V &= \frac{A}{1-\omega} + \frac{B}{\omega}\end{split}\]In filters where gating is required, the gating region can be written using the innovation covariance matrix as:
\[\mathcal{V}(\gamma) = \left\{ (a,A) : (a-b)^T V^{-1} (a-b) \leq \gamma \right\}\]The specifics for implementing the Covariance Intersection Algorithm in several popular multi-target tracking algorithms was expanded upon by Clark et al 6. The work includes a discussion of Stone Soup and can be used to apply this class to a tracking algorithm of choice.
Note
If you have tracks that you would like to use as measurements for this updater, the
Tracks2GaussianDetectionFeeder
class can be used to convert the tracks to the appropriate format.References
- 3
Hurley, M., “An information theoretic justification for covariance intersection and its generalization,” in [Proceedings of the Fifth International Conference on Information Fusion. FUSION 2002.(IEEE Cat. No. 02EX5997) ], 1, 505–511, IEEE (2002). https://ieeexplore.ieee.org/document/1021196.
- 4
Julier, S., Uhlmann, J., and Durrant-Whyte, H., “A new method for the nonlinear transformation of means and covariances in filters and estimators,” IEEE Transactions on automatic control 45(3), 477–482 (2000). https://ieeexplore.ieee.org/abstract/document/847726/similar#similar.
- 5
Clark, D. and Campbell, M., “Integrating covariance intersection into Bayesian multi-target tracking filters,” preprint on TechRxiv. submitted to IEEE Transactions on Aerospace and Electronic Systems.
- 6
Clark, D. and Hunter, E. and Balaji, B. and O’Rourke, S., “Centralized multi-sensor multi-target data fusion with tracks as measurements,” to be submitted to SPIE Defense and Security Symposium 2023.
- Parameters
measurement_model (
MeasurementModel
) – measurement modelomega (
float
, optional) – A weighting parameter in the range \((0,1]\)
- predict_measurement(predicted_state, measurement_model=None, **kwargs)[source]
This function predicts the measurement of a state in situations where measurements consist of a covariance and state vector.
- Parameters
predicted_state (
GaussianState
) – The predicted state \(\mathbf{x}_{k|k-1}\)measurement_model (
MeasurementModel
) – The measurement model. If omitted, the updater will use the model that was specified on initialization.
- Returns
The measurement prediction
- Return type
- update(hypothesis, force_symmetric_covariance=False, **kwargs)[source]
Given a hypothesis, calculate the posterior mean and covariance.
- Parameters
hypothesis (
Hypothesis
) – Hypothesis with the predicted state and the actual/associated measurement which should be used for updating. If the hypothesis does not contain a measurement prediction, one will be calculated.force_symmetric_covariance (bool) – A flag to force the output covariance matrix to be symmetric by way of a simple geometric combination of the matrix and transpose. Default is False.
- Returns
The state posterior, saved in a generic
Update
object.- Return type