Predictors

Base classes for Stone Soup Predictor interface

class stonesoup.predictor.base.Predictor(transition_model: TransitionModel, control_model: ControlModel = None)

Bases: Base

Predictor base class

A predictor is used to predict a new State given a prior State and a TransitionModel. In addition, a ControlModel may be used to model an external influence on the state.

\[\mathbf{x}_{k|k-1} = f_k(\mathbf{x}_{k-1}, \mathbf{\nu}_k) + b_k(\mathbf{u}_k, \mathbf{\eta}_k)\]

where \(\mathbf{x}_{k-1}\) is the prior state, \(f_k(\mathbf{x}_{k-1})\) is the transition function, \(\mathbf{u}_k\) the control vector, \(b_k(\mathbf{u}_k)\) the control input and \(\mathbf{\nu}_k\) and \(\mathbf{\eta}_k\) the transition and control model noise respectively.

Parameters:

• transition_model (TransitionModel) – transition model

• control_model (ControlModel, optional) – control model

transition_model: TransitionModel

transition model

control_model: ControlModel

control model

abstract predict(prior, timestamp=None, **kwargs)

The prediction function itself

Parameters:

• prior (State) – The prior state

• timestamp (datetime.datetime, optional) – Time at which the prediction is made (used by the transition model)

Returns:

State prediction

Return type:

StatePrediction

Kalman

class stonesoup.predictor.kalman.KalmanPredictor(transition_model: LinearGaussianTransitionModel, control_model: LinearControlModel = None)

Bases: Predictor

A predictor class which forms the basis for the family of Kalman predictors. This class also serves as the (specific) Kalman Filter Predictor class. Here transition and control models must be linear:

\[ \begin{align}\begin{aligned}f_k( \mathbf{x}_{k-1}, \mathbf{\nu}_k) &= F_k \mathbf{x}_{k-1} + \mathbf{\nu}_k , \ \mathbf{\nu}_k \sim \mathcal{N}(0,Q_k)\\\ b_k( \mathbf{u}_k, \mathbf{\eta}_k) &= B_k (\mathbf{u}_k + \mathbf{\eta}_k), \ \mathbf{\eta}_k \sim \mathcal{N}(0,\Gamma_k).\end{aligned}\end{align} \]

Raises:

ValueError – If no TransitionModel is specified.

Parameters:

• transition_model (LinearGaussianTransitionModel) – The transition model to be used.

