CoverTree (tinspin-indexes 1.7.0 API)

java.lang.Object
- org.tinspin.index.covertree.CoverTree<T>

All Implemented Interfaces:

Index<T>, PointIndex<T>
```
public class CoverTree<T>
extends Object
implements PointIndex<T>
```
A 'faster' CoverTree implementation based on the paper: "Faster Cover Trees", Mike Izbicki, Christian R. Shelton, Proceedings of the 32nd International Conference on Machine Learning, Lille, France, 2015. Changes over original algorithms: - findNearestNeighbour compares if (d(y, x) greater (d(_x_, q.point()) - q.maxdist(this))) instead of if (d(y, x) greater (d(_y_, q.point()) - q.maxdist(this))) - maxDist: - lazily calculated. - calculated while excluding subbranches that don't need to be calculated - Invalidated on modifications (should speed up remove/insert) - Algorithm 2 (insert) uses BASE=1.3: BASE*covdist(p) instead of 2*covdist(p)) - Rebalancing: - The paper proposes to sort the children on their distance to 'x' and then insert into the first one that has enough covdist. The sorting appears unnecessary because we anyway have to check all children, and finding the closest one is trivially possible without sorting. - Some optimizations for kNN which are not discussed in the paper Other: - We also implemented the kNN algorithm by Hjaltason and Samet, but it about 2x as long as our own algorithm in all scenarios we tested. TODO - Rebalancing (nearest-ancestor) - Merge Node/Point classes

Author:

Tilmann Zäschke

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CoverTree.CTStats

Nested Classes
Modifier and Type	Class and Description
`static class`	`CoverTree.CTStats`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`check()`
`void`	`clear()` Clear all entries.
`boolean`	`containsExact(double[] key)`
`static <T> Point<T>`	`create(double[] point, T value)`
`static <T> CoverTree<T>`	`create(int nDims)`
`static <T> CoverTree<T>`	`create(int nDims, double base, PointDistanceFunction dist)`
`static <T> CoverTree<T>`	`create(Point<T>[] data, double base, PointDistanceFunction distFn)`
`int`	`getDepth()`
`int`	`getDims()`
`int`	`getNodeCount()`
`CoverTree.CTStats`	`getStats()`
`void`	`insert(double[] key, T value)` Insert a point.
`QueryIterator<? extends PointEntry<T>>`	`iterator()`
`QueryIterator<PointEntry<T>>`	`query(double[] min, double[] max)`
`PointEntryDist<T>`	`query1NN(double[] center)` Finds the nearest neighbor.
`T`	`queryExact(double[] point)` Lookup an entry, using exact match.
`QueryIteratorKNN<PointEntryDist<T>>`	`queryKNN(double[] center, int k)` Finds the nearest neighbor.
`T`	`remove(double[] point)` Remove a point entry.
`int`	`size()`
`String`	`toString()`
`String`	`toStringTree()`
`T`	`update(double[] oldPoint, double[] newPoint)` Update the position of an entry.

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

- Method Detail
  - create
```
public static <T> Point<T> create(double[] point,
                                  T value)
```
  - create
```
public static <T> CoverTree<T> create(int nDims)
```
  - create
```
public static <T> CoverTree<T> create(int nDims,
                                      double base,
                                      PointDistanceFunction dist)
```
  - create
```
public static <T> CoverTree<T> create(Point<T>[] data,
                                      double base,
                                      PointDistanceFunction distFn)
```
  - getDims
```
public int getDims()
```
    Specified by:
    
    getDims in interface Index<T>
    
    Returns:
    
    the number of dimensions
  - size
```
public int size()
```
    Specified by:
    
    size in interface Index<T>
    
    Returns:
    
    the number of entries
  - clear
```
public void clear()
```
    Description copied from interface: Index
    
    Clear all entries.
    
    Specified by:
    
    clear in interface Index<T>
  - getStats
```
public CoverTree.CTStats getStats()
```
    Specified by:
    
    getStats in interface Index<T>
    
    Returns:
    
    Collect and return some index statistics. Note that indexes are not required to fill all fields. Also, individual indexes may use subclasses with additional fields.
  - getNodeCount
```
public int getNodeCount()
```
    Specified by:
    
    getNodeCount in interface Index<T>
  - getDepth
```
public int getDepth()
```
    Specified by:
    
    getDepth in interface Index<T>
  - toStringTree
```
public String toStringTree()
```
    Specified by:
    
    toStringTree in interface Index<T>
    
    Returns:
    
    a full string output of the tree structure with all entries
  - insert
```
public void insert(double[] key,
                   T value)
```
    Description copied from interface: PointIndex
    
    Insert a point.
    
    Specified by:
    
    insert in interface PointIndex<T>
    
    Parameters:
    
    key - point
    
    value - value
  - remove
```
public T remove(double[] point)
```
    Description copied from interface: PointIndex
    
    Remove a point entry.
    
    Specified by:
    
    remove in interface PointIndex<T>
    
    Parameters:
    
    point - the point
    
    Returns:
    
    the value of the entry or null if the entry was not found
  - update
```
public T update(double[] oldPoint,
                double[] newPoint)
```
    Description copied from interface: PointIndex
    
    Update the position of an entry.
    
    Specified by:
    
    update in interface PointIndex<T>
    
    Parameters:
    
    oldPoint - old position
    
    newPoint - new position
    
    Returns:
    
    the value of the entry or null if the entry was not found
  - queryExact
```
public T queryExact(double[] point)
```
    Description copied from interface: PointIndex
    
    Lookup an entry, using exact match.
    
    Specified by:
    
    queryExact in interface PointIndex<T>
    
    Parameters:
    
    point - the point
    
    Returns:
    
    the value of the entry or null if the entry was not found
  - iterator
```
public QueryIterator<? extends PointEntry<T>> iterator()
```
    Specified by:
    
    iterator in interface PointIndex<T>
    
    Returns:
    
    An iterator over all entries.
  - query
```
public QueryIterator<PointEntry<T>> query(double[] min,
                                          double[] max)
```
    Specified by:
    
    query in interface PointIndex<T>
    
    Parameters:
    
    min - Lower left corner of the query window
    
    max - Upper right corner of the query window
    
    Returns:
    
    All points that lie inside the query rectangle.
  - query1NN
```
public PointEntryDist<T> query1NN(double[] center)
```
    Description copied from interface: PointIndex
    
    Finds the nearest neighbor. This uses euclidean distance. Other distance types can only be specified directly on the index implementations.
    
    Specified by:
    
    query1NN in interface PointIndex<T>
    
    Parameters:
    
    center - center point
    
    Returns:
    
    the nearest neighbor
  - queryKNN
```
public QueryIteratorKNN<PointEntryDist<T>> queryKNN(double[] center,
                                                    int k)
```
    Description copied from interface: PointIndex
    
    Finds the nearest neighbor. This uses euclidean distance. Other distance types can only be specified directly on the index implementations.
    
    Specified by:
    
    queryKNN in interface PointIndex<T>
    
    Parameters:
    
    center - center point
    
    k - number of neighbors
    
    Returns:
    
    list of nearest neighbors
  - containsExact
```
public boolean containsExact(double[] key)
```
  - check
```
public void check()
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class CoverTree<T>

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

create

create

create

getDims

size

clear

getStats

getNodeCount

getDepth

toStringTree

insert

remove

update

queryExact

iterator

query

query1NN

queryKNN

containsExact

check

toString