uk.ac.starlink.table.join
Class AbstractCartesianMatchEngine

java.lang.Object
  extended by uk.ac.starlink.table.join.AbstractCartesianMatchEngine
All Implemented Interfaces:
MatchEngine
Direct Known Subclasses:
AnisotropicCartesianMatchEngine, IsotropicCartesianMatchEngine

public abstract class AbstractCartesianMatchEngine
extends Object
implements MatchEngine

A matching engine which can match points in an ndim-dimensional space. All tuples (coordinate vectors) submitted to it must be -element arrays of Number objects. Tuples are considered matching if they fall within an ellipsoid defined by a scalar or vector error parameter.

This abstract class defines the mechanics of the matching, but not the match parameters, which will presumably be to do with error radii.


Field Summary
 
Fields inherited from interface uk.ac.starlink.table.join.MatchEngine
NO_BINS
 
Constructor Summary
protected AbstractCartesianMatchEngine(int ndim, boolean normaliseScores)
          Constructs a matcher which matches points in an ndim-dimensional Cartesian space.
 
Method Summary
 boolean canBoundMatch()
          Indicates that the MatchEngine.getMatchBounds(java.lang.Comparable[], java.lang.Comparable[]) method can be invoked to provide some sort of useful result.
 Object[] getBins(Object[] tuple)
          Returns a set of Cell objects representing the cell in which this tuple falls and some or all of its neighbouring ones.
 int getDimensions()
          Returns the number of dimensions of this matcher.
protected  double getError(int idim)
          Returns the matching error along a given axis.
 Comparable[][] getMatchBounds(Comparable[] minTuple, Comparable[] maxTuple)
          Given a range of tuple values, returns a range outside which no match to anything within that range can result.
abstract  DescribedValue[] getMatchParameters()
          Returns a set of DescribedValue objects whose values can be modified to modify the matching criteria.
 ValueInfo getMatchScoreInfo()
          Returns a description of the value returned by the MatchEngine.matchScore(java.lang.Object[], java.lang.Object[]) method.
 boolean getNormaliseScores()
          Indicates whether the results of the matchScore(java.lang.Object[], java.lang.Object[]) method will be normalised.
 double getScaleFactor()
          Returns the grid scaling factor.
 DescribedValue[] getTuningParameters()
          Returns a set of DescribedValue objects whose values can be modified to tune the performance of the match.
 ValueInfo[] getTupleInfos()
          Returns an array of tuple infos, one for each Cartesian dimension.
 double matchScore(Object[] tuple1, Object[] tuple2)
          Matches two tuples if they represent the coordinates of nearby points.
 void setError(int idim, double error)
          Sets one of the principal radii of the ellipsoid within which two points have to fall in order to match.
 void setNormaliseScores(boolean norm)
          Determines whether the results of the matchScore(java.lang.Object[], java.lang.Object[]) method will be normalised or not.
 void setScaleFactor(double scaleFactor)
          Sets the grid scaling factor which determines the size of a grid cell as a multiple of the size of the matching error in each dimension.
abstract  String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractCartesianMatchEngine

protected AbstractCartesianMatchEngine(int ndim,
                                       boolean normaliseScores)
Constructs a matcher which matches points in an ndim-dimensional Cartesian space. The error array (error ellipsoid dimensions) is not initialised to anything sensible by this constructor.

Parameters:
ndim - dimensionality of the space
normaliseScores - true iff you want match scores to be normalised
Method Detail

getDimensions

public int getDimensions()
Returns the number of dimensions of this matcher.

Returns:
dimensionality of Cartesian space

matchScore

public double matchScore(Object[] tuple1,
                         Object[] tuple2)
Matches two tuples if they represent the coordinates of nearby points. If they match (fall within the same error ellipsoid) the return value is a non-negative value giving the distance between them. According to the value of the normaliseScores flag, this is either the actual distance between the points (Pythagoras) or the same thing normalised to the range between 0 (same position) and 1 (on the boundary of the error ellipsoid). If they don't match, -1 is returned.

Specified by:
matchScore in interface MatchEngine
Parameters:
tuple1 - ndim-element array of Number objects representing coordinates of first object
tuple2 - ndim-element array of Number objects representing coordinates of second object
Returns:
the separation of the points represented by tuple1 and tuple2 if they match, or -1 if they don't

getMatchScoreInfo

