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 a invalid shape for a StateVector (i.e. not (n, 1)) then a Matrix view will be returned.

Note

It is not recommended to use a StateVector for indexing another vector. Doing so will lead to unexpected effects. Use a tuple, list or np.ndarray for this.

flatten(order='C')[source]

Return a copy of the array collapsed into one dimension.

Parameters:

order ({'C', 'F', 'A', 'K'}, optional) – ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran- style) order. ‘A’ means to flatten in column-major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means to flatten a in the order the elements occur in memory. The default is ‘C’.

Returns:

y – A copy of the input array, flattened to one dimension.

Return type:

ndarray

See also

ravel

Return a flattened array.

flat

A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])
ravel([order])[source]

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel

equivalent function

ndarray.flat

a flat iterator on the array.

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

Bases: 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 its initialised at 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.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: 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 (TimeRange, optional) – Range of times that association exists over. Default is None

time_range: 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[Association], optional) – Set of independent associations

associations: Set[Association]

Set of independent associations

associations_at_timestamp(timestamp)[source]

Return the associations that exist at a given timestamp

Method will return a set of all the Association type objects which occur at the specified time stamp.

Parameters:

timestamp (datetime.datetime) – Timestamp at which associations should be identified

Returns:

Associations which occur at specified timestamp

Return type:

set of Association

associations_including_objects(objects)[source]

Return associations that include all the given objects

Method will return the set of all the Association type objects which contain an association with the provided object

Parameters:

objects (set of objects) – Set of objects to look for in associations

Returns:

A set of objects which have been associated

Return type:

set of Association

Detection Types

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

Bases: State

Detection type

Parameters:

  • state_vector (StateVector) – State vector.

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

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

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

  • state_vector (StateVector) – State vector.

  • covar (CovarianceMatrix) – Covariance matrix of state.

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

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

