Component Interfaces

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

Enabling Components

class stonesoup.detector.Detector(sensor)

Detector base class

A Detector processes SensorData to generate Detection data.

Parameters

sensor (SensorDataReader) – Source of sensor data

sensor: stonesoup.reader.base.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)

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: stonesoup.reader.base.Reader

Source of detections

class stonesoup.metricgenerator.MetricGenerator

Metric Generator base class

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

abstract compute_metric(manager, **kwargs)

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

class stonesoup.tracker.Tracker

Tracker base class

abstract tracks_gen()

Returns a generator of tracks for each time step.

Yields

• datetime.datetime – Datetime of current time step

• set of Track – Tracks existing in the time step

Data Input

class stonesoup.reader.DetectionReader

Detection Reader 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.reader.GroundTruthReader

Ground Truth Reader base class

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.reader.SensorDataReader

Sensor Data Reader 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

Data Output

class stonesoup.writer.MetricsWriter(metric_generator)

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: stonesoup.metricgenerator.base.MetricGenerator

Source of metric to be written out

class stonesoup.writer.TrackWriter(tracker)

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: stonesoup.tracker.base.Tracker

Source of tracks to be written out

Simulation

class stonesoup.simulator.DetectionSimulator

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

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

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(states, position_mapping, rotation_offsets=None, mounting_offsets=None, sensors=None, velocity_mapping=None)

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

Note

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

• states (Sequence[State]) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

• position_mapping (Sequence[int]) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

• rotation_offsets (MutableSequence[StateVector], optional) – A list of StateVectors 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 position_mapping

• mounting_offsets (MutableSequence[StateVector], optional) – A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’s position_mapping

• sensors (MutableSequence[ForwardRef('BaseSensor')], optional) – A list of N mounted sensors. Defaults to an empty list

• velocity_mapping (Sequence[int], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

states: Sequence[stonesoup.types.state.State]

A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

position_mapping: Sequence[int]

Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

velocity_mapping: Sequence[int]

Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

property position

Return the position of the platform.

Extracted from the state vector of the platform using the platform’s position_mapping. This property is settable for fixed platforms, but not for movable ones, where the position must be set by moving the model with a transition model.

sensors: MutableSequence[BaseSensor]

A list of N mounted sensors. Defaults to an empty list

mounting_offsets: MutableSequence[stonesoup.types.array.StateVector]

A list of StateVectors containing the sensor translation offsets from the platform’s reference point. Defaults to a zero vector with the same length as the Platform’s position_mapping

rotation_offsets: MutableSequence[stonesoup.types.array.StateVector]

A list of StateVectors 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 position_mapping

property ndim

Convenience property to return the number of dimensions in which the platform operates.

Given by the length of the position_mapping

abstract property orientation

Return the orientation of the platform.

Implementation is case dependent and left to the Fixed/Moving subclasses

abstract property velocity

Return the velocity of the platform.

Implementation is case dependent and left to the Fixed/Moving subclasses

abstract is_moving() → bool

Return the True if the platform is moving, False otherwise.

abstract move(timestamp: datetime.datetime, **kwargs) → None

Update the platform position using the transition_model.

Parameters

timestamp (datetime.datetime, optional) – A timestamp signifying when the end of the maneuver (the default is None)

Notes

This methods updates the value of position.

Any provided kwargs are forwarded to the transition_model.

If transition_model or timestamp is None, the method has no effect, but will return successfully.

add_sensor(sensor: BaseSensor, mounting_offset: Optional[stonesoup.types.array.StateVector] = None, rotation_offset: Optional[stonesoup.types.array.StateVector] = None) → None

Add a sensor to the platform

Parameters

• sensor (BaseSensor) – The sensor object to add

• mounting_offset (StateVector, optional) – A StateVector with the mounting offset of the new sensor. If not supplied, defaults to a zero vector

• rotation_offset (StateVector, optional) – A StateVector with the rotation offset of the new sensor. If not supplied, defaults to a zero vector.

remove_sensor(sensor: BaseSensor) → None

Remove a sensor from the platform

Parameters

sensor (BaseSensor) – The sensor object to remove

pop_sensor(index: int)

Remove a sensor from the platform by index

Parameters

index (int) – The index of the sensor to remove

get_sensor_position(sensor: BaseSensor) → stonesoup.types.array.StateVector

Return the position of the given sensor, which should be already attached to the platform. If the sensor is not attached to the platform, raises a ValueError.

Parameters

sensor (BaseSensor) – The sensor for which to return the position.

Returns

The position of the sensor, taking into account the platform position and orientation and the mounting offset of the sensor.

Return type

StateVector

get_sensor_orientation(sensor: BaseSensor) → stonesoup.types.array.StateVector

Return the orientation of the given sensor, which should be already attached to the platform. If the sensor is not attached to the platform, raises a ValueError.

Parameters

sensor (BaseSensor) – The sensor for which to return the orientation.

Returns

The orientation of the sensor, taking into account the platform orientation and the rotation offset of the sensor.

Return type

StateVector

append(value)

S.append(value) – append value to the end of the sequence

clear() → None – remove all items from S

count(value) → integer – return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer – return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, value)

