weka.classifiers.misc.monotone
Class OSDLCore

java.lang.Object
  extended by weka.classifiers.Classifier
      extended by weka.classifiers.misc.monotone.OSDLCore
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, CapabilitiesHandler, OptionHandler, RevisionHandler, TechnicalInformationHandler
Direct Known Subclasses:
OSDL

public abstract class OSDLCore
extends Classifier
implements TechnicalInformationHandler

This class is an implementation of the Ordinal Stochastic Dominance Learner.
Further information regarding the OSDL-algorithm can be found in:

S. Lievens, B. De Baets, K. Cao-Van (2006). A Probabilistic Framework for the Design of Instance-Based Supervised Ranking Algorithms in an Ordinal Setting. Annals of Operations Research..

Kim Cao-Van (2003). Supervised ranking: from semantics to algorithms.

Stijn Lievens (2004). Studie en implementatie van instantie-gebaseerde algoritmen voor gesuperviseerd rangschikken.

For more information about supervised ranking, see

http://users.ugent.be/~slievens/supervised_ranking.php

BibTeX:

 @article{Lievens2006,
    author = {S. Lievens and B. De Baets and K. Cao-Van},
    journal = {Annals of Operations Research},
    title = {A Probabilistic Framework for the Design of Instance-Based Supervised Ranking Algorithms in an Ordinal Setting},
    year = {2006}
 }
 
 @phdthesis{Cao-Van2003,
    author = {Kim Cao-Van},
    school = {Ghent University},
    title = {Supervised ranking: from semantics to algorithms},
    year = {2003}
 }
 
 @mastersthesis{Lievens2004,
    author = {Stijn Lievens},
    school = {Ghent University},
    title = {Studie en implementatie van instantie-gebaseerde algoritmen voor gesuperviseerd rangschikken},
    year = {2004}
 }
 

Valid options are:

 -D
  If set, classifier is run in debug mode and
  may output additional info to the console
 -C <REG|WSUM|MAX|MED|RMED>
  Sets the classification type to be used.
  (Default: MED)
 -B
  Use the balanced version of the Ordinal Stochastic Dominance Learner
 -W
  Use the weighted version of the Ordinal Stochastic Dominance Learner
 -S <value of interpolation parameter>
  Sets the value of the interpolation parameter (not with -W/T/P/L/U)
  (default: 0.5).
 -T
  Tune the interpolation parameter (not with -W/S)
  (default: off)
 -L <Lower bound for interpolation parameter>
  Lower bound for the interpolation parameter (not with -W/S)
  (default: 0)
 -U <Upper bound for interpolation parameter>
  Upper bound for the interpolation parameter (not with -W/S)
  (default: 1)
 -P <Number of parts>
  Determines the step size for tuning the interpolation
  parameter, nl. (U-L)/P (not with -W/S)
  (default: 10)

Version:
$Revision: 1.1 $
Author:
Stijn Lievens (stijn.lievens@ugent.be)
See Also:
Serialized Form

Field Summary
static int CT_MAXPROB
          Constant indicating that the classification type is the mode of the distribution.
static int CT_MEDIAN
          Constant indicating that the classification type is the median.
static int CT_MEDIAN_REAL
          Constant indicating that the classification type is the median, but not rounded to the nearest class.
static int CT_REGRESSION
          Constant indicating that the classification type is regression (probabilistic weighted sum).
static int CT_WEIGHTED_SUM
          Constant indicating that the classification type is the probabilistic weighted sum.
static Tag[] TAGS_CLASSIFICATIONTYPES
          the classification types
 