class stonesoup.types.detection.Clutter(state_vector: 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:

  • state_vector (StateVector) – State vector.

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

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

class stonesoup.types.detection.TrueDetection(state_vector: 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:

  • state_vector (StateVector) – State vector.

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

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

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

groundtruth_path: 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 (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:

  • state_vector (StateVector) – State vector.

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

class stonesoup.types.detection.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:

  • state_vector (StateVector) – State vector.

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

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

class stonesoup.types.detection.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 (Sequence[Detection]) – 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 (Sequence[int], 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:

  • state_vector (StateVector) – State vector.

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

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

metadata: MutableMapping

Dictionary of metadata items for Detections.

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

Bases: GroundTruthState, CategoricalState

Categorical Ground Truth State type

Parameters:

  • state_vector (StateVector) – State vector.

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

  • metadata (MutableMapping, optional) – Dictionary of metadata items for Detections.

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 (MutableSequence[GroundTruthState], optional) – List of groundtruth states to initialise path with. Default None which initialises with an empty list.

  • id (str, optional) – The unique path ID. Default None where random UUID is generated.

states: MutableSequence[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 (Sequence[GroundTruthState]) – 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:

  • prediction (CompositePrediction) – Predicted track state

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

  • sub_hypotheses (Sequence[SingleHypothesis]) – Sequence of sub-hypotheses comprising the composite hypothesis. Must not be empty.

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

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 (Sequence[SingleProbabilityHypothesis], 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, Sized, Iterable, Container

Multiple Hypothesis base type

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

Parameters:

  • single_hypotheses (Sequence[SingleHypothesis], optional) – The initial list of SingleHypothesis. Default None which initialises with empty list.

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

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

single_hypotheses: Sequence[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, Sized, Iterable, Container

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 (Sequence[CompositeHypothesis], 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(left: int | float, right: 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:

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

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

left: int | float

Lower bound of interval

right: 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 (MutableSequence[Interval], 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. Ie. 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, Sized, Iterable, Container

Gaussian Mixture type

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

Parameters:

components (MutableSequence[WeightedGaussianState], optional) –

The initial list of WeightedGaussianState components.

Default None which initialises with empty list.

components: MutableSequence[WeightedGaussianState]

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

Numeric Types

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

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

parent: Particle

Parent particle

state_vector: StateVector

State vector

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:

  • state_vector (StateVector) – State vector

  • weight (float) – Weight of particle

  • model_probabilities (Sequence[float]) – The dynamic probabilities of changing models

  • parent (RaoBlackwellisedParticle, optional) – Parent particle

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

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

class stonesoup.types.prediction.InformationStatePrediction(state_vector: StateVector, precision: PrecisionMatrix, timestamp: datetime = None, transition_model: TransitionModel = 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)[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)[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 (Sequence[datetime.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

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

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

  • correlation_matrices (MutableSequence[MutableMapping[str, numpy.ndarray]], 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

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

class stonesoup.types.prediction.WeightedGaussianStatePrediction(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime = None, weight: Probability = 0, transition_model: TransitionModel = 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)[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

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 (Sequence[datetime.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

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (MutableSequence[MutableMapping[str, numpy.ndarray]], 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, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, transition_model: TransitionModel = None)[source]

Bases: Prediction, ParticleState

ParticleStatePrediction type

This is a simple Particle state prediction object.

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

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

class stonesoup.types.prediction.ParticleMeasurementPrediction(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = 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:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

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

Bases: Prediction, MultiModelParticleState

MultiModelParticleStatePrediction type

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

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • dynamic_model (numpy.ndarray, optional) – Array of indices that identify which model is associated with each particle.

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

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

Bases: Prediction, RaoBlackwellisedParticleState

RaoBlackwellisedParticleStatePrediction type

This is a simple Rao Blackwellised Particle state prediction object.

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • model_probabilities (numpy.ndarray, optional) – 2d NumPy array containing probability of particle belong to particular model. Shape (n-models, m-particles).

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

class stonesoup.types.prediction.EnsembleStatePrediction(state_vector: StateVectors, timestamp: datetime = None, transition_model: TransitionModel = 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

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

Bases: Prediction, CategoricalState

Categorical state prediction type

Parameters:

  • state_vector (StateVector) – State vector.

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

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

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

Bases: MeasurementPrediction, CategoricalState

Categorical measurement prediction type

Parameters:

  • state_vector (StateVector) – State vector.

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

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

Bases: Prediction, CompositeState

Composite prediction type

Composition of Prediction.

Parameters:

  • sub_states (Sequence[Prediction]) – 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

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 (Sequence[MeasurementPrediction], 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 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.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 (Sequence[datetime.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

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

state

A State object representing latest timestamp

Note

This will be cached until multi_state_vector or timestamps are replaced.

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 (MutableSequence[State], 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 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

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

gaussian_state

The Gaussian state.

Note

This will be cached until state_vector or precision are replaced.

covar

Covariance matrix, inverse of precision matrix.

Note

This will be cached until precision is replaced.

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 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 (Sequence[datetime.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

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (MutableSequence[MutableMapping[str, numpy.ndarray]], 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

state

A GaussianState object representing latest timestamp

Note

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

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.

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

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 (Sequence[datetime.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

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • correlation_matrices (MutableSequence[MutableMapping[str, numpy.ndarray]], 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

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

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

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

particle_list: MutableSequence[Particle]

List of Particle objects

fixed_covar: CovarianceMatrix

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

parent: ParticleState

Parent particles

state_vector: StateVectors

State vectors.

weight: MutableSequence[Probability]

Weights of particles

particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or weight are replaced.

property ndim

The number of dimensions represented by the state.

mean

Sample mean for particles

Note

This will be cached until state_vector or weight are replaced.

covar

Sample covariance matrix for particles

Note

This will be cached until state_vector, weight or fixed_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 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.MultiModelParticleState(state_vector: StateVectors, timestamp: datetime = None, weight: MutableSequence[Probability] = 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:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • dynamic_model (numpy.ndarray, optional) – Array of indices that identify which model is associated with each particle.

dynamic_model: ndarray

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

covar

Sample covariance matrix for particles

Note

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

fixed_covar: CovarianceMatrix

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

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

mean

Sample mean for particles

Note

This will be cached until state_vector or 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

particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or 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, parent: ParticleState = None, particle_list: MutableSequence[Particle] = None, fixed_covar: CovarianceMatrix = None, model_probabilities: ndarray = None)[source]

Bases: ParticleState

Parameters:

  • state_vector (StateVectors) – State vectors.

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • model_probabilities (numpy.ndarray, optional) – 2d NumPy array containing probability of particle belong to particular model. Shape (n-models, m-particles).

model_probabilities: ndarray

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

covar

Sample covariance matrix for particles

Note

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

fixed_covar: CovarianceMatrix

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

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

mean

Sample mean for particles

Note

This will be cached until state_vector or 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

particles

Sequence of individual Particle objects.

Note

This will be cached until state_vector or 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.EnsembleState(state_vector: StateVectors, timestamp: datetime = None)[source]

Bases: Type

Ensemble State type

This is an Ensemble state object which describes the system state as a 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)[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 ndim

Number of dimensions in state vectors

property num_vectors

Number of columns in state ensemble

mean

The state mean, numerically equivalent to state vector

Note

This will be cached until state_vector is replaced.

covar

Sample covariance matrix for ensemble

Note

This will be cached until state_vector is replaced.

sqrt_covar
sqrt of sample covariance matrix for ensemble, useful for

some EnKF algorithms

Note

This will be cached until state_vector is replaced.

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.

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

state_vector: StateVector

State vector.

categories: Sequence[float]

Category names. Defaults to a list of integers.

property category

Return the name of the most likely category.

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

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 (Sequence[State]) – 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_timestamp: datetime, end_timestamp: datetime)[source]

Bases: Type

TimeRange type

An object representing a time range between two timestamps.

Can be used to check if timestamp is within via in operator

Example

>>> t0 = datetime.datetime(2018, 1, 1, 14, 00)
>>> t1 = datetime.datetime(2018, 1, 1, 15, 00)
>>> time_range = TimeRange(t0, t1)
>>> test_time = datetime.datetime(2018, 1, 1, 14, 30)
>>> print(test_time in time_range)
True
Parameters:
start_timestamp: datetime

Start of the time range

end_timestamp: datetime

End of the time range

property duration

Duration of the time range

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

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

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

states: MutableSequence[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.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 (MutableSequence[WeightedGaussianState], 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 (Sequence[datetime.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

  • multi_covar (CovarianceMatrix) – Covariance of all timesteps

  • hypothesis (Hypothesis) – Hypothesis used for updating

  • correlation_matrices (MutableSequence[MutableMapping[str, numpy.ndarray]], 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, 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:

  • state_vector (StateVectors) – State vectors.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

class stonesoup.types.update.MultiModelParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = 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:

  • state_vector (StateVectors) – State vectors.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • dynamic_model (numpy.ndarray, optional) – Array of indices that identify which model is associated with each particle.

class stonesoup.types.update.RaoBlackwellisedParticleStateUpdate(state_vector: StateVectors, hypothesis: Hypothesis, timestamp: datetime = None, weight: MutableSequence[Probability] = 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:

  • state_vector (StateVectors) – State vectors.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

  • weight (MutableSequence[Probability], optional) – Weights of particles

  • parent (ParticleState, optional) – Parent particles

  • particle_list (MutableSequence[Particle], optional) – List of Particle objects

  • fixed_covar (CovarianceMatrix, optional) – Fixed covariance value. Default None, whereweighted sample covariance is then used.

  • model_probabilities (numpy.ndarray, optional) – 2d NumPy array containing probability of particle belong to particular model. Shape (n-models, m-particles).

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:

  • state_vector (StateVector) – State vector.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

  • categories (Sequence[float], optional) – Category names. Defaults to a list of integers.

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

  • 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