mlpack 4.6.2__cp39-cp39-win_amd64.whl → 4.7.0__cp39-cp39-win_amd64.whl

mlpack/include/mlpack/core/data/combine_options.hpp

@@ -0,0 +1,151 @@
+/**
+ * @file combine_options.hpp
+ * @author Ryan Curtin
+ * @author Omar Shrit
+ *
+ * Definition of operator+() for DataOptions types.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+#ifndef MLPACK_CORE_DATA_COMBINE_OPTIONS_HPP
+#define MLPACK_CORE_DATA_COMBINE_OPTIONS_HPP
+
+#include <mlpack/prereqs.hpp>
+
+#include "data_options.hpp"
+#include "matrix_options.hpp"
+#include "text_options.hpp"
+
+namespace mlpack {
+
+// This template metaprogram encodes what the result of combining two different
+// DataOptions types are.  For now it exhaustively considers every possibility,
+// but, in the future, perhaps it will be possible to come up with something
+// that scales a little better.
+
+template<typename DataOptionsType1, typename DataOptionsType2>
+struct GetCombinedDataOptionsType
+{
+  typedef void result; // unknown result
+};
+
+template<typename T>
+struct MostDerivedType
+{
+  typedef void result;
+};
+
+template<typename Derived>
+struct MostDerivedType<DataOptionsBase<Derived>>
+{
+  typedef Derived result;
+};
+
+template<>
+struct MostDerivedType<DataOptionsBase<PlainDataOptions>>
+{
+  typedef DataOptions result;
+};
+
+template<>
+struct MostDerivedType<DataOptionsBase<MatrixOptionsBase<PlainMatrixOptions>>>
+{
+  typedef MatrixOptions result;
+};
+
+template<>
+struct MostDerivedType<DataOptionsBase<MatrixOptionsBase<TextOptions>>>
+{
+  typedef TextOptions result;
+};
+
+// When both types are the same, we return that type.
+template<typename Derived>
+struct GetCombinedDataOptionsType<DataOptionsBase<Derived>,
+                                  DataOptionsBase<Derived>>
+{
+  typedef typename MostDerivedType<DataOptionsBase<Derived>>::result result;
+};
+
+// When both types are different, the result is hardcoded.
+template<>
+struct GetCombinedDataOptionsType<DataOptionsBase<PlainDataOptions>,
+    DataOptionsBase<MatrixOptionsBase<PlainMatrixOptions>>>
+{
+  typedef MatrixOptions result;
+};
+
+template<>
+struct GetCombinedDataOptionsType<DataOptionsBase<
+    MatrixOptionsBase<PlainMatrixOptions>>,
+    DataOptionsBase<PlainDataOptions>>
+{
+  typedef MatrixOptions result;
+};
+
+template<>
+struct GetCombinedDataOptionsType<DataOptionsBase<
+    MatrixOptionsBase<TextOptions>>, DataOptionsBase<PlainDataOptions>>
+{
+  typedef TextOptions result;
+};
+
+template<>
+struct GetCombinedDataOptionsType<DataOptionsBase<PlainDataOptions>,
+    DataOptionsBase<MatrixOptionsBase<TextOptions>>>
+{
+  typedef TextOptions result;
+};
+
+template<>
+struct GetCombinedDataOptionsType<
+    DataOptionsBase<MatrixOptionsBase<PlainMatrixOptions>>,
+    DataOptionsBase<MatrixOptionsBase<TextOptions>>>
+{
+  typedef TextOptions result;
+};
+
+template<>
+struct GetCombinedDataOptionsType<
+    DataOptionsBase<MatrixOptionsBase<TextOptions>>,
+    DataOptionsBase<MatrixOptionsBase<PlainMatrixOptions>>>
+{
+  typedef TextOptions result;
+};
+
+// Using the template metaprogram above, return a combined DataOptions.
+
+template<typename Derived1, typename Derived2>
+typename GetCombinedDataOptionsType<DataOptionsBase<Derived1>,
+                                    DataOptionsBase<Derived2>>::result
+operator+(const DataOptionsBase<Derived1>& a,
+          const DataOptionsBase<Derived2>& b)
+{
+  using ReturnType = typename GetCombinedDataOptionsType<
+      DataOptionsBase<Derived1>, DataOptionsBase<Derived2>>::result;
+
+  if (std::is_same_v<Derived1, Derived2>)
+  {
+    // This is the easy case!  They are the same.
+    ReturnType output(a);
+    output += b;
+    return output;
+  }
+  else
+  {
+    // Here's the hard part, where the types are different.
+    // In this case, we can keep only the options from both sides that will be
+    // used in the result.  If members of a or b can't be represented in
+    // ReturnType, then a warning will be printed.
+    ReturnType convertedA(a);
+    ReturnType convertedB(b);
+    return convertedA + convertedB;
+  }
+}
+
+} // namespace mlpack
+
+#endif

mlpack/include/mlpack/core/data/confusion_matrix.hpp

@@ -16,7 +16,6 @@
 #include <mlpack/prereqs.hpp>
 
 namespace mlpack {
-namespace data {
 
 /**
  * A confusion matrix is a summary of prediction results on a classification
@@ -56,7 +55,6 @@ void ConfusionMatrix(const arma::Row<size_t> predictors,
                      arma::Mat<eT>& output,
                      const size_t numClasses);
 
-} // namespace data
 } // namespace mlpack
 
 // Include implementation.

mlpack/include/mlpack/core/data/confusion_matrix_impl.hpp

@@ -17,7 +17,6 @@
 #include "confusion_matrix.hpp"
 
 namespace mlpack {
-namespace data {
 
 /**
  * A confusion matrix is a summary of prediction results on a classification
@@ -60,7 +59,6 @@ void ConfusionMatrix(const arma::Row<size_t> predictors,
   }
 }
 
-} // namespace data
 } // namespace mlpack
 
 #endif

mlpack/include/mlpack/core/data/data.hpp

@@ -13,7 +13,6 @@
 #define MLPACK_CORE_DATA_DATA_HPP
 
 #include "extension.hpp"
-#include "format.hpp"
 #include "has_serialize.hpp"
 
 #include "load.hpp"
@@ -31,8 +30,11 @@
 #include "dataset_mapper.hpp"
 #include "data_options.hpp"
 #include "detect_file_type.hpp"
-#include "image_info.hpp"
+#include "image_layout.hpp"
+#include "image_options.hpp"
 #include "image_resize_crop.hpp"
+#include "image_letterbox.hpp"
+#include "image_bounding_box.hpp"
 #include "imputer.hpp"
 #include "is_naninf.hpp"
 #include "matrix_options.hpp"
@@ -41,7 +43,7 @@
 #include "split_data.hpp"
 #include "string_algorithms.hpp"
 #include "text_options.hpp"
-#include "types.hpp"
-#include "utilities.hpp"
+
+#include "combine_options.hpp"
 
 #endif

mlpack/include/mlpack/core/data/data_options.hpp

@@ -16,14 +16,54 @@
 
 #include <mlpack/prereqs.hpp>
 
-#include "types.hpp"
 #include "dataset_mapper.hpp"
 #include "map_policies/map_policies.hpp"
-#include "format.hpp"
-#include "image_info.hpp"
 
 namespace mlpack {
-namespace data {
+
+enum struct FileType
+{
+  FileTypeUnknown,
+  AutoDetect, // attempt to automatically detect the file type
+  RawASCII,   // raw text (ASCII), without a header
+  ArmaASCII,  // Armadillo text format, with a header specifying matrix type and
+              // size
+  CSVASCII,   // comma separated values (CSV), without a header
+  RawBinary,  // raw binary format (machine dependent), without a header
+  ArmaBinary, // Armadillo binary format (machine dependent), with a header
+              // specifying matrix type and size
+  PGMBinary,  // Portable Grey Map (greyscale image)
+  PPMBinary,  // Portable Pixel Map (colour image), used by the field and cube
+              // classes
+  HDF5Binary, // HDF5: open binary format, not specific to Armadillo, which can
+              // store arbitrary data
+  CoordASCII, // simple co-ordinate format for sparse matrices (indices start at
+              // zero)
+  ARFFASCII,  // ARFF data format, with a header specifying information about
+              // categories of the data.
+  JSON,       // Serialize data using Cereal library into JSON format.
+  XML,        // Serialize data using Cereal library into xml format.
+  BIN,        // Serialize data using Cereal library into binary format.
+  ImageType,  // Any image type, STB will try to detect the type.
+  PNG,        // Portable Network Graphics image type.
+  JPG,        // Joint Photographic Experts Group image type.
+  TGA,        // Truevision TGA image type.
+  BMP,        // Bitmap image type.
+  PSD,        // PhotoShop image type.
+  GIF,        // Graphics Interchange Format image type.
+  PIC,        // PICtor image format.
+  PNM         // Portable Anymap format.
+};
+
+// This should be removed in mlpack 5.0.0. It is only here for backward
+// compatibility.
+enum format
+{
+  autodetect,
+  json,
+  xml,
+  binary
+};
 
 /**
  * All possible DataOptions grouped under one class.
@@ -34,15 +74,15 @@ namespace data {
 template<typename Derived>
 class DataOptionsBase
 {
- public:
-  DataOptionsBase(const bool fatal = defaultFatal,
-                  const FileType format = defaultFormat) :
+ protected:
+  // Users should not construct a DataOptionsBase directly.
+  DataOptionsBase(const std::optional<bool> fatal = std::nullopt,
+                  const std::optional<FileType> format = std::nullopt) :
       fatal(fatal),
       format(format)
-  {
-    // Do nothing.
-  }
+  { }
 
+ public:
   template<typename Derived2>
   explicit DataOptionsBase(const DataOptionsBase<Derived2>& opts)
   {
@@ -77,7 +117,7 @@ class DataOptionsBase
   template<typename Derived2>
   DataOptionsBase& operator=(DataOptionsBase<Derived2>&& other)
   {
-    if ((void*) &other != (void*) this)
+    if ((void*) &other == (void*) this)
       return *this;
 
     // Print warnings for any members that cannot be converted.
@@ -88,6 +128,63 @@ class DataOptionsBase
     return *this;
   }
 
+  // Augment with the options of the other `DataOptionsBase`.
+  template<typename Derived2>
+  DataOptionsBase& operator+=(const DataOptionsBase<Derived2>& other)
+  {
+    Combine(other);
+    return *this;
+  }
+
+  // Augment with the options of the other `DataOptionsBase`.
+  template<typename Derived2>
+  void Combine(const DataOptionsBase<Derived2>& other)
+  {
+    // Combine the fatal option.
+    fatal = CombineBooleanOption(fatal, other.fatal, "Fatal()");
+
+    // Combine the format option.
+    if (format.has_value() && other.format.has_value())
+    {
+      // There are two cases where we can accept the other's format---when we
+      // are unknown or autodetect.
+      if (format == FileType::FileTypeUnknown)
+      {
+        // Here we always take the other format.
+        format = other.format;
+      }
+      else if (format == FileType::AutoDetect && \
+               other.format != FileType::FileTypeUnknown)
+      {
+        format = other.format;
+      }
+      else if (other.format != FileType::FileTypeUnknown && \
+               other.format != FileType::AutoDetect &&
+               format != other.format)
+      {
+        // In any other case, we won't overwrite one specified format with
+        // another.
+        throw std::invalid_argument("DataOptions::operator+(): cannot combine "
+            "options with formats '" + FileTypeToString() + "' and '" +
+            other.FileTypeToString() + "'!");
+      }
+    }
+    else if (!format.has_value() && other.format.has_value())
+    {
+      // Always take the format of the other if it's unspecified.
+      format = other.format;
+    }
+
+    // If the derived type is the same, we can take any options from it.
+    if constexpr (std::is_same_v<Derived, Derived2>)
+    {
+      static_cast<Derived&>(*this).Combine(static_cast<const Derived2&>(other));
+    }
+
+    // If Derived is not the same as Derived2, we will have printed warnings in
+    // the standalone operator+().
+  }
+
   template<typename Derived2>
   void CopyOptions(const DataOptionsBase<Derived2>& other)
   {
@@ -127,6 +224,64 @@ class DataOptionsBase
   // Modify the file format to load.
   FileType& Format() { return ModifyMember(format, defaultFormat); }
 
+  /**
+   * Given a file type, return Armadillo type corresponding to that file type.
+   */
+  inline arma::file_type ArmaFormat() const
+  {
+    FileType f = format.has_value() ? *format : defaultFormat;
+    switch (f)
+    {
+      case FileType::FileTypeUnknown:
+        return arma::file_type_unknown;
+        break;
+
+      case FileType::AutoDetect:
+        return arma::auto_detect;
+        break;
+
+      case FileType::RawASCII:
+        return arma::raw_ascii;
+        break;
+
+      case FileType::ArmaASCII:
+        return arma::arma_ascii;
+        break;
+
+      case FileType::CSVASCII:
+        return arma::csv_ascii;
+        break;
+
+      case FileType::RawBinary:
+        return arma::raw_binary;
+        break;
+
+      case FileType::ArmaBinary:
+        return arma::arma_binary;
+        break;
+
+      case FileType::PGMBinary:
+        return arma::pgm_binary;
+        break;
+
+      case FileType::PPMBinary:
+        return arma::ppm_binary;
+        break;
+
+      case FileType::HDF5Binary:
+        return arma::hdf5_binary;
+        break;
+
+      case FileType::CoordASCII:
+        return arma::coord_ascii;
+        break;
+
+      default:
+        return arma::file_type_unknown;
+        break;
+    }
+  }
+
   /**
    * Given a file type, return a logical name corresponding to that file type.
    */
@@ -145,8 +300,21 @@ class DataOptionsBase
       case FileType::HDF5Binary:  return "HDF5 data";
       case FileType::CoordASCII:
           return "ASCII formatted sparse coordinate data";
+      case FileType::ARFFASCII:   return "ARFF data";
+      case FileType::XML:         return "XML model";
+      case FileType::BIN:         return "binary model";
+      case FileType::JSON:        return "JSON model";
       case FileType::AutoDetect:  return "Detect automatically data type";
       case FileType::FileTypeUnknown: return "Unknown data type";
+      case FileType::ImageType:   return "Any Image type";
+      case FileType::PNG:         return "Portable Network Graphics image data";
+      case FileType::JPG:         return "JPEG image data";
+      case FileType::TGA:         return "Truevision TGA image data";
+      case FileType::BMP:         return "Bitmap image data";
+      case FileType::PSD:         return "PhotoShop image data";
+      case FileType::GIF:         return "GIF image data";
+      case FileType::PIC:         return "PICtor image data";
+      case FileType::PNM:         return "Portable Anymap data";
       default:                    return "";
     }
   }
@@ -187,33 +355,188 @@ class DataOptionsBase
     }
   }
 
+  std::optional<bool> CombineBooleanOption(const std::optional<bool>& a,
+                                           const std::optional<bool>& b,
+                                           const std::string name)
+  {
+    if (a.has_value() && b.has_value() && ((*a) != (*b)))
+    {
+      // If both are set, but not the same, then throw an exception---this is
+      // invalid.
+      throw std::invalid_argument("DataOptions::operator+(): cannot combine "
+          "options where " + name + " is set to true in one object and false "
+          "in the other!");
+    }
+    else if (!a.has_value() && b.has_value())
+    {
+      // If only b is set, take b.
+      return b;
+    }
+    else
+    {
+      // Otherwise, take a (whether or not it is set).
+      return a;
+    }
+  }
+
  private:
   std::optional<bool> fatal;
   std::optional<FileType> format;
 
   constexpr static const bool defaultFatal = false;
   constexpr static const FileType defaultFormat = FileType::AutoDetect;
-
   // For access to internal optional members.
   template<typename Derived2>
   friend class DataOptionsBase;
 };
 
-// This utility class is meant to be used as the Derived parameter for an option
-// that is not actually a derived type.  It provides the WarnBaseConversion()
-// member, which does nothing.
-class EmptyOptions : public DataOptionsBase<EmptyOptions>
+// This is the class that should be used if a DataOptions with no extra options
+// is meant to be constructed.
+class PlainDataOptions : public DataOptionsBase<PlainDataOptions>
 {
  public:
+  // Allow access to all DataOptionsBase non-protected constructors and
+  // operators, but with the PlainDataOptions type name.
+  using DataOptionsBase::DataOptionsBase;
+  using DataOptionsBase::operator=;
+
+  // However, C++ does not allow inheriting copy and move constructors or
+  // operators, and any inherited protected constructors will still be
+  // protected, so forward those manually.
+  PlainDataOptions(const std::optional<bool> fatal = std::nullopt,
+                   const std::optional<FileType> format = std::nullopt) :
+      DataOptionsBase(fatal, format) { }
+  PlainDataOptions(const DataOptionsBase<PlainDataOptions>& other) :
+      DataOptionsBase(other) { }
+  PlainDataOptions(DataOptionsBase<PlainDataOptions>&& other) :
+      DataOptionsBase(std::move(other)) { }
+
+  PlainDataOptions& operator=(const DataOptionsBase<PlainDataOptions>& other)
+  {
+    return static_cast<PlainDataOptions&>(DataOptionsBase::operator=(other));
+  }
+
+  PlainDataOptions& operator=(DataOptionsBase<PlainDataOptions>&& other)
+  {
+    return static_cast<PlainDataOptions&>(
+        DataOptionsBase::operator=(std::move(other)));
+  }
+
   void WarnBaseConversion(const char* /* dataDescription */) const { }
   static const char* DataDescription() { return "general data"; }
   void Reset() { }
+  void Combine(const PlainDataOptions&) { }
+};
+
+using DataOptions = PlainDataOptions;
+
+// Boolean options
+static const DataOptions Fatal   = DataOptions(true);
+static const DataOptions NoFatal = DataOptions(false);
+
+//! File options
+static const DataOptions CSV = DataOptions(std::nullopt, FileType::CSVASCII);
+static const DataOptions PGM = DataOptions(std::nullopt, FileType::PGMBinary);
+static const DataOptions PPM = DataOptions(std::nullopt, FileType::PPMBinary);
+static const DataOptions HDF5 = DataOptions(std::nullopt,
+    FileType::HDF5Binary);
+static const DataOptions ArmaAscii = DataOptions(std::nullopt,
+    FileType::ArmaASCII);
+static const DataOptions ArmaBin = DataOptions(std::nullopt,
+    FileType::ArmaBinary);
+static const DataOptions RawAscii = DataOptions(std::nullopt,
+    FileType::RawASCII);
+static const DataOptions BinAscii = DataOptions(std::nullopt,
+    FileType::RawBinary);
+static const DataOptions CoordAscii = DataOptions(std::nullopt,
+    FileType::CoordASCII);
+static const DataOptions ARFF = DataOptions(std::nullopt,
+    FileType::ARFFASCII);
+static const DataOptions AutoDetect = DataOptions(std::nullopt,
+    FileType::AutoDetect);
+static const DataOptions JSON = DataOptions(std::nullopt, FileType::JSON);
+static const DataOptions XML = DataOptions(std::nullopt, FileType::XML);
+static const DataOptions BIN = DataOptions(std::nullopt, FileType::BIN);
+static const DataOptions PNG = DataOptions(std::nullopt, FileType::PNG);
+static const DataOptions JPG = DataOptions(std::nullopt, FileType::JPG);
+static const DataOptions TGA = DataOptions(std::nullopt, FileType::TGA);
+static const DataOptions BMP = DataOptions(std::nullopt, FileType::BMP);
+static const DataOptions PSD = DataOptions(std::nullopt, FileType::PSD);
+static const DataOptions GIF = DataOptions(std::nullopt, FileType::GIF);
+static const DataOptions PIC = DataOptions(std::nullopt, FileType::PIC);
+static const DataOptions PNM = DataOptions(std::nullopt, FileType::PNM);
+static const DataOptions Image = DataOptions(std::nullopt,
+    FileType::ImageType);
+
+// Utility struct to detect when something is a `DataOptions`.
+
+template<typename T>
+struct IsDataOptions
+{
+  constexpr static bool value = false;
+};
+
+template<typename T>
+struct IsDataOptions<DataOptionsBase<T>>
+{
+  constexpr static bool value = true;
 };
 
