# Updaters¶

class stonesoup.updater.base.Updater(measurement_model: MeasurementModel)[source]

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 prediction

• measurement_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

MeasurementPrediction

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

State

## Kalman¶

class stonesoup.updater.kalman.KalmanUpdater(measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False)[source]

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 calls predict_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 a GaussianMeasurementPrediction. 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: 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}_{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() and matrix()

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
Returns

The posterior state Gaussian with mean $$\mathbf{x}_{k|k}$$ and covariance $$P_{x|x}$$

Return type

GaussianStateUpdate

class stonesoup.updater.kalman.ExtendedKalmanUpdater(measurement_model: MeasurementModel = None, force_symmetric_covariance: bool = False)[source]

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 the jacobian().

• 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]

The Unscented Kalman Filter version of the Kalman Updater. Inherits most of the functionality from KalmanUpdater.

In this case the predict_measurement() function uses the unscented_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 2

• kappa (float, optional) – Secondary spread scaling parameter. Default is calculated as 3-Ns

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.

alpha: float

Primary sigma point spread scaling parameter. Default is 0.5.

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

kappa: float

Secondary spread scaling parameter. Default is calculated as 3-Ns

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 state

• measurement_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

GaussianMeasurementPrediction

class stonesoup.updater.kalman.SqrtKalmanUpdater(measurement_model: LinearGaussian = None, force_symmetric_covariance: bool = False, qr_method: bool = False)[source]

The Square root version of the Kalman Updater.

The input State is a SqrtGaussianState which means that the covariance of the predicted state is stored in square root form. This can be achieved by keeping covar 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

1. Schmidt, S.F. 1970, Computational techniques in Kalman filtering, NATO advisory group for aerospace research and development, London 1970

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

qr_method: bool

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]

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 the jacobian().

• 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

tolerance: float

The value of the difference in the measure used as a stopping criterion.

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

GaussianStateUpdate

## Particle¶

class stonesoup.updater.particle.ParticleUpdater(measurement_model: MeasurementModel, resampler: Resampler = None)[source]

Particle Updater

Perform an update by multiplying particle weights by PDF of measurement model (either measurement_model or measurement_model), and normalising the weights. If provided, a resampler 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
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

ParticleState

class stonesoup.updater.particle.GromovFlowParticleUpdater(measurement_model: MeasurementModel)[source]

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

State

class stonesoup.updater.particle.GromovFlowKalmanParticleUpdater(measurement_model: MeasurementModel, kalman_updater: KalmanUpdater = None)[source]

Gromov Flow Parallel Kalman Particle Updater

This is a wrapper around the GromovFlowParticleUpdater which can use a ExtendedKalmanUpdater or UnscentedKalmanUpdater in parallel in order to maintain a state covariance, as proposed in 2. In this implementation, the mean of the ParticleState is used the EKF/UKF update.

This should be used in conjunction with the ParticleFlowKalmanPredictor.

Parameters

References

2

Ding, Tao & Coates, Mark J., “Implementation of the Daum-Huang Exact-Flow 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

State

predict_measurement(state_prediction, *args, **kwargs)[source]

Get measurement prediction from state prediction

Parameters
• state_prediction (StatePrediction) – The state prediction

• measurement_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

MeasurementPrediction

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

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 normalisation

• prob_detection (Probability, optional) – Probability of a target being detected at the current timestep

• prob_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.

normalisation: bool

Flag for normalisation

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 underlying KalmanUpdater 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]

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.

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 normalisation

• prob_detection (Probability, optional) – Probability of a target being detected at the current timestep

• prob_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]

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 normalisation

• prob_detection (Probability, optional) – Probability of a target being detected at the current timestep

• prob_survival (Probability, optional) – Probability of a target surviving until the next timestep

• mean_number_of_false_alarms (float, optional) – Mean number of false alarms (clutter) expected per timestep

• variance_of_false_alarms (float, optional) – Variance on the number of false alarms (clutter) expected per timestep

mean_number_of_false_alarms: float

Mean number of false alarms (clutter) expected per timestep

variance_of_false_alarms: float

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: numpy.ndarray = None)[source]

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 model

• 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 (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: numpy.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

StateVector

update(hypothesis, time_interval, **kwargs)[source]

Calculate the inferred state following update

Parameters
• hypothesis (Hypothesis) – A hypothesis associates a measurement with a prediction

• time_interval (timedelta) – The time interval over which the prediction has been made.

Returns

The updated state

Return type

StateUpdate