Constructor Summary
OSDLCore()
           
 
Method Summary
 java.lang.String balancedTipText()
          Returns a string suitable for displaying in the gui/experimenter.
 void buildClassifier(Instances instances)
          Builds the classifier.
 java.lang.String classificationTypeTipText()
          Returns the tip text for this property.
 double classifyInstance(Instance instance)
          Classifies a given instance using the current settings of the classifier.
 double crossValidate()
          Tunes the interpolation parameter using the current settings of the classifier.
 double crossValidate(double sLow, double sUp, int sNrParts, int ctype)
          Tune the interpolation parameter using leave-one-out cross validation, the loss function used is the 1-0 loss function.
 double crossValidate(double sLow, double sUp, int sNrParts, int ctype, double[] performanceStats, NominalLossFunction lossFunction)
          Tune the interpolation parameter using leave-one-out cross validation.
 double[] cumulativeDistributionForInstance(Instance instance)
          Calculates the cumulative class probabilities for the given test instance.
 double[] distributionForInstance(Instance instance)
          Calculates the class probabilities for the given test instance.
 boolean getBalanced()
          Returns if the balanced version of OSDL is in effect.
 Capabilities getCapabilities()
          Returns default capabilities of the classifier.
 SelectedTag getClassificationType()
          Returns the classification type.
 double getInterpolationParameter()
          Returns the current value of the interpolation parameter.
 double getInterpolationParameterLowerBound()
          Returns the lower bound for the interpolation parameter tuning (0 <= x < 1).
 double getInterpolationParameterUpperBound()
          Returns the upper bound for the interpolation parameter tuning (0 < x <= 1).
 double getLowerBound()
          Returns the current value of the lower bound for the interpolation parameter.
 int getNumberOfPartsForInterpolationParameter()
          Gets the granularity for tuning the interpolation parameter.
 int getNumInstances()
          Returns the number of instances in the training set.
 java.lang.String[] getOptions()
          Gets the current settings of the OSDLCore classifier.
 TechnicalInformation getTechnicalInformation()
          Returns an instance of a TechnicalInformation object, containing detailed information about the technical background of this class, e.g., paper reference or book this class is based on.
 boolean getTuneInterpolationParameter()
          Returns whether the interpolation parameter is to be tuned based on the bounds.
 double getUpperBound()
          Returns the current value of the upper bound for the interpolation parameter.
 boolean getWeighted()
          Returns if the weighted version is in effect.
 java.lang.String globalInfo()
          Returns a string describing the classifier.
 java.lang.String interpolationParameterLowerBoundTipText()
          Returns the tip text for this property.
 java.lang.String interpolationParameterTipText()
          Returns the tip text for this property.
 java.lang.String interpolationParameterUpperBoundTipText()
          Returns the tip text for this property.
 java.util.Enumeration listOptions()
          Returns an enumeration describing the available options.
 java.lang.String numberOfPartsForInterpolationParameterTipText()
          Returns the tip text for this property.
 void setBalanced(boolean balanced)
          If balanced is true then the balanced version of OSDL will be used, otherwise the ordinary version of OSDL will be in effect.
 void setClassificationType(SelectedTag value)
          Sets the classification type.
 void setInterpolationParameter(double s)
          Sets the interpolation parameter.
 void setInterpolationParameterBounds(double sLow, double sUp)
          Sets the interpolation bounds for the interpolation parameter.
 void setInterpolationParameterLowerBound(double value)
          Sets the lower bound for the interpolation parameter tuning (0 <= x < 1).
 void setInterpolationParameterUpperBound(double value)
          Sets the upper bound for the interpolation parameter tuning (0 < x <= 1).
 void setNumberOfPartsForInterpolationParameter(int sParts)
          Sets the granularity for tuning the interpolation parameter.
 void setOptions(java.lang.String[] options)
          Parses the options for this object.
 void setTuneInterpolationParameter(boolean value)
          Sets whether the interpolation parameter is to be tuned based on the bounds.
 void setWeighted(boolean weighted)
          If weighted is true then the weighted version of the OSDL is used.
 java.lang.String toString()
          Returns a description of the classifier.
 double tuneInterpolationParameter()
          Tune the interpolation parameter using the current settings of the classifier.
 double tuneInterpolationParameter(double sLow, double sUp, int sParts, int ctype)
          Tunes the interpolation parameter using the given settings.
 java.lang.String tuneInterpolationParameterTipText()
          Returns the tip text for this property.
 java.lang.String weightedTipText()
          Returns a string suitable for displaying in the gui/experimenter.
 
Methods inherited from class weka.classifiers.Classifier
debugTipText, forName, getDebug, makeCopies, makeCopy, setDebug
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface weka.core.RevisionHandler
getRevision
 

Field Detail

CT_REGRESSION

public static final int CT_REGRESSION
Constant indicating that the classification type is regression (probabilistic weighted sum).

See Also:
Constant Field Values

CT_WEIGHTED_SUM

public static final int CT_WEIGHTED_SUM
Constant indicating that the classification type is the probabilistic weighted sum.

See Also:
Constant Field Values

CT_MAXPROB

public static final int CT_MAXPROB
Constant indicating that the classification type is the mode of the distribution.

See Also:
Constant Field Values

CT_MEDIAN

public static final int CT_MEDIAN
Constant indicating that the classification type is the median.

See Also:
Constant Field Values

