viper.comparison.distances
Class Distances

java.lang.Object
  viper.comparison.distances.Distances

public class Distances

extends java.lang.Object

Utility class containing a variety of different standard distance measures.

Nested Class Summary

static class	Distances.DefaultDifference A simple differnece object, which keeps track of some information about a computed difference.
static class	Distances.HelperAttrDistance Converts one of the value distance function objects into a AttrDistance.
static class	Distances.HelperMeasureDistance Converts one of the value distance function objects into a MeasureDistance.
static interface	Distances.QuickValueDistance Sometimes, it is convenient to save on computations for values that are compared over-and-over; this distance functor allows cacheing operations when performing multiple comparisons between the same attributes.
static interface	Distances.SmartValueDistance An extended distance function object that can deal with both don't-care values and blackout values.
static interface	Distances.ValueDistance An interface for simplifying implementation of a distance metric; instead of implementing all of AttrDistance, you can just pass this to Distances.HelperAttrDistance.

Field Summary

static double	alpha The coefficient to use with closedDistanceRangeToInfinite(double, double) and infiniteDistanceRangeToClosed(double, double).
static int	MAXIMUM The maximum value statistic.
static int	MEAN The average statistic.
static int	MEDIAN The median value statistic.
static int	MINIMUM The minimum value statistic.

Constructor Summary

Distances()

Method Summary

static boolean	check(java.lang.String type) Check to make sure that the specified attribute has been loaded into the virtual machine.
static double	closedDistanceRangeToInfinite(double distance, double maximum) Converts from the range zero to one to zero to the specified maximum.
static int	getDefaultStatistic() Gets the default statistic to use when comparing descriptors at the 'statistic' level.
static double	getDefaultSTolerance() Gets the default tolerance to apply to the statistic measure of a descriptor to count it as 'statisticked'.
static Distance	getDistanceFunctor(Measurable type, java.lang.String metric) Gets the distance functor for the given type.
static Distance	getDistanceFunctor(java.lang.String type, java.lang.String metric) Gets the distance functor for the given type.
static AttrDistance	getEqualityDistance() Get an AttrDistance object that returns 0 when the attributes are equal (using .equals) or 1 when they are not.
static Measurable.Difference	helpGetDiff(Attribute alpha, FrameSpan alphaSpan, Attribute beta, FrameSpan betaSpan, Attribute blackout, FrameSpan blackoutSpan, Attribute ignore, FrameSpan ignoreSpan, int frame, CanonicalFileDescriptor cfd, Measurable.Difference old) Computes the difference between two attributes using the given distance metric.
static Measurable.Difference	helpGetDiff(Measurable alpha, Measurable beta, Measurable blackout, Measurable ignore, CanonicalFileDescriptor cfd, Measurable.Difference old) Computes the difference between two attributes using the given distance metric.
static double	infiniteDistanceRangeToClosed(double distance, double maximum) Converts from a positive infinite range to the range from zero to maxiumum.
static boolean	isDistanceFor(Measurable type, java.lang.String s) Tests to see if the specified metric name is known for the given attribute data type.
static boolean	isDistanceFor(java.lang.String type, java.lang.String s) Tests to see if the specified metric name is known for the given attribute data type.
static void	putDistanceFunctorFor(java.lang.String type, Distance d) Adds a new distance functor for the given attribute data type.
static void	setDefaultStatistic(java.lang.String s) Sets the default statistic to use when comparing descriptors at the 'statistic' level.
static void	setDefaultSTolerance(double t) Set the default threshold for the level 3-statistic measure.
static void	useSameDistances(java.lang.String to, java.lang.String from) Copies all the distance functors from from attribute type to to attribute type.

Methods inherited from class java.lang.Object

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

Field Detail

alpha

public static double alpha

The coefficient to use with closedDistanceRangeToInfinite(double, double) and infiniteDistanceRangeToClosed(double, double).

MEAN

public static final int MEAN

The average statistic.

See Also:

Constant Field Values

MINIMUM

public static final int MINIMUM

The minimum value statistic.

See Also:

Constant Field Values

MEDIAN

public static final int MEDIAN

The median value statistic.

See Also:

Constant Field Values

MAXIMUM

public static final int MAXIMUM

The maximum value statistic.

See Also:

Constant Field Values

Constructor Detail

Distances

public Distances()

Method Detail

getEqualityDistance

public static AttrDistance getEqualityDistance()

Get an AttrDistance object that returns 0 when the attributes are equal (using .equals) or 1 when they are not.

Returns:

the equality distance measure

helpGetDiff

public static Measurable.Difference helpGetDiff(Attribute alpha,
                                                FrameSpan alphaSpan,
                                                Attribute beta,
                                                FrameSpan betaSpan,
                                                Attribute blackout,
                                                FrameSpan blackoutSpan,
                                                Attribute ignore,
                                                FrameSpan ignoreSpan,
                                                int frame,
                                                CanonicalFileDescriptor cfd,
                                                Measurable.Difference old)
                                         throws IgnoredValueException

