Welcome to VILMA’s documentation!

This web-page provides C++ implementation of VILMA which is a algorithm for learning of ordinal classifier from interval annotations. It was proposed in the paper: (We will add link here if paper is accepted).

Authors:

VILMA installation

VILMA is implemented in C++. Internal optimization problem is solved using Oracle Based Optimization Engine (OBOE) implementation of Analytic Center Cutting Plane Method (ACCPM) as a part of COmputatiomal INfrastructure for Operations Research (COIN-OR). As for Bundle Method Risk Minimization (BMRM) we use implementation from the SHOGUN mahine learning toolbox.

To build VILMA you must have installed the follwing software on your PC:
  • BLAS
  • LAPACK
  • Lapackpp
  • aclocal
  • autoconf
  • cmake

To grab code make git clone git@bitbucket.org:K0stIa/vilma.git

mkdir build && cd build
cmake -DOBOE=/path/to/oboe/lib -DLAPACKPP=/path/to/lapackpp/lib -DCMAKE_CXX_COMPILER=${Your compiler >= gcc-4.7} ..
make
cd ..

Tested with cmake (>= 2.8)

You need to have installed ACCPM OBOE library from the next section.

ACCPM installation

We have addopted original a bit outdated implementation of ACCPM for VILMA.

We have published modified code at Github. Make git clone git@github.com:K0stIa/OBOE.git to grab modified code.

To run OBOE for ACCPM you must have following packages installed on your machine:

To install modified version, first you have to install following required packages:

install.sh script installs ACCPM assuming you have all requireed software

VILMA installation is tested on MacOs Yosemite 10.10.5 and Gentoo Base System release 2.1.

How to use

Given data pairs \(({\bf x},y_l, y_r)\), the linear method learns the model vector \(\left( {\bf w}, { \bf b } \right)\) by minizing the following objective function:

\[\begin{equation} ({\bf w}^*,{\bf b}^*) = \mathop{\rm argmin}_{ {\bf w}\in\Re^n,{\bf b}\in\Re^Y} \bigg [ \frac{\lambda}{2}\|{\bf w}\|^2 + \frac{1}{m}\sum_{i=1}^m \ell_I({\bf x}^i,y_l^i,y_r^i,{\bf w},{\bf b}) \bigg ] \:, \end{equation}\]

where

\[\begin{split}\begin{equation} \label{equ:genericCvxSurrogate} \begin{array}{rcl} \ell_I({\bf x},y_l,y_r,{\bf w},{\bf b}) &= &\displaystyle\max_{y \leq y_l}\Big [\Delta(y,y_l) + \langle {\bf x}, {\bf w} \rangle (y-y_l) + b_y - b_{y_l} \Big ] \\ & & \displaystyle+ \max_{y\ge y_r} \Big [ \Delta(y,y_r) + \langle {\bf x}, {\bf w} \rangle (y-y_r) + b_y - b_{y_r} \Big ]\:, \end{array} \end{equation}\end{split}\]

where \(\Delta(y1, y2)\) is so-called V-shaped loss function, see Config Loss

Train VILMA

To get VILMA model from your data use train_vilma from build directory.

Provide all(!) parameters exactly in given bellow order!:

$ ./build/train_vilma features_path labeling_path model_path dim n_classes lambda bmrm_buffer_size
features_path
absolute path to your txt with features, see Train && Test file formats.
labeling_path
absolutte path to your rxr with given labeling, see Train && Test file formats.
model_path
absolute path to save trained model.
dim
dimensionality of feature vector, for provided data it is 723712.
n_classes
number of classes, for provided data it is 55.
lambda
regularizer parameter, e.g. 0.1 for provided data.
bmrm_buffer_size
size of cutting plane model used in BMRM, always estimate it(!) if you have small RAM, e.g. if you want to use 100 cutting planes, then VILMA will use at least \(100 \times dim \times sizeof (double) / 1e6\) MB of RAM.

Evaluate VILMA

To calculate test error use test_vilma from your build directory.

Provide all(!) parameters exactly in given bellow order!:

$ ./build/test_vilma features_path labeling_path model_path dim n_classes
features_path
absolute path to your txt with features, see Train && Test file formats.
labeling_path
absolutte path to your rxr with given labeling, see Train && Test file formats.
model_path
absolute path to save trained model.
dim
dimensionality of feature vector, for provided data it is 723712.
n_classes
number of classes, for provided data it is 55.

Config Loss

Name Description Formula $typedef
0/1 zero loss \(\mathbb{1} \left( y_1 \neq y_2 \right)\) typedef Vilma::ZOLoss Loss;
MAE mean absolute error loss \(|y_1 - y_2|\) typedef Vilma::MAELoss Loss;

Define $typedef in train_vilma.cpp to use either of losses. Of course, you have to re-build VILMA. You can define your own loss function, see loss.h. Note, it has to be a V-shaped function, see [Antoniuk-Franc-Hlavac-MORD2013] || [Antoniuk-Franc-Hlavac-ACML2014].

Train && Test file formats

Yor features.txt must contain in each row exactly one feature vector in the form index:value where index are integers between 0 and dim-1, e.g. dim=6 features.txt:

0:2.4 1:4 4:5.8
1:1 2:5 3:1.6
3:2 4:2 5:9

labeling.txt must have same number of rows as features.txt. Each row must have two integers: \(y_l y_r\), \(y_l <= y_r\), \(0 <= y_l, y_r < \mbox{n_classes}\), e.g. n_classes=5

0 4
1 1
3 4

Demo

Download files features.txt and supervised_labeling.txt, partial_labeling.txt put them into folder ./data and run script run_demo.sh.

Script creates 5 folders each with 1K same supervised examples + 0/1K/2K/3K/4K partial examples and test obtained model on the same test set of 5K examples. You get same number as bellow.

Supervsed 1K 1K 1K 1K 1K
Partial 0K 1K 2K 3K 4K
MAE 12.548 12.642 12.264 12.1185 12.1102

References:

[Antoniuk-Franc-Hlavac-MORD2013]Antoniuk, K., Franc, V., and Hlavac, V. (2013). Mord: Multi-class classifier for ordinal regression. In ECML/PKDD (3), pages 96–111.
[Antoniuk-Franc-Hlavac-ACML2014]Antoniuk, K., Franc, V., and Hlavac, V. (2014). Interval Insensitive Loss for Ordinal Classification. In ACML 2014, pages 189-204.