[mlpack-git] master: * added documentation to all update rules (64e29ef)

gitdub at big.cc.gt.atl.ga.us gitdub at big.cc.gt.atl.ga.us
Thu Mar 5 21:57:34 EST 2015


Repository : https://github.com/mlpack/mlpack

On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/904762495c039e345beba14c1142fd719b3bd50e...f94823c800ad6f7266995c700b1b630d5ffdcf40

>---------------------------------------------------------------

commit 64e29ef751ad0e0e2e4c487a15c2fe73adc3ebfd
Author: sumedhghaisas <sumedhghaisas at gmail.com>
Date:   Tue Aug 12 19:33:29 2014 +0000

    * added documentation to all update rules


>---------------------------------------------------------------

64e29ef751ad0e0e2e4c487a15c2fe73adc3ebfd
 src/mlpack/methods/amf/amf.hpp                     | 80 +++++++++++++++++++--
 .../amf/update_rules/svd_batch_learning.hpp        |  4 +-
 .../svd_complete_incremental_learning.hpp          | 81 ++++++++++++++++------
 .../svd_incomplete_incremental_learning.hpp        | 57 ++++++++++++++-
 4 files changed, 190 insertions(+), 32 deletions(-)

diff --git a/src/mlpack/methods/amf/amf.hpp b/src/mlpack/methods/amf/amf.hpp
index ba6e96a..c87d76a 100644
--- a/src/mlpack/methods/amf/amf.hpp
+++ b/src/mlpack/methods/amf/amf.hpp
@@ -137,51 +137,119 @@ typedef amf::AMF<amf::SimpleResidueTermination,
 //! Add simple typedefs 
 #ifdef MLPACK_USE_CXX11
 
+/**
+ * SVDBatchFactorizer factorizes given matrix V into two matrices W and H by
+ * gradient descent. SVD batch learning is described in paper 'A Guide to 
+ * singular Value Decomposition' by Chih-Chao Ma.
+ *
+ * @see SVDBatchLearning
+ */
 template<class MatType>
 using SVDBatchFactorizer = amf::AMF<amf::SimpleToleranceTermination<MatType>,
                                     amf::RandomInitialization,
                                     amf::SVDBatchLearning>;
 
+/**
+ * SVDIncompleteIncrementalFactorizer factorizes given matrix V into two matrices 
+ * W and H by incomplete incremental gradient descent. SVD incomplete incremental 
+ * learning is described in paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma.
+ *
+ * @see SVDIncompleteIncrementalLearning
+ */                                    
 template<class MatType>
 using SVDIncompleteIncrementalFactorizer = amf::AMF<amf::SimpleToleranceTermination<MatType>,
                                                     amf::RandomInitialization,
                                                     amf::SVDIncompleteIncrementalLearning>;
-                                                    
+/**
+ * SVDCompleteIncrementalFactorizer factorizes given matrix V into two matrices 
+ * W and H by complete incremental gradient descent. SVD complete incremental 
+ * learning is described in paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma.
+ *
+ * @see SVDCompleteIncrementalLearning
+ */                                                        
 template<class MatType>
 using SVDCompleteIncrementalFactorizer = amf::AMF<amf::SimpleToleranceTermination<MatType>,
                                                   amf::RandomInitialization,
                                                   amf::SVDCompleteIncrementalLearning<MatType> >;
 
-#else                
+#else // #ifdef MLPACK_USE_CXX11
+
+/**
+ * SparseSVDBatchFactorizer factorizes given sparse matrix V into two matrices 
+ * W and H by gradient descent. SVD batch learning is described in paper 'A Guide to 
+ * singular Value Decomposition' by Chih-Chao Ma. 
+ *
+ * @see SVDBatchLearning
+ */              
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::sp_mat>,
                  amf::RandomInitialization,
-               amf::SVDBatchLearning> SparseSVDBatchFactorizer;
+                 amf::SVDBatchLearning> SparseSVDBatchFactorizer;
 
+/**
+ * SparseSVDBatchFactorizer factorizes given matrix V into two matrices 
+ * W and H by gradient descent. SVD batch learning is described in paper 'A Guide to 
+ * singular Value Decomposition' by Chih-Chao Ma. 
+ *
+ * @see SVDBatchLearning
+ */             
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::mat>,
                  amf::RandomInitialization,
                  amf::SVDBatchLearning> SVDBatchFactorizer;
