Predictors¶
Base classes for Stone Soup Predictor interface

class
stonesoup.predictor.base.
Predictor
(transition_model, control_model=None)[source]¶ Bases:
stonesoup.base.Base
Predictor base class
A predictor is used to predict a new
State
given a priorState
and aTransitionModel
. In addition, aControlModel
may be used to model an external influence on the state.\[\mathbf{x}_{kk1} = f_k(\mathbf{x}_{k1}, \mathbf{\nu}_k) + b_k(\mathbf{u}_k, \mathbf{\eta}_k)\]where \(\mathbf{x}_{k1}\) is the prior state, \(f_k(\mathbf{x}_{k1})\) 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 modelcontrol_model (
ControlModel
, optional) – control model

transition_model
: stonesoup.models.transition.base.TransitionModel¶ transition model

control_model
: stonesoup.models.control.base.ControlModel¶ control model

abstract
predict
(prior, timestamp=None, **kwargs)[source]¶ The prediction function itself
 Parameters
prior (
State
) – The prior statetimestamp (
datetime.datetime
, optional) – Time at which the prediction is made (used by the transition model)
 Returns
State prediction
 Return type
Kalman¶

class
stonesoup.predictor.kalman.
KalmanPredictor
(transition_model, control_model=None)[source]¶ Bases:
stonesoup.predictor.base.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\[f_k( \mathbf{x}_{k1}) = F_k \mathbf{x}_{k1}, \ b_k( \mathbf{u}_k) = B_k \mathbf{u}_k \ \mathrm{and} \ \mathbf{\nu}_k \sim \mathcal{N}(0,Q_k)\]Notes
In the Kalman filter, transition and control models must be linear.
 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 zeroeffect linearControlModel
.

transition_model
: stonesoup.models.transition.linear.LinearGaussianTransitionModel¶ The transition model to be used.

control_model
: stonesoup.models.control.linear.LinearControlModel¶ The control model to be used. Default None where the predictor will create a zeroeffect linear
ControlModel
.

predict
(prior, timestamp=None, **kwargs)[source]¶ The predict function
 Parameters
prior (
State
) – \(\mathbf{x}_{k1}\)timestamp (
datetime.datetime
, optional) – \(k\)**kwargs – These are passed, via
transition_function()
tomatrix()
 Returns
\(\mathbf{x}_{kk1}\), the predicted state and the predicted state covariance \(P_{kk1}\)
 Return type

class
stonesoup.predictor.kalman.
ExtendedKalmanPredictor
(transition_model, control_model=None)[source]¶ Bases:
stonesoup.predictor.kalman.KalmanPredictor
ExtendedKalmanPredictor class
An implementation of the Extended Kalman Filter predictor. Here the transition and control functions may be nonlinear, their transition and control matrices are approximated via Jacobian matrices. To this end the transition and control models, if nonlinear, 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 zeroeffect linearControlModel
.

transition_model
: stonesoup.models.transition.base.TransitionModel¶ The transition model to be used.

control_model
: stonesoup.models.control.base.ControlModel¶ The control model to be used. Default None where the predictor will create a zeroeffect linear
ControlModel
.

class
stonesoup.predictor.kalman.
UnscentedKalmanPredictor
(transition_model, control_model=None, alpha=0.5, beta=2, kappa=0)[source]¶ Bases:
stonesoup.predictor.kalman.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 nonlinear) 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 zeroeffect linearControlModel
.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

transition_model
: stonesoup.models.transition.base.TransitionModel¶ The transition model to be used.

control_model
: stonesoup.models.control.base.ControlModel¶ The control model to be used. Default None where the predictor will create a zeroeffect linear
ControlModel
.

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
(prior, timestamp=None, **kwargs)[source]¶ The unscented version of the predict step
 Parameters
prior (
State
) – Prior state, \(\mathbf{x}_{k1}\)timestamp (
datetime.datetime
) – Time to transit to (\(k\))**kwargs (various, optional) – These are passed to
covar()
 Returns
The predicted state \(\mathbf{x}_{kk1}\) and the predicted state covariance \(P_{kk1}\)
 Return type

class
stonesoup.predictor.kalman.
SqrtKalmanPredictor
(transition_model, control_model=None, qr_method=False)[source]¶ Bases:
stonesoup.predictor.kalman.KalmanPredictor
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 theqr_method = True
flag, is to predict via a modified GramSchmidt 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 andsqrt_control_noise
for control models), then these are used directly. If not then they are created from the full matrices using the scipy.linalgsqrtm()
method. (Unlike the Cholesky decomposition this works on positive semidefinite matrices, as well as positive definite ones.References
Maybeck, P.S. 1994, Stochastic Models, Estimation, and Control, Vol. 1, NavtechGPS, Springfield, VA.
 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 zeroeffect linearControlModel
.qr_method (
bool
, optional) – A switch to do the prediction via a QR decomposition, rather than using a Cholesky decomposition.
Particle¶

class
stonesoup.predictor.particle.
ParticlePredictor
(transition_model, control_model=None)[source]¶ Bases:
stonesoup.predictor.base.Predictor
ParticlePredictor class
An implementation of a Particle Filter predictor.
 Parameters
transition_model (
TransitionModel
) – transition modelcontrol_model (
ControlModel
, optional) – control model

predict
(prior, control_input=None, timestamp=None, **kwargs)[source]¶ Particle Filter prediction step
 Parameters
prior (
ParticleState
) – A prior state objectcontrol_input (
State
, optional) – The control input. It will only have an effect ifcontrol_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