DCDs (Java Statistical Analysis Tool 0.0.8 API)

java.lang.Object
- jsat.classifiers.svm.DCDs

All Implemented Interfaces:

Serializable, Cloneable, BinaryScoreClassifier, Classifier, WarmClassifier, Parameterized, Regressor, WarmRegressor, SimpleWeightVectorModel, SingleWeightVectorModel
```
public class DCDs
extends Object
implements BinaryScoreClassifier, Regressor, Parameterized, SingleWeightVectorModel, WarmClassifier, WarmRegressor
```
Implements Dual Coordinate Descent with shrinking (DCDs) training algorithms for a Linear L¹ or L² Support Vector Machine for binary classification and regression. NOTE: While this implementation makes use of the dual formulation only the linear kernel is ever used. The algorithm also uses the primal representation and uses the explicit formulation of w in training and classification. As such, the support vectors found are not necessary once training is complete - and will be discarded.

DCDs man be warm started by other DCDs models trained on the same data set.

See:
- Hsieh, C.-J., Chang, K.-W., Lin, C.-J., Keerthi, S. S., & Sundararajan, S. (2008). A Dual Coordinate Descent Method for Large-scale Linear SVM. Proceedings of the 25th international conference on Machine learning - ICML ’08 (pp. 408–415). New York, New York, USA: ACM Press. doi:10.1145/1390156.1390208
- Ho, C.-H., & Lin, C.-J. (2012). Large-scale Linear Support Vector Regression. Journal of Machine Learning Research, 13, 3323–3348. Retrieved from here
Author:

Edward Raff

See Also:

DCD, Serialized Form

Constructor Summary

Constructors
Constructor and Description
`DCDs()` Creates a new DCDL2 SVM object
`DCDs(int maxIterations, boolean useL1)` Creates a new DCD SVM object
`DCDs(int maxIterations, double tolerance, double C, boolean useL1)` Creates a new DCD SVM object

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CategoricalResults`	`classify(DataPoint data)` Performs classification on the given data point.
`DCDs`	`clone()`
`protected static double`	`eq24(double beta_i, double gN, double gP, double U)` returns the result of evaluation equation 24 of an individual index
`double`	`getBias()` Returns the bias term used for the model, or 0 of the model does not support or was not trained with a bias term.
`double`	`getBias(int index)` Returns the bias term used with the weight vector for the given class index.
`double`	`getC()` Returns the penalty parameter for misclassifications.
`double`	`getEps()` Returns the epsilon insensitivity parameter used in regression problems.
`int`	`getMaxIterations()` Returns the maximum number of allowed training epochs
`Parameter`	`getParameter(String paramName)` Returns the parameter with the given name.
`List<Parameter>`	`getParameters()` Returns the list of parameters that can be altered for this learner.
`Vec`	`getRawWeight()` Returns the only weight vector used for the model
`Vec`	`getRawWeight(int index)` Returns the raw weight vector associated with the given class index.
`double`	`getScore(DataPoint dp)` Returns the numeric score for predicting a class of a given data point, where the sign of the value indicates which class the data point is predicted to belong to.
`double`	`getTolerance()` Returns the tolerance value used to terminate early
`static Distribution`	`guessC(DataSet d)` Guess the distribution to use for the regularization term `C` in a SVM.
`boolean`	`isUseBias()` Returns `true` if an implicit bias term is in use, or `false` if not.
`boolean`	`isUseL1()` Returns `true` if the L¹ form is in use
`int`	`numWeightsVecs()` Returns the number of weight vectors that can be returned.
`double`	`regress(DataPoint data)`
`void`	`setC(double C)` Sets the penalty parameter for misclassifications.
`void`	`setEps(double eps)` Sets the `eps` used in the epsilon insensitive loss function used when performing regression.
`void`	`setMaxIterations(int maxIterations)` Sets the maximum number of iterations allowed through the whole training set.
`void`	`setTolerance(double tolerance)` Sets the tolerance for the stopping condition when training, a small value near zero allows training to stop early when little to no additional convergence is possible.
`void`	`setUseBias(boolean useBias)` Sets whether or not an implicit bias term should be added to the inputs.
`void`	`setUseL1(boolean useL1)` Determines whether or not to use the L¹ or L² SVM
`boolean`	`supportsWeightedData()` Indicates whether the model knows how to train using weighted data points.
`void`	`train(RegressionDataSet dataSet)`
`void`	`train(RegressionDataSet dataSet, ExecutorService threadPool)`
`void`	`train(RegressionDataSet dataSet, Regressor warmSolution)` Trains the regressor and constructs a model for regression using the given data set.
`void`	`train(RegressionDataSet dataSet, Regressor warmSolution, ExecutorService threadPool)` Trains the regressor and constructs a model for regression using the given data set.
`void`	`trainC(ClassificationDataSet dataSet)` Trains the classifier and constructs a model for classification using the given data set.
`void`	`trainC(ClassificationDataSet dataSet, Classifier warmSolution)` Trains the classifier and constructs a model for classification using the given data set.
`void`	`trainC(ClassificationDataSet dataSet, Classifier warmSolution, ExecutorService threadPool)` Trains the classifier and constructs a model for classification using the given data set.
`void`	`trainC(ClassificationDataSet dataSet, ExecutorService threadPool)` Trains the classifier and constructs a model for classification using the given data set.
`boolean`	`warmFromSameDataOnly()` Some models can only be warm started from a solution trained on the exact same data set as the model it is warm starting from.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - DCDs
```
public DCDs()
```
    Creates a new DCDL2 SVM object
  - DCDs
```
public DCDs(int maxIterations,
            boolean useL1)
