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: 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: 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 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
- 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 stepset 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 stepset 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 stepset 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
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
- 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
- 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
- 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
andMovingPlatform
- 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 (
MutableSequence[Sensor]
, 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 updatedself.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’svelocity_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 3movement_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:
- 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 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
]
- 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:
- 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.
- 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 trackstimestamp (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 priorState
and aTransitionModel
. In addition, aControlModel
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 modelcontrol_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 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 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) Thesmooth()
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 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 initialisationmeasurement_noise (bool) – Whether to include measurement noise predicted measurement. Default True
- 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[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 ofrvs()
is used)
- Returns:
The StateVector(s) with the model function evaluated.
- Return type:
StateVector
orStateVectors
- 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 statestate2
which is passed tofunction()
.
- abstract pdf(state1: State, state2: State, **kwargs) Probability | 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) 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 dimensionsmapping (
Sequence[int]
) – Mapping between measurement and state dims
- ndim_state: int
Number of state dimensions
- 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 ofrvs()
is used)
- Returns:
The StateVector(s) with the model function evaluated.
- Return type:
StateVector
orStateVectors
- 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 statestate2
which is passed tofunction()
.
- abstract pdf(state1: State, state2: State, **kwargs) Probability | 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) 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 ofrvs()
is used)
- Returns:
The StateVector(s) with the model function evaluated.
- Return type:
StateVector
orStateVectors
- 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 statestate2
which is passed tofunction()
.
- abstract pdf(state1: State, state2: State, **kwargs) Probability | 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) 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
)