Component Interfaces

This sections contains the base classes for the different components within the Stone Soup Framework.

Enabling Components

class stonesoup.detector.Detector(sensor: SensorDataReader)[source]

Detector base class

A Detector processes SensorData to generate Detection data.

Parameters:: sensor (SensorDataReader) – Source of sensor data

sensor: SensorDataReader: Source of sensor data

abstract detections_gen()

Returns a generator of detections for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of Detection – Detections generate in the time step

class stonesoup.feeder.Feeder(reader: Reader)[source]

Feeder base class

Feeder consumes and outputs State data and can be used to modify the sequence, duplicate or drop data.

Parameters:: reader (Reader) – Source of detections

reader: Reader: Source of detections

class stonesoup.metricgenerator.MetricGenerator[source]

Metric Generator base class

Generates Metric objects used to assess the performance of a tracker using data held in a MetricManager object

abstract compute_metric(manager, **kwargs)[source]

Compute metric

Parameters:: manager (MetricManager) – containing the data to be used to create the metric(s)
Returns:: Generated metrics
Return type:: list of Metric objects

abstract property generator_name: str

Unique identifier when accessing generated metrics from MultiManager.

Return type:: unique identifier as string

class stonesoup.tracker.Tracker[source]: Tracker base class

Data Input

class stonesoup.reader.DetectionReader[source]

Detection Reader base class

abstract detections_gen()[source]

Returns a generator of detections for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of Detection – Detections generate in the time step

class stonesoup.reader.GroundTruthReader[source]

Ground Truth Reader base class

abstract groundtruth_paths_gen()[source]

Returns a generator of ground truth paths for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of GroundTruthPath – Ground truth paths existing in the time step

class stonesoup.reader.SensorDataReader[source]

Sensor Data Reader base class

abstract sensor_data_gen()[source]

Returns a generator of sensor data for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of SensorData – Sensor data generated in the time step

Data Output

class stonesoup.writer.MetricsWriter(metric_generator: MetricGenerator)[source]

Metrics Writer base class.

Writes out metrics to some form of storage for analysis.

Parameters:: metric_generator (MetricGenerator) – Source of metric to be written out

metric_generator: MetricGenerator: Source of metric to be written out

class stonesoup.writer.TrackWriter(tracker: Tracker)[source]

Track Writer base class.

Writes out tracks to some form of storage for analysis.

Parameters:: tracker (Tracker) – Source of tracks to be written out

tracker: Tracker: Source of tracks to be written out

Simulation

class stonesoup.simulator.DetectionSimulator[source]

Detection Simulator base class

abstract detections_gen()

Returns a generator of detections for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of Detection – Detections generate in the time step

class stonesoup.simulator.GroundTruthSimulator[source]

Ground truth simulator

abstract groundtruth_paths_gen()

Returns a generator of ground truth paths for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of GroundTruthPath – Ground truth paths existing in the time step

class stonesoup.simulator.SensorSimulator[source]

Sensor Simulator base class

abstract sensor_data_gen()

Returns a generator of sensor data for each time step.

Yields:

datetime.datetime – Datetime of current time step
set of SensorData – Sensor data generated in the time step

class stonesoup.platform.Platform(movement_controller: Movable = None, sensors: MutableSequence[Sensor] = None, id: str = None)[source]

A platform that can carry a number of different sensors.

The location of platform mounted sensors will be maintained relative to the sensor position. Platforms move within a 2 or 3 dimensional rectangular cartesian space.

A simple platform is considered to always be aligned with its principle velocity. It does not take into account issues such as bank angle or body deformation (e.g. flex).

Movement is controlled by the Platform’s Platform.movement_controller, and access to attributes of the Platform is proxied to the movement controller, to allow the Platform to report its own position, orientation etc.

If a movement_controller argument is not supplied to the constructor, the Platform will try to construct one using unused arguments passed to the Platform’s constructor.

Note

This class is abstract and not intended to be instantiated. To get the behaviour of this class use a subclass which gives movement behaviours. Currently, these are FixedPlatform and MovingPlatform

Parameters:

movement_controller (Movable, optional) – Movable object to control the Platform’s movement. Default is None, but it can be constructed transparently by passing Movable’s constructor parameters to the Platform constructor.
sensors (collections.abc.MutableSequence, optional) – A list of N mounted sensors. Defaults to an empty list.
id (str, optional) – The unique platform ID. Default None where random UUID is generated.

movement_controller: Movable: Movable object to control the Platform’s movement. Default is None, but it can be constructed transparently by passing Movable’s constructor parameters to the Platform constructor.

id: str: The unique platform ID. Default None where random UUID is generated.

sensors: MutableSequence[Sensor]: A list of N mounted sensors. Defaults to an empty list.

