Data Types

Base Types

class stonesoup.types.base.Type[source]

Bases: Base

Base type

Array Types

class stonesoup.types.array.Matrix(*args, **kwargs)[source]

Bases: 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: 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 an 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

>>> import numpy as np
>>> 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: 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: Matrix

Covariance matrix wrapper for numpy.ndarray.

This class returns a view to a numpy.ndarray, but ensures that it is initialised as a NxN matrix. It’s called similar to numpy.asarray().

class stonesoup.types.array.PrecisionMatrix(*args, **kwargs)[source]

Bases: Matrix

Precision matrix. This is the matrix inverse of a covariance matrix.

This class returns a view to a numpy.ndarray, but ensures that its initialised as an NxN matrix. It’s called similar to numpy.asarray().

Angle Types

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

Bases: 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: 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: 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.Azimuth(value)[source]

Bases: Angle

Azimuth angle class.

Azimuth handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Azimuth. Multiplication or division produces a float object rather than Azimuth.

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

Bases: 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: 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.

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

Bases: Angle

(Orbital) Inclination angle class.

Inclination handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Inclination. Multiplication or division produces a float object rather than Inclination.

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

Bases: Angle

(Orbital) Ecliptic Longitude angle class.

Ecliptic Longitude handles modulo arithmetic for adding and subtracting angles. The return type for addition and subtraction is Ecliptic Longitude. Multiplication or division produces a float object rather than Ecliptic Longitude.

Association Types

class stonesoup.types.association.Association(objects: set)[source]

Bases: 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: set)[source]

Bases: 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: set, timestamp: datetime = None)[source]

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

Timestamp of the association. Default is None.

class stonesoup.types.association.TimeRangeAssociation(objects: set, time_range: CompoundTimeRange | TimeRange = None)[source]

Bases: 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 (Union[CompoundTimeRange, TimeRange], optional) – Range of times that association exists over. Default is None.

time_range: CompoundTimeRange | TimeRange

Range of times that association exists over. Default is None.

class stonesoup.types.association.AssociationSet(associations: set[Association] = None)[source]

Bases: Type

AssociationSet type

A set of Association type objects representing multiple independent associations. Contains functions for indexing into the associations.

Parameters:

associations (set, optional) – set of independent associations.

associations: set[Association]

set of independent associations.

property key_times

Returns all timestamps at which a component starts or ends, or where there is a SingleTimeAssociation.

property overall_time_range

Returns a CompoundTimeRange covering all times at which at least one association is active.

Note: SingleTimeAssociation are not counted.

property object_set

Returns a set of all objects contained by this instance.

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:

AssociationSet

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) – A set of objects to look for in associations.

Returns:

A set of associations containing every member of objects.

Return type:

AssociationSet

Detection Types

