[mlpack-git] master,mlpack-1.0.x: Minor (and ultimately trivial) documentation changes; add documentation for SparseAutoencoderFunction constructor. (b0af555)

Thu Mar 5 21:46:37 EST 2015

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

On branches: master,mlpack-1.0.x
Link       : https://github.com/mlpack/mlpack/compare/904762495c039e345beba14c1142fd719b3bd50e...f94823c800ad6f7266995c700b1b630d5ffdcf40

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

commit b0af55587bdb68cb5e4d52c38bd79de4ed7f637b
Author: Ryan Curtin <ryan at ratml.org>
Date:   Wed Apr 16 18:45:21 2014 +0000

    Minor (and ultimately trivial) documentation changes; add documentation for
    SparseAutoencoderFunction constructor.


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

b0af55587bdb68cb5e4d52c38bd79de4ed7f637b
 .../sparse_autoencoder/sparse_autoencoder.hpp      | 86 ++++++++++++----------
 .../sparse_autoencoder_function.hpp                | 33 ++++++---
 2 files changed, 67 insertions(+), 52 deletions(-)

diff --git a/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder.hpp b/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder.hpp
index 4617504..2baaf94 100644
--- a/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder.hpp
+++ b/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder.hpp
@@ -12,52 +12,59 @@
 
 #include "sparse_autoencoder_function.hpp"
 