• control_model (LinearControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

transition_model: LinearGaussianTransitionModel

The transition model to be used.

control_model: LinearControlModel

The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

predict(prior, timestamp=None, control_input=None, **kwargs)

The predict function

Parameters:

• prior (State) – \(\mathbf{x}_{k-1}\)

• timestamp (datetime.datetime, optional) – \(k\)

• control_input (StateVector, optional) – \(\mathbf{u}_k\)

• **kwargs – These are passed, via transition_function() to matrix() and function()

Returns:

\(\mathbf{x}_{k|k-1}\), the predicted state and the predicted state covariance \(P_{k|k-1}\)

Return type:

GaussianStatePrediction

class stonesoup.predictor.kalman.ExtendedKalmanPredictor(transition_model: TransitionModel, control_model: ControlModel = None)

Bases: KalmanPredictor

ExtendedKalmanPredictor class

An implementation of the Extended Kalman Filter predictor. Here the transition and control functions may be non-linear, their transition and control matrices are approximated via Jacobian matrices. To this end the transition and control models, if non-linear, must be able to return the jacobian() function.

Parameters:

• transition_model (TransitionModel) – The transition model to be used.

• control_model (ControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

transition_model: TransitionModel

The transition model to be used.

control_model: ControlModel

The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

class stonesoup.predictor.kalman.UnscentedKalmanPredictor(transition_model: TransitionModel, control_model: ControlModel = None, alpha: float = 0.5, beta: float = 2, kappa: float = None)

Bases: KalmanPredictor

UnscentedKalmanFilter class

The predict is accomplished by calculating the sigma points from the Gaussian mean and covariance, then putting these through the (in general non-linear) transition function, then reconstructing the Gaussian.

Parameters:

• transition_model (TransitionModel) – The transition model to be used.

• control_model (ControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

• 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

transition_model: TransitionModel

The transition model to be used.

control_model: ControlModel

The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

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(prior, timestamp=None, control_input=None, **kwargs)

The unscented version of the predict step

Parameters:

• prior (State) – Prior state, \(\mathbf{x}_{k-1}\)

• timestamp (datetime.datetime) – Time to transit to (\(k\))

• control_input (State) – Control input vector, \(\mathbf{u}_k\)

• **kwargs (various, optional) – These are passed to covar()

Returns:

The predicted state \(\mathbf{x}_{k|k-1}\) and the predicted state covariance \(P_{k|k-1}\)

Return type:

GaussianStatePrediction

class stonesoup.predictor.kalman.SqrtKalmanPredictor(transition_model: TransitionModel, control_model: ControlModel = None, qr_method: bool = False)

Bases: ExtendedKalmanPredictor

The version of the Kalman predictor that operates on the square root parameterisation of the Gaussian state, SqrtGaussianState.

The prediction is undertaken in one of two ways. The default is to work in exactly the same way as the parent class, with the exception that the predicted covariance is subject to a Cholesky factorisation prior to initialisation of the SqrtGaussianState output. The alternative, accessible via the qr_method = True flag, is to predict via a modified Gram-Schmidt process. See [1] for details.

If transition and control models are possessed of the square root form of the covariance (as sqrt_covar in the case of the transition model and sqrt_control_noise for control models), then these are used directly. If not then they are created from the full matrices using the scipy.linalg sqrtm() method. (Unlike the Cholesky decomposition this works on positive semi-definite matrices, as well as positive definite ones.

References

1. Maybeck, P.S. 1994, Stochastic Models, Estimation, and Control, Vol. 1, NavtechGPS, Springfield, VA.

Parameters:

• transition_model (TransitionModel) – The transition model to be used.

• control_model (ControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

• qr_method (bool, optional) – A switch to do the prediction via a QR decomposition, rather than using a Cholesky decomposition.

qr_method: bool

A switch to do the prediction via a QR decomposition, rather than using a Cholesky decomposition.

class stonesoup.predictor.kalman.CubatureKalmanPredictor(transition_model: TransitionModel, control_model: ControlModel = None, alpha: float = 1.0)

Bases: KalmanPredictor

CubatureKalmanFilter class

Analogously to the unscented filter, the predict is accomplished by calculating the cubature points from the Gaussian mean and covariance, then putting these through the (in general non-linear) transition function, then reconstructing the Gaussian. This is accomplished via the cubature_transform() function.

Parameters:

• transition_model (TransitionModel) – The transition model to be used.

• control_model (ControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

• alpha (float, optional) – Scaling parameter. Default is 1.0. Lower values select points closer to the mean and vice versa.

transition_model: TransitionModel

The transition model to be used.

control_model: ControlModel

The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

alpha: float

Scaling parameter. Default is 1.0. Lower values select points closer to the mean and vice versa.

predict(prior, timestamp=None, control_input=None, **kwargs)

The unscented version of the predict step

Parameters:

• prior (State) – Prior state, \(\mathbf{x}_{k-1}\)

• timestamp (datetime.datetime) – Time to transit to (\(k\))

• control_input (State) – Control input vector, \(\mathbf{u}_k\)

• **kwargs (various, optional) – These are passed to covar() and ControlModel.covar()

Returns:

The predicted state \(\mathbf{x}_{k|k-1}\) and the predicted state covariance \(P_{k|k-1}\)

Return type:

GaussianStatePrediction

Particle

class stonesoup.predictor.particle.ParticlePredictor(transition_model: TransitionModel, control_model: ControlModel = None, proposal: Proposal = None)

Bases: Predictor

ParticlePredictor class

An implementation of a Particle Filter predictor.

Parameters:

• transition_model (TransitionModel) – transition model

• control_model (ControlModel, optional) – control model

• proposal (Proposal, optional) – A proposal object that generates samples from the proposal distribution. If None,the transition model is used to generate samples.

proposal: Proposal

A proposal object that generates samples from the proposal distribution. If None,the transition model is used to generate samples.

predict(prior, timestamp=None, measurement=None, **kwargs)

Particle Filter prediction step

Parameters:

• prior (ParticleState) – A prior state object

• timestamp (datetime.datetime, optional) – A timestamp signifying when the prediction is performed (the default is None)

• measurement (Detection, optional) – measurement used in the Kalman Filter proposal to update the prediction (the default is None)

Returns:

The predicted state

Return type:

ParticleStatePrediction

class stonesoup.predictor.particle.ParticleFlowKalmanPredictor(transition_model: TransitionModel, control_model: ControlModel = None, proposal: Proposal = None, kalman_predictor: KalmanPredictor = None)

Bases: ParticlePredictor

Gromov Flow Parallel Kalman Particle Predictor

This is a wrapper around the GromovFlowParticlePredictor which can use a ExtendedKalmanPredictor or UnscentedKalmanPredictor in parallel in order to maintain a state covariance, as proposed in [1].

This should be used in conjunction with the ParticleFlowKalmanUpdater.

Parameters:

• transition_model (TransitionModel) – transition model

• control_model (ControlModel, optional) – control model

• proposal (Proposal, optional) – A proposal object that generates samples from the proposal distribution. If None,the transition model is used to generate samples.

• kalman_predictor (KalmanPredictor, optional) – Kalman predictor to use. Default None where a new instance of:class:~.ExtendedKalmanPredictor will be created utilising thesame transition model.

References

[1]

Ding, Tao & Coates, Mark J., “Implementation of the Daum-Huang Exact-Flow Particle Filter” 2012

kalman_predictor: KalmanPredictor

Kalman predictor to use. Default None where a new instance of:class:~.ExtendedKalmanPredictor will be created utilising thesame transition model.

predict(prior, *args, **kwargs)

Particle Filter prediction step

Parameters:

• prior (ParticleState) – A prior state object

• timestamp (datetime.datetime, optional) – A timestamp signifying when the prediction is performed (the default is None)

• measurement (Detection, optional) – measurement used in the Kalman Filter proposal to update the prediction (the default is None)

Returns:

The predicted state

Return type:

ParticleStatePrediction

class stonesoup.predictor.particle.MultiModelPredictor(transition_models: Sequence[TransitionModel], transition_matrix: ndarray, model_mappings: Sequence[Sequence[int]], control_model: ControlModel = None)

Bases: Predictor

MultiModelPredictor class

An implementation of a Particle Filter predictor utilising multiple models.

Parameters:

• transition_models (Sequence[TransitionModel]) – Transition models used to for particle transition, selected by model index on particle. Models dimensions can be subset of the overall state space, by using model_mappings.

• transition_matrix (numpy.ndarray) – n-model by n-model transition matrix.

• model_mappings (Sequence[Sequence[int]]) – Sequence of mappings associated with each transition model. This enables mapping between model and state space, enabling use of models that may have different dimensions (e.g. velocity or acceleration). Parts of the state that aren’t mapped are set to zero.

• control_model (ControlModel, optional) – control model

transition_model: TransitionModel = None

transition_models: Sequence[TransitionModel]

Transition models used to for particle transition, selected by model index on particle. Models dimensions can be subset of the overall state space, by using model_mappings.

transition_matrix: ndarray

n-model by n-model transition matrix.

model_mappings: Sequence[Sequence[int]]

Sequence of mappings associated with each transition model. This enables mapping between model and state space, enabling use of models that may have different dimensions (e.g. velocity or acceleration). Parts of the state that aren’t mapped are set to zero.

predict(prior, timestamp=None, **kwargs)

Particle Filter prediction step

Parameters:

• prior (MultiModelParticleState) – A prior state object

• timestamp (datetime.datetime, optional) – A timestamp signifying when the prediction is performed (the default is None)

Returns:

The predicted state

Return type:

ParticleStatePrediction

class stonesoup.predictor.particle.RaoBlackwellisedMultiModelPredictor(transition_models: Sequence[TransitionModel], transition_matrix: ndarray, model_mappings: Sequence[Sequence[int]], control_model: ControlModel = None)

Bases: MultiModelPredictor

Rao-Blackwellised Multi Model Predictor class

An implementation of a Particle Filter predictor utilising multiple models, with per particle model probabilities.

Parameters:

• transition_models (Sequence[TransitionModel]) – Transition models used to for particle transition, selected by model index on particle. Models dimensions can be subset of the overall state space, by using model_mappings.

• transition_matrix (numpy.ndarray) – n-model by n-model transition matrix.

• model_mappings (Sequence[Sequence[int]]) – Sequence of mappings associated with each transition model. This enables mapping between model and state space, enabling use of models that may have different dimensions (e.g. velocity or acceleration). Parts of the state that aren’t mapped are set to zero.

• control_model (ControlModel, optional) – control model

predict(prior, timestamp=None, **kwargs)

Particle Filter prediction step

Parameters:

• prior (RaoBlackwellisedParticleState) – A prior state object

• timestamp (datetime.datetime, optional) – A timestamp signifying when the prediction is performed (the default is None)

Returns:

The predicted state

Return type:

ParticleStatePrediction

class stonesoup.predictor.particle.BernoulliParticlePredictor(transition_model: TransitionModel, control_model: ControlModel = None, proposal: Proposal = None, birth_probability: float = 0.01, survival_probability: float = 0.98, birth_sampler: Sampler = None)

Bases: ParticlePredictor

Bernoulli Particle Filter Predictor class

An implementation of a particle filter predictor utilising the Bernoulli filter formulation that estimates the spatial distribution of a single target and estimates its existence, as described in [2].

This should be used in conjunction with the BernoulliParticleUpdater.

References

[2]

Ristic, Branko & Vo, Ba-Toung & Vo, Ba-Ngu & Farina, Alfonso, A Tutorial on Bernoulli Filters: Theory, Implementation and Applications, 2013, IEEE Transactions on Signal Processing, 61(13), 3406-3430.

Parameters:

• transition_model (TransitionModel) – transition model

• control_model (ControlModel, optional) – control model

• proposal (Proposal, optional) – A proposal object that generates samples from the proposal distribution. If None,the transition model is used to generate samples.

• birth_probability (float, optional) – Probability of target birth.

• survival_probability (float, optional) – Probability of target survival

• birth_sampler (Sampler, optional) – Sampler object used for sampling birth particles. Currently implementation assumes the DetectionSampler is used

birth_probability: float

Probability of target birth.

survival_probability: float

Probability of target survival

birth_sampler: Sampler

Sampler object used for sampling birth particles. Currently implementation assumes the DetectionSampler is used

predict(prior, timestamp=None, **kwargs)

Bernoulli Particle Filter prediction step

Parameters:

• prior (BernoulliParticleState) – A prior state object

• timestamp (datetime) – A timestamp signifying when the prediction is performed (the default is None)

Returns:

The predicted state and existence

Return type:

ParticleStatePrediction

class stonesoup.predictor.particle.SMCPHDBirthSchemeEnum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

SMC-PHD Birth scheme enumeration

EXPANSION = 'expansion'

Expansion birth scheme

MIXTURE = 'mixture'

Mixture birth scheme

class stonesoup.predictor.particle.SMCPHDPredictor(transition_model: TransitionModel, death_probability: Probability, birth_probability: Probability, birth_rate: float, birth_sampler: ParticleSampler, control_model: ControlModel = None, birth_func_num_samples_field: str = 'num_samples', birth_scheme: SMCPHDBirthSchemeEnum = SMCPHDBirthSchemeEnum.EXPANSION)

Bases: Predictor

Sequential Monte Carlo Probability Hypothesis Density (SMC-PHD) Predictor class

An implementation of a particle predictor that propagates only the first-order moment (i.e. the Probability Hypothesis Density) of the multi-target state density based on [3].

Note

• It is assumed that the proposal distribution is the same as the dynamics

• Target “spawning” is not implemented

Parameters:

• transition_model (TransitionModel) – transition model

• death_probability (Probability) – The probability of death per unit time. This is used to calculate the probability of survival as \(1 - \exp(-\lambda \Delta t)\) where \(\lambda\) is the probability of death and \(\Delta t\) is the time interval

• birth_probability (Probability) – Probability of target birth. In the current implementation, this is used to calculatethe number of birth particles, as per the explanation under birth_scheme

• birth_rate (float) – The expected number of new/born targets at each iteration. This is used to calculatethe weight of the birth particles

• birth_sampler (ParticleSampler) – Sampler object used for sampling birth particles. The weight of the sampled birth particles is ignored and calculated internally based on the birth_rate and number of particles

• control_model (ControlModel, optional) – control model

• birth_func_num_samples_field (str, optional) – The field name of the number of samples parameter for the birth sampler. This is required since the number of samples required for the birth sampler may be varybetween iterations. Default is 'num_samples'

• birth_scheme (SMCPHDBirthSchemeEnum, optional) –

  The scheme for birth particles. Options are 'expansion' | 'mixture'. Default is 'expansion'.

  • The 'expansion' scheme follows the implementation of [3], meaning that birth particles are appended to the list of surviving particles, where the number of birth particles is computed as \(P_b N\) where \(P_b\) is the birth probability and \(N\) is the number of particles.

  • The 'mixture' scheme draws from a binomial distribution, with probability \(P_b\), for each particle to decide if it gets replaced by a birth particle. The weights of the particles are then updated as a mixture of the survival and birth probabilities.

References

[3] (1,2,3)

Ba-Ngu Vo, S. Singh and A. Doucet, “Sequential monte carlo implementation of the phd filter for multi-target tracking,” Sixth International Conference of Information Fusion, 2003. Proceedings of the, Cairns, QLD, Australia, 2003, pp. 792-799, doi: 10.1109/ICIF.2003.177320

death_probability: Probability

The probability of death per unit time. This is used to calculate the probability of survival as \(1 - \exp(-\lambda \Delta t)\) where \(\lambda\) is the probability of death and \(\Delta t\) is the time interval

birth_probability: Probability

Probability of target birth. In the current implementation, this is used to calculatethe number of birth particles, as per the explanation under birth_scheme

birth_rate: float

The expected number of new/born targets at each iteration. This is used to calculatethe weight of the birth particles

birth_sampler: ParticleSampler

Sampler object used for sampling birth particles. The weight of the sampled birth particles is ignored and calculated internally based on the birth_rate and number of particles

birth_func_num_samples_field: str

The field name of the number of samples parameter for the birth sampler. This is required since the number of samples required for the birth sampler may be varybetween iterations. Default is 'num_samples'

birth_scheme: SMCPHDBirthSchemeEnum

The scheme for birth particles. Options are 'expansion' | 'mixture'. Default is 'expansion'.

• The 'expansion' scheme follows the implementation of [3], meaning that birth particles are appended to the list of surviving particles, where the number of birth particles is computed as \(P_b N\) where \(P_b\) is the birth probability and \(N\) is the number of particles.

• The 'mixture' scheme draws from a binomial distribution, with probability \(P_b\), for each particle to decide if it gets replaced by a birth particle. The weights of the particles are then updated as a mixture of the survival and birth probabilities.

predict(prior, timestamp=None, **kwargs)

SMC-PHD prediction step

Parameters:

• prior (ParticleState) – The prior state

• timestamp (datetime.datetime) – The time at which to predict the next state

Returns:

The predicted state

Return type:

ParticleStatePrediction

Kernel

class stonesoup.predictor.kernel.AdaptiveKernelKalmanPredictor(transition_model: LinearGaussianTransitionModel, control_model: LinearControlModel = None, kernel: Kernel = None, lambda_predictor: float = 0.001)

Bases: KalmanPredictor

An implementation of the adaptive kernel Kalman filter (AKKF) predictor. Here, the AKKF draws inspiration from the concepts of kernel mean embeddings (KME) and Kalman Filter to address tracking problems in nonlinear systems.

In the state space, at time \(k\), the prior state particles are generated by passing the proposal particles at time \(k-1\), i.e., \(\tilde{\mathbf{x}}_{k-1}^{\{i=1:M\}}\), through the motion model as

\[\mathbf{x}_k^{\{i\}} = \mathtt{f}\left(\tilde{\mathbf{x}}_{k-1}^{\{i\}}, \mathbf{u}_{k}^{\{i\}} \right).\]

In the kernel space, \({\mathbf{x}}_{k}^{\{i=1:M_{\text{A}}\}}\) are mapped as feature mappings \(\Phi_k\). Then, the predictive kernel weight vector \(\mathbf{w}^{-}_{k}\), and covariance matrix \({S}_{k}^{-}\), are calculated as

\[\begin{split}\mathbf{w}^{-}_{k} &= \Gamma_{k} \mathbf{w}^{+}_{k-1}\\ {S}_{k}^{-} &= \Gamma_{k} {S}^{+}_{k-1} \Gamma_{k} ^{\mathrm{T}} +V_{k}.\end{split}\]

Here, \(\mathbf{w}^{+}_{k-1}\) and \({S}_{k-1}^{+}\) are the posterior kernel weight mean vector and covariance matrix at time \(k-1\), respectively. The transition matrix \(\Gamma_{k}\) represents the change of sample representation, and \({V}_{k}\) represents the finite matrix representation of the transition residual matrix.

Parameters:

• transition_model (LinearGaussianTransitionModel) – The transition model to be used.

• control_model (LinearControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

• kernel (Kernel, optional) – Default is None. If None, the default QuadraticKernel is used.

• lambda_predictor (float, optional) – \(\lambda_{\tilde{K}}\). Regularisation parameter used to stabilise the inverse Gram matrix. Range is \(\left[10^{-4}, 10^{-2}\right]\)

lambda_predictor: float

\(\lambda_{\tilde{K}}\). Regularisation parameter used to stabilise the inverse Gram matrix. Range is \(\left[10^{-4}, 10^{-2}\right]\)

kernel: Kernel

Default is None. If None, the default QuadraticKernel is used.

predict(prior, timestamp=None, proposal=None, **kwargs)

The adaptive kernel version of the predict step

Parameters:

• prior (KernelParticleState) – Prior state, \(\mathbf{x}_{k-1}\)

• timestamp (datetime.datetime) – Time to transit to (\(k\))

• proposal (KernelParticleState) – Proposal state, \(\mathbf{x}_{k-1}\)

• **kwargs (various, optional) – These are passed to covar()

Returns:

The predicted state \(\mathbf{x}_{k|k-1}\) and the predicted state covariance \(P_{k|k-1}\)

Return type:

KernelParticleStatePrediction

Ensemble

class stonesoup.predictor.ensemble.EnsemblePredictor(transition_model: TransitionModel, control_model: LinearControlModel = None)

Bases: KalmanPredictor

Ensemble Kalman Filter Predictor class

The EnKF predicts the state by treating each column of the ensemble matrix as a state vector. The state is propagated through time by applying the transition function to each member (vector) of the ensemble.

\[\hat{X}_k = [f(x_1), f(x_2), ..., f(x_M)]\]

Parameters:

• transition_model (TransitionModel) – The transition model to be used.

• control_model (LinearControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

transition_model: TransitionModel

The transition model to be used.

predict(prior, timestamp=None, **kwargs)

Ensemble Kalman Filter prediction step

Parameters:

• prior (EnsembleState) – A prior state object

• control_input (State, optional) – The control input. It will only have an effect if control_model is not None (the default is None)

• timestamp (datetime.datetime, optional) – A timestamp signifying when the prediction is performed (the default is None)

Returns:

The predicted state

Return type:

EnsembleStatePrediction

Information

class stonesoup.predictor.information.InformationKalmanPredictor(transition_model: LinearGaussianTransitionModel, control_model: LinearControlModel = None)

Bases: KalmanPredictor

A predictor class which uses the information form of the Kalman filter. The key concept is that ‘information’ is encoded as the information matrix, and the so-called ‘information state’, which are:

\[ \begin{align}\begin{aligned}Y_{k-1} &= P^{-1}_{k-1}\\\mathbf{y}_{k-1} &= P^{-1}_{k-1} \mathbf{x}_{k-1}\end{aligned}\end{align} \]

The prediction then proceeds as [4]

\[ \begin{align}\begin{aligned}Y_{k|k-1} &= [F_k Y_{k-1}^{-1} F^T + Q_k + B_k \Gamma_k B_k^T]^{-1}\\\mathbf{y}_{k|k-1} &= Y_{k|k-1} F_k Y_{k-1}^{-1} \mathbf{y}_{k-1} + Y_{k|k-1} B_k\mathbf{u}_k\end{aligned}\end{align} \]

where the symbols have the same meaning as in the description of the Kalman filter (see e.g. tutorial 1) and the prediction equations can be derived from those of the Kalman filter. As it stands the ControlModel must be capable of returning a (perhaps linearised) control matrix and a control noise covariance matrix. In order to cut down on the number of matrix inversions and to benefit from caching these can be recast as [5]

\[ \begin{align}\begin{aligned}M_k &= (F_k^{-1})^T Y_{k-1} F_k^{-1}\\C_k &= (I + M_k Q_k + M_k B_k \Gamma_k B_k^T)^{-1}\\Y_{k|k-1} &= C_k M_k\\\mathbf{y}_{k|k-1} &= C_k (F_k^{-1})^T \mathbf{y}_k + Y_{k|k-1} B_k\mathbf{u}_k\end{aligned}\end{align} \]

The prior state must have a state vector \(\mathbf{y}_{k-1}\) corresponding to \(P_{k-1}^{-1} \mathbf{x}_{k-1}\) and a precision matrix, \(Y_{k-1} = P_{k-1}^{-1}\). The InformationState class is provided for this purpose.

The TransitionModel is queried for the existence of an inverse_matrix() method, and if not present, matrix() is inverted. This gives one the opportunity to cache \(F_k^{-1}\) and save computational resource.

Raises:

ValueError – If no TransitionModel is specified.

References

[4]

Kim, Y-S, Hong, K-S 2003, Decentralized information filter in federated form, SICE annual conference

[5]

Makarenko, A., Durrant-Whyte, H. 2004, Decentralized data fusion and control in active sensor networks, in: The 7th International Conference on Information Fusion (Fusion’04), pp. 479-486

Parameters:

• transition_model (LinearGaussianTransitionModel) – The transition model to be used.

• control_model (LinearControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

transition_model: LinearGaussianTransitionModel

The transition model to be used.

control_model: LinearControlModel

The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

predict(prior, timestamp=None, control_input=None, **kwargs)

The predict function

Parameters:

• prior (InformationState) – \(\mathbf{y}_{k-1}, Y_{k-1}\)

• timestamp (datetime.datetime, optional) – \(k\)

• control_input (StateVector, optional) – \(u\)

• **kwargs – These are passed, via transition_function() to matrix()

Returns:

\(\mathbf{y}_{k|k-1}\), the predicted information state and the predicted information matrix \(Y_{k|k-1}\)

Return type:

InformationStatePrediction

Accumulated State Densities

class stonesoup.predictor.asd.ASDKalmanPredictor(transition_model: LinearGaussianTransitionModel, control_model: LinearControlModel = None)

Bases: KalmanPredictor

Accumulated State Densities Kalman Predictor

A linear predictor for accumulated state densities, for processing out of sequence measurements. This requires the state is represented in ASDGaussianState multi-state.

References

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

2. F. Govaers and W. Koch, Generalized Solution to Smoothing and Out-of-Sequence Processing in IEEE Transactions on Aerospace and Electronic Systems, vol. 50, no. 3, pp. 1739-1748, JULY 2014, doi: 10.1109/TAES.2014.130009.

Parameters:

• transition_model (LinearGaussianTransitionModel) – The transition model to be used.

• control_model (LinearControlModel, optional) – The control model to be used. Default None where the predictor will create a zero-effect linear ControlModel.

predict(prior, timestamp, **kwargs)

The predict function

Parameters:

• prior (ASDGaussianState) – \(\mathbf{x}_{k-1}\)

• timestamp (datetime.datetime,) – \(k\)

• **kwargs – These are passed, via transition_function() to matrix()

Returns:

\(\mathbf{x}_{k|k-1}\), the predicted state and the predicted state covariance \(P_{k|k-1}\)

Return type:

ASDState

prune_state(predicted_state)

Simple ASD pruning function. Deletes timesteps from the multi state if it is longer then max_nstep

Parameters:

predicted_state (ASDState) – \(\mathbf{x}_{k|k-1}\)

Returns:

\(\mathbf{x}_{k|k-1}\), the pruned state and the pruned state covariance \(P_{k|k-1}\)

Return type:

ASDState

Categorical

class stonesoup.predictor.categorical.HMMPredictor(transition_model: MarkovianTransitionModel, control_model: ControlModel = None)

Bases: Predictor

Hidden Markov model predictor

Assumes transition model is time-invariant, and therefore care should be taken when predicting forward to the same time.

Parameters:

• transition_model (MarkovianTransitionModel) – The transition model used to predict states forward in time.

• control_model (ControlModel, optional) – control model

transition_model: MarkovianTransitionModel

The transition model used to predict states forward in time.

predict(prior, timestamp=None, **kwargs)

Predicts a CategoricalState forward using the transition_model.

Parameters:

• prior (CategoricalState) – \(\alpha_{t-1}\)

• timestamp (datetime.datetime, optional) – \(t\)

• **kwargs – These are passed to the transition_model.function() method.

Returns:

The predicted state.

Return type:

CategoricalStatePrediction

Notes

The Markovian transition model is time-invariant and the evaluated time_interval can be None.

Composite

class stonesoup.predictor.composite.CompositePredictor(sub_predictors: Sequence[Predictor], control_model: ControlModel = None)

Bases: Predictor

Composite predictor type

A composition of ordered sub-predictors (Predictor). Independently predicts each sub-state of a CompositeState forward using a corresponding sub-predictor.

Parameters:

• sub_predictors (Sequence[Predictor]) – Sequence of sub-predictors comprising the composite predictor. Must not be empty.

• control_model (ControlModel, optional) – control model

sub_predictors: Sequence[Predictor]

Sequence of sub-predictors comprising the composite predictor. Must not be empty.

property transition_model

transition model

predict(prior, timestamp=None, **kwargs)

The predict function

Parameters:

• prior (CompositeState) – The composite state of an object to be predicted forwards

• timestamp (datetime.datetime, optional) – \(k\)

• **kwargs – These are passed to each sub-predictor’s prediction method

Returns:

The predicted composite state

Return type:

CompositeState