CosineDistance (Java Statistical Analysis Tool 0.0.8 API)

java.lang.Object
- jsat.linear.distancemetrics.CosineDistance

All Implemented Interfaces:

Serializable, Cloneable, DistanceMetric
```
public class CosineDistance
extends Object
implements DistanceMetric
```
The Cosine Distance is a adaption of the Cosine Similarity's range from [-1, 1] into the range [0, 1]. Where 0 means two vectors are the same, and 1 means they are completely different.

Author:

Edward Raff

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description

CosineDistance()

Constructors
Constructor and Description
`CosineDistance()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CosineDistance`	`clone()`
`static double`	`cosineToDistance(double cosAngle)` This method converts the cosine distance in [-1, 1] to a valid distance metric in the range [0, 1]
`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.
`static double`	`distanceToCosine(double dist)` This method converts the distance obtained with `cosineToDistance(double)` back into the cosine angle
`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`	`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.
`String`	`toString()` Returns a descriptive name of the Distance Metric in use

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - CosineDistance
```
public CosineDistance()
```
- Method Detail
  - 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.
    
    Specified by:
    
    dist in interface DistanceMetric
    
    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)
    
    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 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 CosineDistance clone()
```
    Specified by:
    
    clone in interface DistanceMetric
    
    Overrides:
    
    clone in class 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 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.
    
    Specified by:
    
    getAccelerationCache in interface DistanceMetric
    
    Parameters:
    
    vecs - the list of vectors to build an acceleration cache for
    
    Returns:
    
    the list of double for the cache
  - 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.
    
    Specified by:
    
    getAccelerationCache in interface DistanceMetric
    
    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,
                   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.
    
    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,
                   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.
    
    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 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.
    
    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,
                   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.
    
    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
  - cosineToDistance
```
public static double cosineToDistance(double cosAngle)
```
    This method converts the cosine distance in [-1, 1] to a valid distance metric in the range [0, 1]
    
    Parameters:
    
    cosAngle - the cosine similarity in [-1, 1]
    
    Returns:
    
    the distance metric for the cosine value
  - distanceToCosine
```
public static double distanceToCosine(double dist)
```
    This method converts the distance obtained with cosineToDistance(double) back into the cosine angle
    
    Parameters:
    
    dist - the distance value in [0, 1]
    
    Returns:
    
    the cosine angle

Class CosineDistance

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CosineDistance

Method Detail

dist

isSymmetric

isSubadditive

isIndiscemible

metricBound

toString

clone

supportsAcceleration

getAccelerationCache

getAccelerationCache

dist

dist

getQueryInfo

dist

cosineToDistance

distanceToCosine