## org.apache.mahout.classifier.sgd
Class GradientMachine

    java.lang.Object
      org.apache.mahout.classifier.AbstractVectorClassifier
          org.apache.mahout.classifier.sgd.GradientMachine

All Implemented Interfaces:
  Closeable, org.apache.hadoop.io.Writable, OnlineLearner

    public class GradientMachine

extends AbstractVectorClassifier
implements OnlineLearner, org.apache.hadoop.io.Writable

Online gradient machine learner that tries to minimize the label ranking hinge loss. Implements a gradient machine with one sigmpod hidden layer. It tries to minimize the ranking loss of some given set of labels, so this can be used for multi-class, multi-label or auto-encoding of sparse data (e.g. text).

Field Summary
`static int` `WRITABLE_VERSION`

Fields inherited from class org.apache.mahout.classifier.AbstractVectorClassifier
`MIN_LOG_LIKELIHOOD`

Constructor Summary
`GradientMachine(int numFeatures, int numHidden, int numOutput)`

Method Summary
`Vector` `classify(Vector instance)` Compute and return a vector containing `n-1` scores, where `n` is equal to `numCategories()`, given an input vector `instance`.
`Vector` `classifyNoLink(Vector instance)` Compute and return a vector of scores before applying the inverse link function.
`double` `classifyScalar(Vector instance)` Classifies a vector in the special case of a binary classifier where `AbstractVectorClassifier.classify(Vector)` would return a vector with only one element.
`void` `close()` Prepares the classifier for classification and deallocates any temporary data structures.
`GradientMachine` `copy()`
`void` `copyFrom(GradientMachine other)`
`DenseVector` `hiddenToOutput(Vector hiddenActivation)` Feeds forward from hidden to output
`void` `initWeights(Random gen)` Initialize weights.
`DenseVector` `inputToHidden(Vector input)` Feeds forward from input to hidden unit..
`GradientMachine` `learningRate(double learningRate)` Chainable configuration option.
`int` `numCategories()` Returns the number of categories that a target variable can be assigned to.
`int` `numFeatures()`
`int` `numHidden()`
`void` `readFields(DataInput in)`
`GradientMachine` `regularization(double regularization)` Chainable configuration option.
`GradientMachine` `sparsity(double sparsity)` Chainable configuration option.
`GradientMachine` `sparsityLearningRate(double sparsityLearningRate)` Chainable configuration option.
`void` `train(int actual, Vector instance)` Updates the model using a particular target variable value and a feature vector.
`void` `train(long trackingKey, int actual, Vector instance)` Updates the model using a particular target variable value and a feature vector.
`void` `train(long trackingKey, String groupKey, int actual, Vector instance)` Updates the model using a particular target variable value and a feature vector.
`void` `updateRanking(Vector hiddenActivation, Collection<Integer> goodLabels, int numTrials, Random gen)` Updates using ranking loss.
`void` `write(DataOutput out)`

Methods inherited from class org.apache.mahout.classifier.AbstractVectorClassifier
`classify, classifyFull, classifyFull, classifyFull, classifyScalar, logLikelihood`

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

Field Detail

### WRITABLE_VERSION

    public static final int WRITABLE_VERSION

See Also:
  Constant Field Values

Constructor Detail

### GradientMachine

    public GradientMachine(int numFeatures,
                           int numHidden,
                           int numOutput)

Method Detail

### initWeights

    public void initWeights(Random gen)

  Initialize weights.

  Parameters:
    `gen` - random number generator.

### learningRate

    public GradientMachine learningRate(double learningRate)

  Chainable configuration option.

  Parameters:
    `learningRate` - New value of initial learning rate.
  Returns:
    This, so other configurations can be chained.

### regularization

    public GradientMachine regularization(double regularization)

  Chainable configuration option.

  Parameters:
    `regularization` - A positive value that controls the weight vector size.
  Returns:
    This, so other configurations can be chained.

### sparsity

    public GradientMachine sparsity(double sparsity)

  Chainable configuration option.

  Parameters:
    `sparsity` - A value between zero and one that controls the fraction of hidden units that are activated on average.
  Returns:
    This, so other configurations can be chained.

### sparsityLearningRate

    public GradientMachine sparsityLearningRate(double sparsityLearningRate)

  Chainable configuration option.

  Parameters:
    `sparsityLearningRate` - New value of initial learning rate for sparsity.
  Returns:
    This, so other configurations can be chained.

### copyFrom

    public void copyFrom(GradientMachine other)

### numCategories

    public int numCategories()

  Description copied from class: `AbstractVectorClassifier`
  Returns the number of categories that a target variable can be assigned to. A vector classifier will encode it's output as an integer from `0` to `numCategories()-1` (inclusive).

  Specified by:
    `numCategories` in class `AbstractVectorClassifier`
  Returns:
    The number of categories.

### numFeatures

    public int numFeatures()

### numHidden

    public int numHidden()

### inputToHidden

    public DenseVector inputToHidden(Vector input)

  Feeds forward from input to hidden unit..

  Returns:
    Hidden unit activations.

### hiddenToOutput

    public DenseVector hiddenToOutput(Vector hiddenActivation)

  Feeds forward from hidden to output

  Returns:
    Output unit activations.

### updateRanking

    public void updateRanking(Vector hiddenActivation,
                              Collection<Integer> goodLabels,
                              int numTrials,
                              Random gen)

  Updates using ranking loss.

  Parameters:
    `hiddenActivation` - the hidden unit's activation
    `goodLabels` - the labels you want ranked above others.
    `numTrials` - how many times you want to search for the highest scoring bad label.
    `gen` - Random number generator.