-/**
-  * Sparse Autoencoder is a neural network whose aim to learn compressed
-  * representations of the data, typically for dimensionality reduction, with
-  * a constraint on the activity of the neurons in the network. Sparse
-  * Autoencoders can be stacked together to learn a hierarchy of features, which
-  * provide a better representation of the data for classification. This is a
-  * method used in the recently developed field of Deep Learning. More technical
-  * details about the model can be found on the following webpage:
-  * http://deeplearning.stanford.edu/wiki/index.php/UFLDL_Tutorial
-  *
-  * An example of how to use the interface is shown below:
-  * @code
-  * arma::mat data; // Data matrix.
-  * const size_t vSize = 64; // Size of visible layer, depends on the data.
-  * const size_t hSize = 25; // Size of hidden layer, depends on requirements.
-  *
-  * // Train the model using default options.
-  * SparseAutoencoder encoder1(data, vSize, hSize);
-  *
-  * const size_t numBasis = 5; // Parameter required for L-BFGS algorithm.
-  * const size_t numIterations = 100; // Maximum number of iterations.
-  *
-  * // Use an instantiated optimizer for the training.
-  * SparseAutoencoderFunction saf(data, vSize, hSize);
-  * L_BFGS<SparseAutoencoderFunction> optimizer(saf, numBasis, numIterations);
-  * SparseAutoencoder<L_BFGS> encoder2(optimizer);
-  *
-  * arma::mat features1, features2; // Matrices for storing new representations.
-  *
-  * // Get new representations from the trained models.
-  * encoder1.GetNewFeatures(data, features1);
-  * encoder2.GetNewFeatures(data, features2);
-  */
-
 namespace mlpack {
 namespace nn {
 
+/**
+ * A sparse autoencoder is a neural network whose aim to learn compressed
+ * representations of the data, typically for dimensionality reduction, with a
+ * constraint on the activity of the neurons in the network. Sparse autoencoders
+ * can be stacked together to learn a hierarchy of features, which provide a
+ * better representation of the data for classification. This is a method used
+ * in the recently developed field of deep learning. More technical details
+ * about the model can be found on the following webpage:
+ *
+ * http://deeplearning.stanford.edu/wiki/index.php/UFLDL_Tutorial
+ *
+ * An example of how to use the interface is shown below:
+ *
+ * @code
+ * arma::mat data; // Data matrix.
+ * const size_t vSize = 64; // Size of visible layer, depends on the data.
+ * const size_t hSize = 25; // Size of hidden layer, depends on requirements.
+ *
+ * // Train the model using default options.
+ * SparseAutoencoder encoder1(data, vSize, hSize);
+ *
+ * const size_t numBasis = 5; // Parameter required for L-BFGS algorithm.
+ * const size_t numIterations = 100; // Maximum number of iterations.
+ *
+ * // Use an instantiated optimizer for the training.
+ * SparseAutoencoderFunction saf(data, vSize, hSize);
+ * L_BFGS<SparseAutoencoderFunction> optimizer(saf, numBasis, numIterations);
+ * SparseAutoencoder<L_BFGS> encoder2(optimizer);
+ *
+ * arma::mat features1, features2; // Matrices for storing new representations.
+ *
+ * // Get new representations from the trained models.
+ * encoder1.GetNewFeatures(data, features1);
+ * encoder2.GetNewFeatures(data, features2);
+ * @endcode
+ *
+ * This implementation allows the use of arbitrary mlpack optimizers via the
+ * OptimizerType template parameter.
+ *
+ * @tparam OptimizerType The optimizer to use; by default this is L-BFGS.  Any
+ *     mlpack optimizer can be used here.
+ */
 template<
   template<typename> class OptimizerType = mlpack::optimization::L_BFGS
 >
 class SparseAutoencoder
 {
  public:
-
   /**
-   * Construct the Sparse Autoencoder model with the given training data. This
+   * Construct the sparse autoencoder model with the given training data. This
    * will train the model. The parameters 'lambda', 'beta' and 'rho' can be set
    * optionally. Changing these parameters will have an effect on regularization
    * and sparsity of the model.
@@ -77,7 +84,7 @@ class SparseAutoencoder
                     const double rho = 0.01);
 
   /**
-   * Construct the Sparse Autoencoder model with the given training data. This
+   * Construct the sparse autoencoder model with the given training data. This
    * will train the model. This overload takes an already instantiated optimizer
    * and uses it to train the model. The optimizer should hold an instantiated
    * SparseAutoencoderFunction object for the function to operate upon. This
@@ -88,8 +95,8 @@ class SparseAutoencoder
   SparseAutoencoder(OptimizerType<SparseAutoencoderFunction>& optimizer);
 
   /**
-   * Transforms the provided data into a more meaningful and compact
-   * representation. The function basically performs a feedforward computation
+   * Transforms the provided data into the representation learned by the sparse
+   * autoencoder. The function basically performs a feedforward computation
    * using the learned weights, and returns the hidden layer activations.
    *
    * @param data Matrix of the provided data.
@@ -169,7 +176,6 @@ class SparseAutoencoder
   }
 
  private:
-
   //! Parameters after optimization.
   arma::mat parameters;
   //! Size of the visible layer.
diff --git a/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder_function.hpp b/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder_function.hpp
index 55886a1..7a9b0f4 100644
--- a/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder_function.hpp
+++ b/src/mlpack/methods/sparse_autoencoder/sparse_autoencoder_function.hpp
@@ -14,14 +14,24 @@ namespace mlpack {
 namespace nn {
 
 /**
- * This is a class for the Sparse Autoencoder objective function. It can be used
- * to create learning models like Self-Taught Learning, Stacked Autoencoders,
- * Conditional Random Fields etc.
+ * This is a class for the sparse autoencoder objective function. It can be used
+ * to create learning models like self-taught learning, stacked autoencoders,
+ * conditional random fields (CRFs), and so forth.
  */
 class SparseAutoencoderFunction
 {
  public:
-
+  /**
+   * Construct the sparse autoencoder objective function with the given
+   * parameters.
+   *
+   * @param data The data matrix.
+   * @param visibleSize Size of input vector expected at the visible layer.
+   * @param hiddenSize Size of input vector expected at the hidden layer.
+   * @param lambda L2-regularization parameter.
+   * @param beta KL divergence parameter.
+   * @param rho Sparsity parameter.
+   */
   SparseAutoencoderFunction(const arma::mat& data,
                             const size_t visibleSize,
                             const size_t hiddenSize,
@@ -29,11 +39,11 @@ class SparseAutoencoderFunction
                             const double beta = 3,
                             const double rho = 0.01);
 
-  //Initializes the parameters of the model to suitable values.
+  //! Initializes the parameters of the model to suitable values.
   const arma::mat InitializeWeights();
 
   /**
-   * Evaluates the objective function of the Sparse Autoencoder model using the
+   * Evaluates the objective function of the sparse autoencoder model using the
    * given parameters. The cost function has terms for the reconstruction
    * error, regularization cost and the sparsity cost. The objective function
    * takes a low value when the model is able to reconstruct the data well
@@ -45,13 +55,13 @@ class SparseAutoencoderFunction
   double Evaluate(const arma::mat& parameters) const;
 
   /**
-   * Evaluates the gradient values of the parameters given the current set of
-   * parameters. The function performs a feedforward pass and computes the error
-   * in reconstructing the data points. It then uses the backpropagation
-   * algorithm to compute the gradient values.
+   * Evaluates the gradient values of the objective function given the current
+   * set of parameters. The function performs a feedforward pass and computes
+   * the error in reconstructing the data points. It then uses the
+   * backpropagation algorithm to compute the gradient values.
    *
    * @param parameters Current values of the model parameters.
-   * @param gradient Pointer to matrix where gradient values are stored.
+   * @param gradient Matrix where gradient values will be stored.
    */
   void Gradient(const arma::mat& parameters, arma::mat& gradient) const;
 
@@ -130,7 +140,6 @@ class SparseAutoencoderFunction
   }
 
  private:
-
   //! The matrix of data points.
   const arma::mat& data;
   //! Intial parameter vector.

