update documents

Doxyfile

@@ -441,7 +441,7 @@ EXTRACT_ALL            = NO
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
 # scope will be included in the documentation.
@@ -1534,7 +1534,7 @@ FORMULA_TRANSPARENT    = YES
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:

README.md

@@ -2,8 +2,8 @@
 ## Documentations
 The documentations are available [here](https://thundersvm.readthedocs.io) in Readthedoc.
 
-## API Document
-[API Document](http://zeyiwen.github.io/thundersvm/)
+## API
+[API Reference](http://zeyiwen.github.io/thundersvm/)
 ## TODO
 - integrate with interfaces
 

include/thundersvm/model/nusvc.h

@@ -7,6 +7,9 @@
 
 #include "svc.h"
 
+/**
+ * @brief Nu-Support Vector Machine for classification
+ */
 class NuSVC : public SVC {
 protected:
     void train_binary(const DataSet &dataset, int i, int j, SyncData<float_type> &alpha, float_type &rho) override;

include/thundersvm/model/nusvr.h

@@ -7,6 +7,9 @@
 
 #include "svr.h"
 
+/**
+ * @brief-Support Vector Machine for regression
+ */
 class NuSVR : public SVR {
 public:
     void train(const DataSet &dataset, SvmParam param) override;

include/thundersvm/model/oneclass_svc.h

@@ -7,6 +7,9 @@
 
 #include "svmmodel.h"
 
+/**
+ * @brief Support Vector Machine for outlier detection (density estimation)
+ */
 class OneClassSVC : public SvmModel {
 public:
     void train(const DataSet &dataset, SvmParam param) override;

include/thundersvm/model/svc.h

@@ -11,6 +11,9 @@
 
 using std::map;
 
+/**
+ * @brief Support Vector Machine for classification
+ */
 class SVC : public SvmModel {
 public:
 
@@ -19,18 +22,49 @@ class SVC : public SvmModel {
     vector<float_type> predict(const DataSet::node2d &instances, int batch_size) override;
 
 protected:
+    /**
+     * train a binary SVC model \f$SVM_{i,j}\f$ for class i and class j.
+     * @param [in] dataset original dataset
+     * @param [in] i
+     * @param [in] j
+     * @param [out] alpha optimization variables \f$\boldsymbol{\alpha}\f$ in dual problem, should be initialized with
+     * the same size of the number
+     * of instances in this binary problem
+     * @param [out] rho bias term \f$b\f$ in dual problem
+     */
     virtual void train_binary(const DataSet &dataset, int i, int j, SyncData<float_type> &alpha, float_type &rho);
 
     void model_setup(const DataSet &dataset, SvmParam &param) override;
 
 private:
 
+    /**
+     * predict final labels using voting. \f$SVM_{i,j}\f$ will vote for class i if its decision value greater than 0,
+     * otherwise it will vote for class j. The final label will be the one with the most votes.
+     * @param dec_values decision values for each instance and each binary model
+     * @param n_instances the number of instances to be predicted
+     * @return final labels of each instances
+     */
     vector<float_type> predict_label(const SyncData<float_type> &dec_values, int n_instances) const;
 
+    /**
+     * perform probability training.
+     * If param.probability equals to 1, probability_train() will be called to train probA and probB and the model will
+     * be able to produce probability outputs.
+     * @param dataset training dataset, should be already grouped using group_classes().
+     */
     void probability_train(const DataSet &dataset);
 
+    /**
+     * transform n_binary_models binary probabilities in to probabilities of each class
+     * @param [in] r n_binary_models binary probabilities
+     * @param [out] p probabilities for each class
+     */
     void multiclass_probability(const vector<vector<float_type>> &r, vector<float_type> &p) const;
 
+    /**
+     * class weight for each class, the final \f$C_{i}\f$ of class i will be \f$C*\text{c_weight}[i]\f$
+     */
     vector<float_type> c_weight;
 
 

include/thundersvm/model/svmmodel.h

@@ -12,37 +12,110 @@
 
 using std::map;
 
+/**
+ * @brief Abstract class for different SVM models.
+ */
 class SvmModel {
 public:
+    /**
+     * train model given dataset and param.
+     * @param dataset training dataset
+     * @param param param for training
+     */
     virtual void train(const DataSet &dataset, SvmParam param) = 0;
 
+    /**
+     * predict label given instances.
+     * @param instances instances used
+     * @param batch_size the number of instances to predict parallel, higher value needs more memory
+     * @return label (SVC, NuSVC), real number (SVR, NuSVR), {-1,+1} (OneClassSVC)
+     */
     virtual vector<float_type> predict(const DataSet::node2d &instances, int batch_size);
 
+    /**
+     * predict decision values.
+     * @param [in] instances instances used
+     * @param [out] dec_values decision values predicted, #instances \f$times\f$ n_binary_models array
+     * @param [in] batch_size the number of instances to predict parallel, higher value needs more memory
+     */
     void predict_dec_values(const DataSet::node2d &instances, SyncData<float_type> &dec_values, int batch_size) const;
 
+    /**
+     * performing cross-validation.
+     * In \f$k\f$-fold cross_validation, dataset is spilt into \f$k\f$ equal size parts. Then each part is used as
+     * testing set, while the remaining \f$k-1\f$ parts are used as training set. The whole dataset will be predicted
+     * after \f$k\f$ training and testing.
+     * @param dataset training dataset
+     * @param param param for cross-validation
+     * @param n_fold the number of fold in cross-validation
+     * @return the same structure as predict()
+     */
     virtual vector<float_type> cross_validation(DataSet dataset, SvmParam param, int n_fold);
 
+    /**
+     * save SvmModel to a file, the file format is the same as LIBSVM
+     * @param path path and filename of the model file to save
+     */
     virtual void save_to_file(string path);
 
+    /**
+     * load SvmModel from a file, the file format is the same as LIBSVM.
+     * before call this function, one must read the first line of the model file, which contains svm_type. Then construct
+     * right SvmModel (SVC, SVR, ...), since SvmModel is an abstract class.
+     * @param path path and filename of saved model file
+     */
     virtual void load_from_file(string path);
 
 protected:
 
+    /**
+     * called at the begining of train(), do initialization
+     * @param dataset
+     * @param param
+     */
     virtual void model_setup(const DataSet &dataset, SvmParam &param);
 
-
     SvmParam param;
+    /**
+     * coefficients for each support vector, the structure is the same as LIBSVM. The coefficient is equal to
+     * \f$\alpha_iy_i\f$ in SVM dual optimization problem.
+     * For one-vs-one multi-class decomposition, \f$k\f$ is the number of classes, and \f$N_{sv}\f$ is the number of
+     * support vectors. The size of coef is \f$ (k-1)\times N_{sv}\f$. Each support vector has at most \f$k-1\f$
+     * coefficients. For each binary classifier \f$SVM_{i,j}\f$, the coefficients locate in: (1) class i,
+     * coef[j-1][sv_start[i]...]; (2) class j, coef[i][sv_start[j]...], where sv_start[i] is the start position of
+     * support vectors of class i.
+     */
+
     SyncData<float_type> coef;
+    /**
+     * support vectors of this model. The support vectors is grouped in classes 0,1,2,.... The sequence of them in each
+     * group is as they appear in original dataset. A training instance is saved as a support vector IFF it is a
+     * support vector in at least one binary model.
+     */
+
     DataSet::node2d sv;
-    SyncData<int> n_sv;//the number of sv in each class
+    ///the number of support vectors for each class
+    SyncData<int> n_sv;
+
+    ///the number of support vectors for all classes
+    int n_total_sv;
+
+    ///the bias term for each binary model
     SyncData<float_type> rho;
+
+    ///the number of classes
     int n_classes = 2;
+
+    ///the number of binary models, equal to \f$k(k-1)/2\f$, where \f$k\f$ is the number of classes
     size_t n_binary_models;
-    int n_total_sv;
+
+    ///be used to predict probability for each binary model
     vector<float_type> probA;
+
+    ///be used to predict probability for each binary model
     vector<float_type> probB;
 
-    //for classification
+    ///only for SVC, maps logical label (0,1,2,...) to real label in dataset (maybe 2,4,5,...)
     vector<int> label;
 };
 

include/thundersvm/model/svr.h

@@ -11,11 +11,19 @@
 
 using std::map;
 
+/**
+ * Support Vector Machine for regression
+ */
 class SVR : public SvmModel {
 public:
     void train(const DataSet &dataset, SvmParam param) override;
 
 protected:
+    /**
+     * save \f$\boldsymbel{\alpha}\f$ into coef.
+     * @param alpha_2
+     * @param instances
+     */
     void save_svr_coef(const SyncData<float_type> &alpha_2, const DataSet::node2d &instances);
 };
 

include/thundersvm/solver/csmosolver.h

@@ -8,6 +8,9 @@
 #include <thundersvm/thundersvm.h>
 #include <thundersvm/kernelmatrix.h>
 
+/**
+ * @brief C-SMO solver for SVC, SVR and OneClassSVC
+ */
 class CSMOSolver {
 public:
     void solve(const KernelMatrix &k_mat, const SyncData<int> &y, SyncData<float_type> &alpha, float_type &rho,

include/thundersvm/solver/nusmosolver.h

@@ -7,6 +7,9 @@
 
 #include "csmosolver.h"
 
+/**
+ * @brief Nu-SMO solver for NuSVC, NuSVR
+ */
 class NuSMOSolver : public CSMOSolver {
 public:
     explicit NuSMOSolver(bool for_svr) : for_svr(for_svr) {};