```
    Creates a new DCD SVM object
    
    Parameters:
    
    maxIterations - the maximum number of training iterations
    
    useL1 - whether or not to use L1 or L2 form
  - DCDs
```
public DCDs(int maxIterations,
            double tolerance,
            double C,
            boolean useL1)
```
    Creates a new DCD SVM object
    
    Parameters:
    
    maxIterations - the maximum number of training iterations
    
    tolerance - the tolerance value for early stopping
    
    C - the misclassification penalty
    
    useL1 - whether or not to use L1 or L2 form
- Method Detail
  - setC
```
public void setC(double C)
```
    Sets the penalty parameter for misclassifications. The recommended value is 1, and values larger than 4 are not normally needed according to the original paper.
    
    Parameters:
    
    C - the penalty parameter in (0, Inf)
  - getC
```
public double getC()
```
    Returns the penalty parameter for misclassifications.
    
    Returns:
    
    the penalty parameter for misclassifications.
  - setEps
```
public void setEps(double eps)
```
    Sets the eps used in the epsilon insensitive loss function used when performing regression. Errors in the output that less than eps during training are treated as correct.
    This parameter has no impact on classification problems.
    
    Parameters:
    
    eps - the non-negative value to use as the error tolerance in regression
  - getEps
```
public double getEps()
```
    Returns the epsilon insensitivity parameter used in regression problems.
    
    Returns:
    
    the epsilon insensitivity parameter used in regression problems.
  - setTolerance
```
public void setTolerance(double tolerance)
```
    Sets the tolerance for the stopping condition when training, a small value near zero allows training to stop early when little to no additional convergence is possible.
    
    Parameters:
    
    tolerance - the tolerance value to use to stop early
  - getTolerance
```
public double getTolerance()
```
    Returns the tolerance value used to terminate early
    
    Returns:
    
    the tolerance value used to terminate early
  - setUseL1
```
public void setUseL1(boolean useL1)
```
    Determines whether or not to use the L¹ or L² SVM
    
    Parameters:
    
    useL1 - true to use the L¹ form, false to use the L² form.
  - isUseL1
```
public boolean isUseL1()
```
    Returns true if the L¹ form is in use
    
    Returns:
    
    true if the L¹ form is in use
  - setMaxIterations
```
public void setMaxIterations(int maxIterations)
```
    Sets the maximum number of iterations allowed through the whole training set.
    
    Parameters:
    
    maxIterations - the maximum number of training epochs
  - getMaxIterations
```
public int getMaxIterations()
```
    Returns the maximum number of allowed training epochs
    
    Returns:
    
    the maximum number of allowed training epochs
  - setUseBias
```
public void setUseBias(boolean useBias)
```
    Sets whether or not an implicit bias term should be added to the inputs.
    
    Parameters:
    
    useBias - true to add an implicit bias term to inputs, false to use the input data as provided.
  - isUseBias
```
public boolean isUseBias()
```
    Returns true if an implicit bias term is in use, or false if not.
    
    Returns:
    
    true if an implicit bias term is in use, or false if not.
  - getRawWeight
```
public Vec getRawWeight()
```
    Description copied from interface: SingleWeightVectorModel
    
    Returns the only weight vector used for the model
    
    Specified by:
    
    getRawWeight in interface SingleWeightVectorModel
    
    Returns:
    
    the only weight vector used for the model
  - getBias
```
public double getBias()
```
    Description copied from interface: SingleWeightVectorModel
    
    Returns the bias term used for the model, or 0 of the model does not support or was not trained with a bias term.
    
    Specified by:
    
    getBias in interface SingleWeightVectorModel
    
    Returns:
    
    the bias term for the model
  - getRawWeight
```
public Vec getRawWeight(int index)
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the raw weight vector associated with the given class index. If the given class is an implicit zero vector, a ConstantVector object may be returned.
    Do not alter the returned weight vector, as it will change the model's values.
    
    If a regression problem, only index = 0 should be used
    
    Specified by:
    
    getRawWeight in interface SimpleWeightVectorModel
    
    Parameters:
    
    index - the class index to get the weight vector for
    
    Returns:
    
    the weight vector used for the specified class
  - getBias
