Commit c29431c8 authored by André Anjos's avatar André Anjos 💬
Browse files

Clean-up; C++ class documentation

parent af301a29
include LICENSE README.rst bootstrap.py buildout.cfg
recursive-include doc conf.py *.rst
recursive-include doc conf.py doxygen.rc *.rst
recursive-include xbob/learn/libsvm *.cpp *.h
recursive-include xbob/learn/svm/data *.*
recursive-include xbob/learn/libsvm/data *.*
......@@ -5,7 +5,6 @@
[buildout]
parts = scripts
eggs = xbob.learn.libsvm
ipdb
extensions = xbob.buildout
mr.developer
auto-checkout = *
......
......@@ -179,4 +179,343 @@ Other Utilities
You must check for :c:func:`PyErr_Occurred` after a call to this function to
make sure that the conversion was correctly performed.
Pure C/C++ API
--------------
As explained above, each ``PyObject`` produced by this library contains a
pointer to a pure C++ implementation of a similar object. The C++ of such
objects is described in this section.
.. cpp:type:: bob::learn::libsvm::machine_t
Enumeration defining the types of SVM's available within this
implementation. The following are legal values:
* ``C_SVC``
* ``NU_SVC``
* ``ONE_CLASS`` - currently, **unsupported**
* ``EPSILON_SVR`` - currently, **unsupported**
* ``NU_SVR`` - currently, **unsupported**
.. cpp:type:: bob::learn::libsvm::kernel_t
Enumeration defining the types of kernels available within this
implementation. The following are legal values:
* ``LINEAR``
* ``POLY``
* ``RBF``
* ``SIGMOID``
* ``PRECOMPUTED`` - currently, **unsupported**
.. cpp:class:: bob::learn::libsvm::File
Loads a given libsvm data file. The data file format, as defined on the
library README is like this:
[label] [index1]:[value1] [index2]:[value2] ...
[label] [index1]:[value1] [index2]:[value2] ...
[label] [index1]:[value1] [index2]:[value2] ...
The labels are integer values, so are the indexes, starting from "1" (and
not from zero as a C-programmer would expect. The values are floating point.
Zero values are suppressed - this is a sparse format.
.. cpp:function:: File (const std::string & filename)
Constructor, initializes the file readout.
.. cpp:function:: virtual ~File ()
Virtualized destructor
.. cpp:function:: size_t shape()
Returns the size of each entry in the file, in number of
floats
.. cpp:function:: size_t samples()
Returns the number of samples in the file.
.. cpp:function:: void reset()
Resets the file, going back to the beginning.
.. cpp:function:: bool read(int & label, blitz::Array<double, 1> & values)
Reads the next entry. Values are organized according to the
indexed labels at the file. Returns 'false' if the file is
over or something goes wrong.
.. cpp:function:: bool read_(int & label, blitz::Array<double, 1> & values)
Reads the next entry on the file, but without checking.
Returns 'false' if the file is over or something goes wrong
reading the file.
.. cpp:function:: const std::string& filename()
Returns the name of the file being read.
.. cpp:function:: bool good()
Tests if the file is still good to go.
.. cpp:function:: bool eof()
.. cpp:function:: bool fail()
.. cpp:class:: bob::learn::libsvm::Machine
Interface to ``svm_model``, from LIBSVM. Incorporates prediction.
.. cpp:function:: Machine(const std::string& model_file)
Builds a new Support Vector Machine from a LIBSVM model file.
When you load using the libsvm model loader, note that the scaling
parameters will be set to defaults (subtraction of 0.0 and division by
1.0). If you need scaling to be applied, set it individually using the
appropriate methods bellow.
.. cpp:function:: Machine(bob::io::HDF5File& config)
Builds a new Support Vector *Machine* from an HDF5 file
containing the configuration for this machine. Scaling
parameters are also loaded from the file. Using this
constructor assures a 100% state recovery from previous
sessions.
.. cpp:function:: Machine(boost::shared_ptr<svm_model> model)
Builds a new SVM model from a trained model. Scaling parameters will be
neutral (subtraction := 0.0, division := 1.0).
.. note::
This method is typically only used by the respective
:cpp:class`bob::learn::libsvm::Trainer` as it requires the creation of
the object ``svm_model``. You can still make use of it if you decide
to implement the model instantiation yourself.
.. cpp:function:: virtual ~Machine()
Virtual d'tor
.. cpp:function:: size_t inputSize()
Tells the input size this machine expects
.. cpp:function:: size_t outputSize()
The number of outputs depends on the number of classes the machine has to
deal with. If the problem is a regression problem, the number of outputs
is fixed to 1. The same happens in a binary classification problem.
Otherwise, the output size is the same as the number of classes being
discriminated.
.. cpp:function:: size_t numberOfClasses()
Tells the number of classes the problem has.
.. cpp:function:: int classLabel(size_t i)
Returns the class label (as stored inside the svm_model object) for a
given class 'i'.
.. cpp:function:: bob::learn::libsvm::machine_t machineType()
The SVM type
.. cpp:function:: bob::learn::libsvm::kernel_t kernelType()
Kernel type
.. cpp:function:: int polynomialDegree()
Polinomial degree, if kernel is ``POLY``
.. cpp:function:: double gamma()
:math:`\gamma` factor, for ``POLY``, ``RBF`` or ``SIGMOID`` kernels
.. cpp:function:: double coefficient0()
Coefficient 0 for ``POLY`` and ``SIGMOID`` kernels
.. cpp:function:: bool supportsProbability()
Tells if this model supports probability output.
.. cpp:function:: const blitz::Array<double, 1>& getInputSubtraction()
Returns the input subtraction factor
.. cpp:function:: void setInputSubtraction(const blitz::Array<double, 1>& v)
Sets the current input subtraction factor. We will check that the number
of inputs (first dimension of weights) matches the number of values
currently set and will raise an exception if that is not the case.
.. cpp:function:: void setInputSubtraction(double v)
Sets all input subtraction values to a specific value.
.. cpp:function:: const blitz::Array<double, 1> & getInputDivision()
Returns the input division factor
.. cpp:function:: void setInputDivision(const blitz::Array<double, 1> & v)
Sets the current input division factor. We will check that the number of
inputs (first dimension of weights) matches the number of values
currently set and will raise an exception if that is not the case.
.. cpp:function:: void setInputDivision(double v)
Sets all input division values to a specific value.
.. cpp:function:: int predictClass(const blitz::Array<double, 1>& input)
Predict, output classes only. Note that the number of labels in the
output "labels" array should be the same as the number of input.
.. cpp:function:: int predictClass_(const blitz::Array<double, 1> & input)
Predict, output classes only. Note that the number of labels in the
output "labels" array should be the same as the number of input.
This does the same as :cpp:func:`predictClass`, but does not check the
input.
.. cpp:function:: int predictClassAndScores(const blitz::Array<double, 1>& input, blitz::Array<double, 1>& scores)
Predicts class and scores output for each class on this SVM,
.. note::
The output array must be lying on contiguous memory. This is also
checked.
.. cpp:function:: int predictClassAndScores_(const blitz::Array<double, 1>& input, blitz::Array<double, 1>& scores)
Predicts output class and scores. Same as above, but does not check
.. cpp:function:: int predictClassAndProbabilities(const blitz::Array<double, 1>& input, blitz::Array<double, 1>& probabilities)
Predict, output class and probabilities for each class on this SVM, but
only if the model supports it. Otherwise, throws a run-time exception.
.. note::
The output array must be lying on contiguous memory. This is also
checked.
.. cpp:function:: int predictClassAndProbabilities_(const blitz::Array<double, 1>& input, blitz::Array<double, 1>& probabilities)
Predicts, output class and probability, but only if the model supports it.
Same as above, but does not check
.. cpp:function:: void save(const std::string& filename)
Saves the current model state to a file. With this variant, the model is
saved on simpler libsvm model file that does not include the scaling
parameters set on this machine.
.. cpp:function:: void save(bob::io::HDF5File& config)
Saves the whole machine into a configuration file. This
allows for a single instruction parameter loading, which
includes both the model and the scaling parameters.
.. cpp:class:: bob::learn::libsvm::Trainer
This class emulates the behavior of the command line utility called
``svm-train``, from LIBSVM. These bindings do not support:
* Precomputed Kernels
* Regression Problems
* Different weights for every label (-wi option in svm-train)
Fell free to implement those and remove these remarks.
.. todo:: Support for weight cost in multi-class classification?
.. cpp:function:: Trainer(bob::learn::libsvm::machine_t machine_type = C_SVC, bob::learn::libsvm::kernel_t kernel_type = RBF, double cache_size = 100, double eps = 1.e-3, bool shrinking = true, bool probability = false)
Builds a new trainer setting the default parameters as defined in the
command line application ``svm-train``.
.. cpp:function:: ~Trainer()
Destructor virtualisation
.. cpp:function:: bob::learn::libsvm::Machine* train(const std::vector<blitz::Array<double, 2>>& data)
Trains a new machine for multi-class classification. If the number of
classes in data is 2, then the assigned labels will be -1 and +1. If the
number of classes is greater than 2, labels are picked starting from 1
(i.e., 1, 2, 3, 4, etc.). If what you want is regression, the size of
the input data array should be 1.
Returns a new object you must deallocate yourself.
.. cpp:function:: bob::learn::libsvm::Machine* train(const std::vector<blitz::Array< double, 2>>& data, const blitz::Array<double, 1>& input_subtract, const blitz::Array<double, 1>& input_division)
This version accepts scaling parameters that will be applied column-wise
to the input data.
Returns a new object you must deallocate yourself.
.. cpp:function:: machine_t getMachineType()
.. cpp:function:: void setMachineType(machine_t v)
.. cpp:function:: kernel_t getKernelType()
.. cpp:function:: void setKernelType(kernel_t v)
.. cpp:function:: int getDegree()
.. cpp:function:: void setDegree(int v)
.. cpp:function:: double getGamma()
.. cpp:function:: void setGamma(double v)
.. cpp:function:: double getCoef0()
.. cpp:function:: void setCoef0(double v)
.. cpp:function:: double getCacheSizeInMb()
.. cpp:function:: void setCacheSizeInMb(double v)
.. cpp:function:: double getStopEpsilon()
.. cpp:function:: void setStopEpsilon(double v)
.. cpp:function:: double getCost()
.. cpp:function:: void setCost(double v)
.. cpp:function:: double getNu()
.. cpp:function:: void setNu(double v)
.. cpp:function:: double getLossEpsilonSVR()
.. cpp:function:: void setLossEpsilonSVR(double v)
.. cpp:function:: bool getUseShrinking()
.. cpp:function:: void setUseShrinking(bool v)
.. cpp:function:: bool getProbabilityEstimates()
.. cpp:function:: void setProbabilityEstimates(bool v)
.. include:: links.rst
......@@ -31,6 +31,8 @@ extensions = [
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'breathe',
'sphinxcontrib.restbuilder',
]
# The viewcode extension appeared only on Sphinx >= 1.0.0
......@@ -281,5 +283,10 @@ intersphinx_mapping = {
numpy_manual: None,
}
# For Breathe
breathe_projects = {
'cxx': 'doc/xml',
}
def setup(app):
pass
This diff is collapsed.
This diff is collapsed.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment