uk.ac.starlink.table.join
Class AbstractCartesianMatchEngine
java.lang.Object
|
+--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 submitted at construction
time.
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 |
static double |
CELL_SCALE
Scaling factor determining the size of a grid cell as a multiple of
the size of the matching error in each dimension. |
Constructor Summary |
protected |
AbstractCartesianMatchEngine(int ndim,
boolean normaliseScores)
Constructs a matcher which matches points in an
ndim-dimensional Cartesian space. |
CELL_SCALE
public static final double CELL_SCALE
- Scaling factor determining 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.
- See Also:
- Constant Field Values
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 spacenormaliseScores
- true iff you want match scores
to be normalised
getDimensions
public int getDimensions()
- Returns the number of dimensions of this matcher.
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 objecttuple2
- 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 somr 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
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 principle radii of the ellipsoid within which
two points have to fall in order to match.
- Parameters:
idim
- index of axiserror
- error along axis idim
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