```
public double getBias(int index)
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the bias term used with the weight vector for the given class index. If the model does not support or was not trained with bias weights, 0 will be returned.
    
    If a regression problem, only index = 0 should be used
    
    Specified by:
    
    getBias in interface SimpleWeightVectorModel
    
    Parameters:
    
    index - the class index to get the weight vector for
    
    Returns:
    
    the bias term for the specified class
  - numWeightsVecs
```
public int numWeightsVecs()
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the number of weight vectors that can be returned. For binary classification problems the value may be 1 if only a single weight vector's sign is used to determine the class. For multi-class problems, the weight vector count includes the implicit zero vector (if one is being used).
    
    Specified by:
    
    numWeightsVecs in interface SimpleWeightVectorModel
    
    Returns:
    
    the number of weight vectors for which SimpleWeightVectorModel.getRawWeight(int) can be called.
  - classify
```
public CategoricalResults classify(DataPoint data)
```
    Description copied from interface: Classifier
    
    Performs classification on the given data point.
    
    Specified by:
    
    classify in interface Classifier
    
    Parameters:
    
    data - the data point to classify
    
    Returns:
    
    the results of the classification.
  - getScore
```
public double getScore(DataPoint dp)
```
    Description copied from interface: BinaryScoreClassifier
    
    Returns the numeric score for predicting a class of a given data point, where the sign of the value indicates which class the data point is predicted to belong to.
    
    Specified by:
    
    getScore in interface BinaryScoreClassifier
    
    Parameters:
    
    dp - the data point to predict the class label of
    
    Returns:
    
    the score for the given data point
  - trainC
```
public void trainC(ClassificationDataSet dataSet,
                   ExecutorService threadPool)
```
    Description copied from interface: Classifier
    
    Trains the classifier and constructs a model for classification using the given data set. If the training method knows how, it will used the threadPool to conduct training in parallel. This method will block until the training has completed.
    
    Specified by:
    
    trainC in interface Classifier
    
    Parameters:
    
    dataSet - the data set to train on
    
    threadPool - the source of threads to use.
  - trainC
```
public void trainC(ClassificationDataSet dataSet)
```
    Description copied from interface: Classifier
    
    Trains the classifier and constructs a model for classification using the given data set.
    
    Specified by:
    
    trainC in interface Classifier
    
    Parameters:
    
    dataSet - the data set to train on
  - trainC
```
public void trainC(ClassificationDataSet dataSet,
                   Classifier warmSolution,
                   ExecutorService threadPool)
```
    Description copied from interface: WarmClassifier
    
    Trains the classifier and constructs a model for classification using the given data set. If the training method knows how, it will used the threadPool to conduct training in parallel. This method will block until the training has completed.
    
    Specified by:
    
    trainC in interface WarmClassifier
    
    Parameters:
    
    dataSet - the data set to train on
    
    warmSolution - the solution to use to warm start this model
    
    threadPool - the source of threads to use.
  - trainC
```
public void trainC(ClassificationDataSet dataSet,
                   Classifier warmSolution)
```
    Description copied from interface: WarmClassifier
    
    Trains the classifier and constructs a model for classification using the given data set.
    
    Specified by:
    
    trainC in interface WarmClassifier
    
    Parameters:
    
    dataSet - the data set to train on
    
    warmSolution - the solution to use to warm start this model
  - supportsWeightedData