CT_MEDIAN_REAL

public static final int CT_MEDIAN_REAL
Constant indicating that the classification type is the median, but not rounded to the nearest class.

See Also:
Constant Field Values

TAGS_CLASSIFICATIONTYPES

public static final Tag[] TAGS_CLASSIFICATIONTYPES
the classification types

Constructor Detail

OSDLCore

public OSDLCore()
Method Detail

globalInfo

public java.lang.String globalInfo()
Returns a string describing the classifier.

Returns:
a description suitable for displaying in the explorer/experimenter gui

getTechnicalInformation

public TechnicalInformation getTechnicalInformation()
Returns an instance of a TechnicalInformation object, containing detailed information about the technical background of this class, e.g., paper reference or book this class is based on.

Specified by:
getTechnicalInformation in interface TechnicalInformationHandler
Returns:
the technical information about this class

getCapabilities

public Capabilities getCapabilities()
Returns default capabilities of the classifier.

Specified by:
getCapabilities in interface CapabilitiesHandler
Overrides:
getCapabilities in class Classifier
Returns:
the capabilities of this classifier
See Also:
Capabilities

classifyInstance

public double classifyInstance(Instance instance)
                        throws java.lang.Exception
Classifies a given instance using the current settings of the classifier.

Overrides:
classifyInstance in class Classifier
Parameters:
instance - the instance to be classified
Returns:
the classification for the instance. Depending on the settings of the classifier this is a double representing a classlabel (internal WEKA format) or a real value in the sense of regression.
Throws:
java.lang.Exception - if for some reason no distribution could be predicted

distributionForInstance

public double[] distributionForInstance(Instance instance)
Calculates the class probabilities for the given test instance. Uses the current settings of the parameters if these are valid. If necessary it updates the interpolationparameter first, and hence this may change the classifier.

Overrides:
distributionForInstance in class Classifier
Parameters:
instance - the instance to be classified
Returns:
an array of doubles representing the predicted probability distribution over the class labels

cumulativeDistributionForInstance

public double[] cumulativeDistributionForInstance(Instance instance)
Calculates the cumulative class probabilities for the given test instance. Uses the current settings of the parameters if these are valid. If necessary it updates the interpolationparameter first, and hence this may change the classifier.

Parameters:
instance - the instance to be classified
Returns:
an array of doubles representing the predicted cumulative probability distribution over the class labels

buildClassifier

public void buildClassifier(Instances instances)
                     throws java.lang.Exception
Builds the classifier. This means that all relevant examples are stored into memory. If necessary the interpolation parameter is tuned.

Specified by:
buildClassifier in class Classifier
Parameters:
instances - the instances to be used for building the classifier
Throws:
java.lang.Exception - if the classifier can't be built successfully

classificationTypeTipText

public java.lang.String classificationTypeTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setClassificationType

public void setClassificationType(SelectedTag value)
Sets the classification type. Currently ctype must be one of:

Parameters:
value - the classification type

getClassificationType

public SelectedTag getClassificationType()
Returns the classification type.

Returns:
the classification type

tuneInterpolationParameterTipText

public java.lang.String tuneInterpolationParameterTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setTuneInterpolationParameter

public void setTuneInterpolationParameter(boolean value)
Sets whether the interpolation parameter is to be tuned based on the bounds.

Parameters:
value - if true the parameter is tuned

getTuneInterpolationParameter

public boolean getTuneInterpolationParameter()
Returns whether the interpolation parameter is to be tuned based on the bounds.

Returns:
true if the parameter is to be tuned

interpolationParameterLowerBoundTipText

public java.lang.String interpolationParameterLowerBoundTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setInterpolationParameterLowerBound

public void setInterpolationParameterLowerBound(double value)
Sets the lower bound for the interpolation parameter tuning (0 <= x < 1).

Parameters:
value - the tne lower bound
Throws:
java.lang.IllegalArgumentException - if bound is invalid

getInterpolationParameterLowerBound

public double getInterpolationParameterLowerBound()
Returns the lower bound for the interpolation parameter tuning (0 <= x < 1).

Returns:
the lower bound

interpolationParameterUpperBoundTipText

public java.lang.String interpolationParameterUpperBoundTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setInterpolationParameterUpperBound

public void setInterpolationParameterUpperBound(double value)
Sets the upper bound for the interpolation parameter tuning (0 < x <= 1).

Parameters:
value - the tne upper bound
Throws:
java.lang.IllegalArgumentException - if bound is invalid

