From a13ce086bdf628b7f802b2e69ba85ee90da98e8e Mon Sep 17 00:00:00 2001
From: Ryan Curtin <ryan@ratml.org>
Date: Wed, 22 May 2019 00:48:10 -0400
Subject: [PATCH] Some style changes and grammatical fixes, and update HISTORY.

---
 HISTORY.md                                    |  5 ++-
 src/mlpack/core.hpp                           |  1 -
 src/mlpack/core/data/confusion_matrix.hpp     | 31 ++++++++++++-----
 .../core/data/confusion_matrix_impl.hpp       | 34 ++++++++++++-------
 4 files changed, 47 insertions(+), 24 deletions(-)

diff --git a/HISTORY.md b/HISTORY.md
index 15d82698ef..a459110ca6 100644
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -8,7 +8,10 @@
 
   * Accelerate NormalizeLabels function using hashing instead of linear search
     (see `src/mlpack/core/data/normalize_labels_impl.hpp`)(#1780).
-  
+
+  * Add `ConfusionMatrix()` function for checking performance of classifiers
+    (#1798).
+
 ### mlpack 3.1.0
 ###### 2019-04-25
   * Add DiagonalGaussianDistribution and DiagonalGMM classes to speed up the
diff --git a/src/mlpack/core.hpp b/src/mlpack/core.hpp
index 07cea610ed..b5e1805d7b 100644
--- a/src/mlpack/core.hpp
+++ b/src/mlpack/core.hpp
@@ -91,7 +91,6 @@
 #include <mlpack/core/data/confusion_matrix.hpp>
 #include <mlpack/core/data/one_hot_encoding.hpp>
 
-
 // mlpack::backtrace only for linux
 #ifdef HAS_BFD_DL
   #include <mlpack/core/util/backtrace.hpp>
diff --git a/src/mlpack/core/data/confusion_matrix.hpp b/src/mlpack/core/data/confusion_matrix.hpp
index 5a480485e0..224ff25ac7 100644
--- a/src/mlpack/core/data/confusion_matrix.hpp
+++ b/src/mlpack/core/data/confusion_matrix.hpp
@@ -20,29 +20,42 @@ namespace data {
 
 /**
  * A confusion matrix is a summary of prediction results on a classification
- * problem.The number of correct and incorrect predictions are summarized
- * with count values and broken down by each class.
- * for example for 2 classes the function will be
- * confusionmatrix(predictors, responses, output, 2)
- * output matrix will be of size 2 * 2
+ * problem.  The number of correct and incorrect predictions are summarized
+ * by count and broken down by each class.
+ * For example, for 2 classes, the function call will be
  *
+ * @code
+ * ConfusionMatrix(predictors, responses, output, 2)
+ * @endcode
+ *
+ * In this case, the output matrix will be of size 2 * 2:
+ *
+ * @code
  *         0     1
  *    0    TP    FN
  *    1    FP    TN
+ * @endcode
  *
- * Confusion matrix for two labels will look like above.
- * The row contains the predicted values and column contains the actual values.
+ * The confusion matrix for two labels will look like what is shown above.  In
+ * this confusion matrix, TP represents the number of true positives, FP
+ * represents the number of false positives, FN represents the number of false
+ * negatives, and TN represents the number of true negatives.
+ *
+ * When generalizing to 2 or more classes, the row index of the confusion matrix
+ * represents the predicted classes and column index represents the actual
+ * class.
  *
  * @param predictors Vector of data points.
  * @param responses The measured data for each point.
  * @param output Matrix which is represented as confusion matrix.
- * @param countlables Number of classes.
+ * @param numClasses Number of classes.
  */
 template<typename eT>
 void ConfusionMatrix(const arma::Row<size_t> predictors,
                      const arma::Row<size_t> responses,
                      arma::Mat<eT>& output,
-                     const size_t countlabels);
+                     const size_t numClasses);
+
 } // namespace data
 } // namespace mlpack
 
diff --git a/src/mlpack/core/data/confusion_matrix_impl.hpp b/src/mlpack/core/data/confusion_matrix_impl.hpp
index d94c6568b4..78795c97f4 100644
--- a/src/mlpack/core/data/confusion_matrix_impl.hpp
+++ b/src/mlpack/core/data/confusion_matrix_impl.hpp
@@ -21,37 +21,45 @@ namespace data {
 
 /**
  * A confusion matrix is a summary of prediction results on a classification
- * problem.The number of correct and incorrect predictions are summarized
- * with count values and broken down by each class.
- * for example for 2 classes the function will be
- * confusionmatrix(predictors, responses, output, 2)
- * output matrix will be of size 2 * 2
+ * problem.  The number of correct and incorrect predictions are summarized
+ * by count and broken down by each class.
+ * For example, for 2 classes, the function call will be
  *
+ * @code
+ * ConfusionMatrix(predictors, responses, output, 2)
+ * @endcode
+ *
+ * In this case, the output matrix will be of size 2 * 2:
+ *
+ * @code
  *         0     1
  *    0    TP    FN
  *    1    FP    TN
+ * @endcode
  *
- * Confusion matrix for two labels will look like above.
- * The row contains the predicted values and column contains the actual values.
+ * The confusion matrix for two labels will look like what is shown above.  In
+ * this confusion matrix, TP represents the number of true positives, FP
+ * represents the number of false positives, FN represents the number of false
+ * negatives, and TN represents the number of true negatives.
  *
- * @param predictors Vector of data points.
- * @param responses The measured data for each point.
- * @param output Matrix which is represented as confusion matrix.
- * @param countlables Number of classes.
+ * When generalizing to 2 or more classes, the row index of the confusion matrix
+ * represents the predicted classes and column index represents the actual
+ * class.
  */
 template<typename eT>
 void ConfusionMatrix(const arma::Row<size_t> predictors,
                      const arma::Row<size_t> responses,
                      arma::Mat<eT>& output,
-                     const size_t countlabels)
+                     const size_t numClasses)
 {
   // Loop over the actual labels and predicted labels and add the count.
-  output = arma::zeros<arma::Mat<eT> >(countlabels, countlabels);
+  output = arma::zeros<arma::Mat<eT> >(numClasses, numClasses);
   for (size_t i = 0; i < predictors.n_elem; ++i)
   {
     output.at(predictors[i], responses[i])++;
   }
 }
+
 } // namespace data
 } // namespace mlpack