Measures

class stonesoup.measures.base.BaseMeasure

Abstract Measure Base Type

A measure provides a means to assess the separation between two objects item1 and item2.

abstract __call__(item1: Any, item2: Any) → float

Compute the distance between a pair of objects

Parameters:

• item1 (Any)

• item2 (Any)

Returns:

distance measure between a pair of input objects

Return type:

float

__init__()

class stonesoup.measures.base.TrackMeasure

TrackMeasure base class.

A measure provides a means to assess the separation between two Track objects track_1 and track_2. It should return a float value of the distance measure between the two tracks.

abstract __call__(track_1: Track, track_2: Track) → float

Compute the distance between a pair of Track objects.

__init__()

class stonesoup.measures.base.SetComparisonMeasure

This class measures how many items are present in both collections. The type of the collections is ignored and duplicate items are ignored.

• The measure output is between 0 and 1 (inclusive).

• An output of 1 is for both collections to contain the same items.

• An output of 0 is when there are zero items in common between the two sets.

This class compares an object/item’s identity. It doesn’t directly compare objects (obj1 is obj2 rather than obj1 == obj2).

__call__(collection_1: Collection, collection_2: Collection) → float

The measure is calculated by finding the number of items in common between the two collections and divides it by the total number of unique items in the combined collection.

Parameters:

• collection_1

• collection_2

Returns:

distance measure between a pair of input objects.

Return type:

float

__init__()

State Measures

class stonesoup.measures.state.Measure(mapping: ndarray = None, mapping2: ndarray = None)

Measure base type

A measure provides a means to assess the separation between two State objects state1 and state2.

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

mapping: ndarray

Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

__init__(mapping: ndarray = None, mapping2: ndarray = None)

mapping2: ndarray

A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

abstract __call__(state1, state2)

Compute the distance between a pair of State objects

Parameters:

• state1 (State)

• state2 (State)

Returns:

distance measure between a pair of input State objects

Return type:

float

class stonesoup.measures.state.Euclidean(mapping: ndarray = None, mapping2: ndarray = None)

Euclidean distance measure

This measure returns the Euclidean distance between a pair of State objects.

The Euclidean distance between a pair of state vectors \(u\) and \(v\) is defined as:

\[\sqrt{\sum_{i=1}^{N}{(u_i - v_i)^2}}\]

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

__call__(state1, state2)

Calculate the Euclidean distance between a pair of state vectors

Parameters:

• state1 (State)

• state2 (State)

Returns:

Euclidean distance between two input State

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)

class stonesoup.measures.state.EuclideanWeighted(weighting: ndarray, mapping: ndarray = None, mapping2: ndarray = None)

Weighted Euclidean distance measure

This measure returns the Euclidean distance between a pair of State objects, taking into account a specified weighting.

The Weighted Euclidean distance between a pair of state vectors \(u\) and \(v\) with weighting \(w\) is defined as:

\[\sqrt{\sum_{i=1}^{N}{w_i|(u_i - v_i)^2}}\]

Note

The EuclideanWeighted object has a property called weighting, which allows the method to be called on different pairs of states. If different weightings need to be used then multiple Measure objects must be created with the specific weighting

Parameters:

• weighting (numpy.ndarray) – Weighting vector for the Euclidean calculation

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

weighting: ndarray

Weighting vector for the Euclidean calculation

__call__(state1, state2)

Calculate the weighted Euclidean distance between a pair of state objects

Parameters:

• state1 (State)

• state2 (State)

Returns:

dist – Weighted Euclidean distance between two input State objects

Return type:

float

__init__(weighting: ndarray, mapping: ndarray = None, mapping2: ndarray = None)

class stonesoup.measures.state.SquaredMahalanobis(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)

Squared Mahalanobis distance measure

This measure returns the Squared Mahalanobis distance between a pair of State objects taking into account the distribution (i.e. the CovarianceMatrix) of the first State object

The Squared Mahalanobis distance between a distribution with mean \(\mu\) and Covariance matrix \(\Sigma\) and a point \(x\) is defined as:

\[( {\mu - x}) \Sigma^{-1} ({\mu - x}^T )\]

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

• state_covar_inv_cache_size (int, optional) – Number of covariance matrix inversions to cache. Setting to 0 will disable the cache, whilst setting to None will not limit the size of the cache. Default is 128.

state_covar_inv_cache_size: int

Number of covariance matrix inversions to cache. Setting to 0 will disable the cache, whilst setting to None will not limit the size of the cache. Default is 128.

