Python API

This section includes information for using the Python API of bob.learn.boosting.

Machines

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.

Trainers

Available trainers in bob.learn.boosting are:

Loss functions

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:

  1. bob.learn.boosting.ExponentialLoss with bob.learn.boosting.StrumTrainer (uni-variate classification only).
  2. bob.learn.boosting.LogitLoss with bob.learn.boosting.StrumTrainer or bob.learn.boosting.LUTTrainer (uni-variate or multi-variate classification).
  3. bob.learn.boosting.TangentialLoss with bob.learn.boosting.StrumTrainer or bob.learn.boosting.LUTTrainer (uni-variate or multi-variate classification).
  4. bob.learn.boosting.JesorskyLoss with bob.learn.boosting.LUTTrainer (multi-variate regression only).

Details

bob.learn.boosting.get_config()[source]

Returns a string containing the configuration information.

class bob.learn.boosting.BoostedMachine

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:

add_weak_machine()
  • add_weak_machine(machine, weight) -> None
  • add_weak_machine(machine, weights) -> None

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)
alpha

float <#machines,#outputs> <– The weights for the weak machines

feature_indices([start[, end]]) → indices

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
forward()
  • forward(features) -> prediction
  • forward(features, predictions) -> None
  • forward(features, predictions, labels) -> None

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:

  1. (uint16 <#inputs>) will compute and return the uni-variate prediction for a single feature vector.
  2. (uint16 <#samples,#inputs>, float <#samples>) will compute the uni-variate prediction for several feature vectors.
  3. (uint16 <#samples,#inputs>, float <#samples>, float<#samples>) will compute the uni-variate prediction and the labels for several feature vectors.
  4. (uint16 <#inputs>, float <#outputs>) will compute the multi-variate prediction for a single feature vector.
  5. (uint16 <#samples,#inputs>, float <#samples,#outputs>) will compute the multi-variate prediction for several feature vectors.
  6. (uint16 <#samples,#inputs>, float <#samples,#outputs>, float <#samples,#outputs>) will compute the multi-variate prediction and the labels for several feature vectors.

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
indices

int <#machines,#outputs> <– The indices into the feature vector required by all of the weak machines.

load(hdf5) → None

Loads the Strong machine from the given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

The HDF5 file to load this machine from.
outputs

int <– The number of outputs; for uni-variate classifiers always 1

save(hdf5) → None

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.
weak_machines

[WeakMachine] <– The list of weak machines stored in this strong machine

weights

float <#machines,#outputs> <– The weights for the weak machines

class bob.learn.boosting.Boosting(weak_trainer, loss_function)[source]

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.
get_loss_function()[source]

Returns the loss function this trainer will use.

train(training_features, training_targets, number_of_rounds=20, boosted_machine=None)[source]

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:

training_features : uint16 <#samples, #features> or float <#samples, #features>)
Features extracted from the training samples.
training_targets : float <#samples, #outputs>
The values that the boosted classifier should reach for the given samples.
number_of_rounds : int
The number of rounds of boosting, i.e., the number of weak classifiers to select.
boosted_machine bob.learn.boosting.BoostedMachine or None
The machine to add the weak machines to. If not given, a new machine is created.
Returns : bob.learn.boosting.BoostedMachine
The boosted machine that is combination of the weak classifiers.
class bob.learn.boosting.ExponentialLoss[source]

Bases: bob.learn.boosting.LossFunction.LossFunction

The class implements the exponential loss function for the boosting framework.

loss(targets, scores)[source]

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.

Returns
(float <#samples, #outputs>): The loss values for the samples, always >= 0
loss_gradient(targets, scores)[source]

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.

Returns
loss (float <#samples, #outputs>): The gradient of the loss based on the given scores and targets.
loss_gradient_sum(alpha, targets, previous_scores, current_scores)

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.

Returns
(float <#outputs>) The sum of the loss gradient for the current value of the alpha.
loss_sum(alpha, targets, previous_scores, current_scores)

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
class bob.learn.boosting.JesorskyLoss

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:

loss(targets, scores) → errors

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
loss_gradient(targets, scores) → gradient

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
loss_gradient_sum(alpha, targets, previous_scores, current_scores) → gradient_sum

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
loss_sum(alpha, targets, previous_scores, current_scores) → loss_sum

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
class bob.learn.boosting.LUTMachine

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:

feature_indices() → indices

Returns the feature index that will be used in this weak machine

Returns:

indices : int32 <1>

The feature index required by this machine
forward()
  • forward(features) -> prediction
  • forward(features, predictions) -> None

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:

  1. (uint16 <#inputs>) will compute and return the uni-variate prediction for a single feature vector.
  2. (uint16 <#samples,#inputs>, float <#samples>) will compute the uni-variate prediction for several feature vectors.
  3. (uint16 <#inputs>, float <#outputs>) will compute the multi-variate prediction for a single feature vector.
  4. (uint16 <#samples,#inputs>, float <#samples,#outputs>) will compute the multi-variate prediction for several feature vectors.

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
load(hdf5) → None

Loads the LUT machine from the given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

The HDF5 file to load this weak machine from.
lut

float <#entries,#outputs> <– The look-up table associated with this object. In the uni-variate case, #outputs will be 1

save(hdf5) → None

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.
class bob.learn.boosting.LUTTrainer

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-Tables

number_of_outputs : int

The dimensionality of the output vector; defaults to 1 for the uni-variate case

selection_style : str

The way, features are selected; possible values: ‘shared’, ‘independent’; only useful for the multi-variate case; defaults to ‘independent’

Class Members:

number_of_labels

uint16 <– The highest feature value + 1, i.e., the number of entries in the LUT

number_of_outputs

int <– The dimensionality of the output vector (1 for the uni-variate case)

selection_type

str <– The style for selecting features (valid for multi-variate case only)

train(training_features, loss_gradient) → lut_machine

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
class bob.learn.boosting.LogitLoss[source]

Bases: bob.learn.boosting.LossFunction.LossFunction

The class to implement the logit loss function for the boosting framework.

loss(targets, scores)[source]

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.

Returns
(float <#samples, #outputs>): The loss values for the samples, which is always >= 0
loss_gradient(targets, scores)[source]

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.

Returns
loss (float <#samples, #outputs>): The gradient of the loss based on the given scores and targets.
loss_gradient_sum(alpha, targets, previous_scores, current_scores)

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.

Returns
(float <#outputs>) The sum of the loss gradient for the current value of the alpha.
loss_sum(alpha, targets, previous_scores, current_scores)

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
class bob.learn.boosting.StumpMachine

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 threshold

polarity : float

-1 if positive values are below threshold, +1 if positive values are above threshold

index : int

The index into the feature vector that is thresholded

hdf5 : bob.io.base.HDF5File

The HDF5 file object to read the weak classifier from

Class Members:

feature_indices() → indices

Returns the feature index that will be used in this weak machine

Returns:

indices : int32 <1>

The feature index required by this machine
forward()
  • forward(features) -> prediction
  • forward(features, predictions) -> None

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
load(hdf5) → None

Loads the Stump machine from the given HDF5 file

Parameters:

hdf5 : bob.io.base.HDF5File

The HDF5 file to load this weak machine from.
polarity

float <– The polarity of the comparison: -1 if the values lower than the threshold should be accepted, +1 otherwise

save(hdf5) → None

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.
threshold

float <– The thresholds that the feature value will be compared with

class bob.learn.boosting.StumpTrainer[source]

The class for training weak stump classifiers. The weak stump is parameterized the threshold and the polarity.

compute_threshold(features, gradient)[source]

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.

Keyword parameters

features (float<#samples>): The feature values for a single index

gradient (float<#samples>): The negative loss gradient values for the training samples

Returns a triplet containing:
threshold (float): threshold that minimizes the error polarity (float): the polarity or the direction used for stump classification gain (float): gain of the classifier
train(training_features, loss_gradient)[source]

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.

Keyword parameters

training_features (float<#samples, #features>): The training features samples

loss_gradient (float<#samples>): The loss gradient values for the training samples

Returns
A (weak) bob.learn.boosting.StumpMachine
class bob.learn.boosting.TangentialLoss[source]

Bases: bob.learn.boosting.LossFunction.LossFunction

Tangent loss function, as described in http://www.svcl.ucsd.edu/projects/LossDesign/TangentBoost.html.

loss(targets, scores)[source]

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.

Returns
(float <#samples, #outputs>): The loss values for the samples, always >= 0
loss_gradient(targets, scores)[source]

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.

Returns
loss (float <#samples, #outputs>): The gradient of the loss based on the given scores and targets.
loss_gradient_sum(alpha, targets, previous_scores, current_scores)

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.

Returns
(float <#outputs>) The sum of the loss gradient for the current value of the alpha.
loss_sum(alpha, targets, previous_scores, current_scores)

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
class bob.learn.boosting.WeakMachine

Bases: object

Pure virtual base class for weak machines

Class Members:

bob.learn.boosting.weighted_histogram(features, weights, histogram) → None

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