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 generateDetection
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 stepset 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
: stonesoup.reader.base.Reader Source of detections

class
stonesoup.metricgenerator.
MetricGenerator
[source] Metric Generator base class
Generates
Metric
objects used to asses the performance of a tracker using data held in aMetricManager
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

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

abstract
tracks_gen
()[source] Returns a generator of tracks for each time step.
 Yields
datetime.datetime
– Datetime of current time stepset of
Track
– Tracks existing in the time step

abstract
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 stepset of
Detection
– Detections generate in the time step

abstract

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 stepset of
GroundTruthPath
– Ground truth paths existing in the time step

abstract

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 stepset of
SensorData
– Sensor data generated in the time step

abstract
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
: stonesoup.metricgenerator.base.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
: stonesoup.tracker.base.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 stepset of
Detection
– Detections generate in the time step

abstract

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 stepset of
GroundTruthPath
– Ground truth paths existing in the time step

abstract

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 stepset of
SensorData
– Sensor data generated in the time step

abstract

class
stonesoup.platform.
Platform
(states: Sequence[State], position_mapping: Sequence[int], rotation_offsets: MutableSequence[StateVector] = None, mounting_offsets: MutableSequence[StateVector] = None, sensors: MutableSequence[BaseSensor] = None, velocity_mapping: Sequence[int] = 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).
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
andMovingPlatform
 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 positiononly 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’sposition_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’sposition_mapping
sensors (
MutableSequence[ForwardRef('BaseSensor')]
, optional) – A list of N mounted sensors. Defaults to an empty listvelocity_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 positiononly 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 property
is_moving
Return the
True
if the platform is moving,False
otherwise.

abstract
move
(timestamp: datetime.datetime, **kwargs) → None[source] Update the platform position using the
transition_model
. Parameters
timestamp (
datetime.datetime
, optional) – A timestamp signifying when the end of the maneuver (the default isNone
)
Notes
This methods updates the value of
position
.Any provided
kwargs
are forwarded to thetransition_model
.If
transition_model
ortimestamp
isNone
, the method has no effect, but will return successfully.

add_sensor
(sensor: BaseSensor, mounting_offset: Optional[StateVector] = None, rotation_offset: Optional[StateVector] = None) → None[source] Add a sensor to the platform
 Parameters
sensor (
BaseSensor
) – The sensor object to addmounting_offset (
StateVector
, optional) – A StateVector with the mounting offset of the new sensor. If not supplied, defaults to a zero vectorrotation_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[source] Remove a sensor from the platform
 Parameters
sensor (
BaseSensor
) – The sensor object to remove

pop_sensor
(index: int)[source] 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[source] 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[source] 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
[source] 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 theplatform_system
but does allow the Sensor to control (and set) its own position and orientation.
abstract
measure
(ground_truths: Set[GroundTruthState], noise: Union[numpy.ndarray, bool] = True, **kwargs) → Set[stonesoup.types.detection.TrueDetection] Generate a measurement for a given state
 Parameters
ground_truths (Set[
GroundTruthState
]) – A set ofGroundTruthState
noise (
numpy.ndarray
or bool) – An externally generated random process noise sample (the default is True, in which caservs()
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
]

property
orientation
A 3x1 StateVector of angles (rad), specifying the sensor orientation in terms of the counterclockwise rotation around each Cartesian axis in the order \(x,y,z\). The rotation angles are positive if the rotation is in the counterclockwise 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 theplatform_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.

abstract
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 trackdetection pair

hypothesiser
: stonesoup.hypothesiser.base.Hypothesiser Generate a set of hypotheses for each trackdetection pair

abstract
associate
(tracks: Set[Track], detections: Set[Detection], timestamp: datetime.datetime, **kwargs) → Mapping[stonesoup.types.track.Track, stonesoup.types.hypothesis.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.

delete_tracks
(tracks: Set[Track], **kwargs) → Set[stonesoup.types.track.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.

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.datetime, **kwargs) → Sequence[stonesoup.types.hypothesis.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: Union[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
: Union[stonesoup.hypothesiser.base.Hypothesiser, stonesoup.gater.base.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.datetime, **kwargs) → Set[stonesoup.types.track.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

abstract

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 priorState
and aTransitionModel
. In addition, aControlModel
may be used to model an external influence on the state.\[\mathbf{x}_{kk1} = f_k(\mathbf{x}_{k1}, \mathbf{\nu}_k) + b_k(\mathbf{u}_k, \mathbf{\eta}_k)\]where \(\mathbf{x}_{k1}\) is the prior state, \(f_k(\mathbf{x}_{k1})\) 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 modelcontrol_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)[source] The prediction function itself
 Parameters
prior (
State
) – The prior statetimestamp (
datetime.datetime
, optional) – Time at which the prediction is made (used by the transition model)
 Returns
State prediction
 Return type

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 forwardbackward 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) Thesmooth()
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: 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
: stonesoup.models.measurement.base.MeasurementModel measurement model

abstract
predict_measurement
(state_prediction, measurement_model=None, **kwargs)[source] Get measurement prediction from state prediction
 Parameters
state_prediction (
StatePrediction
) – The state predictionmeasurement_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

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

class
stonesoup.models.control.
ControlModel
(ndim_state: int, mapping: Sequence[int])[source] Control Model base class
 Parameters
ndim_state (
int
) – Number of state dimensionsmapping (
Sequence[int]
) – Mapping between control and state dims

ndim_state
: int Number of state dimensions

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

property
ndim
Number of dimensions of model

abstract property
ndim_ctrl
Number of control input dimensions

abstract
function
(state: State, noise: Union[bool, numpy.ndarray] = False, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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 ofrvs()
is used)
 Returns
The StateVector(s) with the model function evaluated.
 Return type
StateVector
orStateVectors

abstract
pdf
(state1: State, state2: State, **kwargs) → Union[stonesoup.types.numeric.Probability, numpy.ndarray] Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
. Parameters
 Returns
The likelihood of
state1
, givenstate2
 Return type
Probability
orndarray
ofProbability

abstract
rvs
(num_samples: int = 1, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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
2D 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 dimensionsmapping (
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: State, noise: Union[bool, numpy.ndarray] = False, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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 ofrvs()
is used)
 Returns
The StateVector(s) with the model function evaluated.
 Return type
StateVector
orStateVectors

abstract
pdf
(state1: State, state2: State, **kwargs) → Union[stonesoup.types.numeric.Probability, numpy.ndarray] Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
. Parameters
 Returns
The likelihood of
state1
, givenstate2
 Return type
Probability
orndarray
ofProbability

abstract
rvs
(num_samples: int = 1, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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
2D array of shape (
ndim
,num_samples
)

class
stonesoup.models.transition.
TransitionModel
[source] Transition Model base class

property
ndim
Number of dimensions of model

abstract property
ndim_state
Number of state dimensions

abstract
function
(state: State, noise: Union[bool, numpy.ndarray] = False, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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 ofrvs()
is used)
 Returns
The StateVector(s) with the model function evaluated.
 Return type
StateVector
orStateVectors

abstract
pdf
(state1: State, state2: State, **kwargs) → Union[stonesoup.types.numeric.Probability, numpy.ndarray] Model pdf/likelihood evaluation function
Evaluates the pdf/likelihood of
state1
, given the statestate2
which is passed tofunction()
. Parameters
 Returns
The likelihood of
state1
, givenstate2
 Return type
Probability
orndarray
ofProbability

abstract
rvs
(num_samples: int = 1, **kwargs) → Union[stonesoup.types.array.StateVector, stonesoup.types.array.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
2D array of shape (
ndim
,num_samples
)

property