Data Types¶
Base Types¶

class
stonesoup.types.base.
Type
[source]¶ Bases:
stonesoup.base.Base
Base type
Array Types¶

class
stonesoup.types.array.
Matrix
(*args, **kwargs)[source]¶ Bases:
numpy.ndarray
Matrix wrapper for
numpy.ndarray
This class returns a view to a
numpy.ndarray
It’s called same as tonumpy.asarray()
.

class
stonesoup.types.array.
StateVector
(*args, **kwargs)[source]¶ Bases:
stonesoup.types.array.Matrix
State vector wrapper for
numpy.ndarray
This class returns a view to a
numpy.ndarray
, but ensures that its initialised as an \(N \times 1\) vector. It’s called same asnumpy.asarray()
. The StateVector will attempt to convert the data given to a \(N \times 1\) vector if it can easily be done. E.g.,StateVector([1., 2., 3.])
,StateVector ([[1., 2., 3.,]])
, andStateVector([[1.], [2.], [3.]])
will all return the same 3x1 StateVector.It also overrides the behaviour of indexing such that my_state_vector[1] returns the second element (as int, float etc), rather than a StateVector of size (1, 1) as would be the case without this override. Behaviour of indexing with lists, slices or other indexing is unaffected (as you would expect those to return StateVectors). This override avoids the need for client to specifically index with zero as the second element (my_state_vector[1, 0]) to get a native numeric type. Iterating through the StateVector returns a sequence of numbers, rather than a sequence of 1x1 StateVectors. This makes the class behave as would be expected and avoids ‘gotchas’.
Note that code using the pattern my_state_vector[1, 0] will continue to work.
When slicing would result in return of a invalid shape for a StateVector (i.e. not (n, 1)) then a
Matrix
view will be returned.Note
It is not recommended to use a StateVector for indexing another vector. Doing so will lead to unexpected effects. Use a
tuple
,list
ornp.ndarray
for this.
flatten
(order='C')[source]¶ Return a copy of the array collapsed into one dimension.
 Parameters
order ({'C', 'F', 'A', 'K'}, optional) – ‘C’ means to flatten in rowmajor (Cstyle) order. ‘F’ means to flatten in columnmajor (Fortran style) order. ‘A’ means to flatten in columnmajor order if a is Fortran contiguous in memory, rowmajor order otherwise. ‘K’ means to flatten a in the order the elements occur in memory. The default is ‘C’.
 Returns
y – A copy of the input array, flattened to one dimension.
 Return type
ndarray
See also
ravel
Return a flattened array.
flat
A 1D flat iterator over the array.
Examples
>>> a = np.array([[1,2], [3,4]]) >>> a.flatten() array([1, 2, 3, 4]) >>> a.flatten('F') array([1, 3, 2, 4])

ravel
([order])[source]¶ Return a flattened array.
Refer to numpy.ravel for full documentation.
See also
numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


class
stonesoup.types.array.
StateVectors
(states, *args, **kwargs)[source]¶ Bases:
stonesoup.types.array.Matrix
Wrapper for
numpy.ndarray for multiple State Vectors
This class returns a view to a
numpy.ndarray
that is in shape (num_dimensions, num_components), customising some numpy functions to ensure custom types are handled correctly. This can be initialised by a sequence type (list, tuple; not array) that containsStateVector
, otherwise it’s called same asnumpy.asarray()
.

class
stonesoup.types.array.
CovarianceMatrix
(*args, **kwargs)[source]¶ Bases:
stonesoup.types.array.Matrix
Covariance matrix wrapper for
numpy.ndarray
.This class returns a view to a
numpy.ndarray
, but ensures that its initialised at a NxN matrix. It’s called similar tonumpy.asarray()
.
Angle Types¶

class
stonesoup.types.angle.
Angle
(value)[source]¶ Bases:
numbers.Real
Angle class.
Angle handles modulo arithmetic for adding and subtracting angles

class
stonesoup.types.angle.
Bearing
(value)[source]¶ Bases:
stonesoup.types.angle.Angle
Bearing angle class.
Bearing handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Bearing. Multiplication or division produces a float object rather than Bearing.

class
stonesoup.types.angle.
Elevation
(value)[source]¶ Bases:
stonesoup.types.angle.Angle
Elevation angle class.
Elevation handles modulo arithmetic for adding and subtracting elevation angles. The return type for addition and subtraction is Elevation. Multiplication or division produces a float object rather than Elevation.

class
stonesoup.types.angle.
Longitude
(value)[source]¶ Bases:
stonesoup.types.angle.Bearing
Longitude angle class.
Longitude handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Longitude. Multiplication or division produces a float object rather than Longitude.

class
stonesoup.types.angle.
Latitude
(value)[source]¶ Bases:
stonesoup.types.angle.Elevation
Latitude angle class.
Latitude handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Latitude. Multiplication or division produces a float object rather than Latitude.
Association Types¶

