Python-to-libsvm interface

Table of Contents
=================

- Introduction
- Installation
- Usage
- Examples

Introduction
============

Python (http://www.python.org/) is a programming language suitable for
rapid development. This python-to-libsvm interface is developed so 
users can easily experiment with libsvm using python. The interface is 
developed with SWIG, 

The original idea and the SWIG interface file was provided by Carl Staelin
(staelin@hpl.hp.com) from HP Labs. The interface was integrated into the
libsvm package by Li-lun Wang (llwang@infor.org) from National Taiwan
University. Chih-Chung Chang (b4506055@csie.ntu.edu.tw) from National
Taiwan University also contributed many useful suggestions.

Installation
============

We first show the instructions for Unix and
then those for MS Windows.

The build process for the various Unix systems is as follows:

Before you build the module, you need to find out the python include
directory, which is typically located at /usr/local/include/python2.5 or
/usr/include/python. You can set the variable PYTHON_INCLUDEDIR in
Makefile manually or use something like the following:

	make PYTHON_INCLUDEDIR=/usr/include/python all

Although the interface is generated by SWIG, it is not necessary to
have SWIG installed because the generated svmc_wrap.c is included in
this package (It was generated using SWIG 1.3.31). If you prefer
generating the interface with SWIG on your own, you can simply remove
the generated files with

	make moreclean

before building the module. Note that SWIG version > 1.3.7 should be used.

When the build process completes, a shared object called svmc.so will be
created.

For win32 systems, the shared library svmc.pyd is ready in the
directory windows/python. You need to copy it to this directory.  The
.pyd file depends on different versions of python, so you may have to
re-make it by following the instruction of building windows binaries
in libsvm README.

To install this module into the system's Python installation, you
should be a system administrator and type:

	python setup.py install

This command will create a directory build/ containing the module and
install it to the Python installation (i.e. the python library
directory).

Usage
=====
To use the module, the files svm.py and the shared library (namely svmc.so
or svmc.pyd) must be placed in the current directory, the python library
directory, or the directory where the environment variable PYTHONPATH
points to. The user then imports everything in svm.py to use libsvm in
python:

	from svm import *

There are three classes in svm.py, namely svm_parameter, svm_problem, and
svm_model.

svm_parameter is used to set the parameters of the training
process. The attributes in svm_parameter include svm_type,
kernel_type, degree, gamma, coef0, nu, cache_size, C, eps, p,
shrinking, nr_weight, weight_label, and weight. Available svm types
include C_SVC, NU_SVC, ONE_CLASS, EPSILON_SVR, and NU_SVR. Available
kernel types include LINEAR, POLY, RBF, and SIGMOID. The user can
setup the parameters with the constructor and keyword arguments:

	param = svm_parameter(kernel_type = LINEAR, C = 10)

The user can also modify the parameters later:

	param.kernel_type = RBF

svm_problem is used to hold the training data for the problem. The
constructor takes two arguments; the first of them is the list of labels,
and the other is the list of samples. For example

	prob = svm_problem([1,-1],[[1,0,1],[-1,0,-1]])

or equivalently

	prob = svm_problem([1,-1],[{1:1,3:1},{1:-1,3:-1}])

Warning: due to supporting the precomputed kernels (described below),
a sample [1,0,1] is internally represented as {0:1, 2:1}. Thus, you
should use only one format in your entire code (for both
training/testing). For example, using

	prob = svm_problem([1,-1],[[1, 0, 1],{1:-1,3:-1}])

will result in a different model from the above example.

For precomputed kernels, the first element of each instance must be
the ID. For example,

	samples = [[1, 0, 0, 0, 0], [2, 0, 1, 0, 1], [3, 0, 0, 1, 1], [4, 0, 1, 1, 2]]
	problem = svm_problem(labels, samples);

For more details of precomputed kernels, please check README of the
parent directory.

Once the parameter and problem are ready, we can construct the model:

	m = svm_model(prob, param)

To conduct n-fold cross validation; predicted labels in the validation
process are returned.

	target = cross_validation(prob, param, n)

To predict a new sample with the model:

	r = m.predict([1, 1, 1])

To obtain decision values of predicting a sample:

	d = m.predict_values([1, 1, 1])	

To predict a new sample and obtain probability estimates;
return value is a dict that maps labels to probabilities.

	prd, prb = m.predict_probability([1, 1, 1])
	sample of prd : 1.0
	sample of prb : {1:0.6, -1:0.4}

To obtain sigma of the probability density function for regression;
see ../README for the definition of the function.

	sigma = m.get_svr_probability()

To obtain the probability density function for regression; see
../README for the definition of the function.

	pdf = m.get_svr_pdf()
	probability = pdf(z)

To save the model to a file:

	m.save('test.model')

and to load the model from a file:

	m = svm_model('test.model')

Examples
========

There are two examples in this package. The one is svm_test.py, and the
other is test_cross_validation.py.

svm_test.py tests various kernels on a three-class problem with
C-SVM. It also demonstrates how to obtain decision values and
probability estimates.

test_cross_validation.py demonstrates loading data from a file and
does a ten-fold cross validation on the heart_scale dataset. It makes
use of cross_validation.py which calls the C++ cross validation
subroutine.
