CGAL 5.4.1 - Classification
CGAL::Classification::Sum_of_weighted_features_classifier Class Reference

#include <CGAL/Classification/Sum_of_weighted_features_classifier.h>

Definition

Classifier based on the sum of weighted features with user-defined effects on labels.

Is Model Of:
CGAL::Classification::Classifier

Public Types

enum  Effect { FAVORING = 0, NEUTRAL = 1, PENALIZING = 2 }
 Defines the effect of a feature on a type. More...
 

Constructor

 Sum_of_weighted_features_classifier (const Label_set &labels, const Feature_set &features)
 instantiates the classifier using the sets of labels and features. More...
 

Weights and Effects

void set_weight (Feature_handle feature, float weight)
 sets the weight of feature (weight must be positive).
 
float weight (Feature_handle feature) const
 returns the weight of feature.
 
void set_effect (Label_handle label, Feature_handle feature, Effect effect)
 sets the effect of feature on label.
 
Effect effect (Label_handle label, Feature_handle feature) const
 returns the effect of feature on label.
 

Training

template<typename ConcurrencyTag , typename LabelIndexRange >
float train (const LabelIndexRange &ground_truth, unsigned int nb_tests=300)
 runs the training algorithm. More...
 

Input/Output

void save_configuration (std::ostream &output)
 saves the current configuration in the stream output. More...
 
bool load_configuration (std::istream &input, bool verbose=false)
 loads a configuration from the stream input. More...
 

Member Enumeration Documentation

◆ Effect

Defines the effect of a feature on a type.

Enumerator
FAVORING 

High values of the feature favor this type.

NEUTRAL 

The feature has no effect on this type.

PENALIZING 

Low values of the feature favor this type.

Constructor & Destructor Documentation

◆ Sum_of_weighted_features_classifier()

CGAL::Classification::Sum_of_weighted_features_classifier::Sum_of_weighted_features_classifier ( const Label_set labels,
const Feature_set features 
)

instantiates the classifier using the sets of labels and features.

Note
If the label set of the feature set are modified after instantiating this object (addition of removal of a label and/or of a feature), another classifier object should be instantiated as the internal data structures of this one are invalidated.

Member Function Documentation

◆ load_configuration()

bool CGAL::Classification::Sum_of_weighted_features_classifier::load_configuration ( std::istream &  input,
bool  verbose = false 
)

loads a configuration from the stream input.

A configuration is a set of weights and effects.

The input file should be in the XML format written by the save_configuration() method. Labels and features are described in the XML file by their name and the corresponding Label and Feature_base object should therefore be given the same names as the ones they had when saving the configuration.

Note
If a feature (or label) found in the input file is not found in the Feature_set (Label_set) provided by the user in the constructor, and if verbose is set up to true, a warning is displayed.
If a feature (or label) provided by the user in the constructor is not described in the input file, the corresponding weights and effects are kept to their default values (1 for the weight and NEUTRAL for the effect).
Parameters
inputinput stream.
verbosedisplays warning if set to true. The method is silent otherwise.
Returns
true if all weights and effects found in the configuration file were applicable to the feature set and label set of this classifier, false otherwise.

◆ save_configuration()

void CGAL::Classification::Sum_of_weighted_features_classifier::save_configuration ( std::ostream &  output)

saves the current configuration in the stream output.

This allows to easily save and recover a specific classification configuration, that is to say:

  • The weight of each feature
  • The effects of each feature on each label

The output file is written in an XML format that is readable by the load_configuration() method.

◆ train()

template<typename ConcurrencyTag , typename LabelIndexRange >
float CGAL::Classification::Sum_of_weighted_features_classifier::train ( const LabelIndexRange &  ground_truth,
unsigned int  nb_tests = 300 
)

runs the training algorithm.

From the set of provided ground truth, this algorithm estimates the sets of weights and effects that produce the most accurate result with respect to this ground truth. Old weights and effects are discarded.

Precondition
At least one ground truth item should be assigned to each label.
Parameters
ground_truthvector 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.
nb_testsnumber of tests to perform. Higher values may provide the user with better results at the cost of a higher computation time. Using a value of at least 10 times the number of features is advised.
Returns
mean intersection-over-union over each label between the provided ground truth and the best classification found by the training set.