__init__(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)

__getstate__()

Helper for pickle.

__call__(state1, state2)

Calculate the Squared Mahalanobis distance between a pair of state objects

Parameters:

• state1 (State)

• state2 (State)

Returns:

Squared Mahalanobis distance between a pair of input State objects

Return type:

float

class stonesoup.measures.state.Mahalanobis(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)

Mahalanobis distance measure

This measure returns the Mahalanobis distance between a pair of State objects taking into account the distribution (i.e. the CovarianceMatrix) of the first State object

The Mahalanobis distance between a distribution with mean \(\mu\) and Covariance matrix \(\Sigma\) and a point \(x\) is defined as:

\[\sqrt{( {\mu - x}) \Sigma^{-1} ({\mu - x}^T )}\]

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

• state_covar_inv_cache_size (int, optional) – Number of covariance matrix inversions to cache. Setting to 0 will disable the cache, whilst setting to None will not limit the size of the cache. Default is 128.

__call__(state1, state2)

Calculate the Mahalanobis distance between a pair of state objects

Parameters:

• state1 (State)

• state2 (State)

Returns:

Mahalanobis distance between a pair of input State objects

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)

class stonesoup.measures.state.SquaredGaussianHellinger(mapping: ndarray = None, mapping2: ndarray = None)

Squared Gaussian Hellinger distance measure

This measure returns the Squared Hellinger distance between a pair of GaussianState multivariate objects.

The Squared Hellinger distance between two multivariate normal distributions \(P \sim N(\mu_1,\Sigma_1)\) and \(Q \sim N(\mu_2,\Sigma_2)\) is defined as:

\[\begin{split}H^{2}(P, Q) &= 1 - {\frac{\det(\Sigma_1)^{\frac{1}{4}}\det(\Sigma_2)^{\frac{1}{4}}} {\det\left(\frac{\Sigma_1+\Sigma_2}{2}\right)^{\frac{1}{2}}}} \exp\left(-\frac{1}{8}(\mu_1-\mu_2)^T \left(\frac{\Sigma_1+\Sigma_2}{2}\right)^{-1}(\mu_1-\mu_2)\right)\\ &\equiv 1 - \sqrt{\frac{\det(\Sigma_1)^{\frac{1}{2}}\det(\Sigma_2)^{\frac{1}{2}}} {\det\left(\frac{\Sigma_1+\Sigma_2}{2}\right)}} \exp\left(-\frac{1}{8}(\mu_1-\mu_2)^T \left(\frac{\Sigma_1+\Sigma_2}{2}\right)^{-1}(\mu_1-\mu_2)\right)\end{split}\]

Note

This distance is bounded between 0 and 1

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

__call__(state1, state2)

Calculate the Squared Hellinger distance multivariate normal distributions

Parameters:

• state1 (GaussianState)

• state2 (GaussianState)

Returns:

Squared Hellinger distance between two input GaussianState

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)

class stonesoup.measures.state.GaussianHellinger(mapping: ndarray = None, mapping2: ndarray = None)

Gaussian Hellinger distance measure

This measure returns the Hellinger distance between a pair of GaussianState multivariate objects.

The Hellinger distance between two multivariate normal distributions \(P \sim N(\mu_1,\Sigma_1)\) and \(Q \sim N(\mu_2,\Sigma_2)\) is defined as:

\[H(P,Q) = \sqrt{1 - {\frac{\det(\Sigma_1)^{\frac{1}{4}}\det(\Sigma_2)^{\frac{1}{4}}} {\det\left(\frac{\Sigma_1+\Sigma_2}{2}\right)^{\frac{1}{2}}}} \exp\left(-\frac{1}{8}(\mu_1-\mu_2)^T \left(\frac{\Sigma_1+\Sigma_2}{2}\right)^{-1}(\mu_1-\mu_2)\right)}\]

Note

This distance is bounded between 0 and 1

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

__call__(state1, state2)

Calculate the Hellinger distance between 2 state elements

Parameters:

• state1 (GaussianState)

• state2 (GaussianState)

Returns:

Hellinger distance between two input GaussianState

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)

class stonesoup.measures.state.ObservationAccuracy(mapping: ndarray = None, mapping2: ndarray = None)

Accuracy measure

This measure evaluates the accuracy of a categorical distribution with respect to another.

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

__call__(state1, state2)

Compute the distance between a pair of State objects

Parameters:

• state1 (State)

