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 tracks
timestamp (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 provided prior_state for each unassociated detection.

Parameters:

prior_state (GaussianState) – Prior state information
measurement_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 detections
timestamp (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 convert Detection state vector and model covariance into state space. It either takes the MeasurementModel from the given detection or uses the measurement_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 initial GaussianState of the Track.

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 information
measurement_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.

diag_load: float: Positive float value for diagonal loading

initiate(detections, timestamp, **kwargs)[source]

Generate tracks from detections.

Parameters:

detections (set of Detection) – Detections used to generate set of tracks
timestamp (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 information
deleter (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) – Whether min_points only counts Update states.
initiator (Initiator, optional) – Initiator used to create tracks. If None, a SimpleMeasurementInitiator will be created using prior_state and measurement_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 a LinearModel or a ReversibleModel.

prior_state: GaussianState: Prior state information

deleter: 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: Measurement model. Can be left as None if all detections have a valid measurement model.

min_points: int: Minimum number of track points required to confirm a track.

updates_only: bool: Whether min_points only counts Update 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 a ReversibleModel.

initiator: Initiator: Initiator used to create tracks. If None, a SimpleMeasurementInitiator will be created using prior_state and measurement_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 tracks
timestamp (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 information
deleter (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) – Whether min_points only counts Update states.
initiator (Initiator, optional) – Initiator used to create tracks. If None, a SimpleMeasurementInitiator will be created using prior_state and measurement_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 a LinearModel or a ReversibleModel.

initiate(*args, **kwargs)[source]

Generate tracks from detections.

Parameters:

detections (set of Detection) – Detections used to generate set of tracks
timestamp (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 state
use_fixed_covar (bool, optional) – If True, the Gaussian state covariance is used for the ParticleState as a fixed covariance. Default False.

initiator: GaussianInitiator: Gaussian Initiator which will be used to generate tracks.

number_particles: int: Number of particles for initial track state

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 detections
timestamp (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 detections
timestamp (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 detections
timestamp (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.

ensemble_size: int: Integer to determine the size of the Gaussian Ensemble State.

initiate(detections, timestamp, **kwargs)[source]

Initiates tracks given unassociated measurements

Parameters:

detections (set of Detection) – A list of unassociated detections
timestamp (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 detections
timestamp (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 density
predictor (SMCPHDPredictor) – SMC-PHD predictor used to predict the PHD density
updater (SMCPHDUpdater) – SMC-PHD updater used to update the PHD density
threshold (float, optional) – Existence probability threshold for initiating tracks. Default is 0.9
num_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

threshold: float: Existence probability threshold for initiating tracks. Default is 0.9

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 tracks
timestamp (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 Initiator
max_length (int) – Length of track history to be stored in memory

initiator: Initiator: Stone Soup Initiator

max_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 tracks
timestamp (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 information
updater (HMMUpdater) – Hidden Markov model updater

prior_state: CategoricalState: Prior state information

updater: HMMUpdater: Hidden Markov model updater

initiate(detections, *args, **kwargs)[source]: Create a new track for each detection. Updating the prior-state with a detection to start-off a new track.

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 a CompositeState 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 the prior_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.