class
stonesoup.types.association.
Association
(objects)[source]¶ Bases:
stonesoup.types.base.Type
Association type
An association between objects
 Parameters
objects (
Set
) – Set of objects being associated

objects
: Set¶ Set of objects being associated

class
stonesoup.types.association.
AssociationPair
(objects)[source]¶ Bases:
stonesoup.types.association.Association
AssociationPair type
An
Association
representing the association of two objects Parameters
objects (
Set
) – Set of objects being associated

class
stonesoup.types.association.
SingleTimeAssociation
(objects, timestamp=None)[source]¶ Bases:
stonesoup.types.association.Association
SingleTimeAssociation type
An
Association
representing the linking of objects at a single time Parameters
objects (
Set
) – Set of objects being associatedtimestamp (
datetime.datetime
, optional) – Timestamp of the association. Default is None.

timestamp
: datetime.datetime¶ Timestamp of the association. Default is None.

class
stonesoup.types.association.
TimeRangeAssociation
(objects, time_range=None)[source]¶ Bases:
stonesoup.types.association.Association
TimeRangeAssociation type
An
AssociationPair
representing the linking of objects over a range of times Parameters
objects (
Set
) – Set of objects being associatedtime_range (
TimeRange
, optional) – Range of times that association exists over. Default is None

time_range
: stonesoup.types.time.TimeRange¶ Range of times that association exists over. Default is None

class
stonesoup.types.association.
AssociationSet
(associations=None)[source]¶ Bases:
stonesoup.types.base.Type
AssociationSet type
A set of
Association
type objects representing multiple independent associations. Contains functions for indexing into the associations Parameters
associations (
Set[Association]
, optional) – Set of independent associations

associations
: Set[stonesoup.types.association.Association]¶ Set of independent associations

associations_at_timestamp
(timestamp)[source]¶ Return the associations that exist at a given timestamp
Method will return a set of all the
Association
type objects which occur at the specified time stamp. Parameters
timestamp (datetime.datetime) – Timestamp at which associations should be identified
 Returns
Associations which occur at specified timestamp
 Return type
set of
Association

associations_including_objects
(objects)[source]¶ Return associations that include all the given objects
Method will return the set of all the
Association
type objects which contain an association with the provided object Parameters
objects (set of objects) – Set of objects to look for in associations
 Returns
A set of objects which have been associated
 Return type
set of
Association
Detection Types¶

class
stonesoup.types.detection.
Detection
(state_vector, timestamp=None, measurement_model=None, metadata=None)[source]¶ Bases:
stonesoup.types.state.State
Detection type
 Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.measurement_model (
MeasurementModel
, optional) – The measurement model used to generate the detection (the default isNone
)metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

measurement_model
: stonesoup.models.measurement.base.MeasurementModel¶ The measurement model used to generate the detection (the default is
None
)

metadata
: MutableMapping¶ Dictionary of metadata items for Detections.

class
stonesoup.types.detection.
GaussianDetection
(state_vector, covar, timestamp=None, measurement_model=None, metadata=None)[source]¶ Bases:
stonesoup.types.detection.Detection
,stonesoup.types.state.GaussianState
GaussianDetection type
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.measurement_model (
MeasurementModel
, optional) – The measurement model used to generate the detection (the default isNone
)metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

class
stonesoup.types.detection.
Clutter
(state_vector, timestamp=None, measurement_model=None, metadata=None)[source]¶ Bases:
stonesoup.types.detection.Detection
Clutter type for detections classed as clutter
This is same as
Detection
, but can be used to identify clutter for metrics and analysis purposes. Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.measurement_model (
MeasurementModel
, optional) – The measurement model used to generate the detection (the default isNone
)metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

class
stonesoup.types.detection.
TrueDetection
(state_vector, groundtruth_path, timestamp=None, measurement_model=None, metadata=None)[source]¶ Bases:
stonesoup.types.detection.Detection
TrueDetection type for detections that come from ground truth
This is same as
Detection
, but can be used to identify true detections for metrics and analysis purposes. Parameters
state_vector (
StateVector
) – State vector.groundtruth_path (
GroundTruthPath
) – Ground truth path that this detection came fromtimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.measurement_model (
MeasurementModel
, optional) – The measurement model used to generate the detection (the default isNone
)metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

groundtruth_path
: stonesoup.types.groundtruth.GroundTruthPath¶ Ground truth path that this detection came from

class
stonesoup.types.detection.
MissedDetection
(state_vector=None, timestamp=None, measurement_model=None, metadata=None)[source]¶ Bases:
stonesoup.types.detection.Detection
Detection type for a missed detection
This is same as
Detection
, but it is used in MultipleHypothesis to indicate the null hypothesis (no detections are associated with the specified track). Parameters
state_vector (
StateVector
, optional) – State vector. Default None.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.measurement_model (
MeasurementModel
, optional) – The measurement model used to generate the detection (the default isNone
)metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

