Initiators
- class stonesoup.initiator.base.Initiator[source]
Bases:
Base
Initiator base class
Creates zero or more tracks based on provided detections.
- abstract initiate(detections: set[Detection], timestamp: datetime, **kwargs) set[Track] [source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
- class stonesoup.initiator.base.GaussianInitiator[source]
Bases:
Initiator
Gaussian Initiator base class
Base class for initiator’s which initialises tracks with a
GaussianState
- class stonesoup.initiator.base.ParticleInitiator[source]
Bases:
Initiator
Particle Initiator base class
Base class for initiator’s which initialises tracks with a
ParticleState
- class stonesoup.initiator.simple.SinglePointInitiator(prior_state: GaussianState, measurement_model: MeasurementModel = None)[source]
Bases:
GaussianInitiator
SinglePointInitiator class
This uses an
ExtendedKalmanUpdater
to carry out an update using providedprior_state
for each unassociated detection.- Parameters:
prior_state (
GaussianState
) – Prior state informationmeasurement_model (
MeasurementModel
, optional) – Measurement model. Can be left as None if all detections have a valid measurement model.
- prior_state: GaussianState
Prior state information
- measurement_model: MeasurementModel
Measurement model. Can be left as None if all detections have a valid measurement model.
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with an initial
GaussianState
- Return type:
set of
Track
- class stonesoup.initiator.simple.SimpleMeasurementInitiator(prior_state: GaussianState, measurement_model: MeasurementModel = None, skip_non_reversible: bool = False, diag_load: float = 0.0)[source]
Bases:
GaussianInitiator
Initiator that maps measurement space to state space
Works for both linear and non-linear co-ordinate input
This initiator utilises the
MeasurementModel
matrix to convertDetection
state vector and model covariance into state space. It either takes theMeasurementModel
from the given detection or uses themeasurement_model
.Utilises the ReversibleModel inverse function to convert non-linear spherical co-ordinates into Cartesian x/y co-ordinates for use in predictions and mapping.
This then replaces mapped values in the
prior_state
to form the initialGaussianState
of theTrack
.The diagonal loading value is used to try to ensure that the estimated covariance matrix is positive definite, especially for subsequent Cholesky decompositions.
- Parameters:
prior_state (
GaussianState
) – Prior state informationmeasurement_model (
MeasurementModel
, optional) – Measurement model. Can be left as None if all detections have a valid measurement model.skip_non_reversible (
bool
, optional)diag_load (
float
, optional) – Positive float value for diagonal loading
- prior_state: GaussianState
Prior state information
- measurement_model: MeasurementModel
Measurement model. Can be left as None if all detections have a valid measurement model.
- initiate(detections, timestamp, **kwargs)[source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
- class stonesoup.initiator.simple.MultiMeasurementInitiator(prior_state: GaussianState, deleter: Deleter, data_associator: DataAssociator, updater: Updater, measurement_model: MeasurementModel = None, min_points: int = 2, updates_only: bool = True, initiator: Initiator = None, skip_non_reversible: bool = False)[source]
Bases:
GaussianInitiator
Multi-measurement initiator.
Utilises features of the tracker to initiate and hold tracks temporarily within the initiator itself, releasing them to the tracker once there are multiple detections associated with them enough to determine that they are ‘sure’ tracks.
Utilises simple initiator to initiate tracks to hold -> prevents code duplication.
Solves issue of short-lived single detection tracks being initiated only to then be removed shortly after. Does cause slight delay in initiation to tracker.
- Parameters:
prior_state (
GaussianState
) – Prior state informationdeleter (
Deleter
) – Deleter used to delete the track.data_associator (
DataAssociator
) – Association algorithm to pair predictions to detections.updater (
Updater
) – Updater used to update the track object to the new state.measurement_model (
MeasurementModel
, optional) – Measurement model. Can be left as None if all detections have a valid measurement model.min_points (
int
, optional) – Minimum number of track points required to confirm a track.updates_only (
bool
, optional) – Whethermin_points
only countsUpdate
states.initiator (
Initiator
, optional) – Initiator used to create tracks. If None, aSimpleMeasurementInitiator
will be created usingprior_state
andmeasurement_model
. Otherwise, these attributes are ignored.skip_non_reversible (
bool
, optional) – Skip measurements that do not have a reversible measurement model. Only allow measurements with a measurement model that is an instance of aLinearModel
or aReversibleModel
.
- prior_state: GaussianState
Prior state information
- data_associator: DataAssociator
Association algorithm to pair predictions to detections.
- measurement_model: MeasurementModel
Measurement model. Can be left as None if all detections have a valid measurement model.
- updates_only: bool
Whether
min_points
only countsUpdate
states.
- skip_non_reversible: bool
Skip measurements that do not have a reversible measurement model. Only allow measurements with a measurement model that is an instance of a
LinearModel
or aReversibleModel
.
- initiator: Initiator
Initiator used to create tracks. If None, a
SimpleMeasurementInitiator
will be created usingprior_state
andmeasurement_model
. Otherwise, these attributes are ignored.
- initiate(detections, timestamp, **kwargs)[source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
- class stonesoup.initiator.simple.NoHistoryMultiMeasurementInitiator(prior_state: GaussianState, deleter: Deleter, data_associator: DataAssociator, updater: Updater, measurement_model: MeasurementModel = None, min_points: int = 2, updates_only: bool = True, initiator: Initiator = None, skip_non_reversible: bool = False)[source]
Bases:
MultiMeasurementInitiator
This initiator is very similar to
MultiMeasurementInitiator
. The only difference being that the holding track’s history is moved to the metadata so that initialised tracks only have one state.- Parameters:
prior_state (
GaussianState
) – Prior state informationdeleter (
Deleter
) – Deleter used to delete the track.data_associator (
DataAssociator
) – Association algorithm to pair predictions to detections.updater (
Updater
) – Updater used to update the track object to the new state.measurement_model (
MeasurementModel
, optional) – Measurement model. Can be left as None if all detections have a valid measurement model.min_points (
int
, optional) – Minimum number of track points required to confirm a track.updates_only (
bool
, optional) – Whethermin_points
only countsUpdate
states.initiator (
Initiator
, optional) – Initiator used to create tracks. If None, aSimpleMeasurementInitiator
will be created usingprior_state
andmeasurement_model
. Otherwise, these attributes are ignored.skip_non_reversible (
bool
, optional) – Skip measurements that do not have a reversible measurement model. Only allow measurements with a measurement model that is an instance of aLinearModel
or aReversibleModel
.
- initiate(*args, **kwargs)[source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
- class stonesoup.initiator.simple.GaussianParticleInitiator(initiator: GaussianInitiator, number_particles: int = 200, use_fixed_covar: bool = False)[source]
Bases:
ParticleInitiator
Gaussian Particle Initiator class
Utilising Gaussian Initiator, sample from the resultant track’s state to generate a number of particles, overwriting with a
ParticleState
.- Parameters:
initiator (
GaussianInitiator
) – Gaussian Initiator which will be used to generate tracks.number_particles (
int
, optional) – Number of particles for initial track stateuse_fixed_covar (
bool
, optional) – If True, the Gaussian state covariance is used for theParticleState
as a fixed covariance. Default False.
- initiator: GaussianInitiator
Gaussian Initiator which will be used to generate tracks.
- use_fixed_covar: bool
If True, the Gaussian state covariance is used for the
ParticleState
as a fixed covariance. Default False.
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with a initial
ParticleState
- Return type:
set of
Track
- class stonesoup.initiator.simple.GaussianMixtureInitiator(initiator: GaussianInitiator)[source]
Bases:
GaussianInitiator
Gaussian Mixture Initiator class
Utilising Gaussian Initiator, applying the resultant track’s state to generate a Tagged Weighted Gaussian State, overwriting with a
GaussianMixture
.- Parameters:
initiator (
GaussianInitiator
) – Gaussian Initiator which will be used to generate tracks.
- initiator: GaussianInitiator
Gaussian Initiator which will be used to generate tracks.
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with an initial
GaussianMixture
- Return type:
set of
Track
- class stonesoup.initiator.simple.ASDGaussianInitiator(initiator: GaussianInitiator, max_nstep: int = 0)[source]
Bases:
GaussianInitiator
ASD Gaussian State Initiator class
Utilising Gaussian Initiator, sample from the resultant track’s state to generate an ASD Gaussian State, overwriting with a
ASDGaussianState
.- Parameters:
initiator (
GaussianInitiator
) – Gaussian Initiator which will be used to generate tracks.max_nstep (
int
, optional) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning
- initiator: GaussianInitiator
Gaussian Initiator which will be used to generate tracks.
- max_nstep: int
Decides when the state is pruned in a prediction step. If 0 then there is no pruning
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with an initial
ASDGaussianState
- Return type:
set of
Track
- class stonesoup.initiator.simple.EnsembleInitiator(initiator: GaussianInitiator, ensemble_size: int = 100)[source]
Bases:
GaussianInitiator
Ensemble State Initiator class
Utilising Gaussian Initiator, sample from the resultant track’s state to generate an Ensemble, overwriting with a
EnsembleState
.- Parameters:
initiator (
GaussianInitiator
) – Gaussian Initiator which will be used to generate tracks.ensemble_size (
int
, optional) – Integer to determine the size of the Gaussian Ensemble State.
- initiator: GaussianInitiator
Gaussian Initiator which will be used to generate tracks.
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with an initial
EnsembleState
- Return type:
set of
Track
- class stonesoup.initiator.simple.ParticleGaussianInitiator(initiator: ParticleInitiator)[source]
Bases:
GaussianInitiator
Particle Gaussian Initiator class
Utilising Particle Initiator, convert the resultant track’s state to generate a Gaussian state, overwriting with a
GaussianState
.- Parameters:
initiator (
ParticleInitiator
) – Particle Initiator which will be used to generate tracks.
- initiator: ParticleInitiator
Particle Initiator which will be used to generate tracks.
- initiate(detections, timestamp, **kwargs)[source]
Initiates tracks given unassociated measurements
- Parameters:
detections (set of
Detection
) – A list of unassociated detectionstimestamp (datetime.datetime) – Current timestamp
- Returns:
A list of new tracks with an initial
GaussianState
- Return type:
set of
Track
- class stonesoup.initiator.particle.SMCPHDInitiator(prior_state: ParticleState, predictor: SMCPHDPredictor, updater: SMCPHDUpdater, threshold: float = 0.9, num_track_samples: int = None, resampler: Resampler = None)[source]
Bases:
ParticleInitiator
Sequential Monte Carlo Probability Hypothesis Density (SMC-PHD) Initiator class
An implementation of a particle initiator that uses a Sequential Monte Carlo Probability Hypothesis Density (SMC-PHD) filter to generate tracks from detections, based on [1].
Note
The current implementation does not support non-association weights (i.e. \(\rho_i\) in [1]).
- Parameters:
prior_state (
ParticleState
) – Prior particle state used to initialise the PHD densitypredictor (
SMCPHDPredictor
) – SMC-PHD predictor used to predict the PHD densityupdater (
SMCPHDUpdater
) – SMC-PHD updater used to update the PHD densitythreshold (
float
, optional) – Existence probability threshold for initiating tracks. Default is 0.9num_track_samples (
int
, optional) – Number of particles for initiated tracks. Default is None in which case the number of particles will be set to the number of particles in the prior state.resampler (
Resampler
, optional) – Resampler used to resample the particles of output tracks before returning. Default is None in which case the resampler of the updater will be used.
References
- prior_state: ParticleState
Prior particle state used to initialise the PHD density
- predictor: SMCPHDPredictor
SMC-PHD predictor used to predict the PHD density
- updater: SMCPHDUpdater
SMC-PHD updater used to update the PHD density
- num_track_samples: int
Number of particles for initiated tracks. Default is None in which case the number of particles will be set to the number of particles in the prior state.
- resampler: Resampler
Resampler used to resample the particles of output tracks before returning. Default is None in which case the resampler of the updater will be used.
- initiate(detections, timestamp, **kwargs)[source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
Wrappers
- class stonesoup.initiator.wrapper.StatesLengthLimiter(initiator: Initiator, max_length: int)[source]
Bases:
Initiator
Wrapper that defines the length of track history stored in memory
By default Stone Soup stores the track history for all tracks in memory. If running Stone Soup on very large data your application may run out of memory and the process terminated - often by the operating system.
This wrapper converts the states space list to a collections.deque data type with the maximum length specified.
from stonesoup.initiator.wrapper import StatesLengthLimiter initiator = StatesLengthLimiter(<initiator model>, max_length)
- Parameters:
initiator (
Initiator
) – Stone Soup Initiatormax_length (
int
) – Length of track history to be stored in memory
- initiate(*args, **kwargs)[source]
Generate tracks from detections.
- Parameters:
detections (set of
Detection
) – Detections used to generate set of trackstimestamp (datetime.datetime) – Current timestamp
- Returns:
Tracks generated from detections
- Return type:
set of
Track
Categorical
- class stonesoup.initiator.categorical.SimpleCategoricalMeasurementInitiator(prior_state: CategoricalState, updater: HMMUpdater)[source]
Bases:
Initiator
Initiator that creates tracks in a categorical state space.
Uses state updates from an
HMMUpdater
to initialise new tracks. Initialises a new track on every detection received.- Parameters:
prior_state (
CategoricalState
) – Prior state informationupdater (
HMMUpdater
) – Hidden Markov model updater
- prior_state: CategoricalState
Prior state information
- updater: HMMUpdater
Hidden Markov model updater
Composite
- class stonesoup.initiator.composite.CompositeUpdateInitiator(sub_initiators: Sequence[Initiator])[source]
Bases:
Initiator
Composite initiator type
A composition of sub-initiators (
Initiator
).Requires that all sub-initiators have a defined prior state in order to compose its own composite prior state
- Parameters:
sub_initiators (
Sequence[Initiator]
) – Sequence of sub-initiators comprising the composite initiator. Must not be empty.
- sub_initiators: Sequence[Initiator]
Sequence of sub-initiators comprising the composite initiator. Must not be empty.
- initiate(detections, timestamp, **kwargs)[source]
Utilises its sub-initiators to attempt to initiate a track for a
CompositeDetection
in each sub-state space, then combines the resultant track states in to aCompositeState
track. If any sub-state is missing from the detection, or a sub-initiator fails to initiate in its sub-state space, the corresponding sub-state of theprior_state
will be used instead. It is required that the sub-initiators initiate on a single measurement, in order for the individual sub-states of a track to be linked to one another.