Initiators

class stonesoup.initiator.base.Initiator[source]

Bases: stonesoup.base.Base

Initiator base class

Creates zero or more tracks based on provided detections.

abstract initiate(detections: Set[Detection], timestamp: datetime.datetime, **kwargs) → Set[stonesoup.types.track.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: stonesoup.initiator.base.Initiator

Gaussian Initiator base class

Base class for initiator’s which initialises tracks with a GaussianState

class stonesoup.initiator.base.ParticleInitiator[source]

Bases: stonesoup.initiator.base.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: stonesoup.initiator.base.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: stonesoup.types.state.GaussianState: Prior state information

measurement_model: stonesoup.models.measurement.base.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: stonesoup.initiator.base.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: stonesoup.types.state.GaussianState: Prior state information

measurement_model: stonesoup.models.measurement.base.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)[source]

Bases: stonesoup.initiator.base.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: stonesoup.types.state.GaussianState: Prior state information

deleter: stonesoup.deleter.base.Deleter: Deleter used to delete the track.

data_associator: stonesoup.dataassociator.base.DataAssociator: Association algorithm to pair predictions to detections.

updater: stonesoup.updater.base.Updater: Updater used to update the track object to the new state.

measurement_model: stonesoup.models.measurement.base.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: stonesoup.initiator.base.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.GaussianParticleInitiator(initiator: GaussianInitiator, number_particles: int = 200, use_fixed_covar: bool = False)[source]

Bases: stonesoup.initiator.base.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: stonesoup.initiator.base.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

Wrappers

class stonesoup.initiator.wrapper.StatesLengthLimiter(initiator: Initiator, max_length: int)[source]

Bases: stonesoup.initiator.base.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: stonesoup.initiator.base.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: stonesoup.initiator.base.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: stonesoup.types.state.CategoricalState: Prior state information

updater: stonesoup.updater.categorical.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: stonesoup.initiator.base.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[stonesoup.initiator.base.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.