state_vector
: stonesoup.types.array.StateVector¶ State vector. Default None.
Ground Truth Types¶

class
stonesoup.types.groundtruth.
GroundTruthState
(state_vector, timestamp=None, metadata=None)[source]¶ Bases:
stonesoup.types.state.State
Ground Truth State type
 Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.metadata (
MutableMapping
, optional) – Dictionary of metadata items for Detections.

metadata
: MutableMapping¶ Dictionary of metadata items for Detections.

class
stonesoup.types.groundtruth.
GroundTruthPath
(states=None, id=None)[source]¶ Bases:
stonesoup.types.state.StateMutableSequence
Ground Truth Path type
A
StateMutableSequence
representing a track. Parameters
states (
MutableSequence[GroundTruthState]
, optional) – List of groundtruth states to initialise path with. Default None which initialises with an empty list.id (
str
, optional) – The unique path ID. Default None where random UUID is generated.

states
: MutableSequence[stonesoup.types.groundtruth.GroundTruthState]¶ List of groundtruth states to initialise path with. Default None which initialises with an empty list.
Hypothesis Types¶

class
stonesoup.types.hypothesis.
Hypothesis
[source]¶ Bases:
stonesoup.types.base.Type
Hypothesis base type
A Hypothesis has subtypes:
‘SingleHypothesis’, which consists of a prediction for a single Track and a single Measurement that might be associated with it
‘MultipleHypothesis’, which consists of a prediction for a single Track and multiple Measurements of which one might be associated with it

class
stonesoup.types.hypothesis.
SingleHypothesis
(prediction, measurement, measurement_prediction=None)[source]¶ Bases:
stonesoup.types.hypothesis.Hypothesis
A hypothesis based on a single measurement.
 Parameters
prediction (
Prediction
) – Predicted track statemeasurement (
Detection
) – Detection used for hypothesis and updatingmeasurement_prediction (
MeasurementPrediction
, optional) – Optional track prediction in measurement space

prediction
: stonesoup.types.prediction.Prediction¶ Predicted track state

measurement
: stonesoup.types.detection.Detection¶ Detection used for hypothesis and updating

measurement_prediction
: stonesoup.types.prediction.MeasurementPrediction¶ Optional track prediction in measurement space

class
stonesoup.types.hypothesis.
SingleDistanceHypothesis
(prediction, measurement, distance, measurement_prediction=None)[source]¶ Bases:
stonesoup.types.hypothesis.SingleHypothesis
Distance scored hypothesis subclass.
Notes
As smaller distance is ‘better’, comparison logic is reversed i.e. smaller distance is a greater likelihood.
 Parameters
prediction (
Prediction
) – Predicted track statemeasurement (
Detection
) – Detection used for hypothesis and updatingdistance (
float
) – Distance between detection and predictionmeasurement_prediction (
MeasurementPrediction
, optional) – Optional track prediction in measurement space

class
stonesoup.types.hypothesis.
SingleProbabilityHypothesis
(prediction, measurement, probability, measurement_prediction=None)[source]¶ Bases:
stonesoup.types.hypothesis.SingleHypothesis
Single Measurement Probability scored hypothesis subclass.
 Parameters
prediction (
Prediction
) – Predicted track statemeasurement (
Detection
) – Detection used for hypothesis and updatingprobability (
Probability
) – Probability that detection is true location of predictionmeasurement_prediction (
MeasurementPrediction
, optional) – Optional track prediction in measurement space

probability
: stonesoup.types.numeric.Probability¶ Probability that detection is true location of prediction

class
stonesoup.types.hypothesis.
JointHypothesis
(hypotheses)[source]¶ Bases:
stonesoup.types.base.Type
,collections.UserDict
Joint Hypothesis base type
A Joint Hypothesis consists of multiple Hypothesese, each with a single Track and a single Prediction. A Joint Hypothesis can be a ‘ProbabilityJointHypothesis’ or a ‘DistanceJointHypothesis’, with a probability or distance that is a function of the Hypothesis probabilities. Multiple Joint Hypotheses can be compared to see which is most likely to be the “correct” hypothesis.
Note: In reality, the property ‘hypotheses’ is a dictionary where the entries have the form ‘Track: Hypothesis’. However, we cannot define it this way because then Hypothesis imports Track, and Track imports Update, and Update imports Hypothesis, which is a circular import.
 Parameters
hypotheses (
Hypothesis
) – Association hypotheses

hypotheses
: stonesoup.types.hypothesis.Hypothesis¶ Association hypotheses

class
stonesoup.types.hypothesis.
ProbabilityJointHypothesis
(hypotheses)[source]¶ Bases:
stonesoup.types.hypothesis.JointHypothesis
Probabilityscored Joint Hypothesis subclass.
 Parameters
