Data Types

Base Types

class stonesoup.types.base.Type[source]

Bases: stonesoup.base.Base

Base type

Array Types

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

Bases: numpy.ndarray

Matrix wrapper for numpy.ndarray

This class returns a view to a numpy.ndarray It’s called same as to numpy.asarray().

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

Bases: stonesoup.types.array.Matrix

State vector wrapper for numpy.ndarray

This class returns a view to a numpy.ndarray, but ensures that its initialised as an \(N \times 1\) vector. It’s called same as numpy.asarray(). The StateVector will attempt to convert the data given to a \(N \times 1\) vector if it can easily be done. E.g., StateVector([1., 2., 3.]), StateVector ([[1., 2., 3.,]]), and StateVector([[1.], [2.], [3.]]) will all return the same 3x1 StateVector.

It also overrides the behaviour of indexing such that my_state_vector[1] returns the second element (as int, float etc), rather than a StateVector of size (1, 1) as would be the case without this override. Behaviour of indexing with lists, slices or other indexing is unaffected (as you would expect those to return StateVectors). This override avoids the need for client to specifically index with zero as the second element (my_state_vector[1, 0]) to get a native numeric type. Iterating through the StateVector returns a sequence of numbers, rather than a sequence of 1x1 StateVectors. This makes the class behave as would be expected and avoids ‘gotchas’.

Note that code using the pattern my_state_vector[1, 0] will continue to work.

When slicing would result in return of a invalid shape for a StateVector (i.e. not (n, 1)) then a Matrix view will be returned.

Note

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

flatten(order='C')[source]

Return a copy of the array collapsed into one dimension.

Parameters

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

Returns

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

Return type

ndarray

See also

ravel

Return a flattened array.

flat

A 1-D flat iterator over the array.

Examples

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

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel

equivalent function

ndarray.flat

a flat iterator on the array.

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

Bases: stonesoup.types.array.Matrix

Wrapper for numpy.ndarray for multiple State Vectors

This class returns a view to a numpy.ndarray that is in shape (num_dimensions, num_components), customising some numpy functions to ensure custom types are handled correctly. This can be initialised by a sequence type (list, tuple; not array) that contains StateVector, otherwise it’s called same as numpy.asarray().

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

Bases: stonesoup.types.array.Matrix

Covariance matrix wrapper for numpy.ndarray.

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

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

Bases: stonesoup.types.array.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: numbers.Real

Angle class.

Angle handles modulo arithmetic for adding and subtracting angles

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

Calculated the circular mean for sequence of angles

Parameters

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

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

Returns

Circular mean of angles

Return type

Angle

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

Bases: stonesoup.types.angle.Angle

Bearing angle class.

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

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

Bases: stonesoup.types.angle.Angle

Elevation angle class.

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

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

Bases: stonesoup.types.angle.Bearing

Longitude angle class.

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

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

Bases: stonesoup.types.angle.Elevation

Latitude angle class.

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

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

Bases: stonesoup.types.angle.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: stonesoup.types.angle.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: stonesoup.types.base.Type

Association type

An association between objects

Parameters

objects (Set) – Set of objects being associated

objects: Set

Set of objects being associated

class stonesoup.types.association.AssociationPair(objects: Set)[source]

Bases: stonesoup.types.association.Association

AssociationPair type

An Association representing the association of two objects

Parameters

objects (Set) – Set of objects being associated