class stonesoup.types.detection.Detection(state_vector: StateVector, timestamp: datetime = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: State

Detection type

Parameters:
measurement_model: 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: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: Detection, GaussianState

GaussianDetection type

Parameters:
class stonesoup.types.detection.Clutter(state_vector: StateVector, timestamp: datetime = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: 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:
class stonesoup.types.detection.TrueDetection(state_vector: StateVector, groundtruth_path: GroundTruthPath, timestamp: datetime = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: 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:
groundtruth_path: GroundTruthPath

Ground truth path that this detection came from

class stonesoup.types.detection.MissedDetection(state_vector: StateVector = None, timestamp: datetime = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: 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 (collections.abc.MutableMapping, optional) – Dictionary of metadata items for Detections.

state_vector: StateVector

State vector. Default None.

class stonesoup.types.detection.CategoricalDetection(state_vector: StateVector, timestamp: datetime = None, categories: Sequence[float] = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: Detection, CategoricalState

Categorical detection type.

Parameters:
class stonesoup.types.detection.TrueCategoricalDetection(state_vector: StateVector, groundtruth_path: GroundTruthPath, timestamp: datetime = None, categories: Sequence[float] = None, measurement_model: MeasurementModel = None, metadata: MutableMapping = None)[source]

Bases: TrueDetection, CategoricalDetection

TrueCategoricalDetection type for categorical detections that come from ground truth.

Parameters:
class stonesoup.types.detection.CompositeDetection(sub_states: Sequence[Detection], default_timestamp: datetime = None, groundtruth_path: GroundTruthPath = None, mapping: Sequence[int] = None)[source]

Bases: CompositeState

Composite detection type

Composition of Detection.

Parameters:

  • sub_states (collections.abc.Sequence) – Sequence of sub-detections comprising the composite detection. All sub-detections must have matching timestamp. Must not be empty.

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

  • groundtruth_path (GroundTruthPath, optional) – Ground truth path that this detection came from.

  • mapping (collections.abc.Sequence, optional) – Mapping of detections to composite state space. Defaults to None, where sub-detections map to sub-state spaces in order.

sub_states: Sequence[Detection]

Sequence of sub-detections comprising the composite detection. All sub-detections must have matching timestamp. Must not be empty.

groundtruth_path: GroundTruthPath

Ground truth path that this detection came from.

mapping: Sequence[int]

Mapping of detections to composite state space. Defaults to None, where sub-detections map to sub-state spaces in order.

property metadata

Combined metadata of all sub-detections.

Ground Truth Types

class stonesoup.types.groundtruth.GroundTruthState(state_vector: StateVector, timestamp: datetime = None, metadata: MutableMapping = None)[source]

Bases: State

Ground Truth State type

Parameters:
metadata: MutableMapping

Dictionary of metadata items for Detections.

class stonesoup.types.groundtruth.CategoricalGroundTruthState(state_vector: StateVector, timestamp: datetime = None, categories: Sequence[float] = None, metadata: MutableMapping = None)[source]

Bases: GroundTruthState, CategoricalState

Categorical Ground Truth State type

Parameters:
class stonesoup.types.groundtruth.GroundTruthPath(states: MutableSequence[GroundTruthState] = None, id: str = None)[source]

Bases: StateMutableSequence

Ground Truth Path type

A StateMutableSequence representing a track.

Parameters:

  • states (collections.abc.MutableSequence, 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[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.

class stonesoup.types.groundtruth.CompositeGroundTruthState(sub_states: Sequence[GroundTruthState], default_timestamp: datetime = None)[source]

Bases: CompositeState

Composite ground truth state type.

A composition of ordered sub-states (GroundTruthState) existing at the same timestamp, representing a true object with a state for (potentially) multiple, distinct state spaces.

Parameters:

  • sub_states (collections.abc.Sequence) – Sequence of sub-states comprising the composite state. All sub-states must have matching timestamp and metadata attributes. Must not be empty.

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

sub_states: Sequence[GroundTruthState]

Sequence of sub-states comprising the composite state. All sub-states must have matching timestamp and metadata attributes. Must not be empty.

property metadata

Combined metadata of all sub-detections.

Hypothesis Types

class stonesoup.types.hypothesis.Hypothesis[source]

Bases: 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.ProbabilityHypothesis(probability: Probability)[source]

Bases: Hypothesis

Parameters:

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

probability: Probability

Probability that detection is true location of prediction

class stonesoup.types.hypothesis.SingleHypothesis(prediction: Prediction, measurement: Detection, measurement_prediction: MeasurementPrediction = None)[source]

Bases: 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: Prediction

Predicted track state

measurement: Detection

Detection used for hypothesis and updating

measurement_prediction: MeasurementPrediction

Optional track prediction in measurement space

class stonesoup.types.hypothesis.SingleDistanceHypothesis(prediction: Prediction, measurement: Detection, distance: float, measurement_prediction: MeasurementPrediction = None)[source]

Bases: 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: Prediction, measurement: Detection, probability: Probability, measurement_prediction: MeasurementPrediction = None)[source]

Bases: ProbabilityHypothesis, 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

class stonesoup.types.hypothesis.JointHypothesis(hypotheses)[source]

Bases: Type, UserDict

Joint Hypothesis base type

A Joint Hypothesis consists of multiple Hypotheses, 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: Hypothesis

Association hypotheses

class stonesoup.types.hypothesis.ProbabilityJointHypothesis(hypotheses)[source]

Bases: ProbabilityHypothesis, JointHypothesis

Probability-scored Joint Hypothesis subclass.

Parameters:

  • hypotheses (Hypothesis) – Association hypotheses

  • probability (Probability, optional) – Probability that detection is true location of prediction. Defaults to None, whereby the probability is calculated as being the product of the constituent multiple-hypotheses’ probabilities.

probability: Probability

Probability that detection is true location of prediction. Defaults to None, whereby the probability is calculated as being the product of the constituent multiple-hypotheses’ probabilities.

class stonesoup.types.hypothesis.DistanceJointHypothesis(hypotheses)[source]

Bases: 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.hypothesis.CompositeHypothesis(prediction: CompositePrediction, measurement: CompositeDetection, sub_hypotheses: Sequence[SingleHypothesis], measurement_prediction: CompositeMeasurementPrediction = None)[source]

Bases: SingleHypothesis

Composite hypothesis type

A composition of SingleHypothesis.

Parameters:
sub_hypotheses: Sequence[SingleHypothesis]

Sequence of sub-hypotheses comprising the composite hypothesis. Must not be empty.

prediction: CompositePrediction

Predicted track state

measurement: CompositeDetection

Detection used for hypothesis and updating

measurement_prediction: CompositeMeasurementPrediction

Optional track prediction in measurement space

class stonesoup.types.hypothesis.CompositeProbabilityHypothesis(prediction: CompositePrediction, measurement: CompositeDetection, probability: Probability = None, measurement_prediction: CompositeMeasurementPrediction = None, sub_hypotheses: Sequence[SingleProbabilityHypothesis] = None)[source]

Bases: CompositeHypothesis, SingleProbabilityHypothesis

Composite probability hypothesis type

A composition of SingleProbabilityHypothesis.

Calculate hypothesis probability via product of sub-hypotheses’ probabilities. Probability is 1 if there are no sub-hypotheses.

Parameters:

  • prediction (CompositePrediction) – Predicted track state

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

  • probability (Probability, optional) – Probability that detection is true location of prediction. Default is None, whereby probability is calculated as the product of sub-hypotheses’ probabilities

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

  • sub_hypotheses (collections.abc.Sequence, optional) – Sequence of probability-scored sub-hypotheses comprising the composite hypothesis.

sub_hypotheses: Sequence[SingleProbabilityHypothesis]

Sequence of probability-scored sub-hypotheses comprising the composite hypothesis.

probability: Probability

Probability that detection is true location of prediction. Default is None, whereby probability is calculated as the product of sub-hypotheses’ probabilities

class stonesoup.types.multihypothesis.MultipleHypothesis(single_hypotheses: Sequence[SingleHypothesis] = None, normalise: bool = False, total_weight: float = 1)[source]

Bases: Type, Sequence

Multiple Hypothesis base type

A Multiple Hypothesis is a container to store a collection of hypotheses.

Parameters:

  • single_hypotheses (collections.abc.Sequence, 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[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.

class stonesoup.types.multihypothesis.MultipleCompositeHypothesis(single_hypotheses: Sequence[CompositeHypothesis] = None, normalise: bool = False, total_weight: float = 1)[source]

Bases: Type, Sequence

Multiple composite hypothesis type

A Multiple Composite Hypothesis is a container to store a collection of composite hypotheses.

Interfaces the same as MultipleHypothesis, but permits different input, hence methods are redefined.

Parameters:

  • single_hypotheses (collections.abc.Sequence, optional) – The initial list of CompositeHypothesis. Default None which initialises with empty list.

  • normalise (bool, optional) – Normalise probabilities of CompositeHypothesis. Default is False.

  • total_weight (float, optional) – When normalising, weights will sum to this. Default is 1.

single_hypotheses: Sequence[CompositeHypothesis]

The initial list of CompositeHypothesis. Default None which initialises with empty list.

normalise: bool

Normalise probabilities of CompositeHypothesis. Default is False.

total_weight: float

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

Interval Types

class stonesoup.types.interval.Interval(start: int | float, end: int | float)[source]

Bases: Type

Closed continuous interval class.

Represents a continuous, closed interval of real numbers. Represented by a lower and upper bound.

Parameters:

  • start (Union[int, float]) – Lower bound of interval

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

start: int | float

Lower bound of interval

end: 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: MutableSequence[Interval] = None)[source]

Bases: 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 (collections.abc.MutableSequence, optional) – Container of Interval

intervals: MutableSequence[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. I.e., combine any intervals that overlap, returning a new list of disjoint intervals.

Metric Types

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

Bases: 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: str, value: Any, generator: Any)[source]

Bases: 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: str, value: Any, generator: Any, timestamp: datetime = None)[source]

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

Timestamp of the state. Default None.

class stonesoup.types.metric.TimeRangeMetric(title: str, value: Any, generator: Any, time_range: TimeRange = None)[source]

Bases: 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: TimeRange

Time range over which metric assessment will be conducted over. Default is None

class stonesoup.types.metric.TimeRangePlottingMetric(title: str, value: Any, generator: Any, time_range: TimeRange = None)[source]

Bases: TimeRangeMetric, 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: str, value: Any, generator: Any, timestamp: datetime = None)[source]

Bases: SingleTimeMetric, 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: MutableSequence[WeightedGaussianState] = None)[source]

Bases: Type, MutableSequence

Gaussian Mixture type

Represents the target space through a Gaussian Mixture. Individual Gaussian components are contained in a list of WeightedGaussianState.

Parameters:

components (collections.abc.MutableSequence, optional) –

The initial list of WeightedGaussianState components.

Default None which initialises with empty list.

components: MutableSequence[WeightedGaussianState]

The initial list of WeightedGaussianState components. Default None which initialises with empty list.

insert(index, value)[source]

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

property timestamp

Timestamp

Numeric Types

class stonesoup.types.numeric.Probability(value, *, log_value=False)[source]

Bases: 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.

Parameters:

  • value (float) – Value for probability.

  • log_value (bool) – Set to True if value already a log value. Default False.

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

classmethod from_log(value)[source]

Create Probability type from a log value; same as Probability(value, log_value=True)

Parameters:

value (float) – Value for probability.

Return type:

Probability

from_log_ufunc = <ufunc 'from_log (vectorized)'>

Particle Types

class stonesoup.types.particle.Particle(state_vector: StateVector, weight: float, parent: Particle = None)[source]

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

weight: float

Weight of particle

state_vector: StateVector

State vector

parent: Particle

Parent particle

class stonesoup.types.particle.MultiModelParticle(state_vector: StateVector, weight: float, dynamic_model: int, parent: MultiModelParticle = None)[source]

Bases: Particle

Particle type

A MultiModelParticle type which contains a state, weight and the dynamic_model

Parameters:

  • state_vector (StateVector) – State vector

  • weight (float) – Weight of particle

  • dynamic_model (int) – Assigned dynamic model

  • parent (MultiModelParticle, optional) – Parent particle

dynamic_model: int

Assigned dynamic model

parent: MultiModelParticle

Parent particle

class stonesoup.types.particle.RaoBlackwellisedParticle(state_vector: StateVector, weight: float, model_probabilities: Sequence[float], parent: RaoBlackwellisedParticle = None)[source]

Bases: Particle

Particle type

A RaoBlackwellisedParticle type which contains a state, weight, dynamic_model and associated model probabilities

Parameters:
model_probabilities: Sequence[float]

The dynamic probabilities of changing models

parent: RaoBlackwellisedParticle

Parent particle

Prediction Types

class stonesoup.types.prediction.Prediction(transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Type, CreatableFromState

Prediction type

This is the base prediction class.

Parameters:

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

transition_model: TransitionModel

The transition model used to make the prediction

class stonesoup.types.prediction.MeasurementPrediction[source]

Bases: Type, CreatableFromState

Prediction type

This is the base measurement prediction class.

class stonesoup.types.prediction.StatePrediction(state_vector: StateVector, timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, 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.

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

class stonesoup.types.prediction.InformationStatePrediction(state_vector: StateVector, precision: PrecisionMatrix, timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, InformationState

InformationStatePrediction type

Information state prediction type: contains state vector, precision matrix and timestamp

Parameters:
class stonesoup.types.prediction.StateMeasurementPrediction(state_vector: StateVector, timestamp: datetime = None)[source]

Bases: MeasurementPrediction, State

MeasurementPrediction type

Most simple measurement prediction type, which only has time and a state vector.

Parameters:
class stonesoup.types.prediction.GaussianStatePrediction(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, 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.ASDGaussianStatePrediction(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int, multi_covar: CovarianceMatrix, act_timestamp: datetime, correlation_matrices: MutableSequence[MutableMapping[str, ndarray]] = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, ASDGaussianState

ASDGaussianStatePrediction type

This is a simple ASDGaussian state prediction object, which, as the name suggests, is described by a Gaussian distribution.

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • act_timestamp (datetime.datetime) – The timestamp for which the state is predicted

  • correlation_matrices (collections.abc.MutableSequence, optional) – Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

act_timestamp: datetime

The timestamp for which the state is predicted

class stonesoup.types.prediction.SqrtGaussianStatePrediction(state_vector: StateVector, sqrt_covar: CovarianceMatrix, timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, 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.

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

class stonesoup.types.prediction.WeightedGaussianStatePrediction(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, weight: Probability = 0, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, WeightedGaussianState

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:
class stonesoup.types.prediction.TaggedWeightedGaussianStatePrediction(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, weight: Probability = 0, tag: str = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, 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.

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

class stonesoup.types.prediction.GaussianMeasurementPrediction(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, cross_covar: CovarianceMatrix = None)[source]

Bases: MeasurementPrediction, 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: CovarianceMatrix

The state-measurement cross covariance matrix

class stonesoup.types.prediction.ASDGaussianMeasurementPrediction(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int, multi_covar: CovarianceMatrix, correlation_matrices: MutableSequence[MutableMapping[str, ndarray]] = None, cross_covar: CovarianceMatrix = None)[source]

Bases: MeasurementPrediction, ASDGaussianState

ASD Gaussian Measurement Prediction

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (collections.abc.MutableSequence, optional) – Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

  • cross_covar (CovarianceMatrix, optional) – The state-measurement cross covariance matrix

cross_covar: CovarianceMatrix

The state-measurement cross covariance matrix

class stonesoup.types.prediction.ParticleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, ParticleState

ParticleStatePrediction type

This is a simple Particle state prediction object.

Parameters:
class stonesoup.types.prediction.PointMassStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, grid_delta: ndarray = None, grid_dim: ndarray = None, center: ndarray = None, eigVec: ndarray = None, Npa: ndarray = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, PointMassState

PointMassStatePrediction type

This is a simple Point mass state prediction object.

Parameters:
class stonesoup.types.prediction.ParticleMeasurementPrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None)[source]

Bases: MeasurementPrediction, ParticleState

MeasurementStatePrediction type

This is a simple Particle measurement prediction object.

Parameters:
class stonesoup.types.prediction.PointMassMeasurementPrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, grid_delta: ndarray = None, grid_dim: ndarray = None, center: ndarray = None, eigVec: ndarray = None, Npa: ndarray = None)[source]

Bases: MeasurementPrediction, PointMassState

MeasurementStatePrediction type

This is a simple Point mass measurement prediction object.

Parameters:
class stonesoup.types.prediction.MultiModelParticleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, dynamic_model: ndarray = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, MultiModelParticleState

MultiModelParticleStatePrediction type

This is a simple multi-model Particle state prediction object.

Parameters:
class stonesoup.types.prediction.RaoBlackwellisedParticleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, model_probabilities: ndarray = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, RaoBlackwellisedParticleState

RaoBlackwellisedParticleStatePrediction type

This is a simple Rao Blackwellised Particle state prediction object.

Parameters:
class stonesoup.types.prediction.BernoulliParticleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, existence_probability: Probability = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, BernoulliParticleState

BernoulliParticleStatePrediction type

This is a simple Bernoulli Particle state prediction object

Parameters:
class stonesoup.types.prediction.KernelParticleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, weight: ndarray = None, kernel_covar: CovarianceMatrix = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, KernelParticleState

KernelParticleStatePrediction type

This is a kernel particle state prediction object.

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (numpy.ndarray, optional) – Weights of particles. Defaults to [1/N]*N.

  • kernel_covar (CovarianceMatrix, optional) – Kernel covariance value. Default None.If None, the identity matrix is used.

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

class stonesoup.types.prediction.KernelParticleStateMeasurementPrediction(state_vector: StateVectors, timestamp: datetime = None, weight: ndarray = None, kernel_covar: CovarianceMatrix = None)[source]

Bases: MeasurementPrediction, KernelParticleState

KernelParticleStateMeasurementPrediction type

This is a kernel particle state measurement prediction object.

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (numpy.ndarray, optional) – Weights of particles. Defaults to [1/N]*N.

  • kernel_covar (CovarianceMatrix, optional) – Kernel covariance value. Default None.If None, the identity matrix is used.

class stonesoup.types.prediction.EnsembleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, EnsembleState

EnsembleStatePrediction type

This is a simple Ensemble measurement prediction object.

Parameters:

  • state_vector (StateVectors) – An ensemble of state vectors which represent the state

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

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

class stonesoup.types.prediction.EnsembleMeasurementPrediction(state_vector: StateVectors, timestamp: datetime = None)[source]

Bases: MeasurementPrediction, EnsembleState

EnsembleMeasurementPrediction type

This is a simple Ensemble measurement prediction object.

Parameters:

  • state_vector (StateVectors) – An ensemble of state vectors which represent the state

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

class stonesoup.types.prediction.CategoricalStatePrediction(state_vector: StateVector, timestamp: datetime = None, categories: Sequence[float] = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, CategoricalState

Categorical state prediction type

Parameters:
class stonesoup.types.prediction.CategoricalMeasurementPrediction(state_vector: StateVector, timestamp: datetime = None, categories: Sequence[float] = None)[source]

Bases: MeasurementPrediction, CategoricalState

Categorical measurement prediction type

Parameters:
class stonesoup.types.prediction.CompositePrediction(sub_states: Sequence[Prediction], default_timestamp: datetime = None, transition_model: TransitionModel = None, prior: State = None)[source]

Bases: Prediction, CompositeState

Composite prediction type

Composition of Prediction.

Parameters:

  • sub_states (collections.abc.Sequence) – Sequence of sub-predictions comprising the composite prediction. All sub-predictions must have matching timestamp. Must not be empty.

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

  • transition_model (TransitionModel, optional) – The transition model used to make the prediction

  • prior (State, optional)

sub_states: Sequence[Prediction]

Sequence of sub-predictions comprising the composite prediction. All sub-predictions must have matching timestamp. Must not be empty.

class stonesoup.types.prediction.CompositeMeasurementPrediction(sub_states: Sequence[MeasurementPrediction] = None, default_timestamp: datetime = None)[source]

Bases: MeasurementPrediction, CompositeState

Composite measurement prediction type

Composition of MeasurementPrediction.

Parameters:

  • sub_states (collections.abc.Sequence, optional) – Sequence of sub-measurement-predictions comprising the composite measurement prediction. All sub-measurement-predictions must have matching timestamp.

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

sub_states: Sequence[MeasurementPrediction]

Sequence of sub-measurement-predictions comprising the composite measurement prediction. All sub-measurement-predictions must have matching timestamp.

Sensor Data Types

class stonesoup.types.sensordata.SensorData[source]

Bases: Type

Sensor Data type

class stonesoup.types.sensordata.ImageFrame(pixels: ndarray, timestamp: datetime = None)[source]

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

An optional timestamp

State Types

class stonesoup.types.state.State(state_vector: StateVector, timestamp: datetime = None)[source]

Bases: Type

State type.

Most simple state type, which only has time and a state vector.

Parameters:
timestamp: datetime

Timestamp of the state. Default None.

state_vector: StateVector

State vector.

property ndim

The number of dimensions represented by the state.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State[source]

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

class stonesoup.types.state.PointMassState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, grid_delta: ndarray = None, grid_dim: ndarray = None, center: ndarray = None, eigVec: ndarray = None, Npa: ndarray = None)[source]

Bases: State

PointMassState State type

For the Lagrangina Point Mass filter.

Parameters:
state_vector: StateVectors

State vectors.

weight: MutableSequence[Probability]

Masses of grid points

grid_delta: ndarray

Grid step per dim

grid_dim: ndarray

Grid coordinates per dimension before rotation and translation

center: ndarray

Center of the grid

eigVec: ndarray

Eigenvectors of the grid

Npa: ndarray

Points per dim

property ndim

The number of dimensions represented by the state.

property mean

Sample mean for particles

Note

This will be cached until state_vector is replaced.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.ASDState(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int)[source]

Bases: Type

ASD State type

For the use of Accumulated State Densities.

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

multi_state_vector: StateVector

State vector of all timestamps

timestamps: Sequence[datetime]

List of all timestamps which have a state in the ASDState

max_nstep: int

Decides when the state is pruned in a prediction step. If 0 then there is no pruning

property state_vector

The State vector of the newest timestamp

property timestamp

The newest timestamp

property ndim

Dimension of one State

property nstep

Number of timesteps which are in the ASDState

property state

A State object representing latest timestamp

Note

This will be cached until multi_state_vector or timestamps are replaced.

property states

Note

This will be cached until multi_state_vector or timestamps are replaced.

class stonesoup.types.state.StateMutableSequence(states: MutableSequence[State] = None)[source]

Bases: Type, 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.

Notes

If shallow copying, similar to a list, it is safe to add/remove states without affecting the original sequence.

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 (collections.abc.MutableSequence, optional) – The initial list of states. Default None which initialises with empty list.

states: MutableSequence[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

last_timestamp_generator()[source]

Generator yielding the last state for each timestamp

This provides a method of iterating over a sequence of states, such that when multiple states for the same timestamp exist, only the last state is yielded. This is particularly useful in cases where you may have multiple Update states for a single timestamp e.g. multi-sensor tracking example.

Yields:

State – A state for each timestamp present in the sequence.

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: StateVector, covar: CovarianceMatrix, timestamp: datetime = None)[source]

Bases: 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: CovarianceMatrix

Covariance matrix of state.

property mean

The state mean, equivalent to state vector

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property ndim

The number of dimensions represented by the state.

state_vector: StateVector

State vector.

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.SqrtGaussianState(state_vector: StateVector, sqrt_covar: CovarianceMatrix, timestamp: datetime = None)[source]

Bases: 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: 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.

Note

This will be cached until sqrt_covar is replaced.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property ndim

The number of dimensions represented by the state.

state_vector: StateVector

State vector.

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.InformationState(state_vector: StateVector, precision: PrecisionMatrix, timestamp: datetime = None)[source]

Bases: State

Information State Type

The information state class carries the state_vector, \(\mathbf{y}_k = Y_k \mathbf{x}_k\) and the precision or information matrix \(Y_k = P_k^{-1}\), where \(\mathbf{x}_k\) and \(P_k\) are the mean and covariance, respectively, of a Gaussian state.

Parameters:
precision: PrecisionMatrix

precision matrix of state.

property gaussian_state

The Gaussian state.

Note

This will be cached until state_vector or precision are replaced.

property covar

Covariance matrix, inverse of precision matrix.

Note

This will be cached until precision is replaced.

property mean

Equivalent Gaussian mean

Note

This will be cached until state_vector or precision are replaced.

classmethod from_gaussian_state(gaussian_state, *args, **kwargs)[source]

Returns an InformationState instance based on the gaussian_state.

Parameters:
Returns:

Instance of InformationState.

Return type:

InformationState

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property ndim

The number of dimensions represented by the state.

state_vector: StateVector

State vector.

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.ASDGaussianState(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int, multi_covar: CovarianceMatrix, correlation_matrices: MutableSequence[MutableMapping[str, ndarray]] = None)[source]

Bases: ASDState

ASDGaussian State type

This is a simple Accumulated State Density Gaussian state object, which as the name suggests is described by a Gaussian state distribution.

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (collections.abc.MutableSequence, optional) – Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

multi_covar: CovarianceMatrix

Covariance of all timesteps

correlation_matrices: MutableSequence[MutableMapping[str, ndarray]]

Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

property mean

The state mean, equivalent to state vector

property state

A GaussianState object representing latest timestamp

Note

This will be cached until multi_state_vector, multi_covar or timestamps are replaced.

property states

Note

This will be cached until multi_state_vector, multi_covar or timestamps are replaced.

max_nstep: int

Decides when the state is pruned in a prediction step. If 0 then there is no pruning

multi_state_vector: StateVector

State vector of all timestamps

property ndim

Dimension of one State

property nstep

Number of timesteps which are in the ASDState

property state_vector

The State vector of the newest timestamp

property timestamp

The newest timestamp

timestamps: Sequence[datetime]

List of all timestamps which have a state in the ASDState

class stonesoup.types.state.WeightedGaussianState(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, weight: Probability = 0)[source]

Bases: GaussianState

Weighted Gaussian State Type

Gaussian State object with an associated weight. Used as components for a GaussianMixtureState.

Parameters:
weight: Probability

Weight of the Gaussian State.

property gaussian_state

The Gaussian state.

Note

This will be cached until state_vector or covar are replaced.

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

Covariance matrix of state.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property mean

The state mean, equivalent to state vector

property ndim

The number of dimensions represented by the state.

state_vector: StateVector

State vector.

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.TaggedWeightedGaussianState(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, weight: Probability = 0, tag: str = None)[source]

Bases: 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.

BIRTH = 'birth'

Tag value used to signify birth component

tag: str

Unique tag of the Gaussian State.

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

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property gaussian_state

The Gaussian state.

Note

This will be cached until state_vector or covar are replaced.

property mean

The state mean, equivalent to state vector

property ndim

The number of dimensions represented by the state.

state_vector: StateVector

State vector.

timestamp: datetime

Timestamp of the state. Default None.

weight: Probability

Weight of the Gaussian State.

class stonesoup.types.state.ASDWeightedGaussianState(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int, multi_covar: CovarianceMatrix, correlation_matrices: MutableSequence[MutableMapping[str, ndarray]] = None, weight: Probability = 0)[source]

Bases: ASDGaussianState

ASD Weighted Gaussian State Type

ASD Gaussian State object with an associated weight. Used as components for a GaussianMixtureState.

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (collections.abc.MutableSequence, optional) – Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

  • weight (Probability, optional) – Weight of the Gaussian State.

weight: Probability

Weight of the Gaussian State.

correlation_matrices: MutableSequence[MutableMapping[str, ndarray]]

Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

max_nstep: int

Decides when the state is pruned in a prediction step. If 0 then there is no pruning

property mean

The state mean, equivalent to state vector

multi_covar: CovarianceMatrix

Covariance of all timesteps

multi_state_vector: StateVector

State vector of all timestamps

property ndim

Dimension of one State

property nstep

Number of timesteps which are in the ASDState

property state

A GaussianState object representing latest timestamp

Note

This will be cached until multi_state_vector, multi_covar or timestamps are replaced.

property state_vector

The State vector of the newest timestamp

property states

Note

This will be cached until multi_state_vector, multi_covar or timestamps are replaced.

property timestamp

The newest timestamp

timestamps: Sequence[datetime]

List of all timestamps which have a state in the ASDState

class stonesoup.types.state.ParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None)[source]

Bases: State

Particle State type

This is a particle state object which describes the state as a distribution of particles

Parameters:
log_weight: ndarray

Log weights of particles

particle_list: MutableSequence[Particle]

List of Particle objects

fixed_covar: CovarianceMatrix

Fixed covariance value. Default None, whereweighted sample covariance is then used.

state_vector: StateVectors

State vectors.

parent: ParticleState

Parent particles

classmethod from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State[source]

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or log_weight are replaced.

property ndim

The number of dimensions represented by the state.

property mean

Sample mean for particles

Note

This will be cached until state_vector or log_weight are replaced.

property covar

Sample covariance matrix for particles

Note

This will be cached until state_vector, log_weight or fixed_covar are replaced.

weight: MutableSequence[Probability]

Weights of particles

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.MultiModelParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, dynamic_model: ndarray = None)[source]

Bases: ParticleState

Multi-Model Particle State type

This is a particle state object which describes the state as a distribution of particles, where each particle has an associated dynamics model

Parameters:
dynamic_model: ndarray

Array of indices that identify which model is associated with each particle.

property covar

Sample covariance matrix for particles

Note

This will be cached until state_vector, log_weight or fixed_covar are replaced.

fixed_covar: CovarianceMatrix

Fixed covariance value. Default None, whereweighted sample covariance is then used.

classmethod from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

log_weight: ndarray

Log weights of particles

property mean

Sample mean for particles

Note

This will be cached until state_vector or log_weight are replaced.

property ndim

The number of dimensions represented by the state.

parent: ParticleState

Parent particles

particle_list: MutableSequence[Particle]

List of Particle objects

property particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or log_weight are replaced.

state_vector: StateVectors

State vectors.

timestamp: datetime

Timestamp of the state. Default None.

weight: MutableSequence[Probability]

Weights of particles

class stonesoup.types.state.RaoBlackwellisedParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, model_probabilities: ndarray = None)[source]

Bases: ParticleState

Parameters:
model_probabilities: ndarray

2d NumPy array containing probability of particle belong to particular model. Shape (n-models, m-particles).

property covar

Sample covariance matrix for particles

Note

This will be cached until state_vector, log_weight or fixed_covar are replaced.

fixed_covar: CovarianceMatrix

Fixed covariance value. Default None, whereweighted sample covariance is then used.

classmethod from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

log_weight: ndarray

Log weights of particles

property mean

Sample mean for particles

Note

This will be cached until state_vector or log_weight are replaced.

property ndim

The number of dimensions represented by the state.

parent: ParticleState

Parent particles

particle_list: MutableSequence[Particle]

List of Particle objects

property particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or log_weight are replaced.

state_vector: StateVectors

State vectors.

timestamp: datetime

Timestamp of the state. Default None.

weight: MutableSequence[Probability]

Weights of particles

class stonesoup.types.state.BernoulliParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, existence_probability: Probability = None)[source]

Bases: ParticleState

Bernoulli Particle State type

This is a particle state object that describes the target as a distribution of particles and an estimated existence probability according to the Bernoulli particle filter [1].

References

Parameters:
existence_probability: Probability

Target existence probability estimate

property covar

Sample covariance matrix for particles

Note

This will be cached until state_vector, log_weight or fixed_covar are replaced.

fixed_covar: CovarianceMatrix

Fixed covariance value. Default None, whereweighted sample covariance is then used.

classmethod from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

log_weight: ndarray

Log weights of particles

property mean

Sample mean for particles

Note

This will be cached until state_vector or log_weight are replaced.

property ndim

The number of dimensions represented by the state.

parent: ParticleState

Parent particles

particle_list: MutableSequence[Particle]

List of Particle objects

property particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or log_weight are replaced.

state_vector: StateVectors

State vectors.

timestamp: datetime

Timestamp of the state. Default None.

weight: MutableSequence[Probability]

Weights of particles

class stonesoup.types.state.KernelParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: ndarray = None, kernel_covar: CovarianceMatrix = None)[source]

Bases: State

Kernel Particle State type

This is a kernel particle state object which describes the state as a distribution of particles and kernel covariance.

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (numpy.ndarray, optional) – Weights of particles. Defaults to [1/N]*N.

  • kernel_covar (CovarianceMatrix, optional) – Kernel covariance value. Default None.If None, the identity matrix is used.

state_vector: StateVectors

State vectors.

weight: ndarray

Weights of particles. Defaults to [1/N]*N.

kernel_covar: CovarianceMatrix

Kernel covariance value. Default None.If None, the identity matrix is used.

property ndim

The number of dimensions represented by the state.

property mean

Note

This will be cached until state_vector or weight are replaced.

property covar

Note

This will be cached until state_vector or kernel_covar are replaced.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

timestamp: datetime

Timestamp of the state. Default None.

class stonesoup.types.state.EnsembleState(state_vector: StateVectors, timestamp: datetime = None)[source]

Bases: State

Ensemble State type

This is an Ensemble state object which describes the system state as an ensemble of state vectors for use in Ensemble based filters.

This approach is functionally identical to the Particle state type except it doesn’t use any weighting for any of the “particles” or ensemble members. All “particles” or state vectors in the ensemble are equally weighted.

\[\mathbf{X} = [x_1, x_2, ..., x_M]\]
Parameters:

  • state_vector (StateVectors) – An ensemble of state vectors which represent the state

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

state_vector: StateVectors

An ensemble of state vectors which represent the state

timestamp: datetime

Timestamp of the state. Default None.

classmethod from_gaussian_state(gaussian_state, num_vectors, **kwargs)[source]

Returns an EnsembleState instance, from a given GaussianState object.

Parameters:

  • gaussian_state (GaussianState) – The GaussianState used to create the new EnsembleState.

  • num_vectors (int) – The number of desired column vectors present in the ensemble.

Returns:

Instance of EnsembleState.

Return type:

EnsembleState

static generate_ensemble(mean, covar, num_vectors)[source]

Returns a StateVectors wrapped ensemble of state vectors, from a given mean and covariance matrix.

Parameters:

  • mean (ndarray) – The mean value of the distribution being sampled to generate ensemble.

  • covar (ndarray) – The covariance matrix of the distribution being sampled to generate ensemble.

  • num_vectors (int) – The number of desired column vectors present in the ensemble, or the number of “samples”.

Returns:

Instance of EnsembleState.

Return type:

EnsembleState

property num_vectors

Number of columns in state ensemble

property mean

The state mean, numerically equivalent to state vector

Note

This will be cached until state_vector is replaced.

property covar

Sample covariance matrix for ensemble

Note

This will be cached until state_vector is replaced.

property sqrt_covar
sqrt of sample covariance matrix for ensemble, useful for

some EnKF algorithms

Note

This will be cached until state_vector is replaced.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property ndim

The number of dimensions represented by the state.

class stonesoup.types.state.CategoricalState(state_vector: StateVector, timestamp: datetime = None, categories: Sequence[float] = None)[source]

Bases: State

CategoricalState type.

State object representing an object in a categorical state space. A state vector \(\mathbf{\alpha}_t^i = P(\phi_t^i)\) defines a categorical distribution over a finite set of discrete categories \(\Phi = \{\phi^m|m\in \mathbf{N}, m\le M\}\) for some finite \(M\).

Parameters:
state_vector: StateVector

State vector.

categories: Sequence[float]

Category names. Defaults to a list of integers.

static from_state(state: State, *args: Any, target_type: Type | None = None, **kwargs: Any) → State

Class utility function to create a new state (or compatible type) from an existing state. The type and properties of this new state are defined by state except for any explicitly overwritten via args and kwargs.

It acts similarly in feel to a copy constructor, with the optional over-writing of properties.

Parameters:

  • state (State) – State to use existing properties from, and identify new state-type from.

  • *args (Sequence) – Arguments to pass to newly created state, replacing those with same name in state.

  • target_type (Type, optional) – Optional argument specifying the type of object to be created. This need not necessarily be State subclass. Any arguments that match between the input state and the target type will be copied from the old to the new object (except those explicitly specified in args and kwargs).

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

property ndim

The number of dimensions represented by the state.

timestamp: datetime

Timestamp of the state. Default None.

property category

Return the name of the most likely category.

class stonesoup.types.state.CompositeState(sub_states: Sequence[State], default_timestamp: datetime = None)[source]

Bases: Type

Composite state type.

A composition of ordered sub-states (State) existing at the same timestamp, representing an object with a state for (potentially) multiple, distinct state spaces.

Parameters:

  • sub_states (collections.abc.Sequence) – Sequence of sub-states comprising the composite state. All sub-states must have matching timestamp. Must not be empty.

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

sub_states: Sequence[State]

Sequence of sub-states comprising the composite state. All sub-states must have matching timestamp. Must not be empty.

default_timestamp: datetime

Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

property state_vector

A combination of the component states’ state vectors.

OrbitalState Types

Time Types

class stonesoup.types.time.TimeRange(start: datetime, end: datetime)[source]

Bases: Interval

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

Start of the time range

end: datetime

End of the time range

property duration: timedelta

Duration of the time range

property key_times: list[datetime]

Times the TimeRange begins and ends

class stonesoup.types.time.CompoundTimeRange(intervals: MutableSequence[Interval] = None)[source]

Bases: Intervals

CompoundTimeRange type

A container class representing one or more TimeRange objects together

Parameters:

intervals (collections.abc.MutableSequence, optional) – Container of Interval

property duration: timedelta

Duration of the time range

property key_times: list[datetime]

Returns all timestamps at which a component starts or ends

add(time_range)[source]

Add a TimeRange or CompoundTimeRange object to time_ranges.

remove(time_range: TimeRange)[source]

Removes a TimeRange object from the time ranges. It must be a member of self.time_ranges

Track Types

class stonesoup.types.track.Track(states: MutableSequence[State] = None, id: str = None, init_metadata: MutableMapping = {})[source]

Bases: 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 (collections.abc.MutableSequence, optional) – The initial states of the track. Default None which initialises with empty list.

  • id (str, optional) – The unique track ID

  • init_metadata (collections.abc.MutableMapping, optional) – Initial dictionary of metadata items for track. Default None which initialises track metadata as an empty dictionary.

states: MutableSequence[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: Hypothesis)[source]

Bases: Type, CreatableFromState

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

Hypothesis used for updating

class stonesoup.types.update.StateUpdate(state_vector: StateVector, hypothesis: Hypothesis, timestamp: datetime = None)[source]

Bases: Update, 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: StateVector, covar: CovarianceMatrix, hypothesis: Hypothesis, timestamp: datetime = None)[source]

Bases: Update, 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: StateVector, sqrt_covar: CovarianceMatrix, hypothesis: Hypothesis, timestamp: datetime = None)[source]

Bases: Update, 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.WeightedGaussianStateUpdate(state_vector: StateVector, covar: CovarianceMatrix, hypothesis: Hypothesis, timestamp: datetime = None, weight: Probability = 0)[source]

Bases: Update, WeightedGaussianState

WeightedGaussianStateUpdate type

This is a simple Gaussian state update object, which, as the name suggests, is described by a Gaussian distribution with an associated weight.

Parameters:
class stonesoup.types.update.TaggedWeightedGaussianStateUpdate(state_vector: StateVector, covar: CovarianceMatrix, hypothesis: Hypothesis, timestamp: datetime = None, weight: Probability = 0, tag: str = None)[source]

Bases: Update, TaggedWeightedGaussianState

TaggedWeightedGaussianStateUpdate type

This is a simple Gaussian state update 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.

  • hypothesis (Hypothesis) – Hypothesis used for updating

  • 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.update.GaussianMixtureUpdate(hypothesis: Hypothesis, components: MutableSequence[WeightedGaussianState] = None)[source]

Bases: Update, 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 (collections.abc.MutableSequence, optional) –

    The initial list of WeightedGaussianState components.

    Default None which initialises with empty list.

class stonesoup.types.update.ASDGaussianStateUpdate(multi_state_vector: StateVector, timestamps: Sequence[datetime], max_nstep: int, multi_covar: CovarianceMatrix, hypothesis: Hypothesis, correlation_matrices: MutableSequence[MutableMapping[str, ndarray]] = None)[source]

Bases: Update, ASDGaussianState

ASDGaussianStateUpdate type

This is a simple ASD Gaussian state update object, which, as the name suggests, is described by a Gaussian distribution.

Parameters:

  • multi_state_vector (StateVector) – State vector of all timestamps

  • timestamps (collections.abc.Sequence) – List of all timestamps which have a state in the ASDState

  • max_nstep (int) – Decides when the state is pruned in a prediction step. If 0 then there is no pruning

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • hypothesis (Hypothesis) – Hypothesis used for updating

  • correlation_matrices (collections.abc.MutableSequence, optional) – Sequence of Correlation Matrices, consisting of \(P_{l|l}\), \(P_{l|l+1}\) and \(F_{l+1|l}\) built in the Kalman predictor and Kalman updater, aligned to timestamps

class stonesoup.types.update.ParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None)[source]

Bases: Update, ParticleState

ParticleStateUpdate type

This is a simple Particle state update object.

Parameters:
class stonesoup.types.update.MultiModelParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, dynamic_model: ndarray = None)[source]

Bases: Update, MultiModelParticleState

MultiModelStateUpdate type

This is a simple Multi-Model Particle state update object.

Parameters:
class stonesoup.types.update.RaoBlackwellisedParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, model_probabilities: ndarray = None)[source]