hypotheses (
Hypothesis
) – Association hypothesesprobability (
Probability
, optional) – Probability of the Joint Hypothesis

probability
: stonesoup.types.numeric.Probability¶ Probability of the Joint Hypothesis

class
stonesoup.types.hypothesis.
DistanceJointHypothesis
(hypotheses)[source]¶ Bases:
stonesoup.types.hypothesis.JointHypothesis
Distance scored Joint Hypothesis subclass.
Notes
As smaller distance is ‘better’, comparison logic is reversed i.e. smaller distance is a greater likelihood.
 Parameters
hypotheses (
Hypothesis
) – Association hypotheses

class
stonesoup.types.multihypothesis.
MultipleHypothesis
(single_hypotheses=None, normalise=False, total_weight=1)[source]¶ Bases:
stonesoup.types.base.Type
,collections.abc.Sized
,collections.abc.Iterable
,collections.abc.Container
Multiple Hypothesis base type
A Multiple Hypothesis is a container to store a collection of hypotheses.
 Parameters
single_hypotheses (
Sequence[SingleHypothesis]
, optional) – The initial list ofSingleHypothesis
. Default None which initialises with empty list.normalise (
bool
, optional) – Normalise probabilities ofSingleHypothesis
. Default is False.total_weight (
float
, optional) – When normalising, weights will sum to this. Default is 1.

single_hypotheses
: Sequence[stonesoup.types.hypothesis.SingleHypothesis]¶ The initial list of
SingleHypothesis
. Default None which initialises with empty list.

normalise
: bool¶ Normalise probabilities of
SingleHypothesis
. Default is False.
Interval Types¶

class
stonesoup.types.interval.
Interval
(left, right)[source]¶ Bases:
stonesoup.types.base.Type
Closed continuous interval class.
Represents a continuous, closed interval of real numbers. Represented by a lower and upper bound.
 Parameters
left (
Union[int, float]
) – Lower bound of intervalright (
Union[int, float]
) – Upper bound of interval

class
stonesoup.types.interval.
Intervals
(intervals=None)[source]¶ Bases:
stonesoup.types.base.Type
Disjoint closed continuous intervals class.
Represents a set of continuous, closed intervals of real numbers. Represented by a list of
Interval
types. Parameters
intervals (
MutableSequence[Interval]
, optional) – Container ofInterval

intervals
: MutableSequence[stonesoup.types.interval.Interval]¶ Container of
Interval

static
overlap
(intervals)[source]¶ Determine whether a pair of intervals in a list overlap (are not disjoint). Returns a pair of overlapping intervals if there are any, otherwise returns None.
Metric Types¶

class
stonesoup.types.metric.
Metric
(title, value, generator)[source]¶ Bases:
stonesoup.types.base.Type
Metric type
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metric

value
: Any¶ Value of the metric

generator
: Any¶ Generator used to create the metric

class
stonesoup.types.metric.
PlottingMetric
(title, value, generator)[source]¶ Bases:
stonesoup.types.metric.Metric
Metric which is to be visualised as plot, value should be a pyplot figure
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metric

class
stonesoup.types.metric.
SingleTimeMetric
(title, value, generator, timestamp=None)[source]¶ Bases:
stonesoup.types.metric.Metric
Metric for a specific timestamp
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metrictimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

class
stonesoup.types.metric.
TimeRangeMetric
(title, value, generator, time_range=None)[source]¶ Bases:
stonesoup.types.metric.Metric
Metric for a range of times (e.g. for example an entire run)
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metrictime_range (
TimeRange
, optional) – Time range over which metric assessment will be conducted over. Default is None

time_range
: stonesoup.types.time.TimeRange¶ Time range over which metric assessment will be conducted over. Default is None

class
stonesoup.types.metric.
TimeRangePlottingMetric
(title, value, generator, time_range=None)[source]¶ Bases:
stonesoup.types.metric.TimeRangeMetric
,stonesoup.types.metric.PlottingMetric
Plotting metric covering a period of time
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metrictime_range (
TimeRange
, optional) – Time range over which metric assessment will be conducted over. Default is None

class
stonesoup.types.metric.
SingleTimePlottingMetric
(title, value, generator, timestamp=None)[source]¶ Bases:
stonesoup.types.metric.SingleTimeMetric
,stonesoup.types.metric.PlottingMetric
Plotting metric covering a specific timestamp
 Parameters
title (
str
) – Name of the metricvalue (
Any
) – Value of the metricgenerator (
Any
) – Generator used to create the metrictimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.
Mixture Types¶