class stonesoup.types.association.SingleTimeAssociation(objects: Set, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.association.Association

SingleTimeAssociation type

An Association representing the linking of objects at a single time

Parameters

  • objects (Set) – Set of objects being associated

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

timestamp: datetime.datetime

Timestamp of the association. Default is None.

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

Bases: stonesoup.types.association.Association

TimeRangeAssociation type

An AssociationPair representing the linking of objects over a range of times

Parameters

  • objects (Set) – Set of objects being associated

  • time_range (TimeRange, optional) – Range of times that association exists over. Default is None

time_range: stonesoup.types.time.TimeRange

Range of times that association exists over. Default is None

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

Bases: stonesoup.types.base.Type

AssociationSet type

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

Parameters

associations (Set[Association], optional) – Set of independent associations

associations: Set[stonesoup.types.association.Association]

Set of independent associations

associations_at_timestamp(timestamp)[source]

Return the associations that exist at a given timestamp

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

Parameters

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

Returns

Associations which occur at specified timestamp

Return type

set of Association

associations_including_objects(objects)[source]

Return associations that include all the given objects

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

Parameters

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

Returns

A set of objects which have been associated

Return type

set of Association

Detection Types

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

Bases: stonesoup.types.state.State

Detection type

Parameters

  • state_vector (StateVector) – State vector.

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

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

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

measurement_model: stonesoup.models.measurement.base.MeasurementModel

The measurement model used to generate the detection (the default is None)

metadata: MutableMapping

Dictionary of metadata items for Detections.

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

Bases: stonesoup.types.detection.Detection, stonesoup.types.state.GaussianState

GaussianDetection type

Parameters

  • state_vector (StateVector) – State vector.

  • covar (CovarianceMatrix) – Covariance matrix of state.

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

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

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

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

Bases: stonesoup.types.detection.Detection

Clutter type for detections classed as clutter

This is same as Detection, but can be used to identify clutter for metrics and analysis purposes.

Parameters

  • state_vector (StateVector) – State vector.

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

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

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

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

Bases: stonesoup.types.detection.Detection

TrueDetection type for detections that come from ground truth

This is same as Detection, but can be used to identify true detections for metrics and analysis purposes.

Parameters

  • state_vector (StateVector) – State vector.

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

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

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

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

groundtruth_path: stonesoup.types.groundtruth.GroundTruthPath

Ground truth path that this detection came from

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

Bases: stonesoup.types.detection.Detection

Detection type for a missed detection

This is same as Detection, but it is used in MultipleHypothesis to indicate the null hypothesis (no detections are associated with the specified track).

Parameters

  • state_vector (StateVector, optional) – State vector. Default None.

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

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

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

state_vector: stonesoup.types.array.StateVector

State vector. Default None.

Ground Truth Types

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

Bases: stonesoup.types.state.State

Ground Truth State type

Parameters

  • state_vector (StateVector) – State vector.

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

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

metadata: MutableMapping

Dictionary of metadata items for Detections.

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

Bases: stonesoup.types.state.StateMutableSequence

Ground Truth Path type

A StateMutableSequence representing a track.

Parameters

  • states (MutableSequence[GroundTruthState], optional) – List of groundtruth states to initialise path with. Default None which initialises with an empty list.

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

states: MutableSequence[stonesoup.types.groundtruth.GroundTruthState]

List of groundtruth states to initialise path with. Default None which initialises with an empty list.

id: str

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

Hypothesis Types

class stonesoup.types.hypothesis.Hypothesis[source]

Bases: stonesoup.types.base.Type

Hypothesis base type

A Hypothesis has sub-types:

‘SingleHypothesis’, which consists of a prediction for a single Track and a single Measurement that might be associated with it

‘MultipleHypothesis’, which consists of a prediction for a single Track and multiple Measurements of which one might be associated with it

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

Bases: stonesoup.types.hypothesis.Hypothesis

A hypothesis based on a single measurement.

Parameters

  • prediction (Prediction) – Predicted track state

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

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

prediction: stonesoup.types.prediction.Prediction

Predicted track state

measurement: stonesoup.types.detection.Detection

Detection used for hypothesis and updating

measurement_prediction: stonesoup.types.prediction.MeasurementPrediction

Optional track prediction in measurement space

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

Bases: stonesoup.types.hypothesis.SingleHypothesis

Distance scored hypothesis subclass.

Notes

As smaller distance is ‘better’, comparison logic is reversed i.e. smaller distance is a greater likelihood.

Parameters

  • prediction (Prediction) – Predicted track state

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

  • distance (float) – Distance between detection and prediction

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

distance: float

Distance between detection and prediction

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

Bases: stonesoup.types.hypothesis.SingleHypothesis

Single Measurement Probability scored hypothesis subclass.

Parameters

  • prediction (Prediction) – Predicted track state

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

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

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

probability: stonesoup.types.numeric.Probability

Probability that detection is true location of prediction

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

Bases: stonesoup.types.base.Type, collections.UserDict

Joint Hypothesis base type

A Joint Hypothesis consists of multiple Hypothesese, each with a single Track and a single Prediction. A Joint Hypothesis can be a ‘ProbabilityJointHypothesis’ or a ‘DistanceJointHypothesis’, with a probability or distance that is a function of the Hypothesis probabilities. Multiple Joint Hypotheses can be compared to see which is most likely to be the “correct” hypothesis.

Note: In reality, the property ‘hypotheses’ is a dictionary where the entries have the form ‘Track: Hypothesis’. However, we cannot define it this way because then Hypothesis imports Track, and Track imports Update, and Update imports Hypothesis, which is a circular import.

Parameters

hypotheses (Hypothesis) – Association hypotheses

hypotheses: stonesoup.types.hypothesis.Hypothesis

Association hypotheses

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

Bases: stonesoup.types.hypothesis.JointHypothesis

Probability-scored Joint Hypothesis subclass.

Parameters

  • hypotheses (Hypothesis) – Association hypotheses

  • probability (Probability, optional) – Probability of the Joint Hypothesis

probability: stonesoup.types.numeric.Probability

Probability of the Joint Hypothesis

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

Bases: stonesoup.types.hypothesis.JointHypothesis

Distance scored Joint Hypothesis subclass.

Notes

As smaller distance is ‘better’, comparison logic is reversed i.e. smaller distance is a greater likelihood.

Parameters

hypotheses (Hypothesis) – Association hypotheses

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

Bases: stonesoup.types.base.Type, collections.abc.Sized, collections.abc.Iterable, collections.abc.Container

Multiple Hypothesis base type

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

Parameters

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

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

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

single_hypotheses: Sequence[stonesoup.types.hypothesis.SingleHypothesis]

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

normalise: bool

Normalise probabilities of SingleHypothesis. Default is False.

total_weight: float

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

Interval Types

class stonesoup.types.interval.Interval(left: Union[int, float], right: Union[int, float])[source]

Bases: stonesoup.types.base.Type

Closed continuous interval class.

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

Parameters

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

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

left: Union[int, float]

Lower bound of interval

right: Union[int, float]

Upper bound of interval

isdisjoint(other)[source]

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

class stonesoup.types.interval.Intervals(intervals: MutableSequence[Interval] = None)[source]

Bases: stonesoup.types.base.Type

Disjoint closed continuous intervals class.

Represents a set of continuous, closed intervals of real numbers. Represented by a list of Interval types.

Parameters

intervals (MutableSequence[Interval], optional) – Container of Interval

intervals: MutableSequence[stonesoup.types.interval.Interval]

Container of Interval

static overlap(intervals)[source]

Determine whether a pair of intervals in a list overlap (are not disjoint). Returns a pair of overlapping intervals if there are any, otherwise returns None.

isdisjoint(other)[source]

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

static get_merged_intervals(intervals)[source]

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

Metric Types

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

Bases: stonesoup.types.base.Type

Metric type

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

title: str

Name of the metric

value: Any

Value of the metric

generator: Any

Generator used to create the metric

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

Bases: stonesoup.types.metric.Metric

Metric which is to be visualised as plot, value should be a pyplot figure

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

class stonesoup.types.metric.SingleTimeMetric(title: str, value: Any, generator: Any, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.metric.Metric

Metric for a specific timestamp

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

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

timestamp: datetime.datetime

Timestamp of the state. Default None.

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

Bases: stonesoup.types.metric.Metric

Metric for a range of times (e.g. for example an entire run)

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

  • time_range (TimeRange, optional) – Time range over which metric assessment will be conducted over. Default is None

time_range: stonesoup.types.time.TimeRange

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

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

Bases: stonesoup.types.metric.TimeRangeMetric, stonesoup.types.metric.PlottingMetric

Plotting metric covering a period of time

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

  • time_range (TimeRange, optional) – Time range over which metric assessment will be conducted over. Default is None

class stonesoup.types.metric.SingleTimePlottingMetric(title: str, value: Any, generator: Any, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.metric.SingleTimeMetric, stonesoup.types.metric.PlottingMetric

Plotting metric covering a specific timestamp

Parameters

  • title (str) – Name of the metric

  • value (Any) – Value of the metric

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

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

Mixture Types

class stonesoup.types.mixture.GaussianMixture(components: MutableSequence[WeightedGaussianState] = None)[source]

Bases: stonesoup.types.base.Type, collections.abc.Sized, collections.abc.Iterable, collections.abc.Container

Gaussian Mixture type

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

Parameters

components (MutableSequence[WeightedGaussianState], optional) –

The initial list of WeightedGaussianState components.

Default None which initialises with empty list.

components: MutableSequence[stonesoup.types.state.WeightedGaussianState]

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

Numeric Types

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

Bases: numbers.Real

Probability class.

Similar to a float, but value stored as natural log value internally. All operations are attempted with log values where possible, and failing that a float will be returned instead.

sqrt()[source]

Square root which can be called by NumPy

log()[source]

Log which can be called by NumPy

classmethod sum(values)[source]

Carry out LogSumExp

Particle Types

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

Bases: stonesoup.types.base.Type

Particle type

A particle type which contains a state and weight

Parameters

  • state_vector (StateVector) – State vector

  • weight (float) – Weight of particle

  • parent (Particle, optional) – Parent particle

state_vector: stonesoup.types.array.StateVector

State vector

weight: float

Weight of particle

parent: stonesoup.types.particle.Particle

Parent particle

class stonesoup.types.particle.Particles(state_vector: StateVectors = None, weight: MutableSequence[Probability] = None, parent: Particles = None, particle_list: MutableSequence[Particle] = None)[source]

Bases: stonesoup.types.base.Type

Particle type

A collection of particles. Contains a state and weight for each particle

Parameters

  • state_vector (StateVectors, optional) – State vectors of particles

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

  • parent (Particles, optional) – Parent particles

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

state_vector: stonesoup.types.array.StateVectors

State vectors of particles

weight: MutableSequence[stonesoup.types.numeric.Probability]

Weights of particles

parent: stonesoup.types.particle.Particles

Parent particles

particle_list: MutableSequence[stonesoup.types.particle.Particle]

List of Particle objects

Prediction Types

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

Bases: stonesoup.types.base.Type

Prediction type

This is the base prediction class.

Parameters

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

classmethod from_state(state: State, *args: Any, prediction_type: Optional[Union[Prediction, MeasurementPrediction]] = None, **kwargs: Any) → Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]

Return new (Measurement)Prediction instance of suitable type using existing properties

Parameters

  • state (State) – State to use existing properties from, and identify prediction type from

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

  • prediction_type (Prediction or MeasurementPrediction, optional) – Type to use for prediction, overriding one from class_mapping.

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

transition_model: stonesoup.models.transition.base.TransitionModel

The transition model used to make the prediction

class stonesoup.types.prediction.MeasurementPrediction[source]

Bases: stonesoup.types.base.Type

Prediction type

This is the base measurement prediction class.

classmethod from_state(state: State, *args: Any, prediction_type: Optional[Union[Prediction, MeasurementPrediction]] = None, **kwargs: Any) → Union[stonesoup.types.prediction.Prediction, stonesoup.types.prediction.MeasurementPrediction]

Return new (Measurement)Prediction instance of suitable type using existing properties

Parameters

  • state (State) – State to use existing properties from, and identify prediction type from

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

  • prediction_type (Prediction or MeasurementPrediction, optional) – Type to use for prediction, overriding one from class_mapping.

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

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

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.State

StatePrediction type

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

Parameters

  • state_vector (StateVector) – State vector.

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

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

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

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.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.datetime = None)[source]

Bases: stonesoup.types.prediction.MeasurementPrediction, stonesoup.types.state.State

MeasurementPrediction type

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

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

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.GaussianState

GaussianStatePrediction type

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

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

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.SqrtGaussianState

SqrtGaussianStatePrediction type

This is a Gaussian state prediction object, with the covariance held as the square root of the covariance matrix

Parameters

  • state_vector (StateVector) – State vector.

  • sqrt_covar (CovarianceMatrix) – A square root form of the Gaussian covariance matrix.

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

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

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

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.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.datetime = None, weight: Probability = 0, tag: str = None, transition_model: TransitionModel = None)[source]

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.TaggedWeightedGaussianState