```
public boolean supportsWeightedData()
```
    Description copied from interface: Classifier
    
    Indicates whether the model knows how to train using weighted data points. If it does, the model will train assuming the weights. The values returned by this method may change depending on the parameters set for the model.
    
    Specified by:
    
    supportsWeightedData in interface Classifier
    
    Specified by:
    
    supportsWeightedData in interface Regressor
    
    Returns:
    
    true if the model supports weighted data, false otherwise
  - warmFromSameDataOnly
```
public boolean warmFromSameDataOnly()
```
    Description copied from interface: WarmClassifier
    
    Some models can only be warm started from a solution trained on the exact same data set as the model it is warm starting from. If this is the case true will be returned. The behavior for training on a different data set when this is defined is undefined. It may cause an error, or it may cause the algorithm to take longer or reach a worse solution.
    When true, it is important that the data set be unaltered - this includes mutating the values stored or re-arranging the data points within the data set.
    
    Specified by:
    
    warmFromSameDataOnly in interface WarmClassifier
    
    Specified by:
    
    warmFromSameDataOnly in interface WarmRegressor
    
    Returns:
    
    true if the algorithm can only be warm started from the model trained on the exact same data set.
  - clone
```
public DCDs clone()
```
    Specified by:
    
    clone in interface BinaryScoreClassifier
    
    Specified by:
    
    clone in interface Classifier
    
    Specified by:
    
    clone in interface Regressor
    
    Overrides:
    
    clone in class Object
  - getParameters
```
public List<Parameter> getParameters()
```
    Description copied from interface: Parameterized
    
    Returns the list of parameters that can be altered for this learner.
    
    Specified by:
    
    getParameters in interface Parameterized
    
    Returns:
    
    the list of parameters that can be altered for this learner.
  - getParameter
```
public Parameter getParameter(String paramName)
```
    Description copied from interface: Parameterized
    
    Returns the parameter with the given name. Two different strings may map to a single Parameter object. An ASCII only string, and a Unicode style string.
    
    Specified by:
    
    getParameter in interface Parameterized
    
    Parameters:
    
    paramName - the name of the parameter to obtain
    
    Returns:
    
    the Parameter in question, or null if no such named Parameter exists.
  - regress
```
public double regress(DataPoint data)
```
    Specified by:
    
    regress in interface Regressor
  - train
```
public void train(RegressionDataSet dataSet,
                  Regressor warmSolution,
                  ExecutorService threadPool)
```
    Description copied from interface: WarmRegressor
    
    Trains the regressor and constructs a model for regression using the given data set. If the training method knows how, it will used the threadPool to conduct training in parallel. This method will block until the training has completed.
    
    Specified by:
    
    train in interface WarmRegressor
    
    Parameters:
    
    dataSet - the data set to train on
    
    warmSolution - the solution to use to warm start this model
    
    threadPool - the source of threads to use.
  - train
```
public void train(RegressionDataSet dataSet,
                  ExecutorService threadPool)
```
    Specified by:
    
    train in interface Regressor
  - train
```
public void train(RegressionDataSet dataSet)
```
    Specified by:
    
    train in interface Regressor
  - train
```
public void train(RegressionDataSet dataSet,
                  Regressor warmSolution)
```
    Description copied from interface: WarmRegressor
    
    Trains the regressor and constructs a model for regression using the given data set.
    
    Specified by:
    
    train in interface WarmRegressor
    
    Parameters:
    
    dataSet - the data set to train on
    
    warmSolution - the solution to use to warm start this model
  - eq24
```
protected static double eq24(double beta_i,
                             double gN,
                             double gP,
                             double U)
```
    returns the result of evaluation equation 24 of an individual index
    
    Parameters:
    
    beta_i - the weight coefficent value
    
    gN - the g'_n(beta_i) value
    
    gP - the g'_p(beta_i) value
    
    U - the upper bound value obtained from getU(double)
    
    Returns:
    
    the result of equation 24
  - guessC
```
public static Distribution guessC(DataSet d)
```
    Guess the distribution to use for the regularization term C in a SVM.
    
    Parameters:
    
    d - the data set to get the guess for
    
    Returns:
    
    the guess for the C parameter in the SVM

Class DCDs

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DCDs

DCDs

DCDs

Method Detail

setC

getC

setEps

getEps

setTolerance

getTolerance

setUseL1

isUseL1

setMaxIterations

getMaxIterations

setUseBias

isUseBias

getRawWeight

getBias

getRawWeight

getBias

numWeightsVecs

classify

getScore

trainC

trainC

trainC

trainC

supportsWeightedData

warmFromSameDataOnly

clone

getParameters

getParameter

regress

train

train

train

train

eq24

guessC