S.insert(index, value) – insert value before index

pop([index]) → item – remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class stonesoup.sensor.sensor.Sensor

Sensor Base class for general use.

Most properties and methods are inherited from BaseSensor, but this class includes crucial functionality and so should be used in preference.

All sensors must be mounted on a platform to calculate their position and orientation. To make this easier, if the sensor has a position and/or orientation specified in the constructor, and no platform_system, then the default is to create an internally held “private” platform for the Sensor. This restricts the later setting of the platform_system but does allow the Sensor to control (and set) its own position and orientation.

property orientation

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 platform on which the sensor is mounted.

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

property platform

Return the platform system to which the sensor is attached. Resolves the weakref stored in the platform_system Property.

property platform_system

Return a weakref to the platform on which the sensor is mounted

property position

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 platform on which the sensor is mounted.

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

property velocity

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 platform on which the sensor is mounted.

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

Algorithm Components

class stonesoup.dataassociator.DataAssociator(hypothesiser)

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: stonesoup.hypothesiser.base.Hypothesiser

Generate a set of hypotheses for each track-detection pair

abstract associate(tracks, detections, timestamp=None, **kwargs)

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.

Returns

Mapping of track to Hypothesis

Return type

mapping of Track : Hypothesis

class stonesoup.deleter.Deleter

Deleter base class.

Proposes tracks for deletion.

abstract check_for_deletion(track, **kwargs)

Abstract method to check if a given track should be deleted

delete_tracks(tracks, **kwargs)

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

Hypothesiser base class

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

hypothesise(track, detections, timestamp, **kwargs)

Hypothesise track and detection association

Parameters

• track (Track) – Track which hypotheses will be generated for.

• detections – 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)

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: Union[stonesoup.hypothesiser.base.Hypothesiser, stonesoup.gater.base.Gater]

Hypothesiser or Gater that is being wrapped.

class stonesoup.initiator.Initiator

Initiator base class

Creates zero or more tracks based on provided detections.

abstract initiate(detections, **kwargs)

Generate tracks from detections.

Parameters

detections (set of Detection) – Detections used to generate set of tracks

Returns

Tracks generated from detections

Return type

set of Track

class stonesoup.mixturereducer.MixtureReducer

Mixture Reducer base class

class stonesoup.predictor.Predictor(transition_model, control_model=None)

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: stonesoup.models.transition.base.TransitionModel

transition model

control_model: stonesoup.models.control.base.ControlModel

control model

abstract predict(prior, timestamp=None, **kwargs)

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

Resampler base class

class stonesoup.smoother.Smoother(transition_model=None)

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: stonesoup.models.transition.base.TransitionModel

Transition Model.

class stonesoup.updater.Updater(measurement_model)

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: stonesoup.models.measurement.base.MeasurementModel

measurement model

abstract predict_measurement(state_prediction, measurement_model=None, **kwargs)

Get measurement prediction from state prediction

Parameters

• state_prediction (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

Returns

The predicted measurement

Return type

MeasurementPrediction

abstract update(hypothesis, **kwargs)

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(ndim_state, mapping)

Control Model base class

Parameters

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between control and state dims

ndim_state: int

Number of state dimensions

mapping: Sequence[int]

Mapping between control and state dims

abstract property ndim_ctrl

Number of control input dimensions

abstract function(state, noise=False)

Model function

abstract property ndim

Number of dimensions of model

abstract pdf(state1, state2)

Model pdf/likelihood evaluator method

abstract rvs(num_samples=1)

Model noise/sample generation method

class stonesoup.models.measurement.MeasurementModel(ndim_state, mapping)

Measurement Model base class

Parameters

• ndim_state (int) – Number of state dimensions

• mapping (Sequence[int]) – Mapping between measurement and state dims

ndim_state: int

Number of state dimensions

mapping: Sequence[int]

Mapping between measurement and state dims

property ndim

Number of dimensions of model

abstract property ndim_meas

Number of measurement dimensions

abstract function(state, noise=False)

Model function

abstract pdf(state1, state2)

Model pdf/likelihood evaluator method

abstract rvs(num_samples=1)

Model noise/sample generation method

class stonesoup.models.transition.TransitionModel

Transition Model base class

property ndim

Number of dimensions of model

abstract property ndim_state

Number of state dimensions

abstract function(state, noise=False)

Model function

abstract pdf(state1, state2)

Model pdf/likelihood evaluator method

abstract rvs(num_samples=1)

Model noise/sample generation method