Bases: Update, RaoBlackwellisedParticleState

RaoBlackwellisedStateUpdate type

This is a simple Rao Blackwellised Particle state update object.

Parameters:
class stonesoup.types.update.BernoulliParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = None, log_weight: ndarray = None, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, existence_probability: Probability = None)[source]

Bases: Update, BernoulliParticleState

BernoulliStateUpdate type

This is a simple Bernoulli Particle state update object.

Parameters:
class stonesoup.types.update.KernelParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: ndarray = None, kernel_covar: CovarianceMatrix = None, proposal: StateVectors = None)[source]

Bases: Update, KernelParticleState

KernelParticleStateUpdate type

This is a Kernel Particle state update object.

Parameters:

  • state_vector (StateVectors) – State vectors.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

  • weight (numpy.ndarray, optional) – Weights of particles. Defaults to [1/N]*N.

  • kernel_covar (CovarianceMatrix, optional) – Kernel covariance value. Default None.If None, the identity matrix is used.

  • proposal (StateVectors, optional) – Kernel covariance value. Default None.

proposal: StateVectors

Kernel covariance value. Default None.

class stonesoup.types.update.EnsembleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None)[source]

Bases: Update, EnsembleState

EnsembleStateUpdate type

This is a simple Ensemble state update object.

