MLPACK  1.0.4
Public Member Functions | Private Attributes
mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule > Class Template Reference

This class implements the NMF on the given matrix V. More...

List of all members.

Public Member Functions

 NMF (const size_t maxIterations=10000, const double minResidue=1e-10, const InitializationRule initializeRule=InitializationRule(), const WUpdateRule wUpdate=WUpdateRule(), const HUpdateRule hUpdate=HUpdateRule())
 Create the NMF object and (optionally) set the parameters which NMF will run with.
void Apply (const arma::mat &V, const size_t r, arma::mat &W, arma::mat &H) const
 Apply Non-Negative Matrix Factorization to the provided matrix.
const HUpdateRule & HUpdate () const
 Access the H update rule.
HUpdateRule & HUpdate ()
 Modify the H update rule.
const InitializationRule & InitializeRule () const
 Access the initialization rule.
InitializationRule & InitializeRule ()
 Modify the initialization rule.
size_t MaxIterations () const
 Access the maximum number of iterations.
size_t & MaxIterations ()
 Modify the maximum number of iterations.
double MinResidue () const
 Access the minimum residue before termination.
double & MinResidue ()
 Modify the minimum residue before termination.
const WUpdateRule & WUpdate () const
 Access the W update rule.
WUpdateRule & WUpdate ()
 Modify the W update rule.

Private Attributes

HUpdateRule hUpdate
 Instantiated H update rule.
InitializationRule initializeRule
 Instantiated initialization Rule.
size_t maxIterations
 The maximum number of iterations allowed before giving up.
double minResidue
 The minimum residue, below which iteration is considered converged.
WUpdateRule wUpdate
 Instantiated W update rule.

Detailed Description

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
class mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >

This class implements the NMF on the given matrix V.

Non-negative Matrix Factorization decomposes V in the form $ V \approx WH $ where W is called the basis matrix and H is called the encoding matrix. V is taken to be of size n x m and the obtained W is n x r and H is r x m. The size r is called the rank of the factorization.

The implementation requires two template types; the first contains the update rule for the W matrix during each iteration and the other contains the update rule for the H matrix during each iteration. This templatization allows the user to try various update rules (including ones not supplied with MLPACK) for factorization.

A simple example of how to run NMF is shown below.

 extern arma::mat V; // Matrix that we want to perform NMF on.
 size_t r = 10; // Rank of decomposition
 arma::mat W; // Basis matrix
 arma::mat H; // Encoding matrix

 NMF<> nmf(); // Default options
 nmf.Apply(V, W, H, r);

For more information on non-negative matrix factorization, see the following paper:

 @article{
   title = {{Learning the parts of objects by non-negative matrix
       factorization}},
   author = {Lee, Daniel D. and Seung, H. Sebastian},
   journal = {Nature},
   month = {Oct},
   year = {1999},
   number = {6755},
   pages = {788--791},
   publisher = {Nature Publishing Group},
   url = {http://dx.doi.org/10.1038/44565}
 }
Template Parameters:
WUpdateRuleThe update rule for calculating W matrix at each iteration;
See also:
MultiplicativeDistanceW for an example.
Template Parameters:
HUpdateRuleThe update rule for calculating H matrix at each iteration;
See also:
MultiplicativeDistanceH for an example.

Definition at line 84 of file nmf.hpp.


Constructor & Destructor Documentation

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::NMF ( const size_t  maxIterations = 10000,
const double  minResidue = 1e-10,
const InitializationRule  initializeRule = InitializationRule(),
const WUpdateRule  wUpdate = WUpdateRule(),
const HUpdateRule  hUpdate = HUpdateRule() 
)

Create the NMF object and (optionally) set the parameters which NMF will run with.

The minimum residue refers to the root mean square of the difference between two subsequent iterations of the product W * H. A low residue indicates that subsequent iterations are not producing much change in W and H. Once the residue goes below the specified minimum residue, the algorithm terminates.

Parameters:
maxIterationsMaximum number of iterations allowed before giving up. A value of 0 indicates no limit.
minResidueThe minimum allowed residue before the algorithm terminates.
InitializeOptional Initialization object for initializing the W and H matrices
WUpdateOptional WUpdateRule object; for when the update rule for the W vector has states that it needs to store.
HUpdateOptional HUpdateRule object; for when the update rule for the H vector has states that it needs to store.

Member Function Documentation

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
void mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::Apply ( const arma::mat &  V,
const size_t  r,
arma::mat &  W,
arma::mat &  H 
) const

Apply Non-Negative Matrix Factorization to the provided matrix.

Parameters:
VInput matrix to be factorized.
WBasis matrix to be output.
HEncoding matrix to output.
rRank r of the factorization.
template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
const HUpdateRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::HUpdate ( ) const [inline]

Access the H update rule.

Definition at line 153 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::hUpdate.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
HUpdateRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::HUpdate ( ) [inline]

Modify the H update rule.

Definition at line 155 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::hUpdate.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
const InitializationRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::InitializeRule ( ) const [inline]

Access the initialization rule.

Definition at line 145 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::initializeRule.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
InitializationRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::InitializeRule ( ) [inline]

Modify the initialization rule.

Definition at line 147 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::initializeRule.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
size_t mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MaxIterations ( ) const [inline]

Access the maximum number of iterations.

Definition at line 137 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::maxIterations.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
size_t& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MaxIterations ( ) [inline]

Modify the maximum number of iterations.

Definition at line 139 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::maxIterations.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
double mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MinResidue ( ) const [inline]

Access the minimum residue before termination.

Definition at line 141 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::minResidue.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
double& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MinResidue ( ) [inline]

Modify the minimum residue before termination.

Definition at line 143 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::minResidue.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
const WUpdateRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::WUpdate ( ) const [inline]

Access the W update rule.

Definition at line 149 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::wUpdate.

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
WUpdateRule& mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::WUpdate ( ) [inline]

Modify the W update rule.

Definition at line 151 of file nmf.hpp.

References mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::wUpdate.


Member Data Documentation

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
HUpdateRule mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::hUpdate [private]

Instantiated H update rule.

Definition at line 133 of file nmf.hpp.

Referenced by mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::HUpdate().

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
InitializationRule mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::initializeRule [private]

Instantiated initialization Rule.

Definition at line 129 of file nmf.hpp.

Referenced by mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::InitializeRule().

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
size_t mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::maxIterations [private]

The maximum number of iterations allowed before giving up.

Definition at line 125 of file nmf.hpp.

Referenced by mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MaxIterations().

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
double mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::minResidue [private]

The minimum residue, below which iteration is considered converged.

Definition at line 127 of file nmf.hpp.

Referenced by mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::MinResidue().

template<typename InitializationRule = RandomInitialization, typename WUpdateRule = WMultiplicativeDistanceRule, typename HUpdateRule = HMultiplicativeDistanceRule>
WUpdateRule mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::wUpdate [private]

Instantiated W update rule.

Definition at line 131 of file nmf.hpp.

Referenced by mlpack::nmf::NMF< InitializationRule, WUpdateRule, HUpdateRule >::WUpdate().


The documentation for this class was generated from the following file: