jsat.linear.distancemetrics

Class MahalanobisDistance

java.lang.Object

jsat.linear.distancemetrics.TrainableDistanceMetric

jsat.linear.distancemetrics.MahalanobisDistance

All Implemented Interfaces:

Serializable, Cloneable, DistanceMetric

public class MahalanobisDistance
extends TrainableDistanceMetric

The Mahalanobis Distance is a metric that takes into account the variance of the data. This requires training the metric with the data set to learn the variance of. The extra work involved adds computation time to training and prediction. However, improvements in accuracy can be obtained for many data sets. At the same time, the Mahalanobis Distance can also be detrimental to accuracy.

Author:

Edward Raff

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
MahalanobisDistance()

Method Summary

Modifier and Type	Method and Description
MahalanobisDistance	clone()
double	dist(int a, int b, List<? extends Vec> vecs, List<Double> cache) Computes the distance between 2 vectors in the original list of vectors.
double	dist(int a, Vec b, List<? extends Vec> vecs, List<Double> cache) Computes the distance between one vector in the original list of vectors with that of another vector not from the original list.
double	dist(int a, Vec b, List<Double> qi, List<? extends Vec> vecs, List<Double> cache) Computes the distance between one vector in the original list of vectors with that of another vector not from the original list, but had information generated by DistanceMetric.getQueryInfo(jsat.linear.Vec).
double	dist(Vec a, Vec b) Computes the distance between 2 vectors.
List<Double>	getAccelerationCache(List<? extends Vec> vecs) Returns a cache of double values associated with the given list of vectors in the given order.
List<Double>	getAccelerationCache(List<? extends Vec> vecs, ExecutorService threadpool) Returns a cache of double values associated with the given list of vectors in the given order.
List<Double>	getQueryInfo(Vec q) Pre computes query information that would have be generated if the query was a member of the original list of vectors when calling DistanceMetric.getAccelerationCache(java.util.List) .
boolean	isIndiscemible() Returns true if this distance metric obeys the rule that, for any x and y ∈ S d(x, y) = 0 if and only if x = y
boolean	isReTrain() Returns true if this metric will indicate a need to be retrained once it has been trained once.
boolean	isSubadditive() Returns true if this distance metric obeys the rule that, for any x, y, and z ∈ S d(x, z) ≤ d(x, y) + d(y, z)
boolean	isSymmetric() Returns true if this distance metric obeys the rule that, for any x, y, and z ∈ S d(x, y) = d(y, x)
double	metricBound() All metrics must return values greater than or equal to 0.
boolean	needsTraining() Returns true if the metric needs to be trained.
void	setReTrain(boolean reTrain) It may be desirable to have the metric trained only once, and use the same parameters for all other training sessions of the learning algorithm using the metric.
boolean	supportsAcceleration() Indicates if this distance metric supports building an acceleration cache using the DistanceMetric.getAccelerationCache(java.util.List) and associated distance methods.
boolean	supportsClassificationTraining() Some metrics might be special purpose, and not trainable for all types of data sets or tasks.
boolean	supportsRegressionTraining() Some metrics might be special purpose, and not trainable for all types of data sets tasks.
String	toString() Returns a descriptive name of the Distance Metric in use
void	train(ClassificationDataSet dataSet) Trains this metric on the given classification problem data set
void	train(ClassificationDataSet dataSet, ExecutorService threadpool) Trains this metric on the given classification problem data set
void	train(DataSet dataSet) Trains this metric on the given data set
void	train(DataSet dataSet, ExecutorService threadpool) Trains this metric on the given data set
<V extends Vec> void	train(List<V> dataSet) Trains this metric on the given data set
<V extends Vec> void	train(List<V> dataSet, ExecutorService threadpool) Trains this metric on the given data set
void	train(RegressionDataSet dataSet) Trains this metric on the given regression problem data set
void	train(RegressionDataSet dataSet, ExecutorService threadpool) Trains this metric on the given regression problem data set

Methods inherited from class jsat.linear.distancemetrics.TrainableDistanceMetric

trainIfNeeded, trainIfNeeded, trainIfNeeded, trainIfNeeded

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MahalanobisDistance

public MahalanobisDistance()

Method Detail

isReTrain

public boolean isReTrain()

Returns true if this metric will indicate a need to be retrained once it has been trained once. This will mean needsTraining() will always return true. false means the metric will not indicate a need to be retrained once it has been trained once.

