Documentation>C API
Typedefs
svmdataset.h File Reference

SVM Dataset. More...

`#include "generic.h"`
`#include "homkermap.h"`

## Typedefs

typedef OPAQUE | VlSvmDataset
| SVM dataset object.
SVM callbacks
typedef void(* | VlSvmDiagnosticFunction) (struct VlSvm_ *svm, void *data)
| SVM diagnostic function pointer.
typedef double(* | VlSvmLossFunction) (double inner, double label)
| SVM loss function pointer.
typedef double(* | VlSvmDcaUpdateFunction) (double alpha, double inner, double norm2, double label)
| SVM SDCA update function pointer.
typedef double(* | VlSvmInnerProductFunction) (const void *data, vl_uindex element, double *model)
| Pointer to a function that defines the inner product between the data point at position element and the SVM model.
typedef void(* | VlSvmAccumulateFunction) (const void *data, vl_uindex element, double *model, double multiplier)
| Pointer to a function that adds to model the data point at position element multiplied by the constant multiplier.

## Functions

Create and destroy
VlSvmDataset * | vl_svmdataset_new (vl_type dataType, void *data, vl_size dimension, vl_size numData)
| Create a new object wrapping a dataset.
void | vl_svmdataset_delete (VlSvmDataset *dataset)
| Delete the object.
Set parameters
void | vl_svmdataset_set_homogeneous_kernel_map (VlSvmDataset *self, VlHomogeneousKernelMap *hom)
| Set the homogeneous kernel map object.
Get data and parameters
void * | vl_svmdataset_get_data (VlSvmDataset const *self)
| Get the wrapped data.
vl_size | vl_svmdataset_get_num_data (VlSvmDataset const *self)
| Get the number of wrapped data elements.
vl_size | vl_svmdataset_get_dimension (VlSvmDataset const *self)
| Get the dimension of the wrapped data.
VlSvmAccumulateFunction | vl_svmdataset_get_accumulate_function (VlSvmDataset const *self)
| Get the accumulate function.
VlSvmInnerProductFunction | vl_svmdataset_get_inner_product_function (VlSvmDataset const *self)
| Get the inner product function.
VlHomogeneousKernelMap * | vl_svmdataset_get_homogeneous_kernel_map (VlSvmDataset const *self)
| Get the homogeneous kernel map object.

## Detailed Description

Author
  Daniele Perrone
  Andrea Vedaldi

The SVM solver object VlSvm, supporting SVM learning in VLFeat, uses an abstraction mechanism to work on arbitrary data types. This module provides an helper object, VlSvmDataset, that simplify taking advantage of this functionality, supporting for example different data types and the computation of feature maps out of the box.

# Getting started

As discussed in Advanced SVM topics, most linear SVM solvers, such as the ones implemented in VLFeat in Support Vector Machines (SVM), require only two operations to be defined on the data:

- Inner product between a data point \(\bx\) and the model vector \(\bw\). This is implemented by a function of type VlSvmInnerProductFunction.
- Accumulation of a dataobint \(\bx\) to the model vector \(\bw\): \(\bw \leftarrow \bw + \alpha \bx\). This is implemented by a function of the type VlSvmAccumulateFunction .

The SVM solver needs to know nothing about the data once these two operations are defined. These functions can do any number of things, such as supporting different formats for the data (dense or sparse, float or double), computing feature maps, or expanding compressed representations such as Product Quantization.

VLFeat provides the helper object VlSvmDataset to support some of these functionalities out of the box (it is important to remark that its use with the SVM solver VlSvm is entirely optional).

Presently, VlSvmDataset supports:

- `float` and `double` dense arrays.
- The on-the-fly application of the homogeneous kernel map to implement additive non-linear kernels (see Homogeneous kernel map).

For example, to learn a linear SVM on SINGLE data:

int main()
{
vl_size const numData = 4 ;
vl_size const dimension = 2 ;
single x [dimension * numData] = {
0.0, -0.5,
0.6, -0.3,
0.0, 0.5,
0.6, 0.0} ;
double y [numData] = {1, 1, -1, 1} ;
double lambda = 0.01;
double * const model ;
double bias ;
VlSvmDataset * dataset = vl_svmdataset_new (VL_TYPE_SINGLE, x, dimension, numData) ;
VlSvm * svm = vl_svm_new_with_dataset (VlSvmSolverSgd, dataset, y, lambda) ;
vl_svm_train(svm) ;
model = vl_svm_get_model(svm) ;
bias = vl_svm_get_bias(svm) ;
printf("model w = [ %f , %f ] , bias b = %f \n",
model[0],
model[1],
bias);
vl_svm_delete(svm) ;
vl_svmdataset_delete(dataset) ;
return 0;
}
vl_size
vl_uint64 vl_size
Unsigned integer holding the size of a memory block.
Definition host.h:392
vl_svm_new_with_dataset
VlSvm * vl_svm_new_with_dataset(VlSvmSolverType solver, VlSvmDataset *dataset, double const *labels, double lambda)
Create a new object with a dataset.
Definition svm.c:980
vl_svm_train
void vl_svm_train(VlSvm *self)
Run the SVM solver.
Definition svm.c:2156
vl_svm_delete
void vl_svm_delete(VlSvm *self)
Delete object.
Definition svm.c:1097
vl_svm_get_model
double const * vl_svm_get_model(VlSvm const *self)
Get the SVM model.
Definition svm.c:1374
vl_svm_get_bias
double vl_svm_get_bias(VlSvm const *self)
Get the value of the bias.
Definition svm.c:1422
VlSvmSolverSgd
@ VlSvmSolverSgd
Definition svm.h:41
VlSvm
OPAQUE VlSvm
SVM solver. This object implements VLFeat SVM solvers (see svm.h).
Definition svm.h:34
vl_svmdataset_new
VlSvmDataset * vl_svmdataset_new(vl_type dataType, void *data, vl_size dimension, vl_size numData)
Create a new object wrapping a dataset.
Definition svmdataset.c:138
vl_svmdataset_delete
void vl_svmdataset_delete(VlSvmDataset *self)
Delete the object.
Definition svmdataset.c:164
VlSvmDataset
OPAQUE VlSvmDataset
SVM dataset object.
Definition svmdataset.h:39

