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

Python (http://www.python.org/) is a powerful scripting language which
supports easy-to-use object-oriented programming and has gained more and
more popularity. This python-to-libsvm interface is developed so users can
easily experiment with libsvm using python.

The interface is developed with SWIG, the Simplified Wrapper and Interface
Generator (http://www.swig.org/). SWIG can be used to connect libraries
written in C and C++ to a variety of high-level scripting languages.

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 a lot of useful suggestions and help.

Installation
============
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.1 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.
If you prefer to generate the interface with SWIG on your own, you can 
simply remove the generated files with

	make moreclean

before building the module.

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

For win32 systems, the shared library svmc.dll is ready in this package.

Usage
=====
To use the module, the files svm.py and the shared library (namely svmc.so
or svmc.dll) must be placed in the current directory, the python library
directory, or the directory where the environment variable PYTHONHOME
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, and nr_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}])

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

	m = svm_model(prob, param)

To predict a new sample with the model:

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

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 four kernels, i.e., linear, polynomial, RBF, and
sigmoid, on the XOR problem with C-SVM.

test_cross_validation.py makes use of cross_validation.py which is an
implementation of cross validation in python. This example demonstrates
loading data from file and does a ten-fold cross validation on the
heart_scale dataset.