add_sensor(sensor: Sensor) → None[source]

Add a sensor to the platform.

Parameters:: sensor (BaseSensor) – The sensor object to add.

remove_sensor(sensor: Sensor) → None[source]

Remove a sensor from the platform.

Parameters:: sensor (BaseSensor) – The sensor object to remove.

pop_sensor(index: int = -1)[source]

Remove and return a sensor from the platform by index. If no index is specified, remove and return the last sensor in self.sensors.

Parameters:: index (int) – The index of the sensor to remove. Defaults to the last item in the list.

property ground_truth_path: GroundTruthPath

Produce a GroundTruthPath with the same id and states as the platform.

The states property for the platform and ground_truth_path are dynamically linked: self.ground_truth_path.states is self.states

So after platform.move() the ground_truth_path will contain the new state. However, replacing the id, states or movement_controller variables in either the platform or ground truth path will not be reflected in the other object. platform_gtp = self.ground_truth_path platform_gtp.states = [] self.states is not platform_gtp.states

Platform.ground_truth_path produces a new GroundTruthPath on every instance. It is not an object that is updated self.ground_truth_path.states is not self.ground_truth_path.states

class stonesoup.sensor.sensor.Sensor(rotation_offset: StateVector = None, mounting_offset: StateVector = None, movement_controller: Movable = None)[source]

Sensor Base class for general use.

Most properties and methods are inherited from PlatformMountable.

Notes

Sensors must have a measure function.
Attributes that are modifiable via actioning the sensor should be ActionableProperty types.
The sensor has a timestamp property that should be updated via its act() method.

Parameters:

rotation_offset (StateVector, optional) – A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping
mounting_offset (StateVector, optional) – A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3
movement_controller (Movable, optional) – The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

validate_timestamp()[source]

Method to validate the timestamp of the actionable.

Returns:: True if timestamp is valid, False otherwise.
Return type:: bool

abstract measure(ground_truths: set[GroundTruthState], noise: ndarray | bool = True, **kwargs) → set[TrueDetection][source]

Generate a measurement for a given state

Parameters:

ground_truths (Set[GroundTruthState]) – A set of GroundTruthState
noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is True, in which case rvs() is used; if False, no noise will be added)

Returns:

A set of measurements generated from the given states. The timestamps of the measurements are set equal to that of the corresponding states that they were calculated from. Each measurement stores the ground truth path that it was produced from.

Return type:

Set[TrueDetection]

abstract property measurement_model: Measurement model of the sensor, describing general sensor model properties

act(timestamp: datetime, **kwargs)

Carry out actions up to a timestamp.

Parameters:: timestamp (datetime.datetime) – Carry out actions up to this timestamp.

actions(timestamp: datetime, start_timestamp: datetime = None) → set[ActionGenerator]

Method to return a set of action generators available up to a provided timestamp.

A generator is returned for each actionable property that the sensor has.

Parameters:

timestamp (datetime.datetime) – Time of action finish.
start_timestamp (datetime.datetime, optional) – Time of action start.

Returns:

Set of action generators, that describe the bounds of each action space.

Return type:

set of ActionGenerator

add_actions(actions: Sequence[Action]) → bool

Add actions to the sensor

Parameters:: actions (sequence of Action) – Sequence of actions that will be executed in order
Returns:: Return True if actions accepted. False if rejected. Returns neither if timestamp is invalid.
Return type:: bool
Raises:: NotImplementedError – If sensor cannot be tasked.

Notes

Base class returns True

mounting_offset: StateVector: A StateVector containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with length 3