Parameters:

  • state_vector (StateVectors) – An ensemble of state vectors which represent the state

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

class stonesoup.types.update.InformationStateUpdate(state_vector: StateVector, precision: PrecisionMatrix, hypothesis: Hypothesis, timestamp: datetime = None)[source]

Bases: Update, InformationState

InformationUpdate type

This is a simple Information state update object, which, as the name suggests, is described by a precision matrix and its corresponding state vector.

Parameters:
class stonesoup.types.update.CategoricalStateUpdate(state_vector: StateVector, hypothesis: Hypothesis, timestamp: datetime = None, categories: Sequence[float] = None)[source]

Bases: Update, CategoricalState

Categorical state prediction type

Parameters:
class stonesoup.types.update.CompositeUpdate(sub_states: Sequence[Update], hypothesis: CompositeHypothesis, default_timestamp: datetime = None)[source]

Bases: Update, CompositeState

Composite update type

Composition of Update.

Parameters:

  • sub_states (collections.abc.Sequence) – Sequence of sub-updates comprising the composite update. All sub-updates must have matching timestamp. Must not be empty.

  • hypothesis (CompositeHypothesis) – Hypothesis used for updating

  • default_timestamp (datetime.datetime, optional) – Default timestamp if no sub-states exist to attain timestamp from. Defaults to None, whereby sub-states will be required to have timestamps.

sub_states: Sequence[Update]

Sequence of sub-updates comprising the composite update. All sub-updates must have matching timestamp. Must not be empty.

hypothesis: CompositeHypothesis

Hypothesis used for updating