class
stonesoup.types.mixture.
GaussianMixture
(components=None)[source]¶ Bases:
stonesoup.types.base.Type
,collections.abc.Sized
,collections.abc.Iterable
,collections.abc.Container
Gaussian Mixture type
Represents the target space through a Gaussian Mixture. Individual Gaussian components are contained in a
list
ofWeightedGaussianState
. Parameters
components (
MutableSequence[WeightedGaussianState]
, optional) – The initial list of
WeightedGaussianState
components. Default None which initialises with empty list.
 The initial list of

components
: MutableSequence[stonesoup.types.state.WeightedGaussianState]¶ The initial list of
WeightedGaussianState
components. Default None which initialises with empty list.
Numeric Types¶

class
stonesoup.types.numeric.
Probability
(value, *, log_value=False)[source]¶ Bases:
numbers.Real
Probability class.
Similar to a float, but value stored as natural log value internally. All operations are attempted with log values where possible, and failing that a float will be returned instead.
Particle Types¶

class
stonesoup.types.particle.
Particle
(state_vector, weight, parent=None)[source]¶ Bases:
stonesoup.types.base.Type
Particle type
A particle type which contains a state and weight
 Parameters
state_vector (
StateVector
) – State vectorweight (
float
) – Weight of particleparent (
Particle
, optional) – Parent particle

state_vector
: stonesoup.types.array.StateVector¶ State vector

parent
: stonesoup.types.particle.Particle¶ Parent particle
Prediction Types¶

class
stonesoup.types.prediction.
Prediction
[source]¶ Bases:
stonesoup.types.base.Type
Prediction type
This is the base prediction class.

classmethod
from_state
(state: stonesoup.types.state.State, *args: Any, prediction_type: Optional[Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]] = None, **kwargs: Any) → Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]¶ Return new (Measurement)Prediction instance of suitable type using existing properties
 Parameters
state (State) –
State
to use existing properties from, and identify prediction type from*args (Sequence) – Arguments to pass to newly created prediction, replacing those with same name on
state
parameter.prediction_type (
Prediction
orMeasurementPrediction
, optional) – Type to use for prediction, overriding one fromclass_mapping
.**kwargs (Mapping) – New property names and associate value for use in newly created prediction, replacing those on the
state
parameter.

classmethod

class
stonesoup.types.prediction.
MeasurementPrediction
[source]¶ Bases:
stonesoup.types.base.Type
Prediction type
This is the base measurement prediction class.

classmethod
from_state
(state: stonesoup.types.state.State, *args: Any, prediction_type: Optional[Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]] = None, **kwargs: Any) → Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]¶ Return new (Measurement)Prediction instance of suitable type using existing properties
 Parameters
state (State) –
State
to use existing properties from, and identify prediction type from*args (Sequence) – Arguments to pass to newly created prediction, replacing those with same name on
state
parameter.prediction_type (
Prediction
orMeasurementPrediction
, optional) – Type to use for prediction, overriding one fromclass_mapping
.**kwargs (Mapping) – New property names and associate value for use in newly created prediction, replacing those on the
state
parameter.

classmethod