getInterpolationParameterUpperBound

public double getInterpolationParameterUpperBound()
Returns the upper bound for the interpolation parameter tuning (0 < x <= 1).

Returns:
the upper bound

setInterpolationParameterBounds

public void setInterpolationParameterBounds(double sLow,
                                            double sUp)
                                     throws java.lang.IllegalArgumentException
Sets the interpolation bounds for the interpolation parameter. When tuning the interpolation parameter only values in the interval [sLow, sUp] are considered. It is important to note that using this method immediately implies that the interpolation parameter is to be tuned.

Parameters:
sLow - lower bound for the interpolation parameter, should not be smaller than 0 or greater than sUp
sUp - upper bound for the interpolation parameter, should not exceed 1 or be smaller than sLow
Throws:
java.lang.IllegalArgumentException - if one of the above conditions is not satisfied.

interpolationParameterTipText

public java.lang.String interpolationParameterTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setInterpolationParameter

public void setInterpolationParameter(double s)
                               throws java.lang.IllegalArgumentException
Sets the interpolation parameter. This immediately means that the interpolation parameter is not to be tuned.

Parameters:
s - value for the interpolation parameter.
Throws:
java.lang.IllegalArgumentException - if s is not in the range [0,1].

getInterpolationParameter

public double getInterpolationParameter()
Returns the current value of the interpolation parameter.

Returns:
the value of the interpolation parameter

numberOfPartsForInterpolationParameterTipText

public java.lang.String numberOfPartsForInterpolationParameterTipText()
Returns the tip text for this property.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setNumberOfPartsForInterpolationParameter

public void setNumberOfPartsForInterpolationParameter(int sParts)
                                               throws java.lang.IllegalArgumentException
Sets the granularity for tuning the interpolation parameter. The interval between lower and upper bounds for the interpolation parameter is divided into sParts parts, i.e. sParts + 1 values will be checked when tuneInterpolationParameter is invoked. This also means that the interpolation parameter is to be tuned.

Parameters:
sParts - the number of parts
Throws:
java.lang.IllegalArgumentException - if sParts is smaller or equal than 0.

getNumberOfPartsForInterpolationParameter

public int getNumberOfPartsForInterpolationParameter()
Gets the granularity for tuning the interpolation parameter.

Returns:
the number of parts in which the interval [s_low, s_up] is to be split

balancedTipText

public java.lang.String balancedTipText()
Returns a string suitable for displaying in the gui/experimenter.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setBalanced

public void setBalanced(boolean balanced)
If balanced is true then the balanced version of OSDL will be used, otherwise the ordinary version of OSDL will be in effect.

Parameters:
balanced - if true then B-OSDL is used, otherwise it is OSDL

getBalanced

public boolean getBalanced()
Returns if the balanced version of OSDL is in effect.

Returns:
true if the balanced version is in effect, false otherwise

weightedTipText

public java.lang.String weightedTipText()
Returns a string suitable for displaying in the gui/experimenter.

Returns:
tip text for this property suitable for displaying in the explorer/experimenter gui

setWeighted

public void setWeighted(boolean weighted)
If weighted is true then the weighted version of the OSDL is used. Note: using the weighted (non-balanced) version only ensures the quasi monotonicity of the results w.r.t. to training set.

Parameters:
weighted - true if the weighted version to be used, false otherwise

getWeighted

public boolean getWeighted()
Returns if the weighted version is in effect.

Returns:
true if the weighted version is in effect, false otherwise.

getLowerBound

public double getLowerBound()
Returns the current value of the lower bound for the interpolation parameter.

Returns:
the current value of the lower bound for the interpolation parameter

getUpperBound

public double getUpperBound()
Returns the current value of the upper bound for the interpolation parameter.

Returns:
the current value of the upper bound for the interpolation parameter

getNumInstances

public int getNumInstances()
Returns the number of instances in the training set.

Returns:
the number of instances used for training

tuneInterpolationParameter

public double tuneInterpolationParameter()
Tune the interpolation parameter using the current settings of the classifier. This also sets the interpolation parameter.

Returns:
the value of the tuned interpolation parameter.

tuneInterpolationParameter

public double tuneInterpolationParameter(double sLow,
                                         double sUp,
                                         int sParts,
                                         int ctype)
                                  throws java.lang.IllegalArgumentException
Tunes the interpolation parameter using the given settings. The parameters of the classifier are updated accordingly! Marks the interpolation parameter as valid.