movement_controller: Movable: The `Movable object that controls the movement of this sensor. Will be set by the platform if the sensor is assigned to a platform.

property orientation: StateVector | None: A 3x1 StateVector of angles (rad), specifying the sensor orientation in terms of the counter-clockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin.

Note

This property delegates the actual calculation of orientation to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller.

property position: StateVector | None: The sensor position on a 3D Cartesian plane, expressed as a 3x1 StateVector of Cartesian coordinates in the order \(x,y,z\).

Note

This property delegates the actual calculation of position to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller.

rotation_offset: StateVector: A StateVector containing the sensor rotation offsets from the platform’s primary axis (defined as the direction of motion). Defaults to a zero vector with the same length as the Platform’s velocity_mapping

property velocity: StateVector | None: The sensor velocity on a 3D Cartesian plane, expressed as a 3x1 StateVector of Cartesian coordinates in the order \(x,y,z\).

Note

This property delegates the actual calculation of velocity to the Sensor’s movement_controller

It is settable if, and only if, the sensor holds its own internal movement_controller which is a MovingMovable.

Algorithm Components

class stonesoup.dataassociator.DataAssociator(hypothesiser: Hypothesiser)[source]

Data Associator base class

A data associator is used to associate tracks and detections, and may also include an association of a missed detection. The associations generate are in the form a mapping each track to a hypothesis, based on “best” choice from hypotheses generate from a Hypothesiser.

Parameters:: hypothesiser (Hypothesiser) – Generate a set of hypotheses for each track-detection pair

hypothesiser: Hypothesiser: Generate a set of hypotheses for each track-detection pair

abstract associate(tracks: set[Track], detections: set[Detection], timestamp: datetime, **kwargs) → Mapping[Track, Hypothesis][source]

Associate tracks and detections

Parameters:

tracks (set of Track) – Tracks which detections will be associated to.
detections (set of Detection) – Detections to be associated to tracks.
timestamp (datetime.datetime) – Timestamp to be used for missed detections and to predict to.

Returns:

Mapping of track to Hypothesis

Return type:

mapping of Track : Hypothesis

class stonesoup.deleter.Deleter(delete_last_pred: bool = False)[source]

Deleter base class.

Proposes tracks for deletion.

Parameters:: delete_last_pred (bool, optional) – Remove the state that caused a track to be deleted if it is a prediction.

delete_last_pred: bool: Remove the state that caused a track to be deleted if it is a prediction.

abstract check_for_deletion(track: Track, **kwargs) → bool[source]

Check if a given track should be deleted.

Parameters:: track (Track) – A track object to be checked for deletion.
Returns:: True if track should be deleted, False otherwise.
Return type:: bool

delete_tracks(tracks: set[Track], **kwargs) → set[Track][source]

Generic/Base track deletion method.

Iterates through all tracks in a given list and calls check_for_deletion() to determine which tracks should be deleted and which should survive.

Parameters:: tracks (set of Track) – A set of Track objects
Returns:: Set of tracks proposed for deletion.
Return type:: set of Track

class stonesoup.hypothesiser.Hypothesiser[source]

Hypothesiser base class

Given a track and set of detections, generate hypothesis of association.

hypothesise(track: Track, detections: set[Detection], timestamp: datetime, **kwargs) → Sequence[Hypothesis][source]

Hypothesise track and detection association

Parameters:

track (Track) – Track which hypotheses will be generated for.
detections (set of Detection) – Detections used to generate hypotheses.
timestamp (datetime.datetime) – A timestamp used when evaluating the state and measurement predictions. Note that if a given detection has a non empty timestamp, then prediction will be performed according to the timestamp of the detection.

Returns:

Ordered sequence of “best” to “worse” hypothesis.

Return type:

sequence of Hypothesis

class stonesoup.gater.Gater(hypothesiser: Hypothesiser | Gater)[source]

Gater base class

Gaters wrap Hypothesiser objects and can be used to modify (typically reduce) the returned hypotheses.

Parameters:: hypothesiser (Union[Hypothesiser, ForwardRef('Gater')]) – Hypothesiser or Gater that is being wrapped.

hypothesiser: Hypothesiser | Gater: Hypothesiser or Gater that is being wrapped.

class stonesoup.initiator.Initiator[source]

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.mixturereducer.MixtureReducer[source]: Mixture Reducer base class

class stonesoup.predictor.Predictor(transition_model: TransitionModel, control_model: ControlModel = None)[source]

Predictor base class

A predictor is used to predict a new State given a prior State and a TransitionModel. In addition, a ControlModel may be used to model an external influence on the state.

\[\mathbf{x}_{k|k-1} = f_k(\mathbf{x}_{k-1}, \mathbf{\nu}_k) + b_k(\mathbf{u}_k, \mathbf{\eta}_k)\]

where \(\mathbf{x}_{k-1}\) is the prior state, \(f_k(\mathbf{x}_{k-1})\) is the transition function, \(\mathbf{u}_k\) the control vector, \(b_k(\mathbf{u}_k)\) the control input and \(\mathbf{\nu}_k\) and \(\mathbf{\eta}_k\) the transition and control model noise respectively.

Parameters:

transition_model (TransitionModel) – transition model
control_model (ControlModel, optional) – control model

transition_model: TransitionModel: transition model

control_model: ControlModel: control model

abstract predict(prior, timestamp=None, **kwargs)[source]

The prediction function itself

Parameters:

prior (State) – The prior state
timestamp (datetime.datetime, optional) – Time at which the prediction is made (used by the transition model)

Returns:

State prediction

Return type:

StatePrediction

class stonesoup.resampler.Resampler[source]: Resampler base class

class stonesoup.smoother.Smoother(transition_model: TransitionModel = None)[source]

Smoother Base Class

(Fixed interval) Smoothers in general are used to infer a state, or series of states, \(\mathbf{x}_k\) from measurements \(\mathbf{z}_{1:K}\) where \(k < K\).

The calculation is forward-backward in nature. The forward algorithm is “standard” filtering, provided by other Stone Soup components. The Smoother’s input is therefore a Track (created by whatever means) The smooth() function undertakes the backward algorithm.

Parameters:: transition_model (TransitionModel, optional) – Transition Model.

transition_model: TransitionModel: Transition Model.

class stonesoup.updater.Updater(measurement_model: MeasurementModel)[source]

Updater base class

An updater is used to update the predicted state, utilising a measurement and a MeasurementModel. The general observation model is

\[\mathbf{z} = h(\mathbf{x}, \mathbf{\sigma})\]

where \(\mathbf{x}\) is the state, \(\mathbf{\sigma}\), the measurement noise and \(\mathbf{z}\) the resulting measurement.

Parameters:: measurement_model (MeasurementModel) – measurement model

measurement_model: MeasurementModel: measurement model

abstract predict_measurement(predicted_state, measurement_model=None, measurement_noise=True, **kwargs)[source]

Get measurement prediction from state prediction

Parameters:

predicted_state (StatePrediction) – The state prediction
measurement_model (MeasurementModel, optional) – The measurement model used to generate the measurement prediction. Should be used in cases where the measurement model is dependent on the received measurement. The default is None, in which case the updater will use the measurement model specified on initialisation
measurement_noise (bool) – Whether to include measurement noise predicted measurement. Default True

Returns:

The predicted measurement

Return type:

MeasurementPrediction

abstract update(hypothesis, **kwargs)[source]

Update state using prediction and measurement.

Parameters:: hypothesis (Hypothesis) – Hypothesis with predicted state and associated detection used for updating.
Returns:: The state posterior
Return type:: State

Models

class stonesoup.models.control.ControlModel[source]

Control Model base class

property ndim: int: Number of dimensions of model

abstract property ndim_ctrl: int: Number of control input dimensions

abstract function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model function \(f_k(x(k),w(k))\)

Parameters:

state (State) – An input state
noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:: state (State) – An input state
Returns:: The model jacobian matrix evaluated around the given state vector.
Return type:: numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

abstract pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

abstract rvs(num_samples: int = 1, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

Parameters:: num_samples (scalar, optional) – The number of samples to be generated (the default is 1)
Returns:: noise – A set of Np samples, generated from the model’s noise distribution.
Return type:: 2-D array of shape (ndim, num_samples)

class stonesoup.models.measurement.MeasurementModel(ndim_state: int, mapping: Sequence[int])[source]

Measurement Model base class

Parameters:

ndim_state (int) – Number of state dimensions
mapping (collections.abc.Sequence) – Mapping between measurement and state dims

ndim_state: int: Number of state dimensions

mapping: Sequence[int]: Mapping between measurement and state dims

property ndim: int: Number of dimensions of model

abstract property ndim_meas: int: Number of measurement dimensions

abstract function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model function \(f_k(x(k),w(k))\)

Parameters:

state (State) – An input state
noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:: state (State) – An input state
Returns:: The model jacobian matrix evaluated around the given state vector.
Return type:: numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

abstract pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

abstract rvs(num_samples: int = 1, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

Parameters:: num_samples (scalar, optional) – The number of samples to be generated (the default is 1)
Returns:: noise – A set of Np samples, generated from the model’s noise distribution.
Return type:: 2-D array of shape (ndim, num_samples)

class stonesoup.models.transition.TransitionModel[source]

Transition Model base class

property ndim: int: Number of dimensions of model

abstract property ndim_state: int: Number of state dimensions

abstract function(state: State, noise: bool | ndarray = False, **kwargs) → StateVector | StateVectors

Model function \(f_k(x(k),w(k))\)

Parameters:

state (State) – An input state
noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

jacobian(state, **kwargs)

Model jacobian matrix \(H_{jac}\)

Parameters:: state (State) – An input state
Returns:: The model jacobian matrix evaluated around the given state vector.
Return type:: numpy.ndarray of shape (ndim_meas, ndim_state)

logpdf(state1: State, state2: State, **kwargs) → float | ndarray

Model log pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The log likelihood of state1, given state2

Return type:

float or ndarray

abstract pdf(state1: State, state2: State, **kwargs) → Probability | ndarray

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

abstract rvs(num_samples: int = 1, **kwargs) → StateVector | StateVectors

Model noise/sample generation function

Generates noise samples from the model.

Parameters:: num_samples (scalar, optional) – The number of samples to be generated (the default is 1)
Returns:: noise – A set of Np samples, generated from the model’s noise distribution.
Return type:: 2-D array of shape (ndim, num_samples)