TaggedWeightedGaussianStatePrediction type

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

Parameters

  • state_vector (StateVector) – State vector.

  • covar (CovarianceMatrix) – Covariance matrix of state.

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

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

  • tag (str, optional) – Unique tag of the Gaussian State.

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

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

Bases: stonesoup.types.prediction.MeasurementPrediction, stonesoup.types.state.GaussianState

GaussianMeasurementPrediction type

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

Parameters
cross_covar: stonesoup.types.array.CovarianceMatrix

The state-measurement cross covariance matrix

class stonesoup.types.prediction.ParticleStatePrediction(particles: Particles, fixed_covar: CovarianceMatrix = None, timestamp: datetime.datetime = None, transition_model: TransitionModel = None)[source]

Bases: stonesoup.types.prediction.Prediction, stonesoup.types.state.ParticleState

ParticleStatePrediction type

This is a simple Particle state prediction object.

Parameters

  • particles (Particles) – All particles.

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

  • 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.ParticleMeasurementPrediction(particles: Particles, fixed_covar: CovarianceMatrix = None, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.prediction.MeasurementPrediction, stonesoup.types.state.ParticleState

MeasurementStatePrediction type

This is a simple Particle measurement prediction object.

Parameters

  • particles (Particles) – All particles.

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

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

Sensor Data Types

class stonesoup.types.sensordata.SensorData[source]

Bases: stonesoup.types.base.Type

Sensor Data type

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

Bases: stonesoup.types.sensordata.SensorData

Image Frame type used to represent a simple image/video frame

Parameters

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

  • timestamp (datetime.datetime, optional) – An optional timestamp

pixels: numpy.ndarray

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

timestamp: datetime.datetime

An optional timestamp

State Types

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

Bases: stonesoup.types.base.Type

State type.

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

Parameters
timestamp: datetime.datetime

Timestamp of the state. Default None.

state_vector: stonesoup.types.array.StateVector

State vector.

property ndim

The number of dimensions represented by the state.

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

Bases: stonesoup.types.base.Type, collections.abc.MutableSequence

A mutable sequence for State instances

This sequence acts like a regular list object for States, as well as proxying state attributes to the last state in the sequence. This sequence can also be indexed/sliced by datetime.datetime instances.

Example

>>> t0 = datetime.datetime(2018, 1, 1, 14, 00)
>>> t1 = t0 + datetime.timedelta(minutes=1)
>>> state0 = State([[0]], t0)
>>> sequence = StateMutableSequence([state0])
>>> print(sequence.state_vector, sequence.timestamp)
[[0]] 2018-01-01 14:00:00
>>> sequence.append(State([[1]], t1))
>>> for state in sequence[t1:]:
...     print(state.state_vector, state.timestamp)
[[1]] 2018-01-01 14:01:00
Parameters

states (MutableSequence[State], optional) – The initial list of states. Default None which initialises with empty list.

states: MutableSequence[stonesoup.types.state.State]

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

insert(index, value)[source]

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

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.datetime = None)[source]

