Refactor PCA class: able to use different decomposition techniques (exact, randomized, QUIC SVD).

src/mlpack/methods/pca/decomposition_policies/exact_svd_method.hpp

@@ -24,10 +24,10 @@ class ExactSVDPolicy
   public:
   /**
    * Apply Principal Component Analysis to the provided data set using the
-   * randomized SVD.
+   * exact SVD method.
    *
    * @param data Data matrix.
-   * @param data Centered data matrix.
+   * @param centeredData Centered data matrix.
    * @param transformedData Matrix to put results of PCA into.
    * @param eigVal Vector to put eigenvalues into.
    * @param eigvec Matrix to put eigenvectors (loadings) into.
@@ -37,7 +37,7 @@ class ExactSVDPolicy
              const arma::mat& centeredData,
              arma::mat& transformedData,
              arma::vec& eigVal,
-             arma::mat& coeff,
+             arma::mat& eigvec,
              const size_t /* rank */)
   {
     // This matrix will store the right singular values; we do not need them.
@@ -49,11 +49,11 @@ class ExactSVDPolicy
     {
       // Do economical singular value decomposition and compute only the left
       // singular vectors.
-      arma::svd_econ(coeff, eigVal, v, centeredData, 'l');
+      arma::svd_econ(eigvec, eigVal, v, centeredData, 'l');
     }
     else
     {
-      arma::svd(coeff, eigVal, v, centeredData);
+      arma::svd(eigvec, eigVal, v, centeredData);
     }
 
     // Now we must square the singular values to get the eigenvalues.
@@ -62,7 +62,7 @@ class ExactSVDPolicy
     eigVal %= eigVal / (data.n_cols - 1);
 
     // Project the samples to the principals.
-    transformedData = arma::trans(coeff) * centeredData;
+    transformedData = arma::trans(eigvec) * centeredData;
   }
 };
 

src/mlpack/methods/pca/decomposition_policies/quic_svd_method.hpp

@@ -40,7 +40,7 @@ class QUICSVDPolicy
    * QUIC-SVD method.
    *
    * @param data Data matrix.
-   * @param data Centered data matrix.
+   * @param centeredData Centered data matrix.
    * @param transformedData Matrix to put results of PCA into.
    * @param eigVal Vector to put eigenvalues into.
    * @param eigvec Matrix to put eigenvectors (loadings) into.
@@ -50,22 +50,22 @@ class QUICSVDPolicy
              const arma::mat& centeredData,
              arma::mat& transformedData,
              arma::vec& eigVal,
-             arma::mat& coeff,
+             arma::mat& eigvec,
              const size_t /* rank */)
   {
     // This matrix will store the right singular values; we do not need them.
     arma::mat v, sigma;
 
     // Do singular value decomposition using the QUIC-SVD algorithm.
-    svd::QUIC_SVD quicsvd(centeredData, coeff, v, sigma, epsilon, delta);
+    svd::QUIC_SVD quicsvd(centeredData, eigvec, v, sigma, epsilon, delta);
 
     // Now we must square the singular values to get the eigenvalues.
     // In addition we must divide by the number of points, because the
     // covariance matrix is X * X' / (N - 1).
     eigVal = arma::pow(arma::diagvec(sigma), 2) / (data.n_cols - 1);
 
     // Project the samples to the principals.
-    transformedData = arma::trans(coeff) * centeredData;
+    transformedData = arma::trans(eigvec) * centeredData;
   }
 
   //! Get the error tolerance fraction for calculated subspace.

src/mlpack/methods/pca/decomposition_policies/randomized_svd_method.hpp

@@ -44,7 +44,7 @@ class RandomizedSVDPolicy
    * randomized SVD.
    *
    * @param data Data matrix.
-   * @param data Centered data matrix.
+   * @param centeredData Centered data matrix.
    * @param transformedData Matrix to put results of PCA into.
    * @param eigVal Vector to put eigenvalues into.
    * @param eigvec Matrix to put eigenvectors (loadings) into.
@@ -54,23 +54,23 @@ class RandomizedSVDPolicy
              const arma::mat& centeredData,
              arma::mat& transformedData,
              arma::vec& eigVal,
-             arma::mat& coeff,
+             arma::mat& eigvec,
              const size_t rank)
   {
     // This matrix will store the right singular values; we do not need them.
     arma::mat v;
 
     // Do singular value decomposition using the randomized SVD algorithm.
     svd::RandomizedSVD rsvd(iteratedPower, maxIterations);
-    rsvd.Apply(data, coeff, eigVal, v, rank);
+    rsvd.Apply(data, eigvec, eigVal, v, rank);
 
     // Now we must square the singular values to get the eigenvalues.
     // In addition we must divide by the number of points, because the
     // covariance matrix is X * X' / (N - 1).
     eigVal %= eigVal / (data.n_cols - 1);
 
     // Project the samples to the principals.
-    transformedData = arma::trans(coeff) * centeredData;
+    transformedData = arma::trans(eigvec) * centeredData;
   }
 
   //! Get the size of the normalized power iterations.

src/mlpack/methods/pca/pca.hpp