Computes the difference between two attributes using the given distance metric. This function takes care of things like dynamic attributes and null values. This one allows reclamation of a difference object.

Parameters:

alpha - the target attribute

alphaSpan - the target attribute's span

beta - the candidate attribute

betaSpan - the candidate attribute's framespan

blackout - the blackout data

blackoutSpan - when the blackout is defined

ignore - the don't-care data

ignoreSpan - the don't-care framespan

frame - the frame to compare

cfd - information about the media

old - cached difference object

Returns:

the new difference object, or the same one, changed

Throws:

IgnoredValueException - if the whole of the data on the frame was ignored

helpGetDiff

public static Measurable.Difference helpGetDiff(Measurable alpha,
                                                Measurable beta,
                                                Measurable blackout,
                                                Measurable ignore,
                                                CanonicalFileDescriptor cfd,
                                                Measurable.Difference old)
                                         throws IgnoredValueException

Computes the difference between two attributes using the given distance metric. This must operate on the attribute values directly

Parameters:

alpha - the target attribute

beta - the candidate attribute

blackout - the blackout data

ignore - the don't-care data

cfd - information about the media

old - cached difference object

Returns:

the difference

Throws:

IgnoredValueException - if the whole of the data on the frame was ignored

putDistanceFunctorFor

public static final void putDistanceFunctorFor(java.lang.String type,
                                               Distance d)

Adds a new distance functor for the given attribute data type.

Parameters:

type - the attribute data type

d - the distance functor to use on the data type

isDistanceFor

public static final boolean isDistanceFor(Measurable type,
                                          java.lang.String s)
                                   throws UnknownDistanceException

Tests to see if the specified metric name is known for the given attribute data type.

Parameters:

type - the attribute type

s - the name of the distance metric to look for

Returns:

true if s is the name of a known metric for the type

Throws:

UnknownDistanceException - if the type is unknown. XXX: shouldn't this be the other way around?

isDistanceFor

public static final boolean isDistanceFor(java.lang.String type,
                                          java.lang.String s)
                                   throws UnknownDistanceException

Tests to see if the specified metric name is known for the given attribute data type.

Parameters:

type - the attribute type

s - the name of the distance metric to look for

Returns:

true if s is the name of a known metric for the type

Throws:

UnknownDistanceException - if the type is unknown. XXX: shouldn't this be the other way around?

getDistanceFunctor

public static final Distance getDistanceFunctor(Measurable type,
                                                java.lang.String metric)
                                         throws UnknownDistanceException

Gets the distance functor for the given type.

Parameters:

type - the attribute data type

metric - the metric name

Returns:

the metric

Throws:

UnknownDistanceException - if the metric isn't found

check

public static final boolean check(java.lang.String type)

Check to make sure that the specified attribute has been loaded into the virtual machine.

Parameters:

type - the name of the attribute to check

Returns:

true if the attribute has been or can be loaded

getDistanceFunctor

public static final Distance getDistanceFunctor(java.lang.String type,
                                                java.lang.String metric)
                                         throws UnknownDistanceException

Gets the distance functor for the given type.

Parameters:

type - the attribute data type

metric - the metric name

Returns:

the metric

Throws:

UnknownDistanceException - if the metric isn't found

useSameDistances

public static final void useSameDistances(java.lang.String to,
                                          java.lang.String from)

Copies all the distance functors from from attribute type to to attribute type.

Parameters:

to - the attribute type to get the copies

from - the attribute type to receive the distance functor references

closedDistanceRangeToInfinite

public static double closedDistanceRangeToInfinite(double distance,
                                                   double maximum)

Converts from the range zero to one to zero to the specified maximum. It uses a log value.

Parameters:

distance - the distance

maximum - the max

Returns:

the undamped distance

See Also:

infiniteDistanceRangeToClosed(double, double)

infiniteDistanceRangeToClosed

public static double infiniteDistanceRangeToClosed(double distance,
                                                   double maximum)

Converts from a positive infinite range to the range from zero to maxiumum. Uses an exponential conversion.

Parameters:

distance - a (possibly very great) distance

maximum - the new maximum value.

Returns:

the clamped value

See Also:

closedDistanceRangeToInfinite(double, double)

setDefaultSTolerance

public static void setDefaultSTolerance(double t)

Set the default threshold for the level 3-statistic measure.

Parameters:

t - sets the default tolerance level

getDefaultSTolerance

public static double getDefaultSTolerance()

Gets the default tolerance to apply to the statistic measure of a descriptor to count it as 'statisticked'.

Returns:

the default statistic tolerance

getDefaultStatistic

public static int getDefaultStatistic()

Gets the default statistic to use when comparing descriptors at the 'statistic' level.

Returns:

MEDIAN, for example

setDefaultStatistic

public static void setDefaultStatistic(java.lang.String s)
                                throws ImproperMetricException

Sets the default statistic to use when comparing descriptors at the 'statistic' level. The string must be either "mean", "minimum", "median", or "maximum".

Parameters:

s - MEDIAN, for example

Throws:

ImproperMetricException - not a known metric.