Documentation - C API
svm.h File Reference

Support Vector Machines (Support Vector Machines (SVM)) More...

#include "generic.h"
#include "svmdataset.h"

Data Structures

struct  VlSvmStatistics
 SVM statistics This structure contains statistics characterising the state of the SVM solver, such as the current value of the objective function. More...

Typedefs

typedef OPAQUE VlSvm
 SVM solver. This object implements VLFeat SVM solvers (see svm.h).

Enumerations

enum  VlSvmSolverType { VlSvmSolverNone = 0, VlSvmSolverSgd = 1, VlSvmSolverSdca }
 Type of SVM solver. More...
enum  VlSvmLossType {
  VlSvmLossHinge = 0, VlSvmLossHinge2 = 1, VlSvmLossL1, VlSvmLossL2,
  VlSvmLossLogistic
}
 Type of SVM loss. More...
enum  VlSvmSolverStatus { VlSvmStatusTraining = 1, VlSvmStatusConverged, VlSvmStatusMaxNumIterationsReached }
 Solver status. More...

Functions

Create and destroy
VlSvmvl_svm_new (VlSvmSolverType type, double const *data, vl_size dimension, vl_size numData, double const *labels, double lambda)
 Create a new object with plain data.
VlSvmvl_svm_new_with_dataset (VlSvmSolverType type, VlSvmDataset *dataset, double const *labels, double lambda)
 Create a new object with a dataset.
VlSvmvl_svm_new_with_abstract_data (VlSvmSolverType type, void *data, vl_size dimension, vl_size numData, double const *labels, double lambda)
 Create a new object with abstract data.
void vl_svm_delete (VlSvm *self)
 Delete object.
Retrieve parameters and data
VlSvmStatistics const * vl_svm_get_statistics (VlSvm const *self)
 Get the solver statistics.
double const * vl_svm_get_model (VlSvm const *self)
 Get the SVM model.
double vl_svm_get_bias (VlSvm const *self)
 Get the value of the bias.
vl_size vl_svm_get_dimension (VlSvm *self)
 Get the model dimenison.
vl_size vl_svm_get_num_data (VlSvm *self)
 Get the number of data samples.
double vl_svm_get_epsilon (VlSvm const *self)
 Get the convergence threshold.
double vl_svm_get_bias_learning_rate (VlSvm const *self)
 Get the bias leraning rate.
vl_size vl_svm_get_max_num_iterations (VlSvm const *self)
 Get the maximum number of iterations.
vl_size vl_svm_get_diagnostic_frequency (VlSvm const *self)
 Get the diagnostic frequency.
VlSvmSolverType vl_svm_get_solver (VlSvm const *self)
 Get the SVM solver type.
double vl_svm_get_bias_multiplier (VlSvm const *self)
 Get the bias multiplier.
double vl_svm_get_lambda (VlSvm const *self)
 Get the regularizer parameter lambda.
vl_size vl_svm_get_iteration_number (VlSvm const *self)
 Get the current iteration number.
double const * vl_svm_get_scores (VlSvm const *self)
 Get the scores of the data points.
double const * vl_svm_get_weights (VlSvm const *self)
 Get the data weights.
Set parameters
void vl_svm_set_epsilon (VlSvm *self, double epsilon)
 Set the convergence threshold.
void vl_svm_set_bias_learning_rate (VlSvm *self, double rate)
 Set the bias learning rate.
void vl_svm_set_max_num_iterations (VlSvm *self, vl_size maxNumIterations)
 Set the maximum number of iterations.
void vl_svm_set_diagnostic_frequency (VlSvm *self, vl_size f)
 Set the diagnostic frequency.
void vl_svm_set_bias_multiplier (VlSvm *self, double b)
 Set the bias multiplier.
void vl_svm_set_model (VlSvm *self, double const *model)
 Set the SVM model.
void vl_svm_set_bias (VlSvm *self, double b)
 Set the SVM bias.
