CGAL 6.2 - Classification: CGAL::Classification::ETHZ::Random_forest_classifier Class Reference

CGAL 6.2 - Classification

Loading...
Searching...
No Matches
List of all members
CGAL::Classification::ETHZ::Random_forest_classifier Class Reference
Reference Manual » Classifiers » ETHZ

`#include <CGAL/Classification/ETHZ/Random_forest_classifier.h>`

## Definition

Classifier based on the ETH Zurich version of the random forest algorithm [2].

Note
  This classifier is distributed under the MIT license.

Is model of
  `CGAL::Classification::Classifier`

## Constructor
| Random_forest_classifier (const Label_set &labels, const Feature_set &features)
| instantiates the classifier using the sets of `labels` and `features`.
| Random_forest_classifier (const Random_forest_classifier &other, const Feature_set &features)
| copies the `other` classifier's configuration using another set of `features`.

## Training
template<typename ConcurrencyTag , typename LabelIndexRange >
void | train (const LabelIndexRange &ground_truth, bool reset_trees=true, std::size_t num_trees=25, std::size_t max_depth=20)
| runs the training algorithm.

## Miscellaneous
void | get_feature_usage (std::vector< std::size_t > &count) const
| computes, for each feature, how many nodes in the forest uses it as a split criterion.

## Input/Output
void | save_configuration (std::ostream &output) const
| saves the current configuration in the stream `output`.
void | load_configuration (std::istream &input)
| loads a configuration from the stream `input`.

## Deprecated Input/Output
static void | convert_deprecated_configuration_to_new_format (std::istream &input, std::ostream &output)
| converts a deprecated configuration (in compressed ASCII format) to a new configuration (in binary format).

## Constructor & Destructor Documentation

## ◆ Random_forest_classifier()

CGAL::Classification::ETHZ::Random_forest_classifier::Random_forest_classifier | ( | const Random_forest_classifier & | other,
|  | const Feature_set & | features
| ) |  |

copies the `other` classifier's configuration using another set of `features`.

This constructor can be used to apply a trained random forest to another data set.

Warning
  The feature set should be composed of the same features than the ones used by `other`, and in the same order.

## Member Function Documentation

## ◆ convert_deprecated_configuration_to_new_format()

static void CGAL::Classification::ETHZ::Random_forest_classifier::convert_deprecated_configuration_to_new_format | ( | std::istream & | input,
|  | std::ostream & | output
| ) |  |
| static

converts a deprecated configuration (in compressed ASCII format) to a new configuration (in binary format).

The input file should be a GZIP container written by the `save_configuration()` method from CGAL 5.1 and earlier. The output is a valid configuration for CGAL 5.2 and later.

Note
  This function depends on the Boost libraries Serialization and IO Streams (compiled with the GZIP dependency).

Examples
  Classification/example_deprecated_conversion.cpp.

## ◆ get_feature_usage()

void CGAL::Classification::ETHZ::Random_forest_classifier::get_feature_usage | ( | std::vector< std::size_t > & | count | ) | const

computes, for each feature, how many nodes in the forest uses it as a split criterion.

Each tree of the random forest recursively splits the training data set using at each node one of the input features. This method counts, for each feature, how many times it was selected by the training algorithm as a split criterion.

This method allows to evaluate how useful a feature was with respect to a training set: if a feature is used a lot, that means that it has a strong discriminative power with respect to how the labels are represented by the feature set; on the contrary, if a feature is not used very often, its discriminative power is probably low; if a feature is never used, it likely has no interest at all and is completely uncorrelated to the label segmentation of the training set.

Parameters

  count | vector where the result is stored. After running the method, it contains, for each feature, the number of nodes in the forest that use it as a split criterion, in the same order as the feature set order.

## ◆ load_configuration()

void CGAL::Classification::ETHZ::Random_forest_classifier::load_configuration | ( | std::istream & | input | ) |

loads a configuration from the stream `input`.

The input file should be a binary file written by the `save_configuration()` method. The feature set of the classifier should contain the exact same features in the exact same order as the ones present when the file was generated using `save_configuration()`.

Warning
  If the file you are trying to load was saved using CGAL 5.1 or earlier, you have to convert it first using `convert_deprecated_configuration_to_new_format()` as the exchange format for ETHZ Random Forest changed in CGAL 5.2.

## ◆ save_configuration()

void CGAL::Classification::ETHZ::Random_forest_classifier::save_configuration | ( | std::ostream & | output | ) | const

saves the current configuration in the stream `output`.

This allows to easily save and recover a specific classification configuration.

The output file is written in a binary format that is readable by the `load_configuration()` method.

## ◆ train()

template<typename ConcurrencyTag , typename LabelIndexRange >

void CGAL::Classification::ETHZ::Random_forest_classifier::train | ( | const LabelIndexRange & | ground_truth,
|  | bool | reset_trees = `true`,
|  | std::size_t | num_trees = `25`,
|  | std::size_t | max_depth = `20`
| ) |  |

runs the training algorithm.

From the set of provided ground truth, this algorithm estimates sets up the random trees that produce the most accurate result with respect to this ground truth.

Precondition
  At least one ground truth item should be assigned to each label.

Template Parameters

  ConcurrencyTag | enables sequential versus parallel algorithm. Possible values are `Parallel_tag` (default value if CGAL is linked with TBB) or `Sequential_tag` (default value otherwise).

Parameters

  ground_truth | vector of label indices. It should contain for each input item, in the same order as the input set, the index of the corresponding label in the `Label_set` provided in the constructor. Input items that do not have a ground truth information should be given the value `-1`.
  reset_trees | should be set to `false` if the users wants to add new trees to the existing forest, and kept to `true` if the training should be recomputing from scratch (discarding the current forest).
  num_trees | number of trees generated by the training algorithm. Higher values may improve result at the cost of higher computation times (in general, using a few dozens of trees is enough).
  max_depth | maximum depth of the trees. Higher values will improve how the forest fits the training set. A overly low value will underfit the test data and conversely an overly high value will likely overfit.