public ValueInfo getMatchScoreInfo()
Description copied from interface: MatchEngine
Returns a description of the value returned by the MatchEngine.matchScore(java.lang.Object[], java.lang.Object[]) method. The content class should be numeric (though need not be Double), and the name, description and units should be descriptive of whatever the physical significance of the value is. If the result of matchScore is not interesting (for instance, if it's always either 0 or -1), null may be returned.

Specified by:
getMatchScoreInfo in interface MatchEngine
Returns:
metadata for the match score results

getBins

public Object[] getBins(Object[] tuple)
Returns a set of Cell objects representing the cell in which this tuple falls and some or all of its neighbouring ones.

Specified by:
getBins in interface MatchEngine
Parameters:
tuple - ndim-element array of Number objects representing coordinates of an object
Returns:
set of bin keys which might be returned by invoking this method on other tuples which count as matches for the submitted tuple

getTupleInfos

public ValueInfo[] getTupleInfos()
Returns an array of tuple infos, one for each Cartesian dimension.

Specified by:
getTupleInfos in interface MatchEngine
Returns:
array of objects describing the requirements on each element of the tuples used for matching

canBoundMatch

public boolean canBoundMatch()
Description copied from interface: MatchEngine
Indicates that the MatchEngine.getMatchBounds(java.lang.Comparable[], java.lang.Comparable[]) method can be invoked to provide some sort of useful result.

Specified by:
canBoundMatch in interface MatchEngine
Returns:
true iff getMatchBounds may provide useful information

getMatchBounds

public Comparable[][] getMatchBounds(Comparable[] minTuple,
                                     Comparable[] maxTuple)
Description copied from interface: MatchEngine
Given a range of tuple values, returns a range outside which no match to anything within that range can result. If the tuples on which this engine works represent some kind of space, the input values and output values specify a hyper-rectangular region of this space. In the common case in which the match criteria are based on proximity in this space up to a certain error, this method should return a rectangle which is like the input one but broadened in each direction by an amount corresponding to the error.

Both the input and output rectangles are specified by tuples representing its opposite corners; equivalently, they are the minimum and maximum values of each tuple element. In either the input or output min/max tuples, any element may be null to indicate that no information is available on the bounds of that tuple element (coordinate).

This method can be used by match algorithms which know in advance the range of coordinates they will match against and wish to reduce workload by not attempting matches which are bound to fail.

For example, a 1-d Cartesian match engine with an isotropic match error 0.5 would turn input values of ((0,200),(10,210)) into output values ((-0.5,199.5),(10.5,210.5)).

This method will only be called if MatchEngine.canBoundMatch() returns true. Thus engines that cannot provide any useful information along these lines (for instance because none of its tuple elements is Comparable do not need to implement it in a meaningful way.

Specified by:
getMatchBounds in interface MatchEngine
Parameters:
minTuple - tuple consisting of the minimum values of each tuple element in a possible match (to put it another way - coordinates of one corner of a tuple-space rectangle containing such a match)
maxTuple - tuple consisting of the maximum values of each tuple element in a possible match (to put it another way - coordinates of the other corner of a tuple-space rectangle containing such a match)
Returns:
2-element array of tuples - effectively (minTuple,maxTuple) broadened by errors
See Also:
MatchEngine.canBoundMatch()

getMatchParameters

public abstract DescribedValue[] getMatchParameters()
Description copied from interface: MatchEngine
Returns a set of DescribedValue objects whose values can be modified to modify the matching criteria. Typically at least one of these will be some sort of tolerance separation which determines how close tuples must be to count as a match. This match engine's behaviour can be modified by calling DescribedValue.setValue(java.lang.Object) on the returned objects.

Specified by:
getMatchParameters in interface MatchEngine
Returns:
array of described values which influence the match

getTuningParameters

public DescribedValue[] getTuningParameters()
Description copied from interface: MatchEngine
Returns a set of DescribedValue objects whose values can be modified to tune the performance of the match. This match engine's performance can be influenced by calling DescribedValue.setValue(java.lang.Object) on the returned objects.

Changing these values will make no difference to the output of MatchEngine.matchScore(java.lang.Object[], java.lang.Object[]), but may change the output of MatchEngine.getBins(java.lang.Object[]). This may change the CPU and memory requirements of the match, but will not change the result. The default value should be something sensible, so that setting the value of these parameters is not in general required.

Specified by:
getTuningParameters in interface MatchEngine
Returns:
array of described values which may influence match performance

getError

protected double getError(int idim)
Returns the matching error along a given axis. This is the principle radius of an ellipsoid within which two points must fall in order to match.

Returns:
error array

setError

public void setError(int idim,
                     double error)
Sets one of the principal radii of the ellipsoid within which two points have to fall in order to match.

Parameters:
idim - index of axis
error - error along axis idim

getScaleFactor

public double getScaleFactor()
Returns the grid scaling factor.

Returns:
grid scaling factor

setScaleFactor

public void setScaleFactor(double scaleFactor)
Sets the grid scaling factor which determines the size of a grid cell as a multiple of the size of the matching error in each dimension. It can be used as a tuning parameter. It must be >= 1.

Parameters:
scaleFactor - new scaling factor
Throws:
IllegalArgumentException - if out of range

setNormaliseScores

public void setNormaliseScores(boolean norm)
Determines whether the results of the matchScore(java.lang.Object[], java.lang.Object[]) method will be normalised or not. If norm is true, successful matches always result in a score between 0 and 1; if it's false, the score is the distance in the space defined by the supplied tuples.

If your errors are significantly anisotropic and/or your coordinates do not represent a physical space, you probably want to set this false.

Parameters:
norm - true iff you want match scores to be normalised

getNormaliseScores

public boolean getNormaliseScores()
Indicates whether the results of the matchScore(java.lang.Object[], java.lang.Object[]) method will be normalised.

Returns:
true iff match scores will be normalised

toString

public abstract String toString()
Overrides:
toString in class Object

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.