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
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
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
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)[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.

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.

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
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
Returns

A list of new tracks with a initial ParticleState

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

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.