Parameters:
sLow - lower end point of interval of paramters to be examined
sUp - upper end point of interval of paramters to be examined
sParts - number of parts the interval is divided into. This thus determines the granularity of the search
ctype - the classification type to use
Returns:
the value of the tuned interpolation parameter
Throws:
java.lang.IllegalArgumentException - if the given parameter list is not valid

crossValidate

public double crossValidate()
                     throws java.lang.IllegalArgumentException
Tunes the interpolation parameter using the current settings of the classifier. This doesn't change the classifier, i.e. none of the internal parameters is changed!

Returns:
the tuned value of the interpolation parameter
Throws:
java.lang.IllegalArgumentException - if somehow the current settings of the classifier are illegal.

crossValidate

public double crossValidate(double sLow,
                            double sUp,
                            int sNrParts,
                            int ctype)
                     throws java.lang.IllegalArgumentException
Tune the interpolation parameter using leave-one-out cross validation, the loss function used is the 1-0 loss function.

The given settings are used, but the classifier is not updated!. Also, the interpolation parameter s is not set.

Parameters:
sLow - lower end point of interval of paramters to be examined
sUp - upper end point of interval of paramters to be examined
sNrParts - number of parts the interval is divided into. This thus determines the granularity of the search
ctype - the classification type to use
Returns:
the best value for the interpolation parameter
Throws:
java.lang.IllegalArgumentException - if the settings for the interpolation parameter are not valid or if the classification type is not valid

crossValidate

public double crossValidate(double sLow,
                            double sUp,
                            int sNrParts,
                            int ctype,
                            double[] performanceStats,
                            NominalLossFunction lossFunction)
                     throws java.lang.IllegalArgumentException
Tune the interpolation parameter using leave-one-out cross validation. The given parameters are used, but the classifier is not changed, in particular, the interpolation parameter remains unchanged.

Parameters:
sLow - lower bound for interpolation parameter
sUp - upper bound for interpolation parameter
sNrParts - determines the granularity of the search
ctype - the classification type to use
performanceStats - array acting as output, and that will contain the total loss of the leave-one-out cross validation for each considered value of the interpolation parameter
lossFunction - the loss function to use
Returns:
the value of the interpolation parameter that is considered best
Throws:
java.lang.IllegalArgumentException - the length of the array performanceStats is not sufficient
java.lang.IllegalArgumentException - if the interpolation parameters are not valid
java.lang.IllegalArgumentException - if the classification type is not valid

listOptions

public java.util.Enumeration listOptions()
Returns an enumeration describing the available options. For a list of available options, see setOptions .

Specified by:
listOptions in interface OptionHandler
Overrides:
listOptions in class Classifier
Returns:
an enumeration of all available options.

setOptions

public void setOptions(java.lang.String[] options)
                throws java.lang.Exception
Parses the options for this object.

Valid options are:

 -D
  If set, classifier is run in debug mode and
  may output additional info to the console
 -C <REG|WSUM|MAX|MED|RMED>
  Sets the classification type to be used.
  (Default: MED)
 -B
  Use the balanced version of the Ordinal Stochastic Dominance Learner
 -W
  Use the weighted version of the Ordinal Stochastic Dominance Learner
 -S <value of interpolation parameter>
  Sets the value of the interpolation parameter (not with -W/T/P/L/U)
  (default: 0.5).
 -T
  Tune the interpolation parameter (not with -W/S)
  (default: off)
 -L <Lower bound for interpolation parameter>
  Lower bound for the interpolation parameter (not with -W/S)
  (default: 0)
 -U <Upper bound for interpolation parameter>
  Upper bound for the interpolation parameter (not with -W/S)
  (default: 1)
 -P <Number of parts>
  Determines the step size for tuning the interpolation
  parameter, nl. (U-L)/P (not with -W/S)
  (default: 10)

Specified by:
setOptions in interface OptionHandler
Overrides:
setOptions in class Classifier
Parameters:
options - the list of options as an array of strings
Throws:
java.lang.Exception - if an option is not supported

getOptions

public java.lang.String[] getOptions()
Gets the current settings of the OSDLCore classifier.

Specified by:
getOptions in interface OptionHandler
Overrides:
getOptions in class Classifier
Returns:
an array of strings suitable for passing to setOptions

toString

public java.lang.String toString()
Returns a description of the classifier. Attention: if debugging is on, the description can be become very lengthy.

Overrides:
toString in class java.lang.Object
Returns:
a string containing the description