mlpack  master
MahalanobisDistance< TakeRoot > Class Template Reference

The Mahalanobis distance, which is essentially a stretched Euclidean distance. More...

Public Member Functions

 MahalanobisDistance ()
 Initialize the Mahalanobis distance with the empty matrix as covariance. More...

 
 MahalanobisDistance (const size_t dimensionality)
 Initialize the Mahalanobis distance with the identity matrix of the given dimensionality. More...

 
 MahalanobisDistance (const arma::mat &covariance)
 Initialize the Mahalanobis distance with the given covariance matrix. More...

 
const arma::mat & Covariance () const
 Access the covariance matrix. More...

 
arma::mat & Covariance ()
 Modify the covariance matrix. More...

 
template
<
typename
VecTypeA
,
typename
VecTypeB
>
double Evaluate (const VecTypeA &a, const VecTypeB &b)
 Evaluate the distance between the two given points using this Mahalanobis distance. More...

 
template
<
typename
Archive
>
void serialize (Archive &ar, const unsigned int version)
 Serialize the Mahalanobis distance. More...

 

Detailed Description


template<bool TakeRoot = true>
class mlpack::metric::MahalanobisDistance< TakeRoot >

The Mahalanobis distance, which is essentially a stretched Euclidean distance.

Given a square covariance matrix $ Q $ of size $ d $ x $ d $, where $ d $ is the dimensionality of the points it will be evaluating, and given two vectors $ x $ and $ y $ also of dimensionality $ d $,

\[ d(x, y) = \sqrt{(x - y)^T Q (x - y)} \]

where Q is the covariance matrix.

Because each evaluation multiplies (x_1 - x_2) by the covariance matrix, it may be much quicker to use an LMetric and simply stretch the actual dataset itself before performing any evaluations. However, this class is provided for convenience.

Similar to the LMetric class, this offers a template parameter TakeRoot which, when set to false, will instead evaluate the distance

\[ d(x, y) = (x - y)^T Q (x - y) \]

which is faster to evaluate.

Template Parameters
TakeRootIf true, takes the root of the output. It is slightly faster to leave this at the default of false, but this means the metric may not satisfy the triangle inequality and may not be usable for methods that expect a true metric.

Definition at line 53 of file mahalanobis_distance.hpp.

Constructor & Destructor Documentation

◆ MahalanobisDistance() [1/3]

MahalanobisDistance ( )
inline

Initialize the Mahalanobis distance with the empty matrix as covariance.

Don't call Evaluate() until you set the covariance with Covariance()!

Definition at line 60 of file mahalanobis_distance.hpp.

◆ MahalanobisDistance() [2/3]

MahalanobisDistance ( const size_t  dimensionality)
inline

Initialize the Mahalanobis distance with the identity matrix of the given dimensionality.

Parameters
dimensionalityDimesnsionality of the covariance matrix.

Definition at line 68 of file mahalanobis_distance.hpp.

◆ MahalanobisDistance() [3/3]

MahalanobisDistance ( const arma::mat &  covariance)
inline

Initialize the Mahalanobis distance with the given covariance matrix.

The given covariance matrix will be copied (this is not optimal).

Parameters
covarianceThe covariance matrix to use for this distance.

Definition at line 77 of file mahalanobis_distance.hpp.

References MahalanobisDistance< TakeRoot >::Evaluate().

Member Function Documentation

◆ Covariance() [1/2]

const arma::mat& Covariance ( ) const
inline

Access the covariance matrix.

Returns
Constant reference to the covariance matrix.

Definition at line 96 of file mahalanobis_distance.hpp.

◆ Covariance() [2/2]

arma::mat& Covariance ( )
inline

Modify the covariance matrix.

Returns
Reference to the covariance matrix.

Definition at line 103 of file mahalanobis_distance.hpp.

References MahalanobisDistance< TakeRoot >::serialize().

◆ Evaluate()

double Evaluate ( const VecTypeA &  a,
const VecTypeB &  b 
)

Evaluate the distance between the two given points using this Mahalanobis distance.

If the covariance matrix has not been set (i.e. if you used the empty constructor and did not later modify the covariance matrix), calling this method will probably result in a crash.

Parameters
aFirst vector.
bSecond vector.

Referenced by MahalanobisDistance< TakeRoot >::MahalanobisDistance().

◆ serialize()

void serialize ( Archive &  ar,
const unsigned int  version 
)

Serialize the Mahalanobis distance.

Referenced by MahalanobisDistance< TakeRoot >::Covariance().


The documentation for this class was generated from the following file: