StaticInterfaces.mainpage

Go to the documentation of this file.

/*! \page staticinterfaces Static Interfaces

As mentioned before SHOGUN interfaces to several programming languages and
toolkits such as Matlab(tm), R, Python, Octave. The following sections shall
give you an overview over the static interface commands of SHOGUN. For the
static interfaces we tried to preserve the syntax of the commands in a
consistent manner through all the different languages. However as in some cases
this was not possible and we document the subtle differences of syntax and
semantic in the respective toolkit. Instead of reading through all this, we
suggest to have a look at the large number of examples available in the \b
examples / interface directory. For example examples/R or examples/python etc.

<b>Overview of Static Interfaces & Testing the Installation</b>
\li \ref staticoctaveinterf_sec
\li \ref staticpythoninterf_sec
\li \ref staticrinterf_sec

<b>Interface Commands</b>
\li \ref staticiffeatures_sec
\li \ref staticifkernel_sec
\li \ref staticifsvm_sec
\li \ref staticifhmm_sec
\li \ref staticifpoim_sec
\li \ref staticifutil_sec
\li \ref staticifexample_sec

<b>Command Reference</b>
\li \ref staticifcmdref_sec

\section staticifoverview_sec Overview of Static Interfaces & Testing the Installation

\subsection staticoctaveinterf_sec Static Matlab and Octave Interface

Since octave is nowadays up to par with matlab a single documentation for both
interfaces is sufficient and will be based on octave (matlab can be used
synonymously).

To start SHOGUN in octave, start octave and check if it is correctly installed
by by typing ( let ">" be the octave prompt )

\verbatim
  sg('help')
\endverbatim

inside of octave. This should show you some help text.

\subsection staticpythoninterf_sec Static Python Interface

To start SHOGUN in python, start python and check if it is correctly installed
by by typing ( let ">" be the python prompt )

\verbatim
  from sg import sg
  sg('help')
\endverbatim

inside of python. This should show you some help text.

\subsection staticrinterf_sec Static R Interface

To fire up SHOGUN in R make sure that you have SHOGUN correctly installed in
R. You can check this by typing ( let ">" be the R prompt ):

\verbatim
  > library()
\endverbatim

inside of R, this command should list all R packages that have been
installed on your system.
You should have an entry like:

\verbatim
  sg                     The SHOGUN Machine Learning Toolbox
\endverbatim

After you made sure that SHOGUN is installed correctly you can start it via:

\verbatim
  > library(sg)
\endverbatim

you will see some informations of the SHOGUN core (compile options etc).
After this command R and SHOGUN are ready to receive your commands.

In general all commands in SHOGUN are issued using the function sg(...).
To invoke the SHOGUN command help one types:

\verbatim
  > sg('help')
\endverbatim

and then a help text appears giving a short description of all commands.


\section staticifcmds Static Interface Commands

\subsection staticiffeatures_sec Features
These functions transfer data from the interface to shogun and back.
Suppose you have a matlab matrix or R matrix  "features" which
contains your training data and you want to register this data, you simply
type:

Transfer the features to shogun
\arg \b set_features \verbatim sg('set_features', 'TRAIN|TEST', features[, DNABINFILE|<ALPHABET>]) \endverbatim
\arg \b add_features \verbatim sg('add_features', 'TRAIN|TEST', features[, DNABINFILE|<ALPHABET>]) \endverbatim

Features can be char/byte/word/int/real valued matrices, real values sparse
matrices, or strings (lists or cell arrays of strings). When dealing with
strings an alphabet name has to be specified (DNA, RAW, ...). Use 'TRAIN' to
tell SHOGUN that this is the data you want to train your classifier and TEST for
the test data.

In contrast to \b set_features, \b add_features will create a combined feature
object and append the features to it. This is useful when dealing with a set of
different features (real valued and strings) and multiple kernels.

In case a single string was set using \b set_features, it can be "multiplexed"
by sliding a window over it using
\arg \b from_position_list \verbatim sg('from_position_list', 'TRAIN|TEST', winsize, shift[, skip]) \endverbatim
or
\arg \b obtain_from_sliding_window \verbatim sg('obtain_from_sliding_window', winsize, skip) \endverbatim

Deletes the features which we assigned before in the actual SHOGUN session.
\arg clean_features \verbatim sg('clean_features') \endverbatim

Obtain the Features from shogun
\arg \b get_features \verbatim [features]=sg('get_features', 'TRAIN|TEST') \endverbatim

One proceeds similar when assigning labels to the training data and obtaining
labels from shogun: The commands

\arg \b set_labels \verbatim sg('set_labels', 'TRAIN', trainlab) \endverbatim
\arg \b get_labels \verbatim [labels]=sg('get_labels', 'TRAIN|TEST') \endverbatim

tell SHOGUN that the labels of the assigned training data reside in trainlab,
respectively return the current labels (note that currently all data is
\b copied into SHOGUN, so modifications to trainlab are local within the
interface).

\subsection staticifkernel_sec Kernel & Distances

Kernel and DistanceMatrix specific commands, used to create, obtain and setting
the kernel matrix.

Creating a kernel in shogun
\arg \b set_kernel \verbatim sg('set_kernel', 'KERNELNAME', 'FEATURETYPE', CACHESIZE, PARAMETERS) \endverbatim
\arg \b add_kernel \verbatim sg('add_kernel', WEIGHT, 'KERNELNAME', 'FEATURETYPE', CACHESIZE, PARAMETERS) \endverbatim

Here KERNELNAME is the name of the kernel one wishes to use, FEATURETYPE the
type of features (e.g. REAL for standard realvalued feature vectors), CACHESIZE
the size of the kernel cache in megabytes and PARAMETERS kernel specific
additional parameters.

\subsubsection staticifsuppkernels_sec Supported Kernels

The following kernels are implemented in SHOGUN:

\li AUC
\li Chi2
\li Spectrum
\li Const Kernel
\li User defined CustomKernel
\li Diagonal Kernel
\li Kernel from Distance
\li Fixed Degree StringKernel
\li Gaussian \f$ k(x,x')=e^{-\frac{||x-x'||^2}{\sigma}} \f$

To work with a gaussian kernel on real values one issues:
\verbatim sg('set_kernel', 'GAUSSIAN', 'TYPE', CACHESIZE, SIGMA)\endverbatim

For example:
\verbatim sg('set_kernel', 'GAUSSIAN', 'REAL', 40, 1)\endverbatim
creates a gaussian kernel on real values with a cache size of 40MB and a sigma
value of one. Available types for the gaussian kernel: REAL, SPARSEREAL.

\li Gaussian Shift Kernel
\li Histogram Kernel
\li Linear \f$k(x,x')=x\cdot x'\f$

A linear kernel is created via:
\verbatim sg('set_kernel', 'LINEAR', 'TYPE', CACHESIZE)\endverbatim

For example:
\verbatim sg('add_kernel', 1.0, 'LINEAR', 'REAL', 50')\endverbatim

creates a linear kernel of cache size 50 for real datavalues, with weight 1.0.

Available types for the linear kernel: BYTE, WORD CHAR, REAL, SPARSEREAL.

\li Local Alignment StringKernel
\li Locality Improved StringKernel
\li Polynomial Kernel \f$k(x,x')=(x\cdot x')^d\f$

A polynomial kernel is created via:
\verbatim sg('set_kernel', 'POLY', 'TYPE', CACHESIZE, DEGREE, INHOMOGENE, NORMALIZE) \endverbatim

For example:
\verbatim sg('add_kernel', 0.1, 'POLY', 'REAL', 50, 3, 0) \endverbatim
adds a polynomial kernel.  Available types for the polynomial kernel: REAL,
CHAR, SPARSEREAL.

\li Salzberg Kernel
\li Sigmoid Kernel
To work with a sigmoid kernel on real values one issues:

\verbatim sg('set_kernel', 'SIGMOID', 'TYPE', CACHESIZE, GAMMA, COEFF)\endverbatim

For example:

\verbatim sg('set_kernel', 'SIGMOID', 'REAL', 40, 0.1, 0.1) \endverbatim

creates a sigmoid kernel on real values with a cache size of 40MB, a gamma
value of 0.1 and a coefficient of 0.1. Available types for the gaussian kernel: REAL.

\li Weighted Spectrum Kernel
\li Weighted Degree Kernels
\li Match Kernel
\li Custom Kernel

Assign a user defined custom kernel, fo which only the upper triangle may be
given (DIAG) or the FULL matrix (FULL), or the full matrix which is then
internally stored as a upper triangle (FULL2DIAG).
\arg \b set_custom_kernel \verbatim sg('set_custom_kernel', kernelmatrix, 'DIAG|FULL|FULL2DIAG') \endverbatim

The purpose of the get_kernel_matrix and get_distance_matrix commands is to
return a kernel or distance matrix representing the kernel/distance matrix for
the actual problem.

\arg \b get_distance_matrix \verbatim [D]=sg('get_distance_matrix', 'TRAIN|TEST') \endverbatim
\arg \b get_kernel_matrix \verbatim [K]=sg('get_kernel_matrix', 'TRAIN|TEST') \endverbatim

km refers to a matrix object.

\subsection staticifsvm_sec SVM
\arg new_classifier Creates a new classifier (e.g. SVM instance).
\arg train_classifier Starts the training of the SVM on the assigned features and kernels.

The get_svm command returns some properties of an SVM such as the Langrange
multipliers alpha, the bias b and the index of the support vectors SV (zero
based).
\arg \b get_classifier \verbatim [bias, alphas]=sg('get_svm') \endverbatim
\arg \b set_classifier \verbatim sg('set_classifier', bias, alphas) \endverbatim

This commands returns a list of arguments. \b set_classifier may be later on used (after creating an SVM classifier) to set alphas and bias again.

The result of the classification of the test sample is obtained via:
\arg \b classify \verbatim [result]=sg('classify') \endverbatim
\arg \b classify_example \verbatim [result]=sg('classify_example', feature_vector_index) \endverbatim
where result is a vector containing the classification result for each
datapoint and \b classify_example only obtains the output for a single example
(index is zero based like in python. note that octave, matlab, R are 1 based).

\subsection staticifhmm_sec HMM
\li get_hmm
\li set_hmm
\li hmm_classify
\li hmm_classify_example
\li hmm_likelihood
\li get_viterbi_path

\subsection staticifpoim_sec POIM
\li compute_poim_wd
\li get_SPEC_consensus
\li get_SPEC_scoring
\li get_WD_consensus
\li get_WD_scoring

\subsection staticifutil_sec Utility
Miscellaneous functions.

Returns the svn version number
\arg \b help \verbatim sg('get_version') \endverbatim

Gives you a help text.
\arg \b help \verbatim sg('help') \endverbatim
\arg \b help \verbatim sg('help', 'CMD') \endverbatim

Sets a debugging log level - useful to trace errors.
\arg loglevel \verbatim sg('loglevel', 'LEVEL') \endverbatim
LEVEL can be one of DEBUG, WARN, ERROR
  \li ALL: very verbose logging output (useful only for hunting memory leaks)
  \li DEBUG: verbose logging output (useful for debugging).
  \li WARN: less logging output (useful for error search).
  \li ERROR:  only logging output on critical errors.

For example
\verbatim
  > sg('loglevel', 'ALL')
\endverbatim
gives you a list of instructions.


Let's get started, equipped with the above information on the basic SHOGUN
commands you are now able to create your own SHOGUN applications.

\section staticifexample_sec Example
Let us discuss an example:

   \li \verbatim sg('set_features', 'TRAIN', traindat) \endverbatim
   registers the training sample which reside in traindat.

   \li \verbatim sg('set_labels', 'TRAIN', trainlab) \endverbatim
   registers the training labels.

   \li \verbatim sg('set_kernel', 'GAUSSIAN', 'REAL', 100, 1.0) \endverbatim
   creates a new gaussian kernel for reals with cache size 100Mb and width = 1.

   \li \verbatim sg('new_classifier', 'SVMLIGHT') \endverbatim
   creates a new SVM object inside the SHOGUN core.

   \li \verbatim sg('c', 20.0)  \endverbatim
   sets the C value of the new SVM to 20.0.

   \li \verbatim sg('train_classifier') \endverbatim
   attaches the data to the kernel and does some initialization then
   starts the training on the sample.

   \li \verbatim sg('set_features', 'TEST', testdat) \endverbatim
   registers the test sample

   \li \verbatim out=sg('classify') \endverbatim
   attaches the data to the kernel and classifies. Then
   gives you the classification result as a vector.


\section staticifcmdref_sec Function Reference
  \li \subpage staticoctave
  \li \subpage staticpython
  \li \subpage staticcmdline
  \li \subpage staticr
*/