-using DataOptions = DataOptionsBase<EmptyOptions>;
+template<>
+struct IsDataOptions<DataOptions>
+{
+  constexpr static bool value = true;
+};
 
+template<typename Derived>
+bool HandleError(const std::stringstream& oss,
+    const DataOptionsBase<Derived>& opts)
+{
+  bool success = true; // this should never be returned as true.
+  if (opts.Fatal())
+  {
+    Log::Fatal << oss.str() << std::endl;
+  }
+  else
+  {
+    Log::Warn << oss.str() << std::endl;
+    success = false;
+  }
+  return success;
+}
+
+template<typename Derived>
+bool HandleError(const std::string& msg,
+    const DataOptionsBase<Derived>& opts)
+{
+  std::stringstream oss;
+  oss << msg;
+  return HandleError(oss, opts);
+}
+
+// Required for backward compatibility.
+inline bool HandleError(const std::stringstream& oss, bool fatal)
+{
+  bool success = true; // this should never be returned as true.
+  if (fatal)
+  {
+    Log::Fatal << oss.str() << std::endl;
+  }
+  else
+  {
+    Log::Warn << oss.str() << std::endl;
+    success = false;
+  }
+  return success;
+}
+
+inline bool HandleError(const std::string& msg, bool fatal)
+{
+  std::stringstream oss;
+  oss << msg;
+  return HandleError(oss, fatal);
+}
 
