Measures
- class stonesoup.measures.base.BaseMeasure[source]
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 [source]
Compute the distance between a pair of objects
- Parameters:
item1 (Any) –
item2 (Any) –
- Returns:
distance measure between a pair of input objects
- Return type:
- __init__()
- class stonesoup.measures.base.TrackMeasure[source]
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 [source]
Compute the distance between a pair of
Track
objects.
- __init__()
- class stonesoup.measures.base.SetComparisonMeasure[source]
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 thanobj1 == obj2
).- __call__(collection_1: Collection, collection_2: Collection) float [source]
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:
- __init__()
State Measures
- class stonesoup.measures.state.Measure(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 measuremapping2 (
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
- class stonesoup.measures.state.Euclidean(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 measuremapping2 (
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
- class stonesoup.measures.state.EuclideanWeighted(weighting: ndarray, mapping: ndarray = None, mapping2: ndarray = None)[source]
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 calculationmapping (
numpy.ndarray
, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measuremapping2 (
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
- class stonesoup.measures.state.SquaredMahalanobis(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)[source]
Squared Mahalanobis distance measure
This measure returns the Squared Mahalanobis distance between a pair of
State
objects taking into account the distribution (i.e. theCovarianceMatrix
) of the firstState
objectThe 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 measuremapping2 (
numpy.ndarray
, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mappingstate_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.
- class stonesoup.measures.state.Mahalanobis(mapping: ndarray = None, mapping2: ndarray = None, state_covar_inv_cache_size: int = 128)[source]
Mahalanobis distance measure
This measure returns the Mahalanobis distance between a pair of
State
objects taking into account the distribution (i.e. theCovarianceMatrix
) of the firstState
objectThe 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 measuremapping2 (
numpy.ndarray
, optional) – A second mapping for when the states being compared exist in different parameter spaces. Defaults to the same as the first mappingstate_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.
- class stonesoup.measures.state.SquaredGaussianHellinger(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 measuremapping2 (
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)[source]
Calculate the Squared Hellinger distance multivariate normal distributions
- Parameters:
state1 (
GaussianState
) –state2 (
GaussianState
) –
- Returns:
Squared Hellinger distance between two input
GaussianState
- Return type:
- class stonesoup.measures.state.GaussianHellinger(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 measuremapping2 (
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)[source]
Calculate the Hellinger distance between 2 state elements
- Parameters:
state1 (
GaussianState
) –state2 (
GaussianState
) –
- Returns:
Hellinger distance between two input
GaussianState
- Return type:
- class stonesoup.measures.state.ObservationAccuracy(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 measuremapping2 (
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
- class stonesoup.measures.state.KLDivergence(mapping: ndarray = None, mapping2: ndarray = None)[source]
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 acceptsParticleState
.References
- Parameters:
mapping (
numpy.ndarray
, optional) – Mapping array which specifies which elements within the state vectors are to be assessed as part of the measuremapping2 (
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)[source]
Computes the Kullback–Leibler divergence from
state1
tostate2
- Parameters:
state1 (
ParticleState
) –state2 (
ParticleState
) –
- Returns:
Kullback–Leibler divergence from
state1
tostate2
- Return type:
Multi Measures
- class stonesoup.measures.multi.MultipleMeasure[source]
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] [source]
Compute the distance between a pair of objects
- Parameters:
item1 (Any) –
item2 (Any) –
- Returns:
distance measure between a pair of input objects
- Return type:
- __init__()
- class stonesoup.measures.multi.StateSequenceMeasure(state_measure: Measure)[source]
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.
- __call__(state_sequence_1: StateMutableSequence, state_sequence_2: StateMutableSequence, times_to_measure: Sequence[datetime] = None) List[float] [source]
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]
- class stonesoup.measures.multi.RecentStateSequenceMeasure(state_measure: Measure, n_states_to_compare: int)[source]
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.
- __call__(state_sequence_1: StateMutableSequence, state_sequence_2: StateMutableSequence) List[float] [source]
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:
- class stonesoup.measures.multi.MeanMeasure(measure: MultipleMeasure)[source]
This class converts multiple measures into one mean average measure.
- Parameters:
measure (
MultipleMeasure
) –
- __call__(*args, **kwargs) float | None [source]
Compute the distance between a pair of objects
- Parameters:
item1 (Any) –
item2 (Any) –
- Returns:
distance measure between a pair of input objects
- Return type:
- __init__(measure: MultipleMeasure)