# Measures¶

class stonesoup.measures.Measure(mapping: numpy.ndarray = None, mapping2: numpy.ndarray = None)[source]

Measure base type

A measure provides a means to assess the seperation 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: numpy.ndarray

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

__init__(mapping: numpy.ndarray = None, mapping2: numpy.ndarray = None)[source]

Initialize self. See help(type(self)) for accurate signature.

mapping2: numpy.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: numpy.ndarray = None, mapping2: numpy.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

class stonesoup.measures.EuclideanWeighted(weighting: numpy.ndarray, mapping: numpy.ndarray = None, mapping2: numpy.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: numpy.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

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

__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

class stonesoup.measures.SquaredGaussianHellinger(mapping: numpy.ndarray = None, mapping2: numpy.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

class stonesoup.measures.GaussianHellinger(mapping: numpy.ndarray = None, mapping2: numpy.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