Author
  Daniele Perrone
  Andrea Vedaldi

## Typedef Documentation

## ◆ VlSvmDataset

typedef OPAQUE VlSvmDataset

This objects contain a training set to be used in combination with the SVM solver object VlSvm. Its main purpose is to implement the two basic operations inner product (VlSvmInnerProductFunction) and accumulation (VlSvmAccumulateFunction).

See Support Vector Machines (SVM) and Advanced SVM topics for further information.

## ◆ VlSvmDcaUpdateFunction

typedef double(* VlSvmDcaUpdateFunction) (double alpha, double inner, double norm2, double label)

Parameters

  alpha | current value of the dual variable.
  inner | inner product \(\bw^\top \bx\) of the sample with the SVM model.
  norm2 | normalization factor \(\|\bx\|^2/\lambda n\).
  label | label \(y\) of the sample.

Returns
  incremental update \(\Delta\alpha\) of the dual variable.

See also
  Stochastic Dual Coordinate Ascent

## ◆ VlSvmDiagnosticFunction

typedef void(* VlSvmDiagnosticFunction) (struct VlSvm_ *svm, void *data)

Parameters

  svm | is an instance of VlSvm .

## ◆ VlSvmLossFunction

typedef double(* VlSvmLossFunction) (double inner, double label)

Parameters

  inner | inner product between sample and model \(\bw^\top \bx\).
  label | sample 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

## Function Documentation

## ◆ vl_svmdataset_delete()

void vl_svmdataset_delete | ( | VlSvmDataset * | self | ) |

Parameters

  self | object to delete.

The function frees the resources allocated by vl_svmdataset_new(). Notice that the wrapped data will not be freed as it is not owned by the object.

## ◆ vl_svmdataset_get_accumulate_function()

VlSvmAccumulateFunction vl_svmdataset_get_accumulate_function | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  a pointer to the accumulate function to use with this data.

## ◆ vl_svmdataset_get_data()

void * vl_svmdataset_get_data | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  a pointer to the wrapped data.

## ◆ vl_svmdataset_get_dimension()

vl_size vl_svmdataset_get_dimension | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  dimension of the wrapped data.

## ◆ vl_svmdataset_get_homogeneous_kernel_map()

VlHomogeneousKernelMap * vl_svmdataset_get_homogeneous_kernel_map | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  homogenoeus kernel map object (or `NULL` if any).

## ◆ vl_svmdataset_get_inner_product_function()

VlSvmInnerProductFunction vl_svmdataset_get_inner_product_function | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  a pointer to the inner product function to use with this data.

## ◆ vl_svmdataset_get_num_data()

vl_size vl_svmdataset_get_num_data | ( | VlSvmDataset const * | self | ) |

Parameters

  self | object.

Returns
  number of wrapped data elements.

## ◆ vl_svmdataset_new()

VlSvmDataset * vl_svmdataset_new | ( | vl_type | dataType,
|  | void * | data,
|  | vl_size | dimension,
|  | vl_size | numData )

Parameters

  dataType | of data (`float` and `double` supported).
  data | pointer to the data.
  dimension | the dimension of a data vector.
  numData | number of wrapped data vectors.

Returns
  new object.

The function allocates and returns a new SVM dataset object wrapping the data pointed by data. Note that no copy is made of data, so the caller should keep the data allocated as the object exists.

See also
  vl_svmdataset_delete

## ◆ vl_svmdataset_set_homogeneous_kernel_map()

void vl_svmdataset_set_homogeneous_kernel_map | ( | VlSvmDataset * | self,
|  | VlHomogeneousKernelMap * | hom )

Parameters

  self | object.
  hom | homogeneous kernel map object to use.

After changing the kernel map, the inner product and accumulator function should be queried again (vl_svmdataset_get_inner_product_function adn vl_svmdataset_get_accumulate_function).

Set this to `NULL` to avoid using a kernel map.

Note that this does not transfer the ownership of the object to the function. Furthermore, VlSvmDataset holds to the object until it is destroyed or the object is replaced or removed by calling this function again.