void vl_svm_set_iteration_number (VlSvm *self, vl_uindex n)
 Set the current iteratio number.
void vl_svm_set_weights (VlSvm *self, double const *weights)
 Set the data weights.
void vl_svm_set_diagnostic_function (VlSvm *self, VlSvmDiagnosticFunction f, void *data)
 Set the diagnostic function callback.
void vl_svm_set_loss_function (VlSvm *self, VlSvmLossFunction f)
 Set the loss function callback.
void vl_svm_set_loss_derivative_function (VlSvm *self, VlSvmLossFunction f)
 Set the loss derivative function callback.
void vl_svm_set_conjugate_loss_function (VlSvm *self, VlSvmLossFunction f)
 Set the conjugate loss function callback.
void vl_svm_set_dca_update_function (VlSvm *self, VlSvmDcaUpdateFunction f)
 Set the DCA update function callback.
void vl_svm_set_data_functions (VlSvm *self, VlSvmInnerProductFunction inner, VlSvmAccumulateFunction acc)
 Set the data functions.
void vl_svm_set_loss (VlSvm *self, VlSvmLossType loss)
 Set the loss function to one of the default types.
Process data
void vl_svm_train (VlSvm *self)
 Run the SVM solver.
Loss functions
double vl_svm_hinge_loss (double label, double inner)
 SVM hinge loss.
double vl_svm_hinge_loss_derivative (double label, double inner)
 SVM hinge loss derivative.
double vl_svm_hinge_conjugate_loss (double label, double u)
 SVM hinge loss conjugate.
double vl_svm_hinge_dca_update (double alpha, double inner, double norm2, double label)
 SVM hinge loss DCA update.
double vl_svm_hinge2_loss (double label, double inner)
 SVM square hinge loss.
double vl_svm_hinge2_loss_derivative (double label, double inner)
 SVM square hinge loss derivative.
double vl_svm_hinge2_conjugate_loss (double label, double u)
 SVM square hinge loss conjugate.
double vl_svm_hinge2_dca_update (double alpha, double inner, double norm2, double label)
 SVM square hinge loss DCA update.
double vl_svm_l1_loss (double label, double inner)
 SVM l1 loss.
double vl_svm_l1_loss_derivative (double label, double inner)
 SVM l1 loss derivative.
double vl_svm_l1_conjugate_loss (double label, double u)
 SVM l1 loss conjugate.
double vl_svm_l1_dca_update (double alpha, double inner, double norm2, double label)
 SVM l1 loss DCA update.
double vl_svm_l2_loss (double label, double inner)
 SVM l2 loss.
double vl_svm_l2_loss_derivative (double label, double inner)
 SVM l2 loss derivative.
double vl_svm_l2_conjugate_loss (double label, double u)
 SVM l2 loss conjugate.
double vl_svm_l2_dca_update (double alpha, double inner, double norm2, double label)
 SVM l2 loss DCA update.
double vl_svm_logistic_loss (double label, double inner)
 SVM l2 loss.
double vl_svm_logistic_loss_derivative (double label, double inner)
 SVM l2 loss derivative.
double vl_svm_logistic_conjugate_loss (double label, double u)
 SVM l2 loss conjugate.
double vl_svm_logistic_dca_update (double alpha, double inner, double norm2, double label)
 SVM l2 loss DCA update.

Detailed Description

See also:
Support Vector Machines (SVM).
Author:
Milan Sulc
Daniele Perrone
Andrea Vedaldi

Enumeration Type Documentation

Default SVM loss types. The loss can be set by using vl_svm_set_loss. Note that custom losses can be used too by using vl_svm_set_loss_function, vl_svm_set_loss_derivative_function, etc.

See also:
svm-loss-functions
Enumerator:
VlSvmLossHinge 

Standard hinge loss.

VlSvmLossHinge2 

Hinge loss squared.