Bases: stonesoup.types.state.State

Gaussian State type

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

Parameters
covar: stonesoup.types.array.CovarianceMatrix

Covariance matrix of state.

property mean

The state mean, equivalent to state vector

property ndim

The number of dimensions represented by the state.

state_vector: stonesoup.types.array.StateVector

State vector.

timestamp: datetime.datetime

Timestamp of the state. Default None.

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

Bases: stonesoup.types.state.State

A Gaussian State type where the covariance matrix is stored in a form \(W\) such that \(P = WW^T\)

For \(P\) in general, \(W\) is not unique and the user may choose the form to their taste. No checks are undertaken to ensure that a sensible square root form has been chosen.

Parameters
sqrt_covar: stonesoup.types.array.CovarianceMatrix

A square root form of the Gaussian covariance matrix.

property mean

The state mean, equivalent to state vector

property covar

The full covariance matrix.

Returns

The covariance matrix calculated via \(W W^T\), where \(W\) is a SqrtCovarianceMatrix

Return type

CovarianceMatrix

property ndim

The number of dimensions represented by the state.

state_vector: stonesoup.types.array.StateVector

State vector.

timestamp: datetime.datetime

Timestamp of the state. Default None.

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

Bases: stonesoup.types.state.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: stonesoup.types.array.PrecisionMatrix

