[mlpack] 310/324: * added documentation to all update rules
Barak A. Pearlmutter
barak+git at cs.nuim.ie
Sun Aug 17 08:22:21 UTC 2014
This is an automated email from the git hooks/post-receive script.
bap pushed a commit to branch svn-trunk
in repository mlpack.
commit 63a906327ab144f7fe0a1aec449e0737a1659e69
Author: sumedhghaisas <sumedhghaisas at 9d5b8971-822b-0410-80eb-d18c1038ef23>
Date: Tue Aug 12 19:33:29 2014 +0000
* added documentation to all update rules
git-svn-id: http://svn.cc.gatech.edu/fastlab/mlpack/trunk@17014 9d5b8971-822b-0410-80eb-d18c1038ef23
---
src/mlpack/methods/amf/amf.hpp | 88 +++++++++++++++++++---
.../amf/update_rules/svd_batch_learning.hpp | 4 +-
.../svd_complete_incremental_learning.hpp | 87 ++++++++++++++-------
.../svd_incomplete_incremental_learning.hpp | 59 ++++++++++++++-
4 files changed, 198 insertions(+), 40 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;
@@ -85,38 +109,49 @@ 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);
}
@@ -69,31 +109,46 @@ 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,
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/mlpack.git
More information about the debian-science-commits
mailing list