weka.core.neighboursearch

Class CoverTree

java.lang.Object

weka.core.neighboursearch.NearestNeighbourSearch

weka.core.neighboursearch.CoverTree

All Implemented Interfaces:

java.io.Serializable, AdditionalMeasureProducer, OptionHandler, RevisionHandler, TechnicalInformationHandler

public class CoverTree
extends NearestNeighbourSearch
implements TechnicalInformationHandler

Class implementing the CoverTree datastructure.
The class is very much a translation of the c source code made available by the authors.

For more information and original source code see:

Alina Beygelzimer, Sham Kakade, John Langford: Cover trees for nearest neighbor. In: ICML'06: Proceedings of the 23rd international conference on Machine learning, New York, NY, USA, 97-104, 2006.

BibTeX:

 @inproceedings{Beygelzimer2006,
    address = {New York, NY, USA},
    author = {Alina Beygelzimer and Sham Kakade and John Langford},
    booktitle = {ICML'06: Proceedings of the 23rd international conference on Machine learning},
    pages = {97-104},
    publisher = {ACM Press},
    title = {Cover trees for nearest neighbor},
    year = {2006},
    location = {Pittsburgh, Pennsylvania},
    HTTP = {http://hunch.net/\~jl/projects/cover_tree/cover_tree.html}
 }
 

Valid options are:

 -B <value>
  Set base of the expansion constant
  (default = 1.3).
 

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CoverTree.CoverTreeNode class representing a node of the cover tree.
protected class	CoverTree.MyHeap A class for a heap to store the nearest k neighbours to an instance.
protected class	CoverTree.MyHeapElement A class for storing data about a neighboring instance.

Nested classes/interfaces inherited from class weka.core.neighboursearch.NearestNeighbourSearch

NearestNeighbourSearch.NeighborList, NearestNeighbourSearch.NeighborNode

Field Summary

Fields

Modifier and Type	Field and Description
protected double	il2 if we have base 2 then this can be viewed as 1/ln(2), which can be used later on to do il2*ln(d) instead of ln(d)/ln(2), to get log2(d), in get_scale method.
protected double	m_Base The base of our expansion constant.
protected double[]	m_DistanceList Array holding the distances of the nearest neighbours.
protected EuclideanDistance	m_EuclideanDistance The euclidean distance function to use.
protected int	m_MaxDepth Number of nodes in the tree.
protected int	m_NumLeaves Number of nodes in the tree.
protected int	m_NumNodes Number of nodes in the tree.
protected CoverTree.CoverTreeNode	m_Root The root node.
protected TreePerformanceStats	m_TreeStats Tree Stats variables.

Fields inherited from class weka.core.neighboursearch.NearestNeighbourSearch

m_DistanceFunction, m_Instances, m_kNN, m_MeasurePerformance, m_Stats

Constructor Summary

Constructors

Constructor and Description
CoverTree() default constructor.

Method Summary

Modifier and Type	Method and Description
void	addInstanceInfo(Instance ins) Adds the given instance info.
java.lang.String	baseTipText() Returns the tip text for this property.
protected CoverTree.CoverTreeNode	batch_insert(java.lang.Integer p, int max_scale, int top_scale, Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set, Stack<weka.core.neighboursearch.CoverTree.DistanceNode> consumed_set) Creates a cover tree recursively using batch insert method.
protected void	batch_nearest_neighbor(int k, CoverTree.CoverTreeNode tree_root, CoverTree.CoverTreeNode query_root, Stack<NearestNeighbourSearch.NeighborList> results) Performs k-NN search for a batch of queries provided in the form of a cover tree.
protected void	brute_nearest(int k, CoverTree.CoverTreeNode query, Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set, CoverTree.MyHeap upper_k, Stack<NearestNeighbourSearch.NeighborList> results) Does a brute force NN search on the nodes in the given zero set.
protected void	buildCoverTree(Instances insts) Builds the tree on the given set of instances.
protected void	checkMissing(Instances instances) Checks if there is any instance with missing values.
protected double	compare(int p1, int p2, Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set) Returns the difference of two given nodes distance to the query.
protected void	copy_cover_sets(CoverTree.CoverTreeNode query_chi, CoverTree.MyHeap new_upper_k, Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets, Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> new_cover_sets, int current_scale, int max_scale) Copies the contents of one set of cover sets to the other.
protected void	copy_zero_set(CoverTree.CoverTreeNode query_chi, CoverTree.MyHeap new_upper_k, Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set, Stack<weka.core.neighboursearch.CoverTree.d_node> new_zero_set) Copies the contents of one zero set to the other.
protected int	descend(CoverTree.CoverTreeNode query, CoverTree.MyHeap upper_k, int current_scale, int max_scale, Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets, Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set) This functions adds nodes for inspection at the next level during NN search.
protected double	dist_of_scale(int s) Returns the distance/value of a given scale/level.
protected void	dist_split(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set, Stack<weka.core.neighboursearch.CoverTree.DistanceNode> new_point_set, weka.core.neighboursearch.CoverTree.DistanceNode new_point, int max_scale) Moves all the points in point_set covered by (the ball of) new_point into new_point_set, based on the given scale/level.
java.util.Enumeration<java.lang.String>	enumerateMeasures() Returns an enumeration of the additional measure names.
protected NearestNeighbourSearch.NeighborList	findKNearest(Instance target, int k) Performs k-NN serach for a single given query/test Instance.
protected int	get_scale(double d) Finds the scale/level of a given value.
double	getBase() Returns the base in use for expansion constant.
protected Stack<weka.core.neighboursearch.CoverTree.d_node>	getCoverSet(int idx, Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets) Returns a cover set for a given level/scale.
double[]	getDistances() Returns the distances of the (k)-NN(s) found earlier by kNearestNeighbours()/nearestNeighbour().
double	getMeasure(java.lang.String additionalMeasureName) Returns the value of the named measure.
java.lang.String[]	getOptions() Gets the current settings of KDtree.
java.lang.String	getRevision() Returns the revision string.
TechnicalInformation	getTechnicalInformation() Returns an instance of a TechnicalInformation object, containing detailed information about the technical background of this class, e.g., paper reference or book this class is based on.
java.lang.String	globalInfo() Returns a string describing this nearest neighbour search algorithm.
protected void	halfsort(Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set) Half-sorts a cover set, so that nodes nearer to the query are at the front.
protected void	internal_batch_nearest_neighbor(int k, CoverTree.CoverTreeNode query_node, Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets, Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set, int current_scale, int max_scale, CoverTree.MyHeap upper_k, Stack<NearestNeighbourSearch.NeighborList> results) Performs a recursive k-NN search for a given batch of queries provided in the form of a cover tree.
Instances	kNearestNeighbours(Instance target, int k) Returns k-NNs of a given target instance, from among the previously supplied training instances (supplied through setInstances method) P.S.: May return more than k-NNs if more one instances have the same distance to the target as the kth NN.
java.util.Enumeration<Option>	listOptions() Returns an enumeration describing the available options.
static void	main(java.lang.String[] args) Method for testing the class from command line.
protected double	max_set(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> v) Returns the max distance of the reference point p in current node to it's children nodes.
double	measureMaxDepth() Returns the depth of the tree.
double	measureNumLeaves() Returns the number of leaves.
double	measureTreeSize() Returns the size of the tree.
Instance	nearestNeighbour(Instance target) Returns the NN instance of a given target instance, from among the previously supplied training instances.
protected CoverTree.CoverTreeNode	new_leaf(java.lang.Integer idx) Creates a new leaf node for a given Instance/point p.
protected CoverTree.CoverTreeNode	new_node(java.lang.Integer idx) Creates a new internal node for a given Instance/point p.
protected static void	print_space(int s) Prints the specified number of spaces.
protected static void	print(int depth, CoverTree.CoverTreeNode top_node) Prints a cover tree starting from the given node.
protected static void	print(java.lang.Object o) Prints an object to stdout.
protected static void	print(java.lang.String s) Prints a string to stdout.
protected static void	println(java.lang.Object o) Prints an object to stdout followed by newline.
protected static void	println(java.lang.String s) Prints a string to stdout followed by newline.
void	setBase(double b) Sets the base to use for expansion constant.
void	setDistanceFunction(DistanceFunction df) Sets the distance function to use for nearest neighbour search.
void	setInstances(Instances instances) Builds the Cover Tree on the given set of instances.
void	setOptions(java.lang.String[] options) Parses a given list of options.
protected void	setter(CoverTree.MyHeap heap, double upper_bound, int k) Initializes a heap with k values of the the given upper_bound.
protected boolean	shell(double parent_query_dist, double child_parent_dist, double upper_bound) Function to check if a child node can be inside a query ball, without calculating the child node's distance to the query.
protected void	split(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set, Stack<weka.core.neighboursearch.CoverTree.DistanceNode> far_set, int max_scale) Splits a given point_set into near and far based on the given scale/level.
protected void	SWAP(int a, int b, Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set) Swap two nodes in a cover set.
protected void	update(CoverTree.MyHeap upper_bound, double new_bound) Replaces the current top/max value in the heap with the new one.
void	update(Instance ins) Adds an instance to the cover tree.

Methods inherited from class weka.core.neighboursearch.NearestNeighbourSearch

combSort11, distanceFunctionTipText, getDistanceFunction, getInstances, getMeasurePerformance, getPerformanceStats, measurePerformanceTipText, partition, quickSort, setMeasurePerformance

Methods inherited from class java.lang.Object

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

Field Detail

m_EuclideanDistance

protected EuclideanDistance m_EuclideanDistance

The euclidean distance function to use.

m_Root

protected CoverTree.CoverTreeNode m_Root

The root node.

m_DistanceList

protected double[] m_DistanceList

Array holding the distances of the nearest neighbours. It is filled up both by nearestNeighbour() and kNearestNeighbours().

m_NumNodes

protected int m_NumNodes

Number of nodes in the tree.

m_NumLeaves

protected int m_NumLeaves

Number of nodes in the tree.

m_MaxDepth

protected int m_MaxDepth

Number of nodes in the tree.

m_TreeStats

protected TreePerformanceStats m_TreeStats

Tree Stats variables.

m_Base

protected double m_Base

The base of our expansion constant. In other words the 2 in 2^i used in covering tree and separation invariants of a cover tree. P.S.: In paper it's suggested the separation invariant is relaxed in batch construction.

il2

protected double il2

if we have base 2 then this can be viewed as 1/ln(2), which can be used later on to do il2*ln(d) instead of ln(d)/ln(2), to get log2(d), in get_scale method.

Constructor Detail

CoverTree

public CoverTree()

default constructor.

Method Detail

globalInfo

public java.lang.String globalInfo()

Returns a string describing this nearest neighbour search algorithm.

Overrides:

globalInfo in class NearestNeighbourSearch

Returns:

a description of the algorithm for displaying in the explorer/experimenter gui

getTechnicalInformation

public TechnicalInformation getTechnicalInformation()

Returns an instance of a TechnicalInformation object, containing detailed information about the technical background of this class, e.g., paper reference or book this class is based on.

Specified by:

getTechnicalInformation in interface TechnicalInformationHandler

Returns:

the technical information about this class

listOptions

public java.util.Enumeration<Option> listOptions()

Returns an enumeration describing the available options.

Specified by:

listOptions in interface OptionHandler

Overrides:

listOptions in class NearestNeighbourSearch

Returns:

an enumeration of all the available options.

setOptions

public void setOptions(java.lang.String[] options)
                throws java.lang.Exception

Parses a given list of options.

Valid options are:

 -B <value>
  Set base of the expansion constant
  (default = 1.3).
 

Specified by:

setOptions in interface OptionHandler

Overrides:

setOptions in class NearestNeighbourSearch

Parameters:

options - the list of options as an array of strings

Throws:

java.lang.Exception - if an option is not supported

getOptions

public java.lang.String[] getOptions()

Gets the current settings of KDtree.

Specified by:

getOptions in interface OptionHandler

Overrides:

getOptions in class NearestNeighbourSearch

Returns:

an array of strings suitable for passing to setOptions

dist_of_scale

protected double dist_of_scale(int s)

Returns the distance/value of a given scale/level. I.e. the value of base^i (e.g. 2^i).

Parameters:

s - the level/scale

Returns:

base^s

get_scale

protected int get_scale(double d)

Finds the scale/level of a given value. I.e. the "i" in base^i.

Parameters:

d - the value whose scale/level is to be determined.

Returns:

the scale/level of the given value.

new_node

protected CoverTree.CoverTreeNode new_node(java.lang.Integer idx)

Creates a new internal node for a given Instance/point p.

Parameters:

idx - The index of the instance the node represents.

Returns:

Newly created CoverTreeNode.

new_leaf

protected CoverTree.CoverTreeNode new_leaf(java.lang.Integer idx)

Creates a new leaf node for a given Instance/point p.

Parameters:

idx - The index of the instance this leaf node represents.

Returns:

Newly created leaf CoverTreeNode.

max_set

protected double max_set(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> v)

Returns the max distance of the reference point p in current node to it's children nodes.

Parameters:

v - The stack of DistanceNode objects.

Returns:

Distance of the furthest child.

split

protected void split(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set,
                     Stack<weka.core.neighboursearch.CoverTree.DistanceNode> far_set,
                     int max_scale)

Splits a given point_set into near and far based on the given scale/level. All points with distance > base^max_scale would be moved to far set. In other words, all those points that are not covered by the next child ball of a point p (ball made of the same point p but of smaller radius at the next lower level) are removed from the supplied current point_set and put into far_set.

Parameters:

point_set - The supplied set from which all far points would be removed.

far_set - The set in which all far points having distance > base^max_scale would be put into.

max_scale - The given scale based on which the distances of points are judged to be far or near.

dist_split

protected void dist_split(Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set,
                          Stack<weka.core.neighboursearch.CoverTree.DistanceNode> new_point_set,
                          weka.core.neighboursearch.CoverTree.DistanceNode new_point,
                          int max_scale)

Moves all the points in point_set covered by (the ball of) new_point into new_point_set, based on the given scale/level.

Parameters:

point_set - The supplied set of instances from which all points covered by new_point will be removed.

new_point_set - The set in which all points covered by new_point will be put into.

new_point - The given new point.

max_scale - The scale based on which distances are judged (radius of cover ball is calculated).

batch_insert

protected CoverTree.CoverTreeNode batch_insert(java.lang.Integer p,
                                               int max_scale,
                                               int top_scale,
                                               Stack<weka.core.neighboursearch.CoverTree.DistanceNode> point_set,
                                               Stack<weka.core.neighboursearch.CoverTree.DistanceNode> consumed_set)

Creates a cover tree recursively using batch insert method.

Parameters:

p - The index of the instance from which to create the first node. All other points will be inserted beneath this node for p.

max_scale - The current scale/level where the node is to be created (Also determines the radius of the cover balls created at this level).

top_scale - The max scale in the whole tree.

point_set - The set of unprocessed points from which child nodes need to be created.

consumed_set - The set of processed points from which child nodes have already been created. This would be used to find the radius of the cover ball of p.

Returns:

the node of cover tree created with p.

buildCoverTree

protected void buildCoverTree(Instances insts)
                       throws java.lang.Exception

Builds the tree on the given set of instances. P.S.: For internal use only. Outside classes should call setInstances().

Parameters:

insts - The instances on which to build the cover tree.

Throws:

java.lang.Exception - If the supplied set of Instances is empty, or if there are missing values.

setter

protected void setter(CoverTree.MyHeap heap,
                      double upper_bound,
                      int k)
               throws java.lang.Exception

Initializes a heap with k values of the the given upper_bound.

Parameters:

heap - The heap to put values into.

upper_bound - The value to put into heap (the value with which it should be initialized).

k - The number of times upper_bound should be put into heap for initialization.

Throws:

java.lang.Exception - If there is some problem in initializing the heap (if k > size of the heap).

update

protected void update(CoverTree.MyHeap upper_bound,
                      double new_bound)
               throws java.lang.Exception

Replaces the current top/max value in the heap with the new one. The new max value should be <= the old one.

Parameters:

upper_bound - The heap.

new_bound - The new value that should replace the old top one.

Throws:

java.lang.Exception - if the new value is greater than the old value.

getCoverSet

protected Stack<weka.core.neighboursearch.CoverTree.d_node> getCoverSet(int idx,
                                                                        Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets)

Returns a cover set for a given level/scale. A cover set for a level consists of nodes whose Instances/centres are which are inside the query ball at that level. If no cover set exists for the given level (if it is the first time it is going to be used), than a new one is created.

Parameters:

idx - The level/scale for which the cover set is required.

cover_sets - The covers sets. Consists of stack of a stack of d_node objects.

Returns:

The cover set for the given level/scale.

copy_zero_set

protected void copy_zero_set(CoverTree.CoverTreeNode query_chi,
                             CoverTree.MyHeap new_upper_k,
                             Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set,
                             Stack<weka.core.neighboursearch.CoverTree.d_node> new_zero_set)
                      throws java.lang.Exception

Copies the contents of one zero set to the other. This is required if we are going to inspect child of some query node (if the queries are given in batch in the form of a cover tree). Only those nodes are copied to the new zero set that are inside the query ball of query_chi. P.S.: A zero set is a set of all leaf nodes that are found to be inside the query ball.

Parameters:

query_chi - The child node of our query node that we are going to inspect.

new_upper_k - New heap that will store the distances of the k NNs for query_chi.

zero_set - The zero set of query_chi's parent that needs to be copied.

new_zero_set - The new zero set of query_chi where old zero sets need to be copied into.

Throws:

java.lang.Exception - If there is some problem.

copy_cover_sets

protected void copy_cover_sets(CoverTree.CoverTreeNode query_chi,
                               CoverTree.MyHeap new_upper_k,
                               Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets,
                               Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> new_cover_sets,
                               int current_scale,
                               int max_scale)
                        throws java.lang.Exception

Copies the contents of one set of cover sets to the other. It is required if we are going to inspect child of some query node (if the queries are given in batch in the form of a cover tree). For each level, only those nodes are copied to the new set which are inside the query ball of query_chi at that level.

Parameters:

query_chi - The child node of our query node that we are going to inspect.

new_upper_k - New heap that will store the distances of the k NNs for query_chi.

cover_sets - The cover_sets of query_chi's parent, which need to be copied to new_cover_sets.

new_cover_sets - The new set of cover_sets that need to contain contents of cover_sets.

current_scale - The scale/level we are inspecting in our cover tree.

max_scale - The maximum level so far possible in our search (this is only updated as we descend and a deeper child is found inside the query ball).

Throws:

java.lang.Exception - If there is problem.

SWAP

protected void SWAP(int a,
                    int b,
                    Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set)

Swap two nodes in a cover set.

Parameters:

a - The index first node.

b - The index of second node.

cover_set - The cover set in which the two nodes are.

compare

protected double compare(int p1,
                         int p2,
                         Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set)

Returns the difference of two given nodes distance to the query. It is used in half-sorting a cover set.

Parameters:

p1 - The index of first node.

p2 - The index of second node.

cover_set - The cover set containing the two given nodes.

Returns:

dist_to_query_of_p1 - dist_to_query_of_p2

halfsort

protected void halfsort(Stack<weka.core.neighboursearch.CoverTree.d_node> cover_set)

Half-sorts a cover set, so that nodes nearer to the query are at the front.

Parameters:

cover_set - The cover set to sort.

shell

protected boolean shell(double parent_query_dist,
                        double child_parent_dist,
                        double upper_bound)

Function to check if a child node can be inside a query ball, without calculating the child node's distance to the query. This further avoids unnecessary distance calculation.

Parameters:

parent_query_dist - The distance of parent to the query

child_parent_dist - The distance of child to the parent.

upper_bound - The distance to the query of the best kth NN found so far.

Returns:

true If child can be inside the query ball.

descend

protected int descend(CoverTree.CoverTreeNode query,
                      CoverTree.MyHeap upper_k,
                      int current_scale,
                      int max_scale,
                      Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets,
                      Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set)
               throws java.lang.Exception

This functions adds nodes for inspection at the next level during NN search. The internal nodes are added to one of the cover sets (at the level of the child node which is added) and leaf nodes are added to the zero set. An optimization to consider: Make all distance evaluations occur in descend. Instead of passing a cover_set, pass a stack of cover sets. The last element holds d_nodes with your distance. The next lower element holds a d_node with the distance to your query parent, next = query grand parent, etc.. Compute distances in the presence of the tighter upper bound.

Parameters:

query - The query (in shape of a cover tree node, as we are doing batch searching).

upper_k - Heap containing distances of best k-NNs found so far.

current_scale - The current scale/level being looked at in the tree.

max_scale - The max scale/level that has so far been looked at.

cover_sets - The cover sets of tree nodes for each level of our trees for.

zero_set - The set containing leaf nodes.

Returns:

A new max_scale, if we descend to a deeper level.

Throws:

java.lang.Exception - If there is some problem (in updating the heap upper_k).

brute_nearest

protected void brute_nearest(int k,
                             CoverTree.CoverTreeNode query,
                             Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set,
                             CoverTree.MyHeap upper_k,
                             Stack<NearestNeighbourSearch.NeighborList> results)
                      throws java.lang.Exception

Does a brute force NN search on the nodes in the given zero set. A zero set might have some nodes added to it that were not k-NNs, so need to do a brute-force to pick only the k-NNs (without calculating distances, as each node in the zero set already had its distance calculated to the query, which is stored with the node).

Parameters:

k - The k in kNN.

query - The query.

zero_set - The zero set on which the brute force NN search is performed.

upper_k - The heap storing distances of k-NNs found during the search.

results - The returned k-NNs.

Throws:

java.lang.Exception - If there is somem problem.

internal_batch_nearest_neighbor

protected void internal_batch_nearest_neighbor(int k,
                                               CoverTree.CoverTreeNode query_node,
                                               Stack<Stack<weka.core.neighboursearch.CoverTree.d_node>> cover_sets,
                                               Stack<weka.core.neighboursearch.CoverTree.d_node> zero_set,
                                               int current_scale,
                                               int max_scale,
                                               CoverTree.MyHeap upper_k,
                                               Stack<NearestNeighbourSearch.NeighborList> results)
                                        throws java.lang.Exception

Performs a recursive k-NN search for a given batch of queries provided in the form of a cover tree. P.S.: This function should not be called from outside. Outside classes should use kNearestNeighbours() instead.

Parameters:

k - The number of NNs to find.

query_node - The node of the query tree to start the search from.

cover_sets - The set of sets that contains internal nodes that were found to be inside the query ball at previous scales/levels (intially there would be just the root node at root level).

zero_set - The set that'll contain the leaf nodes that are found to be inside the query ball.

current_scale - The level/scale to do the search from (this value would be used to inspect the cover set in the provided set of cover sets).

max_scale - The max scale/level that has so far been inspected.

upper_k - The heap containing distances of the best k-NNs found so far (initialized to Double.POSITIVE_INFINITY).

results - The list of returned k-NNs.

Throws:

java.lang.Exception - If there is some problem during the search.

batch_nearest_neighbor

protected void batch_nearest_neighbor(int k,
                                      CoverTree.CoverTreeNode tree_root,
                                      CoverTree.CoverTreeNode query_root,
                                      Stack<NearestNeighbourSearch.NeighborList> results)
                               throws java.lang.Exception

Performs k-NN search for a batch of queries provided in the form of a cover tree. P.S.: Outside classes should call kNearestNeighbours().

Parameters:

k - The number of k-NNs to find.

tree_root - The root of the cover tree on which k-NN search is to be performed.

query_root - The root of the cover tree consisting of queries.

results - The list of returned k-NNs.

Throws:

java.lang.Exception - If there is some problem during the search.

findKNearest

protected NearestNeighbourSearch.NeighborList findKNearest(Instance target,
                                                           int k)
                                                    throws java.lang.Exception

Performs k-NN serach for a single given query/test Instance.

Parameters:

target - The query/test instance.

k - Number of k-NNs to find.

Returns:

List of k-NNs.

Throws:

java.lang.Exception - If there is some problem during the search for k-NNs.

kNearestNeighbours

public Instances kNearestNeighbours(Instance target,
                                    int k)
                             throws java.lang.Exception

Returns k-NNs of a given target instance, from among the previously supplied training instances (supplied through setInstances method) P.S.: May return more than k-NNs if more one instances have the same distance to the target as the kth NN.

Specified by:

kNearestNeighbours in class NearestNeighbourSearch

Parameters:

target - The instance for which k-NNs are required.

k - The number of k-NNs to find.

Returns:

The k-NN instances of the given target instance.

Throws:

java.lang.Exception - If there is some problem find the k-NNs.

nearestNeighbour

public Instance nearestNeighbour(Instance target)
                          throws java.lang.Exception

Returns the NN instance of a given target instance, from among the previously supplied training instances.

Specified by:

nearestNeighbour in class NearestNeighbourSearch

Parameters:

target - The instance for which NN is required.

Returns:

The NN instance of the target instance.

Throws:

java.lang.Exception - If there is some problem finding the nearest neighbour.

getDistances

public double[] getDistances()
                      throws java.lang.Exception

Returns the distances of the (k)-NN(s) found earlier by kNearestNeighbours()/nearestNeighbour().

Specified by:

getDistances in class NearestNeighbourSearch

Returns:

The distances (in the same order) of the k-NNs.

Throws:

java.lang.Exception - If the tree hasn't been built (by calling setInstances()), or none of kNearestNeighbours() or nearestNeighbour() has been called before.

checkMissing

protected void checkMissing(Instances instances)
                     throws java.lang.Exception

Checks if there is any instance with missing values. Throws an exception if there is, as KDTree does not handle missing values.

Parameters:

instances - the instances to check

Throws:

java.lang.Exception - if missing values are encountered

setInstances

public void setInstances(Instances instances)
                  throws java.lang.Exception

Builds the Cover Tree on the given set of instances.

Overrides:

setInstances in class NearestNeighbourSearch

Parameters:

instances - The insts on which the Cover Tree is to be built.

Throws:

java.lang.Exception - If some error occurs while building the Cover Tree

update

public void update(Instance ins)
            throws java.lang.Exception

Adds an instance to the cover tree. P.S.: The current version doesn't allow addition of instances after batch construction.

Specified by:

update in class NearestNeighbourSearch

Parameters:

ins - The instance to add.

Throws:

java.lang.Exception - Alway throws this, as current implementation doesn't allow addition of instances after building.

addInstanceInfo

public void addInstanceInfo(Instance ins)

Adds the given instance info. This implementation updates only the range datastructures of the EuclideanDistance. Nothing is required to be updated in the built Cover Tree.

Overrides:

addInstanceInfo in class NearestNeighbourSearch

Parameters:

ins - The instance to add the information of. Usually this is the test instance supplied to update the range of attributes in the distance function.

setDistanceFunction

public void setDistanceFunction(DistanceFunction df)
                         throws java.lang.Exception

Sets the distance function to use for nearest neighbour search. Currently only EuclideanDistance is supported.

Overrides:

setDistanceFunction in class NearestNeighbourSearch

Parameters:

df - the distance function to use

Throws:

java.lang.Exception - if not EuclideanDistance

baseTipText

public java.lang.String baseTipText()

Returns the tip text for this property.

Returns:

tip text for this property suitable for displaying in the explorer/experimenter gui

getBase

public double getBase()

Returns the base in use for expansion constant.

Returns:

base currently in use.

setBase

public void setBase(double b)

Sets the base to use for expansion constant. The 2 in 2^i in the paper.

Parameters:

b - the new base;

measureTreeSize

public double measureTreeSize()

Returns the size of the tree. (number of internal nodes + number of leaves)

Returns:

the size of the tree

measureNumLeaves

public double measureNumLeaves()

Returns the number of leaves.

Returns:

the number of leaves

measureMaxDepth

public double measureMaxDepth()

Returns the depth of the tree.

Returns:

the number of rules

enumerateMeasures

public java.util.Enumeration<java.lang.String> enumerateMeasures()

Returns an enumeration of the additional measure names.

Specified by:

enumerateMeasures in interface AdditionalMeasureProducer

Overrides:

enumerateMeasures in class NearestNeighbourSearch

Returns:

an enumeration of the measure names

getMeasure

public double getMeasure(java.lang.String additionalMeasureName)

Returns the value of the named measure.

Specified by:

getMeasure in interface AdditionalMeasureProducer

Overrides:

getMeasure in class NearestNeighbourSearch

Parameters:

additionalMeasureName - the name of the measure to query for its value

Returns:

the value of the named measure

Throws:

java.lang.IllegalArgumentException - if the named measure is not supported

print

protected static void print(java.lang.String s)

Prints a string to stdout.

Parameters:

s - The string to print.

println

protected static void println(java.lang.String s)

Prints a string to stdout followed by newline.

Parameters:

s - The string to print.

print

protected static void print(java.lang.Object o)

Prints an object to stdout.

Parameters:

o - The object to print.

println

protected static void println(java.lang.Object o)

Prints an object to stdout followed by newline.

Parameters:

o - The object to print.

print_space

protected static void print_space(int s)

Prints the specified number of spaces.

Parameters:

s - The number of space characters to print.

print

protected static void print(int depth,
                            CoverTree.CoverTreeNode top_node)

Prints a cover tree starting from the given node.

Parameters:

depth - The depth of top_node.

top_node - The node to start printing from.

getRevision

public java.lang.String getRevision()

Returns the revision string.

Specified by:

getRevision in interface RevisionHandler

Returns:

the revision

main

public static void main(java.lang.String[] args)

Method for testing the class from command line.

Parameters:

args - The supplied command line arguments.