VlSvmLossL1 

L1 loss.

VlSvmLossL2 

L2 loss.

VlSvmLossLogistic 

Logistic loss.

Enumerator:
VlSvmStatusTraining 

Optimization in progress.

VlSvmStatusConverged 

Optimization finished because the convergence criterion was met.

VlSvmStatusMaxNumIterationsReached 

Optimization finished without convergence.

Enumerator:
VlSvmSolverNone 

No solver (used to evaluate an SVM).

VlSvmSolverSgd 

SGD algorithm (Stochastic Gradient Descent).

VlSvmSolverSdca 

SDCA algorithm (Stochastic Dual Coordinate Ascent).


Function Documentation

void vl_svm_delete ( VlSvm self)
Parameters:
selfobject.
See also:
vl_svm_new
double vl_svm_get_bias ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
bias \(b\).

The value of the bias returned already include the effect of bias mutliplier.

double vl_svm_get_bias_learning_rate ( VlSvm const *  self)
Parameters:
selfobject
Returns:
bias learning rate.
double vl_svm_get_bias_multiplier ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
bias multiplier.
vl_size vl_svm_get_diagnostic_frequency ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
diagnostic frequency.
vl_size vl_svm_get_dimension ( VlSvm self)
Parameters:
selfobject.
Returns:
model dimension.

This is the dimensionality of the weight vector \(\bw\).

double vl_svm_get_epsilon ( VlSvm const *  self)
Parameters:
selfobject
Returns:
epsilon threshold.
vl_size vl_svm_get_iteration_number ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
current iteration number.
double vl_svm_get_lambda ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
diagnostic frequency.
vl_size vl_svm_get_max_num_iterations ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
maximum number of iterations.
double const* vl_svm_get_model ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
model.

This is the weight vector \(\bw\).

vl_size vl_svm_get_num_data ( VlSvm self)
Parameters:
selfobject.
Returns:
model number of data samples

This is the dimensionality of the weight vector \(\bw\).

double const* vl_svm_get_scores ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
vector of scores.

After training or during the diagnostic callback, this function can be used to retrieve the scores of the points, i.e. \(\langle \bx_i, \bw \rangle + b\).

VlSvmSolverType vl_svm_get_solver ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
SVM solver type.
VlSvmStatistics const* vl_svm_get_statistics ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
statistics.
double const* vl_svm_get_weights ( VlSvm const *  self)
Parameters:
selfobject.
Returns:
data weights.
double vl_svm_hinge2_conjugate_loss ( double  u,
double  label 
)

Parameters:
udual variable.
labellabel value.
Returns:
conjugate loss.

double vl_svm_hinge2_dca_update ( double  alpha,
double  inner,
double  norm2,
double  label 
)

Parameters:
alphacurrent value of the dual variable.
innerinner product \(\bw^\top \bx\) of the sample with the SVM model.
norm2normalization factor \(\|\bx\|^2/\lambda n\).
labellabel \(y\) of the sample.
Returns:
incremental update \(\Delta\alpha\) of the dual variable.
See also:
Stochastic Dual Coordinate Ascent

double vl_svm_hinge2_loss ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_hinge2_loss_derivative ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_hinge_conjugate_loss ( double  u,
double  label 
)
Parameters:
udual variable.
labellabel value.
Returns:
conjugate loss.
double vl_svm_hinge_dca_update ( double  alpha,
double  inner,
double  norm2,
double  label 
)

Parameters:
alphacurrent value of the dual variable.
innerinner product \(\bw^\top \bx\) of the sample with the SVM model.
norm2normalization factor \(\|\bx\|^2/\lambda n\).
labellabel \(y\) of the sample.
Returns:
incremental update \(\Delta\alpha\) of the dual variable.
See also:
Stochastic Dual Coordinate Ascent

double vl_svm_hinge_loss ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_hinge_loss_derivative ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_l1_conjugate_loss ( double  u,
double  label 
)