Returns:

true if the data should always be retrained, false if it should not.

setReTrain

public void setReTrain(boolean reTrain)

It may be desirable to have the metric trained only once, and use the same parameters for all other training sessions of the learning algorithm using the metric. This can be controlled through this boolean. Setting true if this metric will indicate a need to be retrained once it has been trained once. This will mean needsTraining() will always return true. false means the metric will not indicate a need to be retrained once it has been trained once.

Parameters:

reTrain - true to make the metric always request retraining, false so it will not.

train

public <V extends Vec> void train(List<V> dataSet)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given data set

Specified by:

train in class TrainableDistanceMetric

Type Parameters:

V - the type of vectors in the list

Parameters:

dataSet - the data set to train on

train

public <V extends Vec> void train(List<V> dataSet,
                                  ExecutorService threadpool)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given data set

Specified by:

train in class TrainableDistanceMetric

Type Parameters:

V - the type of vectors in the list

Parameters:

dataSet - the data set to train on

threadpool - the source of threads for parallel training

train

public void train(DataSet dataSet)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

train

public void train(DataSet dataSet,
                  ExecutorService threadpool)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

threadpool - the source of threads for parallel training

train

public void train(ClassificationDataSet dataSet)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given classification problem data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

train

public void train(ClassificationDataSet dataSet,
                  ExecutorService threadpool)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given classification problem data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

threadpool - the source of threads for parallel training

supportsClassificationTraining

public boolean supportsClassificationTraining()

Description copied from class: TrainableDistanceMetric

Some metrics might be special purpose, and not trainable for all types of data sets or tasks. This method returns true if this metric supports training for classification problems, and false if it does not.
If a metric can learn from unlabeled data, it must return true for this method.

Specified by:

supportsClassificationTraining in class TrainableDistanceMetric

Returns:

true if this metric supports training for classification problems, and false if it does not

train

public void train(RegressionDataSet dataSet)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given regression problem data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

train

public void train(RegressionDataSet dataSet,
                  ExecutorService threadpool)

Description copied from class: TrainableDistanceMetric

Trains this metric on the given regression problem data set

Specified by:

train in class TrainableDistanceMetric

Parameters:

dataSet - the data set to train on

threadpool - the source of threads for parallel training

supportsRegressionTraining

public boolean supportsRegressionTraining()

Description copied from class: TrainableDistanceMetric

Some metrics might be special purpose, and not trainable for all types of data sets tasks. This method returns true if this metric supports training for regression problems, and false if it does not.
If a metric can learn from unlabeled data, it must return true for this method.

Specified by:

supportsRegressionTraining in class TrainableDistanceMetric

Returns:

true if this metric supports training for regression problems, and false if it does not

needsTraining

public boolean needsTraining()

Description copied from class: TrainableDistanceMetric

Returns true if the metric needs to be trained. This may be false if the metric allows the parameters to be specified beforehand. If the information was specified before hand, or does not need training, false is returned.

Specified by:

needsTraining in class TrainableDistanceMetric

Returns:

true if the metric needs training, false if it does not.

dist

public double dist(Vec a,
                   Vec b)

Description copied from interface: DistanceMetric

Computes the distance between 2 vectors. The smaller the value, the closer, and there for, more similar, the vectors are. 0 indicates the vectors are the same.

Parameters:

a - the first vector

b - the second vector

Returns:

the distance between them

isSymmetric

public boolean isSymmetric()

Description copied from interface: DistanceMetric

Returns true if this distance metric obeys the rule that, for any x, y, and z ∈ S
d(x, y) = d(y, x)

Returns:

true if this distance metric is symmetric, false if it is not

isSubadditive

public boolean isSubadditive()

Description copied from interface: DistanceMetric

Returns true if this distance metric obeys the rule that, for any x, y, and z ∈ S
d(x, z) ≤ d(x, y) + d(y, z)

Returns:

true if this distance metric supports the triangle inequality, false if it does not.

isIndiscemible

public boolean isIndiscemible()

Description copied from interface: DistanceMetric

Returns true if this distance metric obeys the rule that, for any x and y ∈ S
d(x, y) = 0 if and only if x = y

Returns:

true if this distance metric is indicemible, false otherwise.

metricBound

public double metricBound()

Description copied from interface: DistanceMetric