class
stonesoup.types.prediction.
StatePrediction
(state_vector, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.State
StatePrediction type
Most simple state prediction type, which only has time and a state vector.
 Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.prediction.
StateMeasurementPrediction
(state_vector, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.MeasurementPrediction
,stonesoup.types.state.State
MeasurementPrediction type
Most simple measurement prediction type, which only has time and a state vector.
 Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.prediction.
GaussianStatePrediction
(state_vector, covar, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.GaussianState
GaussianStatePrediction type
This is a simple Gaussian state prediction object, which, as the name suggests, is described by a Gaussian distribution.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.prediction.
SqrtGaussianStatePrediction
(state_vector, sqrt_covar, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.SqrtGaussianState
SqrtGaussianStatePrediction type
This is a Gaussian state prediction object, with the covariance held as the square root of the covariance matrix
 Parameters
state_vector (
StateVector
) – State vector.sqrt_covar (
CovarianceMatrix
) – A square root form of the Gaussian covariance matrix.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.prediction.
WeightedGaussianStatePrediction
(state_vector, covar, timestamp=None, weight=0, tag=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.TaggedWeightedGaussianState
WeightedGaussianStatePrediction type
This is a simple Gaussian state prediction object, which, as the name suggests, is described by a Gaussian distribution with an associated weight.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.weight (
Probability
, optional) – Weight of the Gaussian State.tag (
str
, optional) – Unique tag of the Gaussian State.

class
stonesoup.types.prediction.
TaggedWeightedGaussianStatePrediction
(state_vector, covar, timestamp=None, weight=0, tag=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.TaggedWeightedGaussianState
TaggedWeightedGaussianStatePrediction type
This is a simple Gaussian state prediction object, which, as the name suggests, is described by a Gaussian distribution, with an associated weight and unique tag.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.weight (
Probability
, optional) – Weight of the Gaussian State.tag (
str
, optional) – Unique tag of the Gaussian State.

class
stonesoup.types.prediction.
GaussianMeasurementPrediction
(state_vector, covar, timestamp=None, cross_covar=None)[source]¶ Bases:
stonesoup.types.prediction.MeasurementPrediction
,stonesoup.types.state.GaussianState
GaussianMeasurementPrediction type
This is a simple Gaussian measurement prediction object, which, as the name suggests, is described by a Gaussian distribution.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.cross_covar (
CovarianceMatrix
, optional) – The statemeasurement cross covariance matrix

cross_covar
: stonesoup.types.array.CovarianceMatrix¶ The statemeasurement cross covariance matrix

class
stonesoup.types.prediction.
ParticleStatePrediction
(particles, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.Prediction
,stonesoup.types.state.ParticleState
ParticleStatePrediction type
This is a simple Particle state prediction object.
 Parameters
particles (
MutableSequence[Particle]
) – List of particles representing statetimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.prediction.
ParticleMeasurementPrediction
(particles, timestamp=None)[source]¶ Bases:
stonesoup.types.prediction.MeasurementPrediction
,stonesoup.types.state.ParticleState
MeasurementStatePrediction type
This is a simple Particle measurement prediction object.
 Parameters
particles (
MutableSequence[Particle]
) – List of particles representing statetimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.
Sensor Data Types¶

class
stonesoup.types.sensordata.
SensorData
[source]¶ Bases:
stonesoup.types.base.Type
Sensor Data type

class
stonesoup.types.sensordata.
ImageFrame
(pixels, timestamp=None)[source]¶ Bases:
stonesoup.types.sensordata.SensorData
Image Frame type used to represent a simple image/video frame
 Parameters
pixels (
numpy.ndarray
) – An array of shape (w,h,x) containing the individual pixel values, where w:width, h:height and x may vary depending on the color formattimestamp (
datetime.datetime
, optional) – An optional timestamp

pixels
: numpy.ndarray¶ An array of shape (w,h,x) containing the individual pixel values, where w:width, h:height and x may vary depending on the color format

timestamp
: datetime.datetime¶ An optional timestamp
State Types¶

class
stonesoup.types.state.
State
(state_vector, timestamp=None)[source]¶ Bases:
stonesoup.types.base.Type
State type.
Most simple state type, which only has time and a state vector.
 Parameters
state_vector (
StateVector
) – State vector.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

state_vector
: stonesoup.types.array.StateVector¶ State vector.

property
ndim
¶ The number of dimensions represented by the state.

class
stonesoup.types.state.
StateMutableSequence
(states=None)[source]¶ Bases:
stonesoup.types.base.Type
,collections.abc.MutableSequence
A mutable sequence for
State
instancesThis sequence acts like a regular list object for States, as well as proxying state attributes to the last state in the sequence. This sequence can also be indexed/sliced by
datetime.datetime
instances.Example
>>> t0 = datetime.datetime(2018, 1, 1, 14, 00) >>> t1 = t0 + datetime.timedelta(minutes=1) >>> state0 = State([[0]], t0) >>> sequence = StateMutableSequence([state0]) >>> print(sequence.state_vector, sequence.timestamp) [[0]] 20180101 14:00:00 >>> sequence.append(State([[1]], t1)) >>> for state in sequence[t1:]: ... print(state.state_vector, state.timestamp) [[1]] 20180101 14:01:00
 Parameters
states (
MutableSequence[State]
, optional) – The initial list of states. Default None which initialises with empty list.

states
: MutableSequence[stonesoup.types.state.State]¶ The initial list of states. Default None which initialises with empty list.

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.

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.types.state.
GaussianState
(state_vector, covar, timestamp=None)[source]¶ Bases:
stonesoup.types.state.State
Gaussian State type
This is a simple Gaussian state object, which, as the name suggests, is described by a Gaussian state distribution.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

covar
: stonesoup.types.array.CovarianceMatrix¶ Covariance matrix of state.

property
mean
¶ The state mean, equivalent to state vector

property
ndim
¶ The number of dimensions represented by the state.

state_vector
: stonesoup.types.array.StateVector¶ State vector.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

class
stonesoup.types.state.
SqrtGaussianState
(state_vector, sqrt_covar, timestamp=None)[source]¶ Bases:
stonesoup.types.state.State
A Gaussian State type where the covariance matrix is stored in a form \(W\) such that \(P = WW^T\)
For \(P\) in general, \(W\) is not unique and the user may choose the form to their taste. No checks are undertaken to ensure that a sensible square root form has been chosen.
 Parameters
state_vector (
StateVector
) – State vector.sqrt_covar (
CovarianceMatrix
) – A square root form of the Gaussian covariance matrix.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

sqrt_covar
: stonesoup.types.array.CovarianceMatrix¶ A square root form of the Gaussian covariance matrix.

property
mean
¶ The state mean, equivalent to state vector

property
covar
¶ The full covariance matrix.
 Returns
The covariance matrix calculated via \(W W^T\), where \(W\) is a
SqrtCovarianceMatrix
 Return type

property
ndim
¶ The number of dimensions represented by the state.

state_vector
: stonesoup.types.array.StateVector¶ State vector.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

class
stonesoup.types.state.
WeightedGaussianState
(state_vector, covar, timestamp=None, weight=0)[source]¶ Bases:
stonesoup.types.state.GaussianState
Weighted Gaussian State Type
Gaussian State object with an associated weight. Used as components for a GaussianMixtureState.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.weight (
Probability
, optional) – Weight of the Gaussian State.

weight
: stonesoup.types.numeric.Probability¶ Weight of the Gaussian State.

property
gaussian_state
¶ The Gaussian state.

classmethod
from_gaussian_state
(gaussian_state, *args, copy=True, **kwargs)[source]¶ Returns a WeightedGaussianState instance based on the gaussian_state.
 Parameters
gaussian_state (
GaussianState
) – The guassian_state used to create the new WeightedGaussianState.*args (See main
WeightedGaussianState
) – args are passed toWeightedGaussianState
__init__()copy (Boolean, optional) – If True, the WeightedGaussianState is created with copies of the elements of gaussian_state. The default is True.
**kwargs (See main
WeightedGaussianState
) – kwargs are passed toWeightedGaussianState
__init__()
 Returns
Instance of WeightedGaussianState.
 Return type

covar
: stonesoup.types.array.CovarianceMatrix¶ Covariance matrix of state.

property
mean
¶ The state mean, equivalent to state vector

property
ndim
¶ The number of dimensions represented by the state.

state_vector
: stonesoup.types.array.StateVector¶ State vector.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

class
stonesoup.types.state.
TaggedWeightedGaussianState
(state_vector, covar, timestamp=None, weight=0, tag=None)[source]¶ Bases:
stonesoup.types.state.WeightedGaussianState
Tagged Weighted Gaussian State Type
Gaussian State object with an associated weight and tag. Used as components for a GaussianMixtureState.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.timestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.weight (
Probability
, optional) – Weight of the Gaussian State.tag (
str
, optional) – Unique tag of the Gaussian State.

covar
: stonesoup.types.array.CovarianceMatrix¶ Covariance matrix of state.

classmethod
from_gaussian_state
(gaussian_state, *args, copy=True, **kwargs)¶ Returns a WeightedGaussianState instance based on the gaussian_state.
 Parameters
gaussian_state (
GaussianState
) – The guassian_state used to create the new WeightedGaussianState.*args (See main
WeightedGaussianState
) – args are passed toWeightedGaussianState
__init__()copy (Boolean, optional) – If True, the WeightedGaussianState is created with copies of the elements of gaussian_state. The default is True.
**kwargs (See main
WeightedGaussianState
) – kwargs are passed toWeightedGaussianState
__init__()
 Returns
Instance of WeightedGaussianState.
 Return type

property
gaussian_state
¶ The Gaussian state.

property
mean
¶ The state mean, equivalent to state vector

property
ndim
¶ The number of dimensions represented by the state.

state_vector
: stonesoup.types.array.StateVector¶ State vector.

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

weight
: stonesoup.types.numeric.Probability¶ Weight of the Gaussian State.

class
stonesoup.types.state.
ParticleState
(particles, timestamp=None)[source]¶ Bases:
stonesoup.types.base.Type
Particle State type
This is a particle state object which describes the state as a distribution of particles
 Parameters
particles (
MutableSequence[Particle]
) – List of particles representing statetimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

particles
: MutableSequence[stonesoup.types.particle.Particle]¶ List of particles representing state

timestamp
: datetime.datetime¶ Timestamp of the state. Default None.

property
mean
¶ The state mean, equivalent to state vector

property
state_vector
¶ The mean value of the particle states
Time Types¶

class
stonesoup.types.time.
TimeRange
(start_timestamp, end_timestamp)[source]¶ Bases:
stonesoup.types.base.Type
TimeRange type
An object representing a time range between two timestamps.
Can be used to check if timestamp is within via in operator
Example
>>> t0 = datetime.datetime(2018, 1, 1, 14, 00) >>> t1 = datetime.datetime(2018, 1, 1, 15, 00) >>> time_range = TimeRange(t0, t1) >>> test_time = datetime.datetime(2018, 1, 1, 14, 30) >>> print(test_time in time_range) True
 Parameters
start_timestamp (
datetime.datetime
) – Start of the time rangeend_timestamp (
datetime.datetime
) – End of the time range

start_timestamp
: datetime.datetime¶ Start of the time range

end_timestamp
: datetime.datetime¶ End of the time range

property
duration
¶ Duration of the time range
Track Types¶

class
stonesoup.types.track.
Track
(states=None, id=None, init_metadata={})[source]¶ Bases:
stonesoup.types.state.StateMutableSequence
Track type
A
StateMutableSequence
representing a track. Notes:
Any manual modifications to
metadata
ormetadatas
will be overwritten if a state is inserted at a point prior to where the modifications are made. For example, inserting a state at the start ofstates
will result in ametadatas
update that will update all subsequent metadata values, resulting in manual metadata modifications being lost.
 Parameters
states (
MutableSequence[State]
, optional) – The initial states of the track. Default None which initialises with empty list.id (
str
, optional) – The unique track IDinit_metadata (
MutableMapping
, optional) – Initial dictionary of metadata items for track. Default None which initialises track metadata as an empty dictionary.

states
: MutableSequence[stonesoup.types.state.State]¶ The initial states of the track. Default None which initialises with empty list.

init_metadata
: MutableMapping¶ Initial dictionary of metadata items for track. Default None which initialises track metadata as an empty dictionary.

property
metadata
¶ Current metadata dictionary of track. If track contains no states, this is the initial metadata dictionary
init_metadata
.
Update Types¶

class
stonesoup.types.update.
Update
(hypothesis)[source]¶ Bases:
stonesoup.types.base.Type
Update type
The base update class. Updates are returned by :class:’~.Updater’ objects and contain the information that was used to perform the updating
 Parameters
hypothesis (
Hypothesis
) – Hypothesis used for updating

hypothesis
: stonesoup.types.hypothesis.Hypothesis¶ Hypothesis used for updating

classmethod
from_state
(state: stonesoup.types.state.State, *args: Any, update_type: Optional[stonesoup.types.update.Update] = None, **kwargs: Any) → stonesoup.types.update.Update¶ Return new Update instance of suitable type using existing properties
 Parameters
state (State) –
State
to use existing properties from, and identify update type from*args (Sequence) – Arguments to pass to newly created update, replacing those with same name on
state
parameter.update_type (
Update
, optional) – Type to use for update, overriding one fromclass_mapping
.**kwargs (Mapping) – New property names and associate value for use in newly created update, replacing those on the
state
parameter.

class
stonesoup.types.update.
StateUpdate
(state_vector, hypothesis, timestamp=None)[source]¶ Bases:
stonesoup.types.update.Update
,stonesoup.types.state.State
StateUpdate type
Most simple state update type, where everything only has time and a state vector. Requires a prior state that was updated, and the hypothesis used to update the prior.
 Parameters
state_vector (
StateVector
) – State vector.hypothesis (
Hypothesis
) – Hypothesis used for updatingtimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.update.
GaussianStateUpdate
(state_vector, covar, hypothesis, timestamp=None)[source]¶ Bases:
stonesoup.types.update.Update
,stonesoup.types.state.GaussianState
GaussianStateUpdate type
This is a simple Gaussian state update object, which, as the name suggests, is described by a Gaussian distribution.
 Parameters
state_vector (
StateVector
) – State vector.covar (
CovarianceMatrix
) – Covariance matrix of state.hypothesis (
Hypothesis
) – Hypothesis used for updatingtimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.update.
SqrtGaussianStateUpdate
(state_vector, sqrt_covar, hypothesis, timestamp=None)[source]¶ Bases:
stonesoup.types.update.Update
,stonesoup.types.state.SqrtGaussianState
SqrtGaussianStateUpdate type
This is equivalent to a Gaussian state update object, but with the covariance of the Gaussian distribution stored in matrix square root form.
 Parameters
state_vector (
StateVector
) – State vector.sqrt_covar (
CovarianceMatrix
) – A square root form of the Gaussian covariance matrix.hypothesis (
Hypothesis
) – Hypothesis used for updatingtimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.

class
stonesoup.types.update.
GaussianMixtureUpdate
(hypothesis, components=None)[source]¶ Bases:
stonesoup.types.update.Update
,stonesoup.types.mixture.GaussianMixture
GaussianMixtureUpdate type
This is a Gaussian mixture update object, which, as the name suggests, is described by a Gaussian mixture.
 Parameters
hypothesis (
Hypothesis
) – Hypothesis used for updatingcomponents (
MutableSequence[WeightedGaussianState]
, optional) – The initial list of
WeightedGaussianState
components. Default None which initialises with empty list.
 The initial list of

class
stonesoup.types.update.
ParticleStateUpdate
(particles, hypothesis, timestamp=None)[source]¶ Bases:
stonesoup.types.update.Update
,stonesoup.types.state.ParticleState
ParticleStateUpdate type
This is a simple Particle state update object.
 Parameters
particles (
MutableSequence[Particle]
) – List of particles representing statehypothesis (
Hypothesis
) – Hypothesis used for updatingtimestamp (
datetime.datetime
, optional) – Timestamp of the state. Default None.