# Measures¶

class stonesoup.measures.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 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)[source]
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)[source]

Compute the distance between a pair of State objects

Parameters:
Returns:

distance measure between a pair of input State objects

Return type:

float

class stonesoup.measures.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 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)[source]

Calculate the Euclidean distance between a pair of state vectors

Parameters:
Returns:

Euclidean distance between two input State

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)
class stonesoup.measures.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 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)[source]

Calculate the weighted Euclidean distance between a pair of state objects

Parameters:
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.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. 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)[source]
__getstate__()[source]

Helper for pickle.

__call__(state1, state2)[source]

Calculate the Squared Mahalanobis distance between a pair of state objects

Parameters:
Returns:

Squared Mahalanobis distance between a pair of input State objects

Return type:

float

class stonesoup.measures.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. 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)[source]

Calculate the Mahalanobis distance between a pair of state objects

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

Calculate the Squared Hellinger distance multivariate normal distributions

Parameters:
Returns:

Squared Hellinger distance between two input GaussianState

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)
class stonesoup.measures.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 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)[source]

Calculate the Hellinger distance between 2 state elements

Parameters:
Returns:

Hellinger distance between two input GaussianState

Return type:

float

__init__(mapping: ndarray = None, mapping2: ndarray = None)
class stonesoup.measures.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 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)[source]

Compute the distance between a pair of State objects

Parameters:
Returns:

distance measure between a pair of input State objects

Return type:

float