weka.classifiers.trees

## Class RandomForest

- java.lang.Object
- - weka.classifiers.AbstractClassifier
  - - weka.classifiers.trees.RandomForest

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, Classifier, AdditionalMeasureProducer, Aggregateable<RandomForest>, CapabilitiesHandler, CapabilitiesIgnorer, OptionHandler, PartitionGenerator, Randomizable, RevisionHandler, TechnicalInformationHandler, WeightedInstancesHandler

      public class RandomForest
      extends AbstractClassifier
      implements OptionHandler, Randomizable, WeightedInstancesHandler, AdditionalMeasureProducer, TechnicalInformationHandler, PartitionGenerator, Aggregateable<RandomForest>

  Class for constructing a forest of random trees.
  For more information see:
  Leo Breiman (2001). Random Forests. Machine Learning. 45(1):5-32.

  BibTeX:

       @article{Breiman2001,
          author = {Leo Breiman},
          journal = {Machine Learning},
          number = {1},
          pages = {5-32},
          title = {Random Forests},
          volume = {45},
          year = {2001}
       }

  Valid options are:

       -I <number of trees>
        Number of trees to build.
        (default 100)

       -K <number of features>
        Number of features to consider (<1=int(log_2(#predictors)+1)).
        (default 0)

       -S
        Seed for random number generator.
        (default 1)

       -depth <num>
        The maximum depth of the trees, 0 for unlimited.
        (default 0)

       -O
        Don't calculate the out of bag error.

       -print
        Print the individual trees in the output

       -num-slots <num>
        Number of execution slots.
        (default 1 - i.e. no parallelism)

       -output-debug-info
        If set, classifier is run in debug mode and
        may output additional info to the console

       -do-not-check-capabilities
        If set, classifier capabilities are not checked before classifier is built
        (use with caution).

  Version:
    $Revision: 11003 $
  Author:
    Richard Kirkby (rkirkby@cs.waikato.ac.nz)
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RandomForest()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `RandomForest` | `aggregate(RandomForest toAggregate)` Aggregate an object with this one
    `void` | `buildClassifier(Instances data)` Builds a classifier for a set of instances.
    `double[]` | `distributionForInstance(Instance instance)` Returns the class probability distribution for an instance.
    `java.lang.String` | `dontCalculateOutOfBagErrorTipText()` Returns the tip text for this property
    `java.util.Enumeration<java.lang.String>` | `enumerateMeasures()` Returns an enumeration of the additional measure names.
    `void` | `finalizeAggregation()` Call to complete the aggregation process.
    `void` | `generatePartition(Instances data)` Builds the classifier to generate a partition.
    `Capabilities` | `getCapabilities()` Returns default capabilities of the classifier.
    `boolean` | `getDontCalculateOutOfBagError()` Get whether to turn off the calculation of out of bag error
    `int` | `getMaxDepth()` Get the maximum depth of trh tree, 0 for unlimited.
    `double` | `getMeasure(java.lang.String additionalMeasureName)` Returns the value of the named measure.
    `double[]` | `getMembershipValues(Instance inst)` Computes an array that indicates leaf membership
    `int` | `getNumExecutionSlots()` Get the number of execution slots (threads) to use for building the members of the ensemble.
    `int` | `getNumFeatures()` Get the number of features used in random selection.
    `int` | `getNumTrees()` Get the value of numTrees.
    `java.lang.String[]` | `getOptions()` Gets the current settings of the forest.
    `boolean` | `getPrintTrees()` Get whether to print the individual ensemble trees in the output
    `java.lang.String` | `getRevision()` Returns the revision string.
    `int` | `getSeed()` Gets the seed for the random number generations
    `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.
    `java.lang.String` | `globalInfo()` Returns a string describing classifier
    `java.util.Enumeration<Option>` | `listOptions()` Returns an enumeration describing the available options.
    `static void` | `main(java.lang.String[] argv)` Main method for this class.
    `java.lang.String` | `maxDepthTipText()` Returns the tip text for this property
    `double` | `measureOutOfBagError()` Gets the out of bag error that was calculated as the classifier was built.
    `int` | `numElements()` Returns the number of elements in the partition.
    `java.lang.String` | `numExecutionSlotsTipText()` Returns the tip text for this property
    `java.lang.String` | `numFeaturesTipText()` Returns the tip text for this property
    `java.lang.String` | `numTreesTipText()` Returns the tip text for this property
    `java.lang.String` | `printTreesTipText()` Returns the tip text for this property
    `java.lang.String` | `seedTipText()` Returns the tip text for this property
    `void` | `setDontCalculateOutOfBagError(boolean b)` Set whether to turn off the calculation of out of bag error
    `void` | `setMaxDepth(int value)` Set the maximum depth of the tree, 0 for unlimited.
    `void` | `setNumExecutionSlots(int numSlots)` Set the number of execution slots (threads) to use for building the members of the ensemble.
    `void` | `setNumFeatures(int newNumFeatures)` Set the number of features to use in random selection.
    `void` | `setNumTrees(int newNumTrees)` Set the value of numTrees.
    `void` | `setOptions(java.lang.String[] options)` Parses a given list of options.
    `void` | `setPrintTrees(boolean print)` Set whether to print the individual ensemble trees in the output
    `void` | `setSeed(int seed)` Set the seed for random number generation.
    `java.lang.String` | `toString()` Outputs a description of this classifier.

    - ### Methods inherited from class weka.classifiers.AbstractClassifier

      `classifyInstance, debugTipText, doNotCheckCapabilitiesTipText, forName, getDebug, getDoNotCheckCapabilities, makeCopies, makeCopy, runClassifier, setDebug, setDoNotCheckCapabilities`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### RandomForest

          public RandomForest()

  - ### Method Detail

    - #### globalInfo

          public java.lang.String globalInfo()

      Returns a string describing 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

    - #### numTreesTipText

          public java.lang.String numTreesTipText()

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

    - #### getNumTrees

          public int getNumTrees()

      Get the value of numTrees.
      Returns:
        Value of numTrees.

    - #### setNumTrees

          public void setNumTrees(int newNumTrees)

      Set the value of numTrees.
      Parameters:
        `newNumTrees` - Value to assign to numTrees.

    - #### numFeaturesTipText

          public java.lang.String numFeaturesTipText()

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

    - #### getNumFeatures

          public int getNumFeatures()

      Get the number of features used in random selection.
      Returns:
        Value of numFeatures.

    - #### setNumFeatures

          public void setNumFeatures(int newNumFeatures)

      Set the number of features to use in random selection.
      Parameters:
        `newNumFeatures` - Value to assign to numFeatures.

    - #### seedTipText

          public java.lang.String seedTipText()

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

    - #### setSeed

          public void setSeed(int seed)

      Set the seed for random number generation.
      Specified by:
        `setSeed` in interface `Randomizable`
      Parameters:
        `seed` - the seed

    - #### getSeed

          public int getSeed()

      Gets the seed for the random number generations
      Specified by:
        `getSeed` in interface `Randomizable`
      Returns:
        the seed for the random number generation

    - #### maxDepthTipText

          public java.lang.String maxDepthTipText()

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

    - #### getMaxDepth

          public int getMaxDepth()

      Get the maximum depth of trh tree, 0 for unlimited.
      Returns:
        the maximum depth.

    - #### setMaxDepth

          public void setMaxDepth(int value)

      Set the maximum depth of the tree, 0 for unlimited.
      Parameters:
        `value` - the maximum depth.

    - #### printTreesTipText

          public java.lang.String printTreesTipText()

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

    - #### setPrintTrees

          public void setPrintTrees(boolean print)

      Set whether to print the individual ensemble trees in the output
      Parameters:
        `print` - true if the individual trees are to be printed

    - #### getPrintTrees

          public boolean getPrintTrees()

      Get whether to print the individual ensemble trees in the output
      Returns:
        true if the individual trees are to be printed

    - #### dontCalculateOutOfBagErrorTipText

          public java.lang.String dontCalculateOutOfBagErrorTipText()

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

    - #### setDontCalculateOutOfBagError

          public void setDontCalculateOutOfBagError(boolean b)

      Set whether to turn off the calculation of out of bag error
      Parameters:
        `b` - true to turn off the calculation of out of bag error

    - #### getDontCalculateOutOfBagError

          public boolean getDontCalculateOutOfBagError()

      Get whether to turn off the calculation of out of bag error
      Returns:
        true to turn off the calculation of out of bag error

    - #### measureOutOfBagError

          public double measureOutOfBagError()

      Gets the out of bag error that was calculated as the classifier was built.
      Returns:
        the out of bag error

    - #### setNumExecutionSlots

          public void setNumExecutionSlots(int numSlots)

      Set the number of execution slots (threads) to use for building the members of the ensemble.
      Parameters:
        `numSlots` - the number of slots to use.

    - #### getNumExecutionSlots

          public int getNumExecutionSlots()

      Get the number of execution slots (threads) to use for building the members of the ensemble.
      Returns:
        the number of slots to use

    - #### numExecutionSlotsTipText

          public java.lang.String numExecutionSlotsTipText()

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

    - #### enumerateMeasures

          public java.util.Enumeration<java.lang.String> enumerateMeasures()

      Returns an enumeration of the additional measure names.
      Specified by:
        `enumerateMeasures` in interface `AdditionalMeasureProducer`
      Returns:
        an enumeration of the measure names

    - #### getMeasure

          public double getMeasure(java.lang.String additionalMeasureName)

      Returns the value of the named measure.
      Specified by:
        `getMeasure` in interface `AdditionalMeasureProducer`
      Parameters:
        `additionalMeasureName` - the name of the measure to query for its value
      Returns:
        the value of the named measure
      Throws:
        `java.lang.IllegalArgumentException` - if the named measure is not supported

    - #### listOptions

          public java.util.Enumeration<Option> listOptions()

      Returns an enumeration describing the available options.
      Specified by:
        `listOptions` in interface `OptionHandler`
      Overrides:
        `listOptions` in class `AbstractClassifier`
      Returns:
        an enumeration of all the available options

    - #### getOptions

          public java.lang.String[] getOptions()

      Gets the current settings of the forest.
      Specified by:
        `getOptions` in interface `OptionHandler`
      Overrides:
        `getOptions` in class `AbstractClassifier`
      Returns:
        an array of strings suitable for passing to setOptions()

    - #### setOptions

          public void setOptions(java.lang.String[] options)
                          throws java.lang.Exception

      Parses a given list of options.

      Valid options are:

           -I <number of trees>
            Number of trees to build.
            (default 100)

           -K <number of features>
            Number of features to consider (<1=int(log_2(#predictors)+1)).
            (default 0)

           -S
            Seed for random number generator.
            (default 1)

           -depth <num>
            The maximum depth of the trees, 0 for unlimited.
            (default 0)

           -O
            Don't calculate the out of bag error.

           -print
            Print the individual trees in the output

           -num-slots <num>
            Number of execution slots.
            (default 1 - i.e. no parallelism)

           -output-debug-info
            If set, classifier is run in debug mode and
            may output additional info to the console

           -do-not-check-capabilities
            If set, classifier capabilities are not checked before classifier is built
            (use with caution).

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

    - #### getCapabilities

          public Capabilities getCapabilities()

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

    - #### buildClassifier

          public void buildClassifier(Instances data)
                               throws java.lang.Exception

      Builds a classifier for a set of instances.
      Specified by:
        `buildClassifier` in interface `Classifier`
      Parameters:
        `data` - the instances to train the classifier with
      Throws:
        `java.lang.Exception` - if something goes wrong

    - #### distributionForInstance

          public double[] distributionForInstance(Instance instance)
                                           throws java.lang.Exception

      Returns the class probability distribution for an instance.
      Specified by:
        `distributionForInstance` in interface `Classifier`
      Overrides:
        `distributionForInstance` in class `AbstractClassifier`
      Parameters:
        `instance` - the instance to be classified
      Returns:
        the distribution the forest generates for the instance
      Throws:
        `java.lang.Exception` - if computation fails

    - #### toString

          public java.lang.String toString()

      Outputs a description of this classifier.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string containing a description of the classifier

    - #### generatePartition

          public void generatePartition(Instances data)
                                 throws java.lang.Exception

      Builds the classifier to generate a partition.
      Specified by:
        `generatePartition` in interface `PartitionGenerator`
      Throws:
        `java.lang.Exception`

    - #### getMembershipValues

          public double[] getMembershipValues(Instance inst)
                                       throws java.lang.Exception

      Computes an array that indicates leaf membership
      Specified by:
        `getMembershipValues` in interface `PartitionGenerator`
      Throws:
        `java.lang.Exception`

    - #### numElements

          public int numElements()
                          throws java.lang.Exception

      Returns the number of elements in the partition.
      Specified by:
        `numElements` in interface `PartitionGenerator`
      Throws:
        `java.lang.Exception`

    - #### getRevision

          public java.lang.String getRevision()

      Returns the revision string.
      Specified by:
        `getRevision` in interface `RevisionHandler`
      Overrides:
        `getRevision` in class `AbstractClassifier`
      Returns:
        the revision

    - #### main

          public static void main(java.lang.String[] argv)

      Main method for this class.
      Parameters:
        `argv` - the options

    - #### aggregate

          public RandomForest aggregate(RandomForest toAggregate)
                                 throws java.lang.Exception

      Description copied from interface: `Aggregateable`
      Aggregate an object with this one
      Specified by:
        `aggregate` in interface `Aggregateable<RandomForest>`
      Parameters:
        `toAggregate` - the object to aggregate
      Returns:
        the result of aggregation
      Throws:
        `java.lang.Exception` - if the supplied object can't be aggregated for some reason

    - #### finalizeAggregation

          public void finalizeAggregation()
                                   throws java.lang.Exception

      Description copied from interface: `Aggregateable`
      Call to complete the aggregation process. Allows implementers to do any final processing based on how many objects were aggregated.
      Specified by:
        `finalizeAggregation` in interface `Aggregateable<RandomForest>`
      Throws:
        `java.lang.Exception` - if the aggregation can't be finalized for some reason