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