-                 
+/**
+ * SparseSVDIncompleteIncrementalFactorizer factorizes given sparse matrix V 
+ * into two matrices W and H by incomplete incremental gradient descent. 
+ * SVD incomplete incremental learning is described in paper 'A Guide to singular 
+ * Value Decomposition' by Chih-Chao Ma.
+ *
+ * @see SVDIncompleteIncrementalLearning
+ */                   
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::sp_mat>,
                  amf::RandomInitialization,
                  amf::SVDIncompleteIncrementalLearning> 
         SparseSVDIncompleteIncrementalFactorizer;
 
+/**
+ * SVDIncompleteIncrementalFactorizer factorizes given matrix V into two matrices 
+ * W and H by incomplete incremental gradient descent. SVD incomplete incremental 
+ * learning is described in paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma.
+ *
+ * @see SVDIncompleteIncrementalLearning
+ */              
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::mat>,
                  amf::RandomInitialization,
                  amf::SVDIncompleteIncrementalLearning> 
         SVDIncompleteIncrementalFactorizer;
 
+/**
+ * SparseSVDCompleteIncrementalFactorizer factorizes given sparse matrix V 
+ * into two matrices W and H by complete incremental gradient descent. SVD 
+ * complete incremental learning is described in paper 'A Guide to singular 
+ * Value Decomposition' by Chih-Chao Ma.
+ *
+ * @see SVDCompleteIncrementalLearning
+ */   
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::sp_mat>,
                  amf::RandomInitialization,
                  amf::SVDCompleteIncrementalLearning<arma::sp_mat> > 
         SparseSVDCompleteIncrementalFactorizer;
 
+/**
+ * SVDCompleteIncrementalFactorizer factorizes given matrix V into two matrices 
+ * W and H by complete incremental gradient descent. SVD complete incremental 
+ * learning is described in paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma.
+ *
+ * @see SVDCompleteIncrementalLearning
+ */                      
 typedef amf::AMF<amf::SimpleToleranceTermination<arma::mat>,
                  amf::RandomInitialization,
                  amf::SVDCompleteIncrementalLearning<arma::mat> > 
         SVDCompleteIncrementalFactorizer;
 
-#endif
+#endif // #ifdef MLPACK_USE_CXX11
 
 
 }; // namespace amf
@@ -190,5 +258,5 @@ typedef amf::AMF<amf::SimpleToleranceTermination<arma::mat>,
 // Include implementation.
 #include "amf_impl.hpp"
 
-#endif
+#endif // __MLPACK_METHODS_AMF_AMF_HPP
 