precision matrix of state.

property ndim

The number of dimensions represented by the state.

state_vector: stonesoup.types.array.StateVector

State vector.

timestamp: datetime.datetime

Timestamp of the state. Default None.

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

Bases: stonesoup.types.state.GaussianState

Weighted Gaussian State Type

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

Parameters
weight: stonesoup.types.numeric.Probability

Weight of the Gaussian State.

property gaussian_state

The Gaussian state.

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

Returns a WeightedGaussianState instance based on the gaussian_state.

Parameters
Returns

Instance of WeightedGaussianState.

Return type

WeightedGaussianState

covar: stonesoup.types.array.CovarianceMatrix

Covariance matrix of state.

property mean

The state mean, equivalent to state vector

property ndim

The number of dimensions represented by the state.

state_vector: stonesoup.types.array.StateVector

State vector.

timestamp: datetime.datetime

Timestamp of the state. Default None.

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

Bases: stonesoup.types.state.WeightedGaussianState

Tagged Weighted Gaussian State Type

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

Parameters

  • state_vector (StateVector) – State vector.

  • covar (CovarianceMatrix) – Covariance matrix of state.

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

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

  • tag (str, optional) – Unique tag of the Gaussian State.

tag: str

Unique tag of the Gaussian State.

covar: stonesoup.types.array.CovarianceMatrix

Covariance matrix of state.

classmethod from_gaussian_state(gaussian_state, *args, copy=True, **kwargs)

Returns a WeightedGaussianState instance based on the gaussian_state.

Parameters
Returns

Instance of WeightedGaussianState.

Return type

WeightedGaussianState

property gaussian_state

The Gaussian state.

property mean

The state mean, equivalent to state vector

property ndim

The number of dimensions represented by the state.

state_vector: stonesoup.types.array.StateVector

State vector.

timestamp: datetime.datetime

Timestamp of the state. Default None.

weight: stonesoup.types.numeric.Probability

Weight of the Gaussian State.