Parameters:
udual variable.
labellabel value.
Returns:
conjugate loss.

double vl_svm_l1_dca_update ( double  alpha,
double  inner,
double  norm2,
double  label 
)

Parameters:
alphacurrent value of the dual variable.
innerinner product \(\bw^\top \bx\) of the sample with the SVM model.
norm2normalization factor \(\|\bx\|^2/\lambda n\).
labellabel \(y\) of the sample.
Returns:
incremental update \(\Delta\alpha\) of the dual variable.
See also:
Stochastic Dual Coordinate Ascent

double vl_svm_l1_loss ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_l1_loss_derivative ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_l2_conjugate_loss ( double  u,
double  label 
)

Parameters:
udual variable.
labellabel value.
Returns:
conjugate loss.

double vl_svm_l2_dca_update ( double  alpha,
double  inner,
double  norm2,
double  label 
)

Parameters:
alphacurrent value of the dual variable.
innerinner product \(\bw^\top \bx\) of the sample with the SVM model.
norm2normalization factor \(\|\bx\|^2/\lambda n\).
labellabel \(y\) of the sample.
Returns:
incremental update \(\Delta\alpha\) of the dual variable.
See also:
Stochastic Dual Coordinate Ascent

double vl_svm_l2_loss ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_l2_loss_derivative ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_logistic_conjugate_loss ( double  u,
double  label 
)

Parameters:
udual variable.
labellabel value.
Returns:
conjugate loss.

double vl_svm_logistic_dca_update ( double  alpha,
double  inner,
double  norm2,
double  label 
)

Parameters:
alphacurrent value of the dual variable.
innerinner product \(\bw^\top \bx\) of the sample with the SVM model.
norm2normalization factor \(\|\bx\|^2/\lambda n\).
labellabel \(y\) of the sample.
Returns:
incremental update \(\Delta\alpha\) of the dual variable.
See also:
Stochastic Dual Coordinate Ascent

double vl_svm_logistic_loss ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

double vl_svm_logistic_loss_derivative ( double  inner,
double  label 
)

Parameters:
innerinner product between sample and model \(\bw^\top \bx\).
labelsample label \(y\).
Returns:
value of the loss.

The interface is the same for a loss function, its derivative, or the conjugate loss.

See also:
SVM fundamentals

VlSvm* vl_svm_new ( VlSvmSolverType  type,
double const *  data,
vl_size  dimension,
vl_size  numData,
double const *  labels,
double  lambda 
)
Parameters:
typetype of SMV solver.
dataa pointer to a matrix of data.
dimensiondimension of the SVM model.
numDatanumber of training samples.
labelstraining labels.
lambdaregularizer parameter.
Returns:
the new object.

data has one column per sample, in double format. More advanced inputs can be used with vl_svm_new_with_dataset and vl_svm_new_with_abstract_data.

See also:
vl_svm_delete
VlSvm* vl_svm_new_with_abstract_data ( VlSvmSolverType  solver,
void *  data,
vl_size  dimension,
vl_size  numData,
double const *  labels,
double  lambda 
)
Parameters:
solvertype of SMV solver.
datapointer to the data.
dimensiondimension of the SVM model.
numDatanum training samples.
labelstraining samples labels.
lambdaregularizer parameter.
Returns:
the new object.

After calling this function, vl_svm_set_data_functions must be used to setup suitable callbacks for the inner product and accumulation operations (

See also:
svm-data-abstraction).
vl_svm_delete
VlSvm* vl_svm_new_with_dataset ( VlSvmSolverType  solver,
VlSvmDataset dataset,
double const *  labels,
double  lambda 
)
Parameters:
solvertype of SMV solver.
datasetSVM dataset object
labelstraining samples labels.
lambdaregularizer parameter.
Returns:
the new object.
See also:
vl_svm_delete
void vl_svm_set_bias ( VlSvm self,
double  b 
)
Parameters:
selfobject.
bbias.