@@ -1,10 +1,12 @@
 /**
  * @file pca.hpp
  * @author Ajinkya Kale
+ * @author Ryan Curtin
+ * @author Marcus Edel
  *
  * Defines the PCA class to perform Principal Components Analysis on the
- * specified data set. There are many variations on how to do this, so template
- * parameters allow the selection of different techniques.
+ * specified data set. There are many variations on how to do this, so
+ * template parameters allow the selection of different techniques.
  */
 #ifndef MLPACK_METHODS_PCA_PCA_HPP
 #define MLPACK_METHODS_PCA_PCA_HPP
@@ -16,14 +18,14 @@ namespace mlpack {
 namespace pca {
 
 /**
- * This class implements principal components analysis (PCA).  This is a common,
- * widely-used technique that is often used for either dimensionality reduction
- * or transforming data into a better basis.  Further information on PCA can be
- * found in almost any statistics or machine learning textbook, and all over the
- * internet.
+ * This class implements principal components analysis (PCA). This is a
+ * common, widely-used technique that is often used for either dimensionality
+ * reduction or transforming data into a better basis.  Further information on
+ * PCA can be found in almost any statistics or machine learning textbook, and
+ * all over the internet.
  */
 template<typename DecompositionPolicy = ExactSVDPolicy>
-class PCA
+class PCAType
 {
  public:
   /**
@@ -32,12 +34,12 @@ class PCA
    *
    * @param scaleData Whether or not to scale the data.
    */
-  PCA(const bool scaleData = false,
-      const DecompositionPolicy& decomposition = DecompositionPolicy());
+  PCAType(const bool scaleData = false,
+          const DecompositionPolicy& decomposition = DecompositionPolicy());
 
   /**
-   * Apply Principal Component Analysis to the provided data set.  It is safe to
-   * pass the same matrix reference for both data and transformedData.
+   * Apply Principal Component Analysis to the provided data set. It is safe
+   * to pass the same matrix reference for both data and transformedData.
    *
    * @param data Data matrix.
    * @param transformedData Matrix to put results of PCA into.
@@ -50,8 +52,8 @@ class PCA
              arma::mat& eigvec);
 
   /**
-   * Apply Principal Component Analysis to the provided data set.  It is safe to
-   * pass the same matrix reference for both data and transformedData.
+   * Apply Principal Component Analysis to the provided data set. It is safe
+   * to pass the same matrix reference for both data and transformedData.
    *
    * @param data Data matrix.
    * @param transformedData Matrix to store results of PCA in.
@@ -62,11 +64,11 @@ class PCA
              arma::vec& eigVal);
 
   /**
-   * Use PCA for dimensionality reduction on the given dataset.  This will save
+   * Use PCA for dimensionality reduction on the given dataset. This will save
    * the newDimension largest principal components of the data and remove the
-   * rest.  The parameter returned is the amount of variance of the data that is
-   * retained; this is a value between 0 and 1.  For instance, a value of 0.9
-   * indicates that 90% of the variance present in the data was retained.
+   * rest. The parameter returned is the amount of variance of the data that
+   * is retained; this is a value between 0 and 1.  For instance, a value of
+   * 0.9 indicates that 90% of the variance present in the data was retained.
    *
    * @param data Data matrix.
    * @param newDimension New dimension of the data.
@@ -81,7 +83,7 @@ class PCA
   }
 
   /**
-   * Use PCA for dimensionality reduction on the given dataset.  This will save
+   * Use PCA for dimensionality reduction on the given dataset. This will save
    * as many dimensions as necessary to retain at least the given amount of
    * variance (specified by parameter varRetained).  The amount should be
    * between 0 and 1; if the amount is 0, then only 1 dimension will be
@@ -97,8 +99,8 @@ class PCA
    */
   double Apply(arma::mat& data, const double varRetained);
 
-  //! Get whether or not this PCA object will scale (by standard deviation) the
-  //! data when PCA is performed.
+  //! Get whether or not this PCA object will scale (by standard deviation)
+  //! the data when PCA is performed.
   bool ScaleData() const { return scaleData; }
   //! Modify whether or not this PCA object will scale (by standard deviation)
   //! the data when PCA is performed.
@@ -110,9 +112,11 @@ class PCA
   {
     if (scaleData)
     {
-      // Scaling the data is when we reduce the variance of each dimension to 1.
-      // We do this by dividing each dimension by its standard deviation.
-      arma::vec stdDev = arma::stddev(centeredData, 0, 1 /* for each dimension */);
+      // Scaling the data is when we reduce the variance of each dimension
+      // to 1. We do this by dividing each dimension by its standard
+      // deviation.
+      arma::vec stdDev = arma::stddev(
+          centeredData, 0, 1 /* for each dimension */);
 
       // If there are any zeroes, make them very small.
       for (size_t i = 0; i < stdDev.n_elem; ++i)
@@ -131,6 +135,8 @@ class PCA
   DecompositionPolicy decomposition;
 }; // class PCA
 
+//! 3.0.0 TODO: break reverse-compatibility by changing PCAType to PCA.
+typedef PCAType<ExactSVDPolicy> PCA;
 
 } // namespace pca
 } // namespace mlpack

src/mlpack/methods/pca/pca_impl.hpp

@@ -1,6 +1,8 @@
 /**
  * @file pca.cpp
  * @author Ajinkya Kale
+ * @author Ryan Curtin
+ * @author Marcus Edel
  *
  * Implementation of PCA class to perform Principal Components Analysis on the
  * specified data set.
@@ -18,8 +20,8 @@ namespace mlpack {
 namespace pca {
 
 template<typename DecompositionPolicy>
-PCA<DecompositionPolicy>::PCA(const bool scaleData,
-                              const DecompositionPolicy& decomposition) :
+PCAType<DecompositionPolicy>::PCAType(const bool scaleData,
+                                      const DecompositionPolicy& decomposition) :
     scaleData(scaleData),
     decomposition(decomposition)
 { }
@@ -33,10 +35,10 @@ PCA<DecompositionPolicy>::PCA(const bool scaleData,
  * @param coeff - PCA Loadings/Coeffs/EigenVectors
  */
 template<typename DecompositionPolicy>
-void PCA<DecompositionPolicy>::Apply(const arma::mat& data,
-                arma::mat& transformedData,
-                arma::vec& eigVal,
-                arma::mat& coeff)
+void PCAType<DecompositionPolicy>::Apply(const arma::mat& data,
+                                         arma::mat& transformedData,
+                                         arma::vec& eigVal,
+                                         arma::mat& coeff)
 {
   Timer::Start("pca");
 
@@ -61,9 +63,9 @@ void PCA<DecompositionPolicy>::Apply(const arma::mat& data,
  * @param eigVal - contains eigen values in a column vector
  */
 template<typename DecompositionPolicy>
-void PCA<DecompositionPolicy>::Apply(const arma::mat& data,
-                arma::mat& transformedData,
-                arma::vec& eigVal)
+void PCAType<DecompositionPolicy>::Apply(const arma::mat& data,
+                                         arma::mat& transformedData,
+                                         arma::vec& eigVal)
 {
   arma::mat coeffs;
   Apply(data, transformedData, eigVal, coeffs);
@@ -81,7 +83,8 @@ void PCA<DecompositionPolicy>::Apply(const arma::mat& data,
  * @return Amount of the variance of the data retained (between 0 and 1).
  */
 template<typename DecompositionPolicy>
-double PCA<DecompositionPolicy>::Apply(arma::mat& data, const size_t newDimension)
+double PCAType<DecompositionPolicy>::Apply(arma::mat& data,
+                                           const size_t newDimension)
 {
   // Parameter validation.
   if (newDimension == 0)
@@ -95,6 +98,8 @@ double PCA<DecompositionPolicy>::Apply(arma::mat& data, const size_t newDimensio
   arma::mat coeffs;
   arma::vec eigVal;
 
+  Timer::Start("pca");
+
   // Center the data into a temporary matrix.
   arma::mat centeredData;
   math::Center(data, centeredData);
@@ -112,6 +117,8 @@ double PCA<DecompositionPolicy>::Apply(arma::mat& data, const size_t newDimensio
   // the right dimension before calculating the amount of variance retained.
   double eigDim = std::min(newDimension - 1, (size_t) eigVal.n_elem - 1);
 
+  Timer::Stop("pca");
+
   // Calculate the total amount of variance retained.
   return (sum(eigVal.subvec(0, eigDim)) / sum(eigVal));
 }
@@ -127,7 +134,8 @@ double PCA<DecompositionPolicy>::Apply(arma::mat& data, const size_t newDimensio
  * always be greater than or equal to the varRetained parameter.
  */
 template<typename DecompositionPolicy>
-double PCA<DecompositionPolicy>::Apply(arma::mat& data, const double varRetained)
+double PCAType<DecompositionPolicy>::Apply(arma::mat& data,
+                                           const double varRetained)
 {
   // Parameter validation.
   if (varRetained < 0)
@@ -159,7 +167,6 @@ double PCA<DecompositionPolicy>::Apply(arma::mat& data, const double varRetained
   return varSum;
 }
 
-
 } // namespace pca
 } // namespace mlpack
 

src/mlpack/methods/pca/pca_main.cpp

@@ -46,7 +46,7 @@ void RunPCA(arma::mat& dataset,
             const size_t scale,
             const double varToRetain)
 {
-  PCA<DecompositionPolicy> p(scale);
+  PCAType<DecompositionPolicy> p(scale);
 
   Log::Info << "Performing PCA on dataset..." << endl;
   double varRetained;
@@ -112,6 +112,12 @@ int main(int argc, char** argv)
   {
     RunPCA<QUICSVDPolicy>(dataset, newDimension, scale, varToRetain);
   }
+  else
+  {
+    // Invalid decomposition method.
+    Log::Fatal << "Invalid decomposition method ('" << decompositionMethod
+        << "'); valid choices are 'exact', 'randomized', 'quic'." << endl;
+  }
 
   // Now save the results.
   string outputFile = CLI::GetParam<string>("output_file");