class stonesoup.types.state.ParticleState(particles: Particles, fixed_covar: CovarianceMatrix = None, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.base.Type

Particle State type

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

Parameters

  • particles (Particles) – All particles.

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

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

particles: stonesoup.types.particle.Particles

All particles.

fixed_covar: stonesoup.types.array.CovarianceMatrix

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

timestamp: datetime.datetime

Timestamp of the state. Default None.

property mean

The state mean, equivalent to state vector

property state_vector

The mean value of the particle states

OrbitalState Types

class stonesoup.types.orbitalstate.CoordinateSystem(value)[source]

Bases: enum.Enum

Enumerates the allowable coordinate systems. See OrbitalState help for full explanation of what each of the elements does.

class stonesoup.types.orbitalstate.OrbitalState(state_vector: StateVector, timestamp: datetime.datetime = None, coordinates: CoordinateSystem = CoordinateSystem.CARTESIAN, grav_parameter: float = 398600441800000.0, metadata: Mapping[Any, Any] = None)[source]

Bases: stonesoup.types.state.State

The orbital state base type. This is the building block of Stone Soup’s orbital inference routines and follows the principle that you shouldn’t have to care which parameterisation you use. The class stores relevant information internally and undertakes whatever conversions are necessary.

The state_vector is held as \([\mathbf{r}, \dot{\mathbf{r}}]\), the “Orbital State Vector” (as traditionally understood in orbital mechanics), where \(\mathbf{r}\) is the (3D) Cartesian position in the primary-centered inertial frame, while \(\dot{\mathbf{r}}\) is the corresponding velocity vector. All other parameters are accessed via functions. Formulae for conversions are generally found in, or derived from 1.

The gravitational parameter \(\mu = GM\) can be defined. If left undefined it defaults to that of the Earth, \(3.986004418 \, (\pm \, 0.000000008) \times 10^{14} \mathrm{m}^3 \mathrm{s}^{−2}\)

The object is constructed from the input vector \(X_{t_{0}}\) at epoch State.timestamp, \(t_0\). The coordinates of \(X_{t_{0}}\) are Cartesian Earth-Centered Inertial (ECI) [m] by default, but may be selected via the “coordinates” keyword by passing a CoordinateSystem object, or an appropriate string. Allowable coordinate systems are,

coordinates = “Cartesian”, the input state vector is

\[X_{t_0} = [r_x, r_y, r_z, \dot{r}_x, \dot{r}_y, \dot{r}_z]^{T}\]

where \(r_x, r_y, r_z\) are the Cartesian position coordinates in the Primary-Centered Inertial frame and \(\dot{r}_x, \dot{r}_y, \dot{r}_z\) are the corresponding velocity coordinates.

coordinates = “Keplerian” (Keplarian elements), construct using input state vector:

\[\begin{split}X_{t_0} = [e, a, i, \Omega, \omega, \theta]^{T} \\\end{split}\]

where: \(e\) is the orbital eccentricity (unitless), \(a\) the semi-major axis ([length]), \(i\) the inclination (radian), \(\Omega\) is the longitude of the ascending node (radian), \(\omega\) the argument of periapsis (radian), and \(\theta\) the true anomaly (radian)

coordinates = “TLE” (Two-Line Elements 2), initiates using input vector

\[X_{t_0} = [i, \Omega, e, \omega, M_0, n]^{T}\]

where \(i\) the inclination (radian), \(\Omega\) is the longitude of the ascending node (radian), \(e\) is the orbital eccentricity (unitless), \(\omega\) the argument of perigee (radian), \(M_0\) the mean anomaly (radian) and \(n\) the mean motion (radian / [time]).

This can also be constructed by passing state_vector=None and using the metadata. In this instance the metadata must conform to the TLE standard format 2 and be included in the metadata dictionary as ‘line_1’ and ‘line_2’.

coordinates = “Equinoctial” (equinoctial elements 3),

\[\begin{split}X_{t_0} = [a, h, k, p, q, \lambda]^{T} \\\end{split}\]

where \(a\) the semi-major axis ([length]), \(h\) is the horizontal component of the eccentricity (unitless), \(k\) is the vertical component of the eccentricity (unitless), \(q\) is the horizontal component of the inclination (radian), \(k\) is the vertical component of the inclination (radian), \(\lambda\) is the mean longitude (radian)

References

1

Curtis, H.D. 2010, Orbital Mechanics for Engineering Students (3rd Ed), Elsevier Aerospace Engineering Series

2(1,2,3)

NASA, Definition of Two-line Element Set Coordinate System, [spaceflight.nasa.gov]( https://spaceflight.nasa.gov/realdata/sightings/SSapplications/Post/JavaSSOP/ SSOP_Help/tle_def.html)

3(1,2)

Broucke, R. A. & Cefola, P. J. 1972, Celestial Mechanics, Volume 5, Issue 3, pp. 303-310

Parameters

  • state_vector (StateVector) – State vector.

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

  • coordinates (CoordinateSystem, optional) – The parameterisation used on initiation. Acceptable values are ‘CARTESIAN’ (default), ‘KEPLERIAN’, ‘TLE’, or ‘EQUINOCTIAL’. All other inputs will return errors. Will accept string inputs.

  • grav_parameter (float, optional) – Standard gravitational parameter \(\mu = G M\). The default is \(3.986004418 \times 10^{14} \,\) \(\mathrm{m}^3 \mathrm{s}^{-2}\).

  • metadata (Mapping[Any, Any], optional) – Dictionary containing metadata about orbit

coordinates: stonesoup.types.orbitalstate.CoordinateSystem

The parameterisation used on initiation. Acceptable values are ‘CARTESIAN’ (default), ‘KEPLERIAN’, ‘TLE’, or ‘EQUINOCTIAL’. All other inputs will return errors. Will accept string inputs.

grav_parameter: float

Standard gravitational parameter \(\mu = G M\). The default is \(3.986004418 \times 10^{14} \,\) \(\mathrm{m}^3 \mathrm{s}^{-2}\).

metadata: Mapping[Any, Any]

Dictionary containing metadata about orbit

property specific_angular_momentum

The specific angular momentum, \(\mathbf{h}\)

property cartesian_state_vector

The state vector \(X_{t_0} = [r_x, r_y, r_z, \dot{r}_x, \dot{r}_y, \dot{r}_z]^{T}\) in ‘Primary-Centred’ Inertial coordinates, equivalent to ECI in the case of the Earth

property epoch

The epoch, or state timestamp

property range

The distance to object (from gravitational centre of primary)

property speed

The current instantaneous speed (scalar)

property eccentricity

The orbital eccentricity, \(e \; (0 \le e \le 1)\)

Note

This version of the calculation uses a form dependent only on scalars

property semimajor_axis

The orbital semi-major axis

property inclination

Orbital inclination, \(i \; (0 \le i < \pi)\), [rad]

property longitude_ascending_node

math:Omega ; (0 leq Omega < 2pi)

Type

The longitude (or right ascension) of ascending node,

property argument_periapsis

The argument of periapsis, \(\omega \; (0 \le \omega < 2\pi)\) in radians

property true_anomaly

The true anomaly, \(\theta \; (0 \le \theta < 2\pi)\) in radians

property eccentric_anomaly

The eccentric anomaly, \(E \; (0 \le E < 2\pi)\) in radians

Note

This computes the quantity exactly via the Keplerian eccentricity and true anomaly rather than via the mean anomaly using an iterative procedure.

property mean_anomaly

Mean anomaly, \(M \; (0 \le M < 2\pi\)), in radians

Note

Uses the eccentric anomaly and Kepler’s equation to get mean anomaly from true anomaly and eccentricity.

property period

Orbital period, \(T\) ([time])

property mean_motion

The mean motion, \(\frac{2 \pi}{T}\), where \(T\) is the period, (rad / [time])

property mag_specific_angular_momentum

The magnitude of the specific angular momentum, \(h\)

property specific_orbital_energy

Specific orbital energy (\(\frac{-GM}{2a}\))

property equinoctial_h

The horizontal component of the eccentricity in equinoctial coordinates is \(h = e \sin (\omega + \Omega)\)

property equinoctial_k

The vertical component of the eccentricity in equinoctial coordinates is \(k = e \cos (\omega + \Omega)\)

property equinoctial_p

The horizontal component of the inclination in equinoctial coordinates is \(p = \tan (i/2) \sin \Omega\)

property equinoctial_q

The vertical component of the inclination in equinoctial coordinates is \(q = \tan (i/2) \cos \Omega\)

property mean_longitude

The mean longitude, defined as \(\lambda = M_0 + \omega + \Omega\) (rad)

property keplerian_elements

The vector of Keplerian elements \(X = [e, a, i, \Omega, \omega, \theta]^{T}\) where \(e\) is the orbital eccentricity (unitless), \(a\) the semi-major axis ([length]), \(i\) the inclination (radian), \(\Omega\) is the longitude of the ascending node (radian), \(\omega\) the argument of periapsis (radian), and \(\theta\) the true anomaly (radian)

property two_line_element

The Two-Line Element vector \(X = [i, \Omega, e, \omega, M_0, n]^{T}\) where \(i\) the inclination (radian) \(\Omega\) is the longitude of the ascending node (radian), \(e\) is the orbital eccentricity (unitless), \(\omega\) the argument of periapsis (radian), \(M_0\) the mean anomaly (radian) \(n\) the mean motion (rad/[time]) 2

property equinoctial_elements

The equinoctial elements, \(X = [a, h, k, p, q, \lambda]^{T}\) where \(a\) the semi-major axis ([length]), \(h\) and \(k\) are the horizontal and vertical components of the eccentricity respectively (unitless), \(p\) and \(q\) are the horizontal and vertical components of the inclination respectively (radian) and \(\lambda\) is the mean longitude (radian) 3

class stonesoup.types.orbitalstate.GaussianOrbitalState(state_vector: StateVector, covar: CovarianceMatrix, timestamp: datetime.datetime = None, coordinates: CoordinateSystem = CoordinateSystem.CARTESIAN, grav_parameter: float = 398600441800000.0, metadata: Mapping[Any, Any] = None)[source]

Bases: stonesoup.types.state.GaussianState, stonesoup.types.orbitalstate.OrbitalState

An Orbital state for use in Kalman filters (and perhaps elsewhere). Inherits from GaussianState so has covariance matrix. As no checks on the validity of the covariance matrix are made, care should be exercised in its use. The propagator will generally require a particular coordinate reference which must be understood.

All methods provided by OrbitalState are available.

Parameters

  • state_vector (StateVector) – State vector.

  • covar (CovarianceMatrix) – Covariance matrix of state.

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

  • coordinates (CoordinateSystem, optional) – The parameterisation used on initiation. Acceptable values are ‘CARTESIAN’ (default), ‘KEPLERIAN’, ‘TLE’, or ‘EQUINOCTIAL’. All other inputs will return errors. Will accept string inputs.

  • grav_parameter (float, optional) – Standard gravitational parameter \(\mu = G M\). The default is \(3.986004418 \times 10^{14} \,\) \(\mathrm{m}^3 \mathrm{s}^{-2}\).

  • metadata (Mapping[Any, Any], optional) – Dictionary containing metadata about orbit

Time Types

class stonesoup.types.time.TimeRange(start_timestamp: datetime.datetime, end_timestamp: datetime.datetime)[source]

Bases: stonesoup.types.base.Type

TimeRange type

An object representing a time range between two timestamps.

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

Example

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

Start of the time range

end_timestamp: datetime.datetime

End of the time range

property duration

Duration of the time range

Track Types

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

Bases: stonesoup.types.state.StateMutableSequence

Track type

A StateMutableSequence representing a track.

Notes:

Any manual modifications to metadata or metadatas will be overwritten if a state is inserted at a point prior to where the modifications are made. For example, inserting a state at the start of states will result in a metadatas update that will update all subsequent metadata values, resulting in manual metadata modifications being lost.

Parameters

  • states (MutableSequence[State], optional) – The initial states of the track. Default None which initialises with empty list.

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

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

states: MutableSequence[stonesoup.types.state.State]

The initial states of the track. Default None which initialises with empty list.

init_metadata: MutableMapping

Initial dictionary of metadata items for track. Default None which initialises track metadata as an empty dictionary.

id: str

The unique track ID

insert(index, value)[source]

Insert value at index of states.

Parameters

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

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

append(value)[source]

Add value at end of states.

Parameters

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

property metadata

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

Update Types

class stonesoup.types.update.Update(hypothesis: Hypothesis)[source]

Bases: stonesoup.types.base.Type

Update type

The base update class. Updates are returned by :class:’~.Updater’ objects and contain the information that was used to perform the updating

Parameters

hypothesis (Hypothesis) – Hypothesis used for updating

hypothesis: stonesoup.types.hypothesis.Hypothesis

Hypothesis used for updating

classmethod from_state(state: State, *args: Any, update_type: Optional[Update] = None, **kwargs: Any) → stonesoup.types.update.Update

Return new Update instance of suitable type using existing properties

Parameters

  • state (State) – State to use existing properties from, and identify update type from

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

  • update_type (Update, optional) – Type to use for update, overriding one from class_mapping.

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

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

Bases: stonesoup.types.update.Update, stonesoup.types.state.State

StateUpdate type

Most simple state update type, where everything only has time and a state vector. Requires a prior state that was updated, and the hypothesis used to update the prior.

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

Bases: stonesoup.types.update.Update, stonesoup.types.state.GaussianState

GaussianStateUpdate type

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

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

Bases: stonesoup.types.update.Update, stonesoup.types.state.SqrtGaussianState

SqrtGaussianStateUpdate type

This is equivalent to a Gaussian state update object, but with the covariance of the Gaussian distribution stored in matrix square root form.

Parameters

  • state_vector (StateVector) – State vector.

  • sqrt_covar (CovarianceMatrix) – A square root form of the Gaussian covariance matrix.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

class stonesoup.types.update.GaussianMixtureUpdate(hypothesis: Hypothesis, components: MutableSequence[WeightedGaussianState] = None)[source]

Bases: stonesoup.types.update.Update, stonesoup.types.mixture.GaussianMixture

GaussianMixtureUpdate type

This is a Gaussian mixture update object, which, as the name suggests, is described by a Gaussian mixture.

Parameters

  • hypothesis (Hypothesis) – Hypothesis used for updating

  • components (MutableSequence[WeightedGaussianState], optional) –

    The initial list of WeightedGaussianState components.

    Default None which initialises with empty list.

class stonesoup.types.update.ParticleStateUpdate(particles: Particles, hypothesis: Hypothesis, fixed_covar: CovarianceMatrix = None, timestamp: datetime.datetime = None)[source]

Bases: stonesoup.types.update.Update, stonesoup.types.state.ParticleState

ParticleStateUpdate type

This is a simple Particle state update object.

Parameters

  • particles (Particles) – All particles.

  • hypothesis (Hypothesis) – Hypothesis used for updating

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

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

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

Bases: stonesoup.types.update.Update, stonesoup.types.state.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