• state2 (State)

Returns:

distance measure between a pair of input State objects

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)

class stonesoup.measures.state.KLDivergence(mapping: ndarray = None, mapping2: ndarray = None)

Kullback-Leibler divergence between two distributions

Kullback-Leibler divergence, also referred to as relative entropy, is a statistical distance. It describes how a probability distribution is different from another. The expression for Kullback-Leibler divergence is given by [1]

\[D_{KL}(P\Vert Q) = \sum_x P(x)\log \frac{P(x)}{Q(x)},\]

where \(P(x)\) is the first distribution, or state1 and \(Q(x)\) is the second distribution or, state2. It is worth noting that Kullback-Leibler divergence is not symmetric under interchange of \(P(x)\) and \(Q(x)\). The implementation here uses natural log meaning the returned divergence has units in nats. This implementation assumes a discrete probability space and currently only accepts ParticleState.

References

[1]

MacKay, David J. C. 2003. Information Theory, Inference and Learning Algorithms, 1st Ed. Cambridge University Press,

Parameters:

• mapping (numpy.ndarray, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measure

• mapping2 (numpy.ndarray, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mapping

__init__(mapping: ndarray = None, mapping2: ndarray = None)

__call__(state1, state2)

Computes the Kullback–Leibler divergence from state1 to state2

Parameters:

• state1 (ParticleState)

• state2 (ParticleState)

Returns:

Kullback–Leibler divergence from state1 to state2

Return type:

float

Multi Measures

class stonesoup.measures.multi.MultipleMeasure

MultipleMeasure base class.

This measure produces a list of float values instead of a singular float value. This can be used when comparing objects that contain multiple other objects.

abstract __call__(item1, item2) → list[float]

Compute the distance between a pair of objects

Parameters:

• item1 (Any)

• item2 (Any)

Returns:

distance measure between a pair of input objects

Return type:

float

__init__()

class stonesoup.measures.multi.StateSequenceMeasure(state_measure: Measure)

Applies a state measure to each state in the state sequence with matching times.

Parameters:

state_measure (Measure) – The measure used to compare individual states.

state_measure: Measure

The measure used to compare individual states.

__call__(state_sequence_1: StateMutableSequence, state_sequence_2: StateMutableSequence, times_to_measure: Sequence[datetime] = None) → list[float]

Compare the states from each state sequence for every time in times_to_measure.

If times_to_measure is None. Find all times that both state sequences have in common.

Parameters:

• state_sequence_1 (StateSequenceMeasure) – a state sequence to compare against state_sequence_2.

• state_sequence_2 (StateSequenceMeasure) – a state sequence to compare against state_sequence_1.

• times_to_measure (Sequence of datetime) – Calculate the state measure for states in the state sequences at these times. Default value is None. If None, times_to_measure is calculated as all the times that both state sequences have in common.

Returns:

a list of distance measures between a states in the state sequence inputs.

Return type:

list[float]

__init__(state_measure: Measure)

class stonesoup.measures.multi.RecentStateSequenceMeasure(state_measure: Measure, n_states_to_compare: int)

Applies a state measure to each state in the state sequence with for the most recent n matching times. It will return less than n_states_to_compare values if there are less matching times.

Parameters:

• state_measure (Measure) – The measure used to compare individual states.

• n_states_to_compare (int) – Maximum number of states to be compared.

state_measure: Measure

The measure used to compare individual states.

n_states_to_compare: int

Maximum number of states to be compared.

__call__(state_sequence_1: StateMutableSequence, state_sequence_2: StateMutableSequence) → list[float]

Compare the states from each state sequence for the most recent n_states_to_compare times.

Parameters:

• state_sequence_1 (StateSequenceMeasure) – a state sequence to compare against state_sequence_2.

• state_sequence_2 (StateSequenceMeasure) – a state sequence to compare against state_sequence_1.

Returns:

a list of distance measures between a states in the state sequence inputs. These are returned in ascending state time order.

Return type:

float

__init__(state_measure: Measure, n_states_to_compare: int)

class stonesoup.measures.multi.MeanMeasure(measure: MultipleMeasure)

This class converts multiple measures into one mean average measure.

Parameters:

measure (MultipleMeasure)

__call__(*args, **kwargs) → float | None

Compute the distance between a pair of objects

Parameters:

• item1 (Any)

• item2 (Any)

Returns:

distance measure between a pair of input objects

Return type:

float

__init__(measure: MultipleMeasure)