This section includes information for using the Python API of bob.learn.boosting.
The bob.learn.boosting module contains classifiers that can predict classes for given input value:
Weak machines might be:
Theoretically, the strong classifier can consist of different types of weak classifiers, but usually all weak classifiers have the same type.
Available trainers in bob.learn.boosting are:
Loss functions are used to define new weights for the weak machines using the scipy.optimize.fmin_l_bfgs_b function. A base class loss function bob.learn.boosting.LossFunction is called by that function, and derived classes implement the actual loss for a single sample.
Note
Loss functions are designed to be used in combination with a specific weak trainer in specific cases. Not all combinations of loss functions and weak trainers make sense. Here is a list of useful combinations:
Bases: object
A strong machine that holds a weighted combination of weak machines
Todo
Improve documentation.
Constructor Documentation:
- BoostedMachine ()
- BoostedMachine (hdf5)
Initializes a BoostedMachine object
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file object to read the weak classifier from
Class Members:
Adds the given weak machine and its weight(s) to the list of weak machines
Parameters:
machine : A derivative from WeakMachine
The weak machine to add
weight : float
The weight for the machine (uni-variate)
weights : float <#outputs>
The weights for the machine (multi-variate)
float <#machines,#outputs> <– The weights for the weak machines
Returns the feature index that will be used in this weak machine
Parameters:
start : int
The first machine index to the the indices for; defaults to 0
end : int
The last machine index +1 to the the indices for; defaults to -1, which correspponds to the last machine + 1
Returns:
indices : array_like <int32>
The feature indices required by the selected machines
Returns the prediction for the given feature vector(s)
Note
The __call__() function is an alias for this function.
This function can be called in six different ways:
Parameters:
features : uint16 <#inputs> or uint16 <#samples, #inputs>
The feature vector(s) the prediction should be computed for.
predictions : float <#samples> or float <#outputs> or float <#samples, #outputs>
The predicted values – see below.
labels : float <#samples> or float <#samples, #outputs>
The predicted labels:
- for the uni-variate case, -1 or +1 is assigned according to threshold 0
- for the multi-variate case, +1 is assigned for the highest value, and 0 for all others
Returns:
prediction : float
The predicted value - in case a single feature is provided and a single output is required
int <#machines,#outputs> <– The indices into the feature vector required by all of the weak machines.
Loads the Strong machine from the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to load this machine from.
int <– The number of outputs; for uni-variate classifiers always 1
Saves the content of this machine to the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to save this weak machine to.
[WeakMachine] <– The list of weak machines stored in this strong machine
float <#machines,#outputs> <– The weights for the weak machines
The class to boost the features from a set of training samples.
It iteratively adds new weak models to assemble a strong classifier. In each round of iteration a weak machine is learned by optimizing a differentiable function.
Constructor Documentation
Keyword parameters
- weak_trainer : bob.learn.boosting.LUTTrainer or bob.learn.boosting.StumpTrainer
- The class to train weak machines.
- loss_function : a class derived from bob.learn.boosting.LossFunction
- The function to define the weights for the weak machines.
Returns the loss function this trainer will use.
The function to train a boosting machine.
The function boosts the training features and returns a strong classifier as a weighted combination of weak classifiers.
Keyword parameters:
Bases: bob.learn.boosting.LossFunction.LossFunction
The class implements the exponential loss function for the boosting framework.
The function computes the exponential loss values using prediction scores and targets. It can be used in classification tasks, e.g., in combination with the StumpTrainer.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient of the exponential loss function using prediction scores and targets.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient as the sum of the derivatives per sample which is used to find the optimized values of alpha.
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
The function computes the sum of the loss which is used to find the optimized values of alpha (x).
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
Returns
(float <#outputs>) The sum of the loss values for the current value of the alpha
Bases: LossFunction
Computes the Jesorsky loss and its derivative.
The Jesorsky loss defines an error function between the target vectors and the currently achieved scores.It is specifically designed to perform regression in a facial feature localization (FFL) task.It assumes that the feature vector \vec p consists of facial landmark positions, which are given in the following way:
\vec p = [y_0, x_0, y_1, x_1, \dots, y_{n-1}, x_{n-1}]
with (y_0, x_0) is the right eye landmark, (y_0, x_0) is the left eye landmark and all other landmarks (a total of n landmarks) are following.
The error between target vector \vec a and test vector \vec b is computed as the average landmark-wise Euclidean distance, normalized by the inter-eye-distance of the target vector:
d(\vec a, \vec b) = \sum_{i=0}^n \frac{\sqrt{(b_{2i} - a_{2i})^2 + (b_{2i+1} - a_{2i+1})^2}} {\sqrt{(a_0 - a_2)^2 + (a_1 - a_3)^2}}
The derivative is a bit more complicated.First, the error is computed for each landmark i=0,\dots,n-1:
d_i(\vec a, \vec b) = \frac{\sqrt{(b_{2i} - a_{2i})^2 + (b_{2i+1} - a_{2i+1})^2}} {\sqrt{(a_0 - a_2)^2 + (a_1 - a_3)^2}}
and then the derivative is computed for each element of the target vector:
\nabla(\vec a, \vec b) = \left[d_i\cdot(b_{2i} - a_{2i}), d_i\cdot(b_{2i+1} - a_{2i+1}) \right]_i
Constructor Documentation:
JesorskyLoss ()
Initializes a JesorskyLoss object.
The constructor comes with no parameters.
Class Members:
Computes the Jesorsky error between the targets and the scores.
This function computes the Jesorsky error between all given targets and samples, using the loss formula as explained above JesorskyLoss
Parameters:
targets : float <#samples, #outputs>
The target values that should be achieved during boosting
scores : float <#samples, #outputs>
The score values that are currently achieved
Returns:
errors : float <#samples, 1>
The resulting Jesorsky errors for each target
Computes the Jesorsky error between the targets and the scores.
This function computes the derivative of the Jesorsky error between all given targets and samples, using the loss formula as explained above JesorskyLoss
Parameters:
targets : float <#samples, #outputs>
The target values that should be achieved during boosting
scores : float <#samples, #outputs>
The score values that are currently achieved
Returns:
gradient : float <#samples, #outputs>
The derivative of the Jesorsky error for each sample
Computes the sum of the loss gradients computed between the targets and the scores.
This function is designed to be used with the L-BFGS method.It computes the new derivative of the loss based on the loss from the current strong classifier, adding the new weak machine with the currently selected weight alpha
Parameters:
alpha : float <#outputs>
The weight for the current_scores that will be optimized in L-BFGS
targets : float <#samples, #outputs>
The target values that should be achieved during boosting
previous_scores : float <#samples, #outputs>
The score values that are achieved by the boosted machine after the previous boosting iteration
current_scores : float <#samples, #outputs>
The score values that are achieved with the weak machine added in this boosting round
Returns:
gradient_sum : float <#outputs>
The sum over the loss gradients for the newly combined strong classifier
Computes the sum of the losses computed between the targets and the scores.
This function is designed to be used with the L-BFGS method.It computes the new loss based on the loss from the current strong classifier, adding the new weak machine with the currently selected weight alpha
Parameters:
alpha : float <#outputs>
The weight for the current_scores that will be optimized in L-BFGS
targets : float <#samples, #outputs>
The target values that should be achieved during boosting
previous_scores : float <#samples, #outputs>
The score values that are achieved by the boosted machine after the previous boosting iteration
current_scores : float <#samples, #outputs>
The score values that are achieved with the weak machine added in this boosting round
Returns:
loss_sum : float <1>
The sum over the loss values for the newly combined strong classifier
Bases: WeakMachine
A weak machine that bases it’s decision on a Look-Up-Table
Todo
Improve documentation.
Constructor Documentation:
- LUTMachine (look_up_table, index)
- LUTMachine (look_up_tables, indices)
- LUTMachine (hdf5)
Initializes a LUTMachine object
Parameters:
look_up_table : float <#entries>
The look up table (for the univariate case)index : int
The index into the feature vector (for the univariate case)look_up_tables : float <#entries,#outputs>
The look up tables, one for each output dimension (for the multi-variate case)indices : int <#outputs>
The indices into the feature vector, one for each output dimension (for the multi-variate case)hdf5 : bob.io.base.HDF5File
The HDF5 file object to read the weak classifier from
Class Members:
Returns the feature index that will be used in this weak machine
Returns:
indices : int32 <1>
The feature index required by this machine
Returns the prediction for the given feature vector(s)
Note
The __call__() function is an alias for this function.
This function can be called in four different ways:
Parameters:
features : uint16 <#inputs> or uint16 <#samples, #inputs>
The feature vector(s) the prediction should be computed for.
predictions : float <#samples> or float <#outputs> or float <#samples, #outputs>
The predicted values – see below.
Returns:
prediction : float
The predicted value – in case a single feature is provided and a single output is required
Loads the LUT machine from the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to load this weak machine from.
float <#entries,#outputs> <– The look-up table associated with this object. In the uni-variate case, #outputs will be 1
Saves the content of this machine to the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to save this weak machine to.
Bases: object
A weak machine that bases it’s decision on a Look-Up-Table
Todo
Improve documentation.
Constructor Documentation:
LUTTrainer (maximum_feature_value, [number_of_outputs, selection_style])
Initializes a LUTTrainer object
Parameters:
maximum_feature_value : int
The number of entries in the Look-Up-Tablesnumber_of_outputs : int
The dimensionality of the output vector; defaults to 1 for the uni-variate caseselection_style : str
The way, features are selected; possible values: ‘shared’, ‘independent’; only useful for the multi-variate case; defaults to ‘independent’
Class Members:
uint16 <– The highest feature value + 1, i.e., the number of entries in the LUT
int <– The dimensionality of the output vector (1 for the uni-variate case)
str <– The style for selecting features (valid for multi-variate case only)
Trains and returns a weak LUT machine
Todo
Write documentation for this
Parameters:
training_features : uint16 <#samples, #inputs>
The feature vectors to train the weak machine
loss_gradient : float <#samples, #outputs>
The gradient of the loss function for the training features
Returns:
lut_machine : bob.boosting.machine.LUTMachine
The weak machine that is obtained in the current round of boosting
Bases: bob.learn.boosting.LossFunction.LossFunction
The class to implement the logit loss function for the boosting framework.
The function computes the logit loss values using prediction scores and targets.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient of the logit loss function using prediction scores and targets.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient as the sum of the derivatives per sample which is used to find the optimized values of alpha.
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
The function computes the sum of the loss which is used to find the optimized values of alpha (x).
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
Returns
(float <#outputs>) The sum of the loss values for the current value of the alpha
Bases: WeakMachine
A weak machine that bases it’s decision on comparing the given value to a threshold
Todo
Improve documentation.
Constructor Documentation:
- StumpMachine (threshold, polarity, index)
- StumpMachine (hdf5)
Initializes a StumpMachine object.
Parameters:
threshold : float
The decision thresholdpolarity : float
-1 if positive values are below threshold, +1 if positive values are above thresholdindex : int
The index into the feature vector that is thresholdedhdf5 : bob.io.base.HDF5File
The HDF5 file object to read the weak classifier from
Class Members:
Returns the feature index that will be used in this weak machine
Returns:
indices : int32 <1>
The feature index required by this machine
Returns the prediction for the given feature vector(s)
Note
The __call__() function is an alias for this function.
Todo
write more detailed documentation
Parameters:
features : float <#inputs> or float <#samples, #inputs>
The feature vector(s) the prediction should be computed for. If only a single feature is given, the resulting prediction is returned as a float. Otherwise it is stored in the second predictions parameter.
predictions : float <#samples> or float <#samples, 1>
The predicted values – in case several features are provided.
Returns:
prediction : float
The predicted value – in case a single feature is provided
Loads the Stump machine from the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to load this weak machine from.
float <– The polarity of the comparison: -1 if the values lower than the threshold should be accepted, +1 otherwise
Saves the content of this machine to the given HDF5 file
Parameters:
hdf5 : bob.io.base.HDF5File
The HDF5 file to save this weak machine to.
float <– The thresholds that the feature value will be compared with
The class for training weak stump classifiers. The weak stump is parameterized the threshold and the polarity.
Computes the stump classifier threshold for a single feature
The threshold is computed for the given feature values using the weak learner algorithm of Viola Jones.
features (float<#samples>): The feature values for a single index
gradient (float<#samples>): The negative loss gradient values for the training samples
Computes a weak stump machine.
The best weak machine is chosen to maximize the dot product of the outputs and the weights (gain). The weights are the negative of the loss gradient for exponential loss.
training_features (float<#samples, #features>): The training features samples
loss_gradient (float<#samples>): The loss gradient values for the training samples
Bases: bob.learn.boosting.LossFunction.LossFunction
Tangent loss function, as described in http://www.svcl.ucsd.edu/projects/LossDesign/TangentBoost.html.
The function computes the logit loss values using prediction scores and targets.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient of the tangential loss function using prediction scores and targets.
Keyword parameters:
targets (float <#samples, #outputs>): The target values that should be reached.
scores (float <#samples, #outputs>): The scores provided by the classifier.
The function computes the gradient as the sum of the derivatives per sample which is used to find the optimized values of alpha.
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
The function computes the sum of the loss which is used to find the optimized values of alpha (x).
The functions computes sum of loss values which is required during the line search step for the optimization of the alpha. This function is given as the input for the L-BFGS optimization function.
Keyword parameters:
alpha (float): The current value of the alpha.
targets (float <#samples, #outputs>): The targets for the samples
previous_scores (float <#samples, #outputs>): The cumulative prediction scores of the samples until the previous round of the boosting.
current_scores (float <#samples, #outputs>): The prediction scores of the samples for the current round of the boosting.
Returns
(float <#outputs>) The sum of the loss values for the current value of the alpha
Bases: object
Pure virtual base class for weak machines
Class Members:
Computes a weighted histogram from the given features.
Parameters:
features : array_like <1D, uint16>
The vector of features to compute a histogram for
weights : array_like <1D, float>
The vector of weights; must be of the same size as the features
histogram : array_like <1D, float>
The histogram that will be filled