Merge branch 'jeffin143-option-inconsistency'

HISTORY.md

@@ -1,6 +1,14 @@
-### mlpack 3.1.0
+### mlpack 3.1.1
 ###### ????-??-??
+  * `output` option changed to `predictions` for adaboost and perceptron
+    binding. Old options are now deprecated and will be preserved until mlpack
+    4.0.0 (#1882).
 
+  * Concatenated ReLU layer (#1843).
+
+  * Accelerate NormalizeLabels function using hashing instead of linear search
+    (see `src/mlpack/core/data/normalize_labels_impl.hpp`)(#1780).
+  
 ### mlpack 3.1.0
 ###### 2019-04-25
   * Add DiagonalGaussianDistribution and DiagonalGMM classes to speed up the

src/mlpack/methods/adaboost/adaboost_main.cpp

@@ -77,10 +77,17 @@ PROGRAM_INFO("AdaBoost",
     "predictions for a given test dataset.  A test dataset may be specified "
     "with the " + PRINT_PARAM_STRING("test") + " parameter.  The predicted "
     "classes for each point in the test dataset are output to the " +
-    PRINT_PARAM_STRING("output") + " output parameter.  The AdaBoost model "
-    "itself is output to the " + PRINT_PARAM_STRING("output_model") +
+    PRINT_PARAM_STRING("predictions") + " output parameter.  The AdaBoost "
+    "model itself is output to the " + PRINT_PARAM_STRING("output_model") +
     " output parameter."
     "\n\n"
+    "Note: the following parameter is deprecated and "
+    "will be removed in mlpack 4.0.0: " + PRINT_PARAM_STRING("output") +
+    "."
+    "\n"
+    "Use " + PRINT_PARAM_STRING("predictions") + " instead of " +
+    PRINT_PARAM_STRING("output") + '.' +
+    "\n\n"
     "For example, to run AdaBoost on an input dataset " +
     PRINT_DATASET("data") + " with perceptrons as the weak learner type, "
     "storing the trained model in " + PRINT_MODEL("model") + ", one could "
@@ -95,7 +102,7 @@ PROGRAM_INFO("AdaBoost",
     PRINT_DATASET("predictions") + " with the following command: "
     "\n\n" +
     PRINT_CALL("adaboost", "input_model", "model", "test", "test_data",
-        "output", "predictions"),
+        "predictions", "predictions"),
     // See also...
     SEE_ALSO("AdaBoost on Wikipedia", "https://en.wikipedia.org/wiki/AdaBoost"),
     SEE_ALSO("Improved boosting algorithms using confidence-rated predictions "
@@ -111,7 +118,9 @@ PARAM_UROW_IN("labels", "Labels for the training set.", "l");
 
 // Classification options.
 PARAM_MATRIX_IN("test", "Test dataset.", "T");
+// PARAM_UROW_OUT("output") is deprecated and will be removed in mlpack 4.0.0.
 PARAM_UROW_OUT("output", "Predicted labels for the test set.", "o");
+PARAM_UROW_OUT("predictions", "Predicted labels for the test set.", "P");
 
 // Training options.
 PARAM_INT_IN("iterations", "The maximum number of boosting iterations to be run"
@@ -155,10 +164,11 @@ static void mlpackMain()
   if (CLI::HasParam("input_model"))
     RequireAtLeastOnePassed({ "test" }, false, "no task will be performed");
 
-  RequireAtLeastOnePassed({ "output_model", "output" }, false,
+  RequireAtLeastOnePassed({ "output_model", "output", "predictions" }, false,
       "no results will be saved");
 
-  ReportIgnoredParam({{ "test", false }}, "output");
+  // "output" will be removed in mlpack 4.0.0.
+  ReportIgnoredParam({{ "test", false }}, "predictions");
 
   AdaBoostModel* m;
   if (CLI::HasParam("training"))
@@ -230,7 +240,11 @@ static void mlpackMain()
     Row<size_t> results;
     data::RevertLabels(predictedLabels, m->Mappings(), results);
 
-    CLI::GetParam<arma::Row<size_t>>("output") = std::move(results);
+    // Save the predicted labels.
+    if (CLI::HasParam("output"))
+      CLI::GetParam<arma::Row<size_t>>("output") = results;
+    if (CLI::HasParam("predictions"))
+      CLI::GetParam<arma::Row<size_t>>("predictions") = std::move(results);
   }
 
   CLI::GetParam<AdaBoostModel*>("output_model") = m;

src/mlpack/methods/perceptron/perceptron_main.cpp

@@ -47,10 +47,18 @@ PROGRAM_INFO("Perceptron",
     " parameter), or both those things at once.  In addition, this program "
     "allows classification on a test dataset (via the " +
     PRINT_PARAM_STRING("test") + " parameter) and the classification results "
-    "on the test set may be saved with the " + PRINT_PARAM_STRING("output") +
-    "output parameter.  The perceptron model may be saved with the " +
+    "on the test set may be saved with the " +
+    PRINT_PARAM_STRING("predictions") +
+    " output parameter.  The perceptron model may be saved with the " +
     PRINT_PARAM_STRING("output_model") + " output parameter."
     "\n\n"
+    "Note: the following parameter is deprecated and "
+    "will be removed in mlpack 4.0.0: " + PRINT_PARAM_STRING("output") +
+    "."
+    "\n"
+    "Use " + PRINT_PARAM_STRING("predictions") + " instead of " +
+    PRINT_PARAM_STRING("output") + '.' +
+    "\n\n"
     "The training data given with the " + PRINT_PARAM_STRING("training") +
     " option may have class labels as its last dimension (so, if the training "
     "data is in CSV format, labels should be the last column).  Alternately, "
@@ -71,7 +79,7 @@ PROGRAM_INFO("Perceptron",
     "saving the predicted classes to " + PRINT_DATASET("predictions") + "."
     "\n\n" +
     PRINT_CALL("perceptron", "input_model", "perceptron_model", "test",
-        "test_data", "output", "predictions") +
+        "test_data", "predictions", "predictions") +
     "\n\n"
     "Note that all of the options may be specified at once: predictions may be "
     "calculated right after training a model, and model training can occur even"
@@ -126,8 +134,11 @@ PARAM_MODEL_OUT(PerceptronModel, "output_model", "Output for trained perceptron"
 
 // Testing/classification parameters.
 PARAM_MATRIX_IN("test", "A matrix containing the test set.", "T");
+// PARAM_UROW_OUT("output") is deprecated and will be removed in
 PARAM_UROW_OUT("output", "The matrix in which the predicted labels for the"
     " test set will be written.", "o");
+PARAM_UROW_OUT("predictions", "The matrix in which the predicted labels for the"
+    " test set will be written.", "P");
 
 static void mlpackMain()
 {
@@ -139,9 +150,10 @@ static void mlpackMain()
 
   // If the user isn't going to save the output model or any predictions, we
   // should issue a warning.
-  RequireAtLeastOnePassed({ "output_model", "output" }, false,
+  RequireAtLeastOnePassed({ "output_model", "output", "predictions" }, false,
       "no output will be saved");
-  ReportIgnoredParam({{ "test", false }}, "output");
+  // "output" will be removed in mlpack 4.0.0.
+  ReportIgnoredParam({{ "test", false }}, "predictions");
 
   // Check parameter validity.
   RequireParamValue<int>("max_iterations", [](int x) { return x >= 0; },
@@ -296,7 +308,9 @@ static void mlpackMain()
 
     // Save the predicted labels.
     if (CLI::HasParam("output"))
-      CLI::GetParam<arma::Row<size_t>>("output") = std::move(results);
+      CLI::GetParam<arma::Row<size_t>>("output") = results;
+    if (CLI::HasParam("predictions"))
+      CLI::GetParam<arma::Row<size_t>>("predictions") = std::move(results);
   }
 
   // Lastly, save the output model.

src/mlpack/tests/main_tests/adaboost_test.cpp

@@ -206,6 +206,29 @@ BOOST_AUTO_TEST_CASE(AdaBoostTrainingDataOrModelTest)
   Log::Fatal.ignoreInput = false;
 }
 
+/**
+ * This test can be removed in mlpack 4.0.0.  This tests that the output and
+ * predictions outputs are the same.
+ */
+BOOST_AUTO_TEST_CASE(AdaBoostOutputPredictionsTest)
+{
+  arma::mat trainData;
+  if (!data::Load("vc2.csv", trainData))
+    BOOST_FAIL("Unable to load train dataset vc2.csv!");
+
+  arma::Row<size_t> labels;
+  if (!data::Load("vc2_labels.txt", labels))
+    BOOST_FAIL("Unable to load label dataset vc2_labels.txt!");
+
+  SetInputParam("training", std::move(trainData));
+  SetInputParam("labels", std::move(labels));
+
+  mlpackMain();
+
+  CheckMatrices(CLI::GetParam<arma::Row<size_t>>("output"),
+                CLI::GetParam<arma::Row<size_t>>("predictions"));
+}
+
 /**
  * Weak learner should be either Decision Stump or Perceptron.
  */

src/mlpack/tests/main_tests/perceptron_test.cpp

@@ -162,6 +162,39 @@ BOOST_AUTO_TEST_CASE(PerceptronLabelsLessDimensionTest)
   CheckMatrices(output, CLI::GetParam<arma::Row<size_t>>("output"));
 }
 
+/**
+ * This test can be removed in mlpack 4.0.0. This tests that the output and
+ * predictions outputs are the same.
+ */
+BOOST_AUTO_TEST_CASE(PerceptronOutputPredictionsCheck)
+{
+  arma::mat trainX1;
+  arma::Row<size_t> labelsX1;
+
+  // Loading a train data set with 3 classes.
+  if (!data::Load("vc2.csv", trainX1))
+  {
+    BOOST_FAIL("Could not load the train data (vc2.csv)");
+  }
+
+  // Loading the corresponding labels to the dataset.
+  if (!data::Load("vc2_labels.txt", labelsX1))
+  {
+    BOOST_FAIL("Could not load the train data (vc2_labels.csv)");
+  }
+
+  SetInputParam("training", std::move(trainX1)); // Training data.
+  // Labels for the training data.
+  SetInputParam("labels", std::move(labelsX1));
+
+  // Training model using first training dataset.
+  mlpackMain();
+
+  // Check that the outputs are the same.
+  CheckMatrices(CLI::GetParam<arma::Row<size_t>>("output"),
+                CLI::GetParam<arma::Row<size_t>>("predictions"));
+}
+
 /**
  * Ensure that saved model can be used again.
  */