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 to numpy.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 as numpy.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.,]]), and StateVector([[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 or np.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 row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-major order if a is Fortran contiguous in memory, row-major 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 1-D 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 contains StateVector, otherwise it’s called same as numpy.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 to numpy.asarray().

Angle Types

class stonesoup.types.angle.Angle(value)[source]

Bases: numbers.Real

Angle class.

Angle handles modulo arithmetic for adding and subtracting angles

classmethod average(angles, weights=None)[source]

Calculated the circular mean for sequence of angles

Parameters

  • angles (sequence of Angle) – Angles which to calculate the mean of.

  • weights (sequence of float, optional) – Weights to calculate weighted mean. Default None, where no weights applied.

Returns

Circular mean of angles

Return type

Angle

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 associated

  • timestamp (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 associated

  • time_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 is None)

  • 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 is None)

  • 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 is None)

  • 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 from

  • timestamp (datetime.datetime, optional) – Timestamp of the state. Default None.

  • measurement_model (MeasurementModel, optional) – The measurement model used to generate the detection (the default is None)

  • 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 is None)

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

id: str

The unique path ID. Default None where random UUID is generated.

Hypothesis Types

class stonesoup.types.hypothesis.Hypothesis[source]

Bases: stonesoup.types.base.Type

Hypothesis base type

A Hypothesis has sub-types:

‘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 state

  • measurement (Detection) – Detection used for hypothesis and updating

  • measurement_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 state

  • measurement (Detection) – Detection used for hypothesis and updating

  • distance (float) – Distance between detection and prediction

  • measurement_prediction (MeasurementPrediction, optional) – Optional track prediction in measurement space

distance: float

Distance between detection and prediction

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 state

  • measurement (Detection) – Detection used for hypothesis and updating

  • probability (Probability) – Probability that detection is true location of prediction

  • measurement_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

Probability-scored Joint Hypothesis subclass.

Parameters

  • hypotheses (Hypothesis) – Association hypotheses

  • probability (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 of SingleHypothesis. Default None which initialises with empty list.

  • normalise (bool, optional) – Normalise probabilities of SingleHypothesis. 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.

total_weight: float

When normalising, weights will sum to this. Default is 1.

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 interval

  • right (Union[int, float]) – Upper bound of interval

left: Union[int, float]

Lower bound of interval

right: Union[int, float]

Upper bound of interval

isdisjoint(other)[source]

Check whether two intervals are disjoint (do not overlap). Returns True if they are disjoint. Note: returns False if intervals endpoints ‘meet’. For example [0, 1] meets [1, 2].

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 of Interval

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.

isdisjoint(other)[source]

Determine whether all intervals in an Intervals type are disjoint from all those in another.

static get_merged_intervals(intervals)[source]

Merge all intervals. Ie. combine any intervals that overlap, returning a new list of disjoint intervals.

Metric Types

class stonesoup.types.metric.Metric(title, value, generator)[source]

Bases: stonesoup.types.base.Type

Metric type

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

  • generator (Any) – Generator used to create the metric

title: str

Name of 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 metric

  • value (Any) – Value of the metric

  • generator (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 metric

  • value (Any) – Value of the metric

  • generator (Any) – Generator used to create the metric

  • timestamp (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 metric

  • value (Any) – Value of the metric

  • generator (Any) – Generator used to create the metric

  • time_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 metric

  • value (Any) – Value of the metric

  • generator (Any) – Generator used to create the metric

  • time_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 metric

  • value (Any) – Value of the metric

  • generator (Any) – Generator used to create the metric

  • timestamp (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 of WeightedGaussianState.

Parameters

components (MutableSequence[WeightedGaussianState], optional) –

The initial list of WeightedGaussianState components.

Default None which initialises with empty list.

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.

sqrt()[source]

Square root which can be called by NumPy

log()[source]

Log which can be called by NumPy

classmethod sum(values)[source]

Carry out LogSumExp

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 vector

  • weight (float) – Weight of particle

  • parent (Particle, optional) – Parent particle

state_vector: stonesoup.types.array.StateVector

State vector

weight: float

Weight of particle

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 or MeasurementPrediction, optional) – Type to use for prediction, overriding one from class_mapping.

  • **kwargs (Mapping) – New property names and associate value for use in newly created prediction, replacing those on the state parameter.

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 or MeasurementPrediction, optional) – Type to use for prediction, overriding one from class_mapping.

  • **kwargs (Mapping) – New property names and associate value for use in newly created prediction, replacing those on the state parameter.

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
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
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
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
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
cross_covar: stonesoup.types.array.CovarianceMatrix

The state-measurement 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 state

  • timestamp (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 state

  • timestamp (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 format

  • timestamp (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
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 instances

This 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]] 2018-01-01 14:00:00
>>> sequence.append(State([[1]], t1))
>>> for state in sequence[t1:]:
...     print(state.state_vector, state.timestamp)
[[1]] 2018-01-01 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.

insert(index, value)[source]

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

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

CovarianceMatrix

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
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
Returns

Instance of WeightedGaussianState.

Return type

WeightedGaussianState

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.

tag: str

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
Returns

Instance of WeightedGaussianState.

Return type

WeightedGaussianState

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 state

  • timestamp (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 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 or metadatas 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 of states will result in a metadatas 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 ID

  • init_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.

id: str

The unique track ID

insert(index, value)[source]

Insert value at index of states.

Parameters

  • index (int) – Index of states to insert value at.

  • value (State) – A state object to be inserted at the specified index of states.

append(value)[source]

Add value at end of states.

Parameters

value (State) – A state object to be added at the end of states.

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 from class_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
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
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 updating

  • timestamp (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 updating

  • components (MutableSequence[WeightedGaussianState], optional) –

    The initial list of WeightedGaussianState components.

    Default None which initialises with empty list.

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 state

  • hypothesis (Hypothesis) – Hypothesis used for updating

  • timestamp (datetime.datetime, optional) – Timestamp of the state. Default None.