diff --git a/src/mlpack/methods/amf/update_rules/svd_batch_learning.hpp b/src/mlpack/methods/amf/update_rules/svd_batch_learning.hpp
index d692696..aca613e 100644
--- a/src/mlpack/methods/amf/update_rules/svd_batch_learning.hpp
+++ b/src/mlpack/methods/amf/update_rules/svd_batch_learning.hpp
@@ -44,8 +44,8 @@ class SVDBatchLearning
   }
 
   /**
-   * Initialize value before factorization.
-   * This function must be called before each new factorization.
+   * Initialize parameters before factorization.
+   * This function must be called before a new factorization.
    *
    * @param dataset Input matrix to be factorized.
    * @param rank rank of factorization
diff --git a/src/mlpack/methods/amf/update_rules/svd_complete_incremental_learning.hpp b/src/mlpack/methods/amf/update_rules/svd_complete_incremental_learning.hpp
index fe3150c..8b354dc 100644
--- a/src/mlpack/methods/amf/update_rules/svd_complete_incremental_learning.hpp
+++ b/src/mlpack/methods/amf/update_rules/svd_complete_incremental_learning.hpp
@@ -1,5 +1,5 @@
 /**
- * @file svd_batch_learning.hpp
+ * @file svd_complete_incremental_learning.hpp
  * @author Sumedh Ghaisas
  *
  * SVD factorizer used in AMF (Alternating Matrix Factorization).
@@ -14,22 +14,48 @@ namespace mlpack
 namespace amf
 {
 
+/**
+ * This class computes SVD by method complete incremental batch learning. 
+ * This procedure is described in the paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma. Class implements 'Algorithm 3' given in the paper. Complete
+ * incremental learning is an extreme extreme case of incremental learning where 
+ * feature vectors are updated after looking at each single score. This approach
+ * differs from incomplete incremental learning where feature vectors are updated 
+ * after seeing scores of individual users.
+ *
+ * @see SVDIncompleteIncrementalLearning
+ */
 template <class MatType>
 class SVDCompleteIncrementalLearning
 {
  public:
+  /**
+   * Empty constructor
+   *
+   * @param u step value used in batch learning
+   * @param kw regularization constant for W matrix
+   * @param kh regularization constant for H matrix
+   */
   SVDCompleteIncrementalLearning(double u = 0.0001,
                                  double kw = 0,
                                  double kh = 0)
             : u(u), kw(kw), kh(kh)
     {}
   
+  /**
+   * Initialize parameters before factorization.
+   * This function must be called before a new factorization.
+   *
+   * @param dataset Input matrix to be factorized.
+   * @param rank rank of factorization
+   */
   void Initialize(const MatType& dataset, const size_t rank)
   {
     (void)rank;
     n = dataset.n_rows;
     m = dataset.n_cols;
 
+    // initialize the current score counters
     currentUserIndex = 0;
     currentItemIndex = 0;
   }
@@ -49,22 +75,20 @@ class SVDCompleteIncrementalLearning
   {
     arma::mat deltaW(1, W.n_cols);
     deltaW.zeros();
+    
+    // loop till a non-zero entry is found 
     while(true)
     {
       double val;
+      // update feature vector if current entry is non-zero and break the loop
       if((val = V(currentItemIndex, currentUserIndex)) != 0)
       {
         deltaW += (val - arma::dot(W.row(currentItemIndex), H.col(currentUserIndex))) 
                                         * arma::trans(H.col(currentUserIndex));
+        // add regularization                               
         if(kw != 0) deltaW -= kw * W.row(currentItemIndex);
         break;
       }
-      currentUserIndex = currentUserIndex + 1;
-      if(currentUserIndex == n)
-      {
-        currentUserIndex = 0;
-        currentItemIndex = (currentItemIndex + 1) % m;
-      }
     }
 
     W.row(currentItemIndex) += u*deltaW;
@@ -86,37 +110,48 @@ class SVDCompleteIncrementalLearning
     arma::mat deltaH(H.n_rows, 1);
     deltaH.zeros();
     
-    while(true)
-    {
-      double val;
-      if((val = V(currentItemIndex, currentUserIndex)) != 0)
-      deltaH += (val - arma::dot(W.row(currentItemIndex), H.col(currentUserIndex))) 
+    const double& val = V(currentItemIndex, currentUserIndex);
+    
+    // update H matrix based on the non-zero enrty found in WUpdate function
+    deltaH += (val - arma::dot(W.row(currentItemIndex), H.col(currentUserIndex))) 
                                       * arma::trans(W.row(currentItemIndex));
-      if(kh != 0) deltaH -= kh * H.col(currentUserIndex);
+    // add regularization
+    if(kh != 0) deltaH -= kh * H.col(currentUserIndex);
 
-      currentUserIndex = currentUserIndex + 1;
-      if(currentUserIndex == n)
-      {
-        currentUserIndex = 0;
-        currentItemIndex = (currentItemIndex + 1) % m;
-      }
+    // move on to the next entry
+    currentUserIndex = currentUserIndex + 1;
+    if(currentUserIndex == n)
+    {
+      currentUserIndex = 0;
+      currentItemIndex = (currentItemIndex + 1) % m;
     }
 
     H.col(currentUserIndex++) += u * deltaH;
   }
 
  private:
+  //! step count of batch learning
   double u;
+  //! regularization parameter for matrix w
   double kw;
+  //! regualrization matrix for matrix H
   double kh;
 
+  //! number of items
   size_t n;
+  //! number of users
   size_t m;
   
+  //! user of index of current entry
   size_t currentUserIndex;
+  //! item index of current entry
   size_t currentItemIndex;
 };
 
+//! TODO : Merge this template specialized function for sparse matrix using 
+//!        common row_col_iterator
+
+//! template specialiazed functions for sparse matrices
 template<>
 class SVDCompleteIncrementalLearning<arma::sp_mat>
 {
@@ -202,7 +237,7 @@ class SVDCompleteIncrementalLearning<arma::sp_mat>
                                         * arma::trans(W.row(currentItemIndex));
     if(kh != 0) deltaH -= kh * H.col(currentUserIndex);
 
-    H.col(currentUserIndex++) += u * deltaH;
+    H.col(currentUserIndex) += u * deltaH;
   }
 
  private:
@@ -217,10 +252,10 @@ class SVDCompleteIncrementalLearning<arma::sp_mat>
   arma::sp_mat::const_iterator* it;
 
   bool isStart;
-};
+}; // class SVDCompleteIncrementalLearning
 
-}
-}
+}; // namespace amf
+}; // namespace mlpack
 
 
 #endif // _MLPACK_METHODS_AMF_SVDCOMPLETEINCREMENTALLEARNING_HPP_INCLUDED