-} // namespace data
 } // namespace mlpack
 
 #endif

mlpack/include/mlpack/core/data/dataset_mapper.hpp

@@ -21,12 +21,11 @@
 #include "map_policies/increment_policy.hpp"
 
 namespace mlpack {
-namespace data {
 
 /**
  * Auxiliary information for a dataset, including mappings to/from strings (or
  * other types) and the datatype of each dimension.  DatasetMapper objects are
- * optionally produced by data::Load(), and store the type of each dimension
+ * optionally produced by Load(), and store the type of each dimension
  * (Datatype::numeric or Datatype::categorical) as well as mappings from strings
  * to unsigned integers and vice versa.
  *
@@ -142,7 +141,7 @@ class DatasetMapper
   /**
    * Get the dimensionality of the DatasetMapper object (that is, how many
    * dimensions it has information for).  If this object was created by a call
-   * to mlpack::data::Load(), then the dimensionality will be the same as the
+   * to mlpack::Load(), then the dimensionality will be the same as the
    * number of rows (dimensions) in the dataset.
    */
   size_t Dimensionality() const;
@@ -193,9 +192,8 @@ class DatasetMapper
 };
 
 // Use typedef to provide backward compatibility
-using DatasetInfo = DatasetMapper<data::IncrementPolicy>;
+using DatasetInfo = DatasetMapper<IncrementPolicy>;
 
-} // namespace data
 } // namespace mlpack
 
 #include "dataset_mapper_impl.hpp"

mlpack/include/mlpack/core/data/dataset_mapper_impl.hpp

@@ -17,7 +17,6 @@
 #include "dataset_mapper.hpp"
 
 namespace mlpack {
-namespace data {
 
 // Default constructor.
 template<typename PolicyType, typename InputType>
@@ -248,7 +247,6 @@ inline void DatasetMapper<PolicyType, InputType>::Policy(PolicyType&& policy)
   this->policy = std::forward<PolicyType>(policy);
 }
 
-} // namespace data
 } // namespace mlpack
 
 #endif