Package weka.core.neighboursearch

# Class NearestNeighbourSearch

java.lang.Object
weka.core.neighboursearch.NearestNeighbourSearch

All Implemented Interfaces:
  `Serializable`, `AdditionalMeasureProducer`, `OptionHandler`, `RevisionHandler`

Direct Known Subclasses:
  `BallTree`, `CoverTree`, `FilteredNeighbourSearch`, `KDTree`, `LinearNNSearch`

public abstract class NearestNeighbourSearch extends Object implements Serializable, OptionHandler, AdditionalMeasureProducer, RevisionHandler
Abstract class for nearest neighbour search. All algorithms (classes) that do nearest neighbour search should extend this class.

Version:
  $Revision: 10203 $
Author:
  Ashraf M. Kibriya (amk14[at-the-rate]cs[dot]waikato[dot]ac[dot]nz)
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NearestNeighbourSearch()`
  Constructor.
  `NearestNeighbourSearch(Instances insts)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addInstanceInfo(Instance ins)`
  Adds information from the given instance without modifying the datastructure a lot.
  `static void`
  `combSort11(double[] arrayToSort, int[] linkedArray)`
  sorts the two given arrays.
  `String`
  `distanceFunctionTipText()`
  Returns the tip text for this property.
  `Enumeration<String>`
  `enumerateMeasures()`
  Returns an enumeration of the additional measure names.
  `DistanceFunction`
  `getDistanceFunction()`
  returns the distance function currently in use.
  `abstract double[]`
  `getDistances()`
  Returns the distances of the k nearest neighbours.
  `Instances`
  `getInstances()`
  returns the instances currently set.
  `double`
  `getMeasure(String additionalMeasureName)`
  Returns the value of the named measure.
  `boolean`
  `getMeasurePerformance()`
  Gets whether performance statistics are being calculated or not.
  `String[]`
  `getOptions()`
  Gets the current settings.
  `PerformanceStats`
  `getPerformanceStats()`
  Gets the class object that contains the performance statistics of the search method.
  `String`
  `globalInfo()`
  Returns a string describing this nearest neighbour search algorithm.
  `abstract Instances`
  `kNearestNeighbours(Instance target, int k)`
  Returns k nearest instances in the current neighbourhood to the supplied instance.
  `Enumeration<Option>`
  `listOptions()`
  Returns an enumeration describing the available options.
  `String`
  `measurePerformanceTipText()`
  Returns the tip text for this property.
  `abstract Instance`
  `nearestNeighbour(Instance target)`
  Returns the nearest instance in the current neighbourhood to the supplied instance.
  `static void`
  `quickSort(double[] arrayToSort, double[] linkedArray, int left, int right)`
  performs quicksort.
  `void`
  `setDistanceFunction(DistanceFunction df)`
  sets the distance function to use for nearest neighbour search.
  `void`
  `setInstances(Instances insts)`
  Sets the instances.
  `void`
  `setMeasurePerformance(boolean measurePerformance)`
  Sets whether to calculate the performance statistics or not.
  `void`
  `setOptions(String[] options)`
  Parses a given list of options.
  `abstract void`
  `update(Instance ins)`
  Updates the NearNeighbourSearch algorithm for the new added instance.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface weka.core.RevisionHandler

  `getRevision`

- ## Constructor Details

  - ### NearestNeighbourSearch

    public NearestNeighbourSearch()
    Constructor.

  - ### NearestNeighbourSearch

    public NearestNeighbourSearch(Instances insts)
    Constructor.
    Parameters:
      `insts` - The set of instances that constitute the neighbourhood.

- ## Method Details

  - ### globalInfo

    public String globalInfo()
    Returns a string describing this nearest neighbour search algorithm.
    Returns:
      a description of the algorithm for displaying in the explorer/experimenter gui

  - ### listOptions

    public Enumeration<Option> listOptions()
    Returns an enumeration describing the available options.
    Specified by:
      `listOptions` in interface `OptionHandler`
    Returns:
      an enumeration of all the available options.

  - ### setOptions

    public void setOptions(String[] options) throws Exception
    Parses a given list of options. Valid options are:
    Specified by:
      `setOptions` in interface `OptionHandler`
    Parameters:
      `options` - the list of options as an array of strings
    Throws:
      `Exception` - if an option is not supported

  - ### getOptions

    public String[] getOptions()
    Gets the current settings.
    Specified by:
      `getOptions` in interface `OptionHandler`
    Returns:
      an array of strings suitable for passing to setOptions()

  - ### distanceFunctionTipText

    public String distanceFunctionTipText()
    Returns the tip text for this property.
    Returns:
      tip text for this property suitable for displaying in the explorer/experimenter gui

  - ### getDistanceFunction

    public DistanceFunction getDistanceFunction()
    returns the distance function currently in use.
    Returns:
      the distance function

  - ### setDistanceFunction

    public void setDistanceFunction(DistanceFunction df) throws Exception
    sets the distance function to use for nearest neighbour search.
    Parameters:
      `df` - the new distance function to use
    Throws:
      `Exception` - if instances cannot be processed

  - ### measurePerformanceTipText

    public String measurePerformanceTipText()
    Returns the tip text for this property.
    Returns:
      tip text for this property suitable for displaying in the explorer/experimenter gui

  - ### getMeasurePerformance

    public boolean getMeasurePerformance()
    Gets whether performance statistics are being calculated or not.
    Returns:
      true if the measure performance is calculated

  - ### setMeasurePerformance

    public void setMeasurePerformance(boolean measurePerformance)
    Sets whether to calculate the performance statistics or not.
    Parameters:
      `measurePerformance` - if true then the performance is calculated

  - ### nearestNeighbour

    public abstract Instance nearestNeighbour(Instance target) throws Exception
    Returns the nearest instance in the current neighbourhood to the supplied instance.
    Parameters:
      `target` - The instance to find the nearest neighbour for.
    Returns:
      the nearest neighbor
    Throws:
      `Exception` - if the nearest neighbour could not be found.

  - ### kNearestNeighbours

    public abstract Instances kNearestNeighbours(Instance target, int k) throws Exception
    Returns k nearest instances in the current neighbourhood to the supplied instance.
    Parameters:
      `target` - The instance to find the k nearest neighbours for.
      `k` - The number of nearest neighbours to find.
    Returns:
      the k nearest neighbors
    Throws:
      `Exception` - if the neighbours could not be found.

  - ### getDistances

    public abstract double[] getDistances() throws Exception
    Returns the distances of the k nearest neighbours. The kNearestNeighbours or nearestNeighbour needs to be called first for this to work.
    Returns:
      the distances
    Throws:
      `Exception` - if called before calling kNearestNeighbours or nearestNeighbours.

  - ### update

    public abstract void update(Instance ins) throws Exception
    Updates the NearNeighbourSearch algorithm for the new added instance. P.S.: The method assumes the instance has already been added to the m_Instances object by the caller.
    Parameters:
      `ins` - the instance to add
    Throws:
      `Exception` - if updating fails

  - ### addInstanceInfo

    public void addInstanceInfo(Instance ins)
    Adds information from the given instance without modifying the datastructure a lot.
    Parameters:
      `ins` - the instance to add the information from

  - ### setInstances

    public void setInstances(Instances insts) throws Exception
    Sets the instances.
    Parameters:
      `insts` - the instances to use
    Throws:
      `Exception` - if setting fails

  - ### getInstances

    public Instances getInstances()
    returns the instances currently set.
    Returns:
      the current instances

  - ### getPerformanceStats

    public PerformanceStats getPerformanceStats()
    Gets the class object that contains the performance statistics of the search method.
    Returns:
      the performance statistics

  - ### enumerateMeasures

    public Enumeration<String> enumerateMeasures()
    Returns an enumeration of the additional measure names.
    Specified by:
      `enumerateMeasures` in interface `AdditionalMeasureProducer`
    Returns:
      an enumeration of the measure names

  - ### getMeasure

    public double getMeasure(String additionalMeasureName)
    Returns the value of the named measure.
    Specified by:
      `getMeasure` in interface `AdditionalMeasureProducer`
    Parameters:
      `additionalMeasureName` - the name of the measure to query for its value
    Returns:
      the value of the named measure
    Throws:
      `IllegalArgumentException` - if the named measure is not supported

  - ### combSort11

    public static void combSort11(double[] arrayToSort, int[] linkedArray)
    sorts the two given arrays.
    Parameters:
      `arrayToSort` - The array sorting should be based on.
      `linkedArray` - The array that should have the same ordering as arrayToSort.

  - ### quickSort

    public static void quickSort(double[] arrayToSort, double[] linkedArray, int left, int right)
    performs quicksort.
    Parameters:
      `arrayToSort` - the array to sort
      `linkedArray` - the linked array
      `left` - the first index of the subset
      `right` - the last index of the subset