jsat.linear.distancemetrics

Class KernelDistance

java.lang.Object

jsat.linear.distancemetrics.KernelDistance

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, DistanceMetric

public class KernelDistance
extends java.lang.Object
implements DistanceMetric

Creates a distance metric from a given kernel trick. For the distance metric to be valid, the kernel used must be positive definite.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
KernelDistance(KernelTrick kf) Creates a distane metric from the given kernel.

Method Summary

Modifier and Type	Method and Description
KernelDistance	clone()
double	dist(int a, int b, java.util.List<? extends Vec> vecs, java.util.List<java.lang.Double> cache) Computes the distance between 2 vectors in the original list of vectors.
double	dist(int a, Vec b, java.util.List<? extends Vec> vecs, java.util.List<java.lang.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, java.util.List<java.lang.Double> qi, java.util.List<? extends Vec> vecs, java.util.List<java.lang.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) Returns the square of the distance function expanded as kernel methods.
java.util.List<java.lang.Double>	getAccelerationCache(java.util.List<? extends Vec> vecs, boolean parallel) Returns a cache of double values associated with the given list of vectors in the given order.
java.util.List<java.lang.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	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	supportsAcceleration() Indicates if this distance metric supports building an acceleration cache using the DistanceMetric.getAccelerationCache(java.util.List) and associated distance methods.
java.lang.String	toString() Returns a descriptive name of the Distance Metric in use

Methods inherited from class java.lang.Object

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

Methods inherited from interface jsat.linear.distancemetrics.DistanceMetric

getAccelerationCache, isValidMetric

Constructor Detail

KernelDistance

public KernelDistance(KernelTrick kf)

Creates a distane metric from the given kernel. For the metric to be valid, the kernel must be positive definite. This means that

∀ c_i ∈ ℜ , x_i ∈ ℜ^d
∑_{i, j = 1}^m c_i c_j K(x_i, x_j) ≥ 0

Parameters:

kf -

Method Detail

dist

public double dist(Vec a,
                   Vec b)

Returns the square of the distance function expanded as kernel methods.
d²(x,y) = K(x,x) - 2*K(x,y) + K(y,y)

Special Notes:
The use of RBFKernel or PolynomialKernel of degree 1 in the NearestNeighbour classifier will degenerate into the normal nearest neighbor algorithm.

Specified by:

dist in interface DistanceMetric

Parameters:

a - the first vector

b - the second vector

Returns:

the distance metric based on a kernel function

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)

Specified by:

isSymmetric in interface DistanceMetric

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)

Specified by:

isSubadditive in interface DistanceMetric

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

Specified by:

isIndiscemible in interface DistanceMetric

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.

Specified by:

metricBound in interface DistanceMetric

Returns:

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

toString

public java.lang.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 java.lang.Object

Returns:

the name of this metric

clone

public KernelDistance clone()

Specified by:

clone in interface DistanceMetric

Overrides:

clone in class java.lang.Object

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.

Specified by:

supportsAcceleration in interface DistanceMetric

Returns:

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

getAccelerationCache

public java.util.List<java.lang.Double> getAccelerationCache(java.util.List<? extends Vec> vecs,
                                                             boolean parallel)

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.

Specified by:

getAccelerationCache in interface DistanceMetric

Parameters:

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

parallel - true if multiple threads should be used to perform clustering. false if it should be done in a single threaded manner.

Returns:

the list of double for the cache

dist

public double dist(int a,
                   int b,
                   java.util.List<? extends Vec> vecs,
                   java.util.List<java.lang.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.

Specified by:

dist in interface DistanceMetric

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,
                   java.util.List<? extends Vec> vecs,
                   java.util.List<java.lang.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.

Specified by:

dist in interface DistanceMetric

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 java.util.List<java.lang.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.

Specified by:

getQueryInfo in interface DistanceMetric

Parameters:

q - the query point to generate cache information for

Returns:

the cache information for the query point

dist

public double dist(int a,
                   Vec b,
                   java.util.List<java.lang.Double> qi,
                   java.util.List<? extends Vec> vecs,
                   java.util.List<java.lang.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.

Specified by:

dist in interface DistanceMetric

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