[mlpack-svn] r10674 - mlpack/trunk/src/mlpack/methods/radical

[fastlab-svn at coffeetalk-1.cc.gatech.edu]

Author: niche
Date: 2011-12-08 17:07:41 -0500 (Thu, 08 Dec 2011)
New Revision: 10674

Modified:
   mlpack/trunk/src/mlpack/methods/radical/radical.cpp
   mlpack/trunk/src/mlpack/methods/radical/radical.hpp
Log:
added lots of comments

Modified: mlpack/trunk/src/mlpack/methods/radical/radical.cpp
===================================================================
--- mlpack/trunk/src/mlpack/methods/radical/radical.cpp	2011-12-08 21:30:14 UTC (rev 10673)
+++ mlpack/trunk/src/mlpack/methods/radical/radical.cpp	2011-12-08 22:07:41 UTC (rev 10674)
@@ -82,12 +82,16 @@
 }
 
 
-void Radical::DoRadical(const mat& matX, mat& matY, mat& matW) {
+void Radical::DoRadical(const mat& matXT, mat& matY, mat& matW) {
   
-  // matX is nPoints by nDims (although less intuitive than columns being points,
-  // and although this is the transpose of the ICA literature, this choice is 
-  // for computational efficiency)
+  // matX is nPoints by nDims (although less intuitive than columns being 
+  // points, and although this is the transpose of the ICA literature, this
+  // choice is for computational efficiency when repeatedly generating 
+  // two-dimensional coordinate projections for Radical2D
+  mat matX = trans(matXT);
   
+  // if m was not specified, initialize m as recommended in 
+  // (Learned-Miller and Fisher, 2003)
   if(m < 1) {
     m = floor(sqrt(matX.n_rows));
   }
@@ -128,8 +132,9 @@
     }
   }
   
-  // the final transpose provides W in the typical form from the ICA literature
+  // the final transposes provide W and Y in the typical form from the ICA literature
   matW = trans(matWhitening * matW);
+  matY = trans(matY);
 }
 
 

Modified: mlpack/trunk/src/mlpack/methods/radical/radical.hpp
===================================================================
--- mlpack/trunk/src/mlpack/methods/radical/radical.hpp	2011-12-08 21:30:14 UTC (rev 10673)
+++ mlpack/trunk/src/mlpack/methods/radical/radical.hpp	2011-12-08 22:07:41 UTC (rev 10674)
@@ -16,22 +16,91 @@
 
 namespace mlpack {
 namespace radical {
-    
+
+/**
+ * An implementation of RADICAL, an algorithm for independent component
+ * analysis (ICA).
+ * Let X be a matrix where each column is a point and each row a dimension.
+ * The goal is to find a square unmixing matrix W such that Y = W X and
+ * the rows of Y are independent components.
+ *
+ * For more details, see the following paper:
+ *
+ * @article{learned2003ica,
+ *   title={ICA Using Spacings Estimates of Entropy},
+ *   author={Learned-Miller, E.G. and Fisher III, J.W.},
+ *   journal={Journal of Machine Learning Research},
+ *   volume={4},
+ *   pages={1271--1295},
+ *   year={2003}
+ * }
+ */
 class Radical {
+
 public:
+  
+  /**
+   * Set the parameters to RADICAL
+   *
+   * @param noiseStdDev Standard deviation of the Gaussian noise added to the
+   *    replicates of the data points during Radical2D
+   * @param nReplicates Number of Gaussian-perturbed replicates to use 
+   *    (per point) in Radical2D
+   * @param nAngles Number of angles to consider in brute-force search during
+   *    Radical2D
+   * @param nSweeps Number of sweeps
+   *    Each sweep calls Radical2D once for each pair of dimensions
+   */
   Radical(double noiseStdDev, size_t nReplicates, size_t nAngles,
 	  size_t nSweeps);
+
+  /**
+   * Set the parameters to RADICAL
+   *
+   * @param noiseStdDev Standard deviation of the Gaussian noise added to the
+   *    replicates of the data points during Radical2D
+   * @param nReplicates Number of Gaussian-perturbed replicates to use 
+   *    (per point) in Radical2D
+   * @param nAngles Number of angles to consider in brute-force search during
+   *    Radical2D
+   * @param nSweeps Number of sweeps
+   *    Each sweep calls Radical2D once for each pair of dimensions
+   * @param m The variable m from Vasicek's m-spacing estimator of entropy
+   */
   Radical(double noiseStdDev, size_t nReplicates, size_t nAngles,
 	  size_t nSweeps, size_t m);
   
-  //const arma::mat X() const { return matX; }
+
+  /**
+   * Vasicek's m-spacing estimator of entropy, with overlap modification from
+   *    (Learned-Miller and Fisher, 2003)
+   * 
+   * @param x Empirical sample (one-dimensional) over which to estimate entropy
+   *
+   */
+  double Vasicek(const arma::vec& x);
   
-  void CopyAndPerturb(arma::mat& XNew, const arma::mat& matX);
-  double Vasicek(const arma::vec& x);
+  /** Make nReplicates copies of each data point and perturb data with Gaussian
+   *     noise with standard deviation noiseStdDev
+   */
+  void CopyAndPerturb(arma::mat& matXNew, const arma::mat& matX);
+  
+  /** Two-dimensional version of RADICAL */
   double DoRadical2D(const arma::mat& matX);
+  
+  /** Run RADICAL
+   *
+   * @param matX Input data into the algorithm - a matrix where each column is
+   *    a point and each row is a dimension
+   * @param matY Estimated independent components - a matrix where each column
+   *    is a point and each row is an estimated independent component
+   * @param matW Estimated unmixing matrix, where matY = matW * matX
+   */
   void DoRadical(const arma::mat& matX, arma::mat& matY, arma::mat& matW);
   
+  
 private:
+
   /**
    * standard deviation of the Gaussian noise added to the replicates of
    * the data points during Radical2D