[mlpack-git] master: Clean up documentation. (c6c04e6)

[gitdub at big.cc.gt.atl.ga.us]

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

On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/29e612eb3383926c84df1ce74f5d33f1e86af0d2...c6c04e60c5953fb44b973ed691dbde0cc634a8f1

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

commit c6c04e60c5953fb44b973ed691dbde0cc634a8f1
Author: Ryan Curtin <ryan at ratml.org>
Date:   Wed Dec 2 13:01:00 2015 -0800

    Clean up documentation.


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

c6c04e60c5953fb44b973ed691dbde0cc634a8f1
 .../methods/sparse_autoencoder/maximal_inputs.cpp  |  8 +--
 .../methods/sparse_autoencoder/maximal_inputs.hpp  | 79 ++++++++++++++--------
 2 files changed, 55 insertions(+), 32 deletions(-)

diff --git a/src/mlpack/methods/sparse_autoencoder/maximal_inputs.cpp b/src/mlpack/methods/sparse_autoencoder/maximal_inputs.cpp
index 0d12309..88ac004 100644
--- a/src/mlpack/methods/sparse_autoencoder/maximal_inputs.cpp
+++ b/src/mlpack/methods/sparse_autoencoder/maximal_inputs.cpp
@@ -3,9 +3,9 @@
 namespace mlpack {
 namespace nn {
 
-void MaximalInputs(const arma::mat &parameters, arma::mat &output)
+void MaximalInputs(const arma::mat& parameters, arma::mat& output)
 {
-  arma::mat paramTemp(parameters.submat(0, 0, (parameters.n_rows-1)/2 - 1,
+  arma::mat paramTemp(parameters.submat(0, 0, (parameters.n_rows - 1) / 2 - 1,
                                         parameters.n_cols - 2).t());
   double const mean = arma::mean(arma::mean(paramTemp));
   paramTemp -= mean;
@@ -17,9 +17,9 @@ void NormalizeColByMax(const arma::mat &input,
                        arma::mat &output)
 {
   output.set_size(input.n_rows, input.n_cols);
-  for(arma::uword i = 0; i != input.n_cols; ++i)
+  for (arma::uword i = 0; i != input.n_cols; ++i)
   {
-    const double max  = arma::max(arma::abs(input.col(i)));
+    const double max = arma::max(arma::abs(input.col(i)));
     if (max != 0.0)
     {
       output.col(i) = input.col(i) / max;
diff --git a/src/mlpack/methods/sparse_autoencoder/maximal_inputs.hpp b/src/mlpack/methods/sparse_autoencoder/maximal_inputs.hpp
index bbc1a96..713c3bd 100644
--- a/src/mlpack/methods/sparse_autoencoder/maximal_inputs.hpp
+++ b/src/mlpack/methods/sparse_autoencoder/maximal_inputs.hpp
@@ -1,3 +1,9 @@
+/**
+ * @file maximal_inputs.hpp
+ * @author Tham Ngap Wei
+ *
+ * A function to find the maximal inputs of an autoencoder.
+ */
 #ifndef __MLPACK_METHODS_NN_MAXIMAL_INPUTS_HPP
 #define __MLPACK_METHODS_NN_MAXIMAL_INPUTS_HPP
 
@@ -7,39 +13,36 @@ namespace mlpack {
 namespace nn {
 
 /**
- * Maximize the hidden units of the parameters, details are located at
- * http://deeplearning.stanford.edu/wiki/index.php/Visualizing_a_Trained_Autoencoder.
- * This function is based on the implementation(display_network.m) from the exercise of UFLDL.
+ * Given a parameters matrix from an autoencoder, maximize the hidden units of
+ * the parameters, storing the maximal inputs in the given output matrix.
+ * Details can be found on the 'Visualizing a Trained Autoencoder' page of the
+ * Stanford UFLDL tutorial:
+ *
+ * http://deeplearning.stanford.edu/wiki/index.php/Main_Page
+ *
+ * This function is based on the implementation (display_network.m) from the
+ * "Exercise: Sparse Autoencoder" page of the UFLDL tutorial:
+ *
  * http://deeplearning.stanford.edu/wiki/index.php/Exercise:Sparse_Autoencoder
- * @param params The parameters want to maximize
- * @param output Parameters after maximize
- * @pre 1 : The layout of the parameters should be same as following
- * //          vSize   1
- * //       |        |  |
- * //  hSize|   w1   |b1|
- * //       |________|__|
- * //       |        |  |
- * //  hSize|   w2'  |  |
- * //       |________|__|
- * //      1|   b2'  |  |
  *
- * 2 : Square root of vSize must be interger and bigger than zero
+ * Example usage of this function can be seen below.  Note that this function
+ * can work with the ColumnsToBlocks class in order to reshape the maximal
+ * inputs for visualization, as in the UFLDL tutorial.  The code below
+ * demonstrates this.
+ *
  * @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.
  *
- *
  * 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);
+ * SparseAutoencoder<L_BFGS> encoder(data, vSize, hSize);
  *
- * arma::mat maximalInput; //store the features learned by sparse autoencoder
- * mlpack::nn::MaximalInputs(encoder2.Parameters(), maximalInput);
+ * arma::mat maximalInput; // Store the features learned by sparse autoencoder
+ * mlpack::nn::MaximalInputs(encoder.Parameters(), maximalInput);
  *
  * arma::mat outputs;
  * const bool scale = true;
@@ -47,20 +50,40 @@ namespace nn {
  * ColumnsToBlocks ctb(5,5);
  * arma::mat output;
  * ctb.Transform(maximalInput, output);
- * //you can save the output as a pgm, this may help you visualize the training results
+ * // Save the output as PGM, for visualization.
  * output.save(fileName, arma::pgm_binary);
+ * @endcode
  *
+ * @pre Layout of parameters
+ *
+ * The layout of the parameters matrix should be same as following
+ * @code
+ * //          vSize   1
+ * //       |        |  |
+ * //  hSize|   w1   |b1|
+ * //       |________|__|
+ * //       |        |  |
+ * //  hSize|   w2'  |  |
+ * //       |________|__|
+ * //      1|   b2'  |  |
  * @endcode
+ *
+ * Also, the square root of vSize must be an integer (i.e. vSize must be a
+ * perfect square).
+ *
+ * @param parameters The parameters of the autoencoder.
+ * @param output Matrix to store the maximal inputs in.
  */
-void MaximalInputs(const arma::mat &parameters, arma::mat &output);
+void MaximalInputs(const arma::mat& parameters, arma::mat& output);
 
 /**
- * Normalize the cols with its maximum value if it is not zero
- * @param input the input data want to normalize
- * @param output inputs after normalize
+ * Normalize each column of the input matrix by its maximum value, if that
+ * maximum value is not zero.
+ *
+ * @param input The input data to normalize.
+ * @param output A matrix to store the input data in after normalization.
  */
-void NormalizeColByMax(const arma::mat &input,
-                       arma::mat &output);
+void NormalizeColByMax(const arma::mat& input, arma::mat& output);
 
 } // namespace nn
 } // namespace mlpack