### classify

    public Vector classify(Vector instance)

  Description copied from class: `AbstractVectorClassifier`
  Compute and return a vector containing `n-1` scores, where `n` is equal to `numCategories()`, given an input vector `instance`. Higher scores indicate that the input vector is more likely to belong to that category. The categories are denoted by the integers `0` through `n-1` (inclusive), and the scores in the returned vector correspond to categories 1 through `n-1` (leaving out category 0). It is assumed that the score for category 0 is one minus the sum of the scores in the returned vector.

  Specified by:
    `classify` in class `AbstractVectorClassifier`
  Parameters:
    `instance` - A feature vector to be classified.
  Returns:
    A vector of probabilities in 1 of `n-1` encoding.

### classifyNoLink

    public Vector classifyNoLink(Vector instance)

  Description copied from class: `AbstractVectorClassifier`
  Compute and return a vector of scores before applying the inverse link function. For logistic regression and other generalized linear models, this is just the linear part of the classification.

  The implementation of this method provided by `AbstractVectorClassifier` throws an `UnsupportedOperationException`. Your subclass must explicitly override this method to support this operation.

  Overrides:
    `classifyNoLink` in class `AbstractVectorClassifier`
  Parameters:
    `instance` - A feature vector to be classified.
  Returns:
    A vector of scores. If transformed by the link function, these will become probabilities.

### classifyScalar

    public double classifyScalar(Vector instance)

  Description copied from class: `AbstractVectorClassifier`
  Classifies a vector in the special case of a binary classifier where `AbstractVectorClassifier.classify(Vector)` would return a vector with only one element. As such, using this method can avoid the allocation of a vector.

  Specified by:
    `classifyScalar` in class `AbstractVectorClassifier`
  Parameters:
    `instance` - The feature vector to be classified.
  Returns:
    The score for category 1.
  See Also:
    `AbstractVectorClassifier.classify(Vector)`

### copy

    public GradientMachine copy()

### write

    public void write(DataOutput out)
               throws IOException

  Specified by:
    `write` in interface `org.apache.hadoop.io.Writable`
  Throws:
    `IOException`

### readFields

    public void readFields(DataInput in)
                    throws IOException

  Specified by:
    `readFields` in interface `org.apache.hadoop.io.Writable`
  Throws:
    `IOException`

### close

    public void close()

  Description copied from interface: `OnlineLearner`
  Prepares the classifier for classification and deallocates any temporary data structures. An online classifier should be able to accept more training after being closed, but closing the classifier may make classification more efficient.

  Specified by:
    `close` in interface `Closeable`
  Specified by:
    `close` in interface `OnlineLearner`

### train

    public void train(long trackingKey,
                      String groupKey,
                      int actual,
                      Vector instance)

  Description copied from interface: `OnlineLearner`
  Updates the model using a particular target variable value and a feature vector.

  There may an assumption that if multiple passes through the training data are necessary that the tracking key for a record will be the same for each pass and that there will be a relatively large number of distinct tracking keys and that the low-order bits of the tracking keys will not correlate with any of the input variables. This tracking key is used to assign training examples to different test/training splits.

  Examples of useful tracking keys include id-numbers for the training records derived from a database id for the base table from the which the record is derived, or the offset of the original data record in a data file.

  Specified by:
    `train` in interface `OnlineLearner`
  Parameters:
    `trackingKey` - The tracking key for this training example.
    `groupKey` - An optional value that allows examples to be grouped in the computation of the update to the model.
    `actual` - The value of the target variable. This value should be in the half-open interval [0..n) where n is the number of target categories.
    `instance` - The feature vector for this example.

### train

    public void train(long trackingKey,
                      int actual,
                      Vector instance)

  Description copied from interface: `OnlineLearner`
  Updates the model using a particular target variable value and a feature vector.

  There may an assumption that if multiple passes through the training data are necessary that the tracking key for a record will be the same for each pass and that there will be a relatively large number of distinct tracking keys and that the low-order bits of the tracking keys will not correlate with any of the input variables. This tracking key is used to assign training examples to different test/training splits.

  Examples of useful tracking keys include id-numbers for the training records derived from a database id for the base table from the which the record is derived, or the offset of the original data record in a data file.

  Specified by:
    `train` in interface `OnlineLearner`
  Parameters:
    `trackingKey` - The tracking key for this training example.
    `actual` - The value of the target variable. This value should be in the half-open interval [0..n) where n is the number of target categories.
    `instance` - The feature vector for this example.

### train

    public void train(int actual,
                      Vector instance)

  Description copied from interface: `OnlineLearner`
  Updates the model using a particular target variable value and a feature vector.

  There may an assumption that if multiple passes through the training data are necessary, then the training examples will be presented in the same order. This is because the order of training examples may be used to assign records to different data splits for evaluation by cross-validation. Without the order invariance, records might be assigned to training and test splits and error estimates could be seriously affected.

  If re-ordering is necessary, then using the alternative API which allows a tracking key to be added to the training example can be used.

  Specified by:
    `train` in interface `OnlineLearner`
  Parameters:
    `actual` - The value of the target variable. This value should be in the half-open interval [0..n) where n is the number of target categories.
    `instance` - The feature vector for this example.

Copyright © 2008–2014 The Apache Software Foundation. All rights reserved.