diff --git a/src/mlpack/methods/amf/update_rules/svd_incomplete_incremental_learning.hpp b/src/mlpack/methods/amf/update_rules/svd_incomplete_incremental_learning.hpp
index 9656bd4..0903c8d 100644
--- a/src/mlpack/methods/amf/update_rules/svd_incomplete_incremental_learning.hpp
+++ b/src/mlpack/methods/amf/update_rules/svd_incomplete_incremental_learning.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file svd_incomplete_incremental_learning.hpp
+ * @author Sumedh Ghaisas
+ *
+ * SVD factorizer used in AMF (Alternating Matrix Factorization).
+ */
 #ifndef SVD_INCREMENTAL_LEARNING_HPP_INCLUDED
 #define SVD_INCREMENTAL_LEARNING_HPP_INCLUDED
 
@@ -5,15 +11,43 @@ namespace mlpack
 {
 namespace amf
 {
+
+/**
+ * This class computes SVD by method incomplete incremental batch learning. 
+ * This procedure is described in the paper 'A Guide to singular Value Decomposition' 
+ * by Chih-Chao Ma. Class implements 'Algorithm 2' given in the paper. 
+ * Incremental learning modifies only some feature values in W and H after 
+ * scanning part of the training data. Incomplete incremental learning approach 
+ * is different from batch learning as each object feature vector Mj has an 
+ * additional regularization coefficient, which is equal to the number of 
+ * existing scores for object j. Therefore, an object with more scores has a 
+ * larger regularization coefficient in this incremental learning approach.
+ *
+ * @see SVDBatchLearning
+ */
 class SVDIncompleteIncrementalLearning
 {
  public:
+  /**
+   * Empty constructor
+   *
+   * @param u step value used in batch learning
+   * @param kw regularization constant for W matrix
+   * @param kh regularization constant for H matrix
+   */
   SVDIncompleteIncrementalLearning(double u = 0.001,
                                    double kw = 0,
                                    double kh = 0)
           : u(u), kw(kw), kh(kh)
-    {}
+  {}
 
+  /**
+   * Initialize parameters before factorization.
+   * This function must be called before a new factorization.
+   *
+   * @param dataset Input matrix to be factorized.
+   * @param rank rank of factorization
+   */
   template<typename MatType>
   void Initialize(const MatType& dataset, const size_t rank)
   {
@@ -22,6 +56,7 @@ class SVDIncompleteIncrementalLearning
     n = dataset.n_rows;
     m = dataset.n_cols;
 
+    // set the current user to 0
     currentUserIndex = 0;
   }
 
@@ -41,12 +76,17 @@ class SVDIncompleteIncrementalLearning
   {
     arma::mat deltaW(n, W.n_cols);
     deltaW.zeros();
+    
+    // iterate through all the rating by this user to update corresponding
+    // item feature feature vector
     for(size_t i = 0;i < n;i++)
     {
       double val;
+      // update only if the rating is non-zero
       if((val = V(i, currentUserIndex)) != 0)
         deltaW.row(i) += (val - arma::dot(W.row(i), H.col(currentUserIndex))) *
                                          arma::trans(H.col(currentUserIndex));
+      // add regularization
       if(kw != 0) deltaW.row(i) -= kw * W.row(i);
     }
 
@@ -70,30 +110,45 @@ class SVDIncompleteIncrementalLearning
     arma::mat deltaH(H.n_rows, 1);
     deltaH.zeros();
     
+    // iterate through all the rating by this user to update corresponding
+    // item feature feature vector
     for(size_t i = 0;i < n;i++)
     {
       double val;
+      // update only if the rating is non-zero
       if((val = V(i, currentUserIndex)) != 0)
         deltaH += (val - arma::dot(W.row(i), H.col(currentUserIndex))) *
                                                     arma::trans(W.row(i));
     }
+    // add regularization
     if(kh != 0) deltaH -= kh * H.col(currentUserIndex);
 
+    // update H matrix and move on to the next user
     H.col(currentUserIndex++) += u * deltaH;
     currentUserIndex = currentUserIndex % m;
   }
 
  private:
+  //! step count of btach learning
   double u;
+  //! regularization parameter for W matrix
   double kw;
+  //! regularization parameter for H matrix
   double kh;
 
+  //! number of items
   size_t n;
+  //! number of users
   size_t m;
 
+  //! current user under consideration 
   size_t currentUserIndex;
 };
 
+//! TODO : Merge this template specialized function for sparse matrix using 
+//!        common row_col_iterator
+
+//! template specialiazed functions for sparse matrices
 template<>
 inline void SVDIncompleteIncrementalLearning::
                                     WUpdate<arma::sp_mat>(const arma::sp_mat& V,



More information about the mlpack-git mailing list