The function set the internal representation of the SVM bias to be equal to b (the bias multiplier is applied). The same remark that applies to vl_svm_set_model applies here too.

void vl_svm_set_bias_learning_rate ( VlSvm self,
double  rate 
)
Parameters:
selfobject
ratebias learning rate (positive).

This parameter applies only to the SGD solver.

void vl_svm_set_bias_multiplier ( VlSvm self,
double  b 
)
Parameters:
selfobject
bbias multiplier.

The bias multiplier is the value of the constant feature appended to the data vectors to implement the bias (Adding a bias).

void vl_svm_set_conjugate_loss_function ( VlSvm self,
VlSvmLossFunction  f 
)

Parameters:
selfobject.
floss function callback.

Note that setting up a loss requires specifying more than just one callback. See Loss functions for details. .

void vl_svm_set_data_functions ( VlSvm self,
VlSvmInnerProductFunction  inner,
VlSvmAccumulateFunction  acc 
)
Parameters:
selfobject.
innerinner product function.
accaccumulate function.

See Data abstraction: working with compressed data.

void vl_svm_set_dca_update_function ( VlSvm self,
VlSvmDcaUpdateFunction  f 
)

Parameters:
selfobject.
floss function callback.

Note that setting up a loss requires specifying more than just one callback. See Loss functions for details. .

void vl_svm_set_diagnostic_frequency ( VlSvm self,
vl_size  f 
)
Parameters:
selfobject.
fdiagnostic frequency (>= 1).

A diagnostic round (to test for convergence and to printout information) is performed every f iterations.

void vl_svm_set_diagnostic_function ( VlSvm self,
VlSvmDiagnosticFunction  f,
void *  data 
)
Parameters:
selfobject.
fdiagnostic function pointer.
datapointer to data used by the diagnostic function.
void vl_svm_set_epsilon ( VlSvm self,
double  epsilon 
)
Parameters:
selfobject
epsilonthreshold (non-negative).
void vl_svm_set_iteration_number ( VlSvm self,
vl_uindex  n 
)
Parameters:
selfobject.
niteration number.

If called before training, this can be used with SGD for a warm start, as the net effect is to slow down the learning rate.

void vl_svm_set_loss ( VlSvm self,
VlSvmLossType  loss 
)
Parameters:
selfobject.
losstype of loss function.
See also:
Loss functions.
void vl_svm_set_loss_derivative_function ( VlSvm self,
VlSvmLossFunction  f 
)

Parameters:
selfobject.
floss function callback.

Note that setting up a loss requires specifying more than just one callback. See Loss functions for details. .

void vl_svm_set_loss_function ( VlSvm self,
VlSvmLossFunction  f 
)
Parameters:
selfobject.
floss function callback.

Note that setting up a loss requires specifying more than just one callback. See Loss functions for details.

void vl_svm_set_max_num_iterations ( VlSvm self,
vl_size  n 
)
Parameters:
selfobject.
nmaximum number of iterations.
void vl_svm_set_model ( VlSvm self,
double const *  model 
)
Parameters:
selfobject.
modelmodel.

The function copies the content of the vector model to the internal model buffer. This operation can be used for warm start with the SGD algorithm, but has undefined effect with the SDCA algorithm.

void vl_svm_set_weights ( VlSvm self,
double const *  weights 
)
Parameters:
selfobject.
weightsdata weights.

weights must be an array of non-negative weights. The loss of each data point is multiplied by the corresponding weight.

Set weights to NULL to weight the data uniformly by 1 (default).

Note that the weights array is not copied and must be valid througout the object lifetime (unless it is replaced).

void vl_svm_train ( VlSvm self)
Parameters:
selfobject.

The data on which the SVM operates is passed upon the cration of the VlSvm object. This function runs a solver to learn a corresponding model. See Getting started.