← Back to branch summary

~ubuntu-branches/ubuntu/precise/weka/precise

« back to all changes in this revision

Viewing changes to weka/core/DistanceFunction.java

  • Committer: Bazaar Package Importer
  • Author(s): Soeren Sonnenburg
  • Date: 2008-02-24 09:18:45 UTC
  • Revision ID: james.westby@ubuntu.com-20080224091845-1l8zy6fm6xipbzsr
Tags: upstream-3.5.7+tut1
Import upstream version 3.5.7+tut1

Show diffs side-by-side

added added

removed removed

Lines of Context:
weka/core/DistanceFunction.java
 
1
/*
 
2
 *    This program is free software; you can redistribute it and/or modify
 
3
 *    it under the terms of the GNU General Public License as published by
 
4
 *    the Free Software Foundation; either version 2 of the License, or
 
5
 *    (at your option) any later version.
 
6
 *
 
7
 *    This program is distributed in the hope that it will be useful,
 
8
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 
9
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
10
 *    GNU General Public License for more details.
 
11
 *
 
12
 *    You should have received a copy of the GNU General Public License
 
13
 *    along with this program; if not, write to the Free Software
 
14
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
15
 */
 
16
 
 
17
/*
 
18
 *    DistanceFunction.java
 
19
 *    Copyright (C) 1999-2005 University of Waikato, Hamilton, New Zealand
 
20
 *
 
21
 */
 
22
 
 
23
package weka.core;
 
24
 
 
25
import weka.core.neighboursearch.PerformanceStats;
 
26
 
 
27
/**
 
28
 * Interface for any class that can compute and return distances between two
 
29
 * instances.
 
30
 *
 
31
 * @author  Ashraf M. Kibriya (amk14@cs.waikato.ac.nz)
 
32
 * @version $Revision: 1.7 $ 
 
33
 */
 
34
public interface DistanceFunction extends OptionHandler {
 
35
 
 
36
  /**
 
37
   * Sets the instances.
 
38
   * 
 
39
   * @param insts       the instances to use
 
40
   */
 
41
  public void setInstances(Instances insts);
 
42
 
 
43
  /**
 
44
   * returns the instances currently set.
 
45
   * 
 
46
   * @return            the current instances
 
47
   */
 
48
  public Instances getInstances();
 
49
 
 
50
  /**
 
51
   * Sets the range of attributes to use in the calculation of the distance.
 
52
   * The indices start from 1, 'first' and 'last' are valid as well. 
 
53
   * E.g.: first-3,5,6-last
 
54
   * 
 
55
   * @param value       the new attribute index range
 
56
   */
 
57
  public void setAttributeIndices(String value);
 
58
  
 
59
  /**
 
60
   * Gets the range of attributes used in the calculation of the distance.
 
61
   * 
 
62
   * @return            the attribute index range
 
63
   */
 
64
  public String getAttributeIndices();
 
65
  
 
66
  /**
 
67
   * Sets whether the matching sense of attribute indices is inverted or not.
 
68
   * 
 
69
   * @param value       if true the matching sense is inverted
 
70
   */
 
71
  public void setInvertSelection(boolean value);
 
72
  
 
73
  /**
 
74
   * Gets whether the matching sense of attribute indices is inverted or not.
 
75
   * 
 
76
   * @return            true if the matching sense is inverted
 
77
   */
 
78
  public boolean getInvertSelection();
 
79
 
 
80
  /**
 
81
   * Calculates the distance between two instances.
 
82
   * 
 
83
   * @param first       the first instance
 
84
   * @param second      the second instance
 
85
   * @return            the distance between the two given instances
 
86
   */
 
87
  public double distance(Instance first, Instance second);
 
88
 
 
89
  /**
 
90
   * Calculates the distance between two instances.
 
91
   * 
 
92
   * @param first       the first instance
 
93
   * @param second      the second instance
 
94
   * @param stats       the performance stats object
 
95
   * @return            the distance between the two given instances
 
96
   * @throws Exception  if calculation fails
 
97
   */
 
98
  public double distance(Instance first, Instance second, PerformanceStats stats) 
 
99
      throws Exception;
 
100
 
 
101
  /**
 
102
   * Calculates the distance between two instances. Offers speed up (if the 
 
103
   * distance function class in use supports it) in nearest neighbour search by 
 
104
   * taking into account the cutOff or maximum distance. Depending on the 
 
105
   * distance function class, post processing of the distances by 
 
106
   * postProcessDistances(double []) may be required if this function is used.
 
107
   *
 
108
   * @param first       the first instance
 
109
   * @param second      the second instance
 
110
   * @param cutOffValue If the distance being calculated becomes larger than 
 
111
   *                    cutOffValue then the rest of the calculation is 
 
112
   *                    discarded.
 
113
   * @return            the distance between the two given instances or 
 
114
   *                    Double.POSITIVE_INFINITY if the distance being 
 
115
   *                    calculated becomes larger than cutOffValue. 
 
116
   */
 
117
  public double distance(Instance first, Instance second, double cutOffValue);
 
118
 
 
119
  /**
 
120
   * Calculates the distance between two instances. Offers speed up (if the 
 
121
   * distance function class in use supports it) in nearest neighbour search by 
 
122
   * taking into account the cutOff or maximum distance. Depending on the 
 
123
   * distance function class, post processing of the distances by 
 
124
   * postProcessDistances(double []) may be required if this function is used.
 
125
   *
 
126
   * @param first       the first instance
 
127
   * @param second      the second instance
 
128
   * @param cutOffValue If the distance being calculated becomes larger than 
 
129
   *                    cutOffValue then the rest of the calculation is 
 
130
   *                    discarded.
 
131
   * @param stats       the performance stats object
 
132
   * @return            the distance between the two given instances or 
 
133
   *                    Double.POSITIVE_INFINITY if the distance being 
 
134
   *                    calculated becomes larger than cutOffValue. 
 
135
   */
 
136
  public double distance(Instance first, Instance second, 
 
137
      double cutOffValue, PerformanceStats stats);
 
138
 
 
139
  /**
 
140
   * Does post processing of the distances (if necessary) returned by
 
141
   * distance(distance(Instance first, Instance second, double cutOffValue). It
 
142
   * may be necessary, depending on the distance function, to do post processing
 
143
   * to set the distances on the correct scale. Some distance function classes
 
144
   * may not return correct distances using the cutOffValue distance function to 
 
145
   * minimize the inaccuracies resulting from floating point comparison and 
 
146
   * manipulation.
 
147
   * 
 
148
   * @param distances   the distances to post-process
 
149
   */
 
150
  public void postProcessDistances(double distances[]);
 
151
 
 
152
  /**
 
153
   * Update the distance function (if necessary) for the newly added instance.
 
154
   * 
 
155
   * @param ins         the instance to add
 
156
   */
 
157
  public void update(Instance ins);
 
158
 
 
159
}