All metrics must return values greater than or equal to 0. The upper bound on the value returned is different for different metrics. This method returns the theoretical maximal value that could be returned by this distance metric. That means Double.POSITIVE_INFINITY is a valid return value.

Returns:

the maximal distance for any two points in that could exist by this distance metric.

toString

public String toString()

Description copied from interface: DistanceMetric

Returns a descriptive name of the Distance Metric in use

Specified by:

toString in interface DistanceMetric

Overrides:

toString in class Object

Returns:

the name of this metric

clone

public MahalanobisDistance clone()

Specified by:

clone in interface DistanceMetric

Specified by:

clone in class TrainableDistanceMetric

supportsAcceleration

public boolean supportsAcceleration()

Description copied from interface: DistanceMetric

Indicates if this distance metric supports building an acceleration cache using the DistanceMetric.getAccelerationCache(java.util.List) and associated distance methods. By default this method will return false. If true, then a cache can be obtained from this distance metric and used in conjunction with DistanceMetric.dist(int, jsat.linear.Vec, java.util.List, java.util.List) and DistanceMetric.dist(int, int, java.util.List, java.util.List) to perform distance computations.

Returns:

true if cache acceleration is supported for this metric, false otherwise.

getAccelerationCache

public List<Double> getAccelerationCache(List<? extends Vec> vecs)

Description copied from interface: DistanceMetric

Returns a cache of double values associated with the given list of vectors in the given order. This can be used by the distance metric to increase runtime at the cost of memory. This is an optional method.
If this metric does not support acceleration, null will be returned.

Parameters:

vecs - the list of vectors to build an acceleration cache for

Returns:

the list of double for the cache

dist

public double dist(int a,
                   int b,
                   List<? extends Vec> vecs,
                   List<Double> cache)

Description copied from interface: DistanceMetric

Computes the distance between 2 vectors in the original list of vectors.
If the cache input is null, then DistanceMetric.dist(jsat.linear.Vec, jsat.linear.Vec) will be called directly.

Parameters:

a - the index of the first vector

b - the index of the second vector

vecs - the list of vectors used to build the cache

cache - the cache associated with the given list of vectors

Returns:

the distance between the two vectors

dist

public double dist(int a,
                   Vec b,
                   List<? extends Vec> vecs,
                   List<Double> cache)

Description copied from interface: DistanceMetric

Computes the distance between one vector in the original list of vectors with that of another vector not from the original list.
If the cache input is null, then DistanceMetric.dist(jsat.linear.Vec, jsat.linear.Vec) will be called directly.

Parameters:

a - the index of the vector in the cache

b - the other vector

vecs - the list of vectors used to build the cache

cache - the cache associated with the given list of vectors

Returns:

the distance between the two vectors

getQueryInfo

public List<Double> getQueryInfo(Vec q)

Description copied from interface: DistanceMetric

Pre computes query information that would have be generated if the query was a member of the original list of vectors when calling DistanceMetric.getAccelerationCache(java.util.List) . This can then be used if a large number of distance computations are going to be done against points in the original set for a point that is outside the original space.

If this metric does not support acceleration, null will be returned.

Parameters:

q - the query point to generate cache information for

Returns:

the cache information for the query point

getAccelerationCache

public List<Double> getAccelerationCache(List<? extends Vec> vecs,
                                         ExecutorService threadpool)

Description copied from interface: DistanceMetric

Returns a cache of double values associated with the given list of vectors in the given order. This can be used by the distance metric to increase runtime at the cost of memory. This is an optional method.
If this metric does not support acceleration, null will be returned.

Parameters:

vecs - the list of vectors to build an acceleration cache for

threadpool - source of threads for parallel computation of result. This may be null, which means the singled threaded version may be used.

Returns:

the list of double for the cache

dist

public double dist(int a,
                   Vec b,
                   List<Double> qi,
                   List<? extends Vec> vecs,
                   List<Double> cache)

Description copied from interface: DistanceMetric

Computes the distance between one vector in the original list of vectors with that of another vector not from the original list, but had information generated by DistanceMetric.getQueryInfo(jsat.linear.Vec).
If the cache input is null, then DistanceMetric.dist(jsat.linear.Vec, jsat.linear.Vec) will be called directly.

Parameters:

a - the index of the vector in the cache

b - the other vector

qi - the query information about b

vecs - the list of vectors used to build the cache

cache - the cache associated with the given list of vectors

Returns:

the distance between the two vectors