Package org.tinspin.index.covertree

Class CoverTree<T>

java.lang.Object

org.tinspin.index.covertree.CoverTree<T>

All Implemented Interfaces:

Index, PointMap<T>

public class CoverTree<T>
extends Object
implements PointMap<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	Description
static class	CoverTree.CTStats

Nested classes/interfaces inherited from interface org.tinspin.index.Index

Index.BEComparator, Index.BoxEntry<T>, Index.BoxEntryKnn<T>, Index.BoxFilterKnn<T>, Index.BoxIterator<T>, Index.BoxIteratorKnn<T>, Index.PEComparator, Index.PointEntry<T>, Index.PointEntryKnn<T>, Index.PointFilterKnn<T>, Index.PointIterator<T>, Index.PointIteratorKnn<T>, Index.QueryIterator<T>, Index.QueryIteratorKnn<T>

Nested classes/interfaces inherited from interface org.tinspin.index.PointMap

PointMap.Factory

Method Summary

Modifier and Type	Method	Description
void	check()
void	clear()	Clear all entries.
boolean	contains(double[] key)	Lookup an entry, using exact match.
static <T> Index.PointEntry<T>	create(double[] point, T value)
static <T> CoverTree<T>	create(int nDims)
static <T> CoverTree<T>	create(int nDims, double base, PointDistance dist)
static <T> CoverTree<T>	create(Index.PointEntry<T>[] data, double base, PointDistance distFn)
int	getDepth()
int	getDims()
int	getNodeCount()
CoverTree.CTStats	getStats()
void	insert(double[] key, T value)	Insert a point.
Index.PointIterator<T>	iterator()
Index.PointIterator<T>	query(double[] min, double[] max)
Index.PointEntryKnn<T>	query1nn(double[] center)	Finds the nearest neighbor.
T	queryExact(double[] point)	Lookup an entry, using exact match.
Index.PointIteratorKnn<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> Index.PointEntry<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,
                                      PointDistance dist)

create

public static <T> CoverTree<T> create(Index.PointEntry<T>[] data,
                                      double base,
                                      PointDistance distFn)

getDims

public int getDims()

Specified by:

getDims in interface Index

Returns:

the number of dimensions

size

public int size()

Specified by:

size in interface Index

Returns:

the number of entries

clear

public void clear()

Description copied from interface: Index

Clear all entries.

Specified by:

clear in interface Index

getStats

public CoverTree.CTStats getStats()

Specified by:

getStats in interface Index

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

getDepth

public int getDepth()

Specified by:

getDepth in interface Index

toStringTree

public String toStringTree()

Specified by:

toStringTree in interface Index

Returns:

a full string output of the tree structure with all entries

insert

public void insert(double[] key,
                   T value)

Description copied from interface: PointMap

Insert a point.

Specified by:

insert in interface PointMap<T>

Parameters:

key - point

value - value

remove

public T remove(double[] point)

Description copied from interface: PointMap

Remove a point entry.

Specified by:

remove in interface PointMap<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: PointMap

Update the position of an entry.

Specified by:

update in interface PointMap<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: PointMap

Lookup an entry, using exact match.

Specified by:

queryExact in interface PointMap<T>

Parameters:

point - the point

Returns:

the value of the entry or null if the entry was not found

iterator

public Index.PointIterator<T> iterator()

Specified by:

iterator in interface PointMap<T>

Returns:

An iterator over all entries.

query

public Index.PointIterator<T> query(double[] min,
                                    double[] max)

Specified by:

query in interface PointMap<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 Index.PointEntryKnn<T> query1nn(double[] center)

Description copied from interface: PointMap

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 PointMap<T>

Parameters:

center - center point

Returns:

the nearest neighbor

queryKnn

public Index.PointIteratorKnn<T> queryKnn(double[] center,
                                          int k)

Description copied from interface: PointMap

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 PointMap<T>

Parameters:

center - center point

k - number of neighbors

Returns:

list of nearest neighbors

contains

public boolean contains(double[] key)

Description copied from interface: PointMap

Lookup an entry, using exact match.

Specified by:

contains in interface PointMap<T>

Parameters:

key - the point

Returns:

`true` if an entry was found, otherwise `false`.

check

public void check()

toString

public String toString()

Overrides:

toString in class Object