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
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,
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.
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.
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.
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.
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().
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
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.
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)
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
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.
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,
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
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}\)
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).
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
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.
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
kalman_updater (KalmanUpdater, optional) – Kalman updater to use. Default None where a new instance of:class:~.ExtendedKalmanUpdater will be created utilising thesame measurement model.
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
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 calls predict_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.
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.
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.
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.
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:
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.
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.
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). An InformationStateUpdate object is returned.
Note
Analogously with the InformationKalmanPredictor, the measurement model is queried
for the existence of an inverse_covar() property. If absent, the covar() 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.
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.
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}\)
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.
A linear updater for accumulated state densities, for processing out of
sequence measurements. This requires the state is represented in
ASDGaussianState multi-state.
References
W. Koch and F. Govaers, On Accumulated State Densities with Applications to
Out-of-Sequence Measurement Processing in IEEE Transactions on Aerospace and
Electronic Systems,
vol. 47, no. 4, pp. 2766-2778, OCTOBER 2011, doi: 10.1109/TAES.2011.6034663.
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.
The Kalman update method. Given a hypothesised association between
a predicted state and an actual measurement,
calculate the posterior state. The Measurement Prediction should be
calculated by this method. It is overwritten in this method
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.
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
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
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 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
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
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 \(\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.
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.
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.
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:
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.
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)\)
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.
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.
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.
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.
To attain measurement predictions, the composite updater will use it’s sub-updaters’
predict_measurement methods and leave combining these to the
CompositeHypothesis type.
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
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.
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:
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.
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.