Updaters¶

class
stonesoup.updater.base.
Updater
(measurement_model: MeasurementModel)[source]¶ Bases:
stonesoup.base.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
: stonesoup.models.measurement.base.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:
stonesoup.updater.base.Updater
A class which embodies Kalmantype 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 crosscovariance,\[ \begin{align}\begin{aligned}\mathbf{z}_{kk1} = H_k \mathbf{x}_{kk1}\\S_k = H_k P_{kk1} H_k^T + R_k\\\Upsilon_k = P_{kk1} H_k^T\end{aligned}\end{align} \]where \(P_{kk1}\) 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}_{kk} = \mathbf{x}_{kk1} + K_k (\mathbf{z}_k  H_k \mathbf{x}_{kk1})\\P_{kk} = P_{kk1}  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
: stonesoup.models.measurement.linear.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}_{kk1}\), \(P_{kk1}\)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}_{kk1}\)
 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 predictionmeasurement 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}_{kk}\) and covariance \(P_{xx}\)
 Return type

class
stonesoup.updater.kalman.
ExtendedKalmanUpdater
(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False)[source]¶ Bases:
stonesoup.updater.kalman.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 nonlinear, 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
: stonesoup.models.measurement.base.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:
stonesoup.updater.kalman.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 3Ns

measurement_model
: stonesoup.models.measurement.base.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 Gaussdistributed 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:
stonesoup.updater.kalman.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_{kk1} = L_{kk1} L^T_{kk1}\) [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, 11651166
 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 = 1e06, measure: Measure = Euclidean(mapping=None), max_iterations: int = 1000)[source]¶ Bases:
stonesoup.updater.kalman.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_{kk1} + K_i [z  h(x_{k,i})  H_i (x_{kk1}  x_{k,i}) ]\\P_{k,i+1} &= (I  K_i H_i) P_{kk1}\end{aligned}\end{align} \]where,
\[ \begin{align}\begin{aligned}H_i &= h^{\prime}(x_{k,i}),\\K_i &= P_{kk1} H_i^T (H_i P_{kk1} H_i^T + R)^{1}\end{aligned}\end{align} \]and
\[ \begin{align}\begin{aligned}x_{k,0} &= x_{kk1}\\P_{k,0} &= P_{kk1}\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 nonconvergence warning is returned

measure
: stonesoup.measures.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 nonconvergence 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 predictionmeasurement 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}_{kk}\) and covariance \(P_{kk}\)
 Return type
Particle¶

class
stonesoup.updater.particle.
ParticleUpdater
(measurement_model: MeasurementModel, resampler: Resampler = None)[source]¶ Bases:
stonesoup.updater.base.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

resampler
: stonesoup.resampler.base.Resampler¶ 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

class
stonesoup.updater.particle.
GromovFlowParticleUpdater
(measurement_model: MeasurementModel)[source]¶ Bases:
stonesoup.updater.base.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

class
stonesoup.updater.particle.
GromovFlowKalmanParticleUpdater
(measurement_model: MeasurementModel, kalman_updater: KalmanUpdater = None)[source]¶ Bases:
stonesoup.updater.particle.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 DaumHuang ExactFlow Particle Filter” 2012

kalman_updater
: stonesoup.updater.kalman.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
Point Process¶

class
stonesoup.updater.pointprocess.
PointProcessUpdater
(updater: KalmanUpdater, clutter_spatial_density: float = 1e26, normalisation: bool = True, prob_detection: Probability = 1, prob_survival: Probability = 1)[source]¶ Bases:
stonesoup.base.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
: stonesoup.updater.kalman.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
: stonesoup.types.numeric.Probability¶ Probability of a target being detected at the current timestep

prob_survival
: stonesoup.types.numeric.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 = 1e26, normalisation: bool = True, prob_detection: Probability = 1, prob_survival: Probability = 1)[source]¶ Bases:
stonesoup.updater.pointprocess.PointProcessUpdater
A implementation of the Gaussian Mixture Probability Hypothesis Density (GMPHD) multitarget 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.
 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 = 1e26, 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:
stonesoup.updater.pointprocess.PointProcessUpdater
A implementation of the Gaussian Mixture Linear Complexity with Cumulants (GMLCC) multitarget filter
References
 [1] D. E. Clark and F. De Melo. “A LinearComplexity SecondOrder
MultiObject 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