From defe9df2a4e973ec7657383ab4ada2463b79bd08 Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Wed, 25 Sep 2024 22:39:05 -0400 Subject: [PATCH] Fix links in documentation. --- doc/index.md | 6 +- doc/user/core.md | 2 - doc/user/load_save.md | 116 ++++++++++++++++++--- doc/user/methods/adaboost.md | 2 +- doc/user/methods/decision_tree.md | 2 +- doc/user/methods/hoeffding_tree.md | 2 +- doc/user/methods/linear_svm.md | 2 +- doc/user/methods/lmnn.md | 2 +- doc/user/methods/logistic_regression.md | 2 +- doc/user/methods/naive_bayes_classifier.md | 2 +- doc/user/methods/nca.md | 2 +- doc/user/methods/perceptron.md | 2 +- doc/user/methods/random_forest.md | 2 +- doc/user/methods/softmax_regression.md | 2 +- 14 files changed, 117 insertions(+), 29 deletions(-) diff --git a/doc/index.md b/doc/index.md index 65e7dc771b..e7870a8f19 100644 --- a/doc/index.md +++ b/doc/index.md @@ -129,9 +129,9 @@ Computations based on distance metrics. Prepare data for machine learning algorithms. - * [Normalizing labels](core/normalizing_labels.md): map labels to and from the - range `[0, numClasses - 1]`. - * [Dataset splitting](core/dataset_splitting.md): split a dataset into a + * [Normalizing labels](user/core/normalizing_labels.md): map labels to and from + the range `[0, numClasses - 1]`. + * [Dataset splitting](user/core/dataset_splitting.md): split a dataset into a training set and a test set. ***NOTE:*** this documentation is still under construction and so not all diff --git a/doc/user/core.md b/doc/user/core.md index 13bbf14304..55a4c70822 100644 --- a/doc/user/core.md +++ b/doc/user/core.md @@ -6,8 +6,6 @@ classes, each of which are documented in the pages below: * [Core math utilities](core/math.md): utility classes for mathematical purposes - * [Data preparation](core/data.md): utility class and functions for data - loading, saving, transformation, and preparation * [Distances](core/distances.md): distance metrics for geometric algorithms * [Distributions](core/distributions.md): probability distributions * [Kernels](core/kernels.md): Mercer kernels for kernel-based algorithms diff --git a/doc/user/load_save.md b/doc/user/load_save.md index 0eef24d523..90859e8c1d 100644 --- a/doc/user/load_save.md +++ b/doc/user/load_save.md @@ -81,8 +81,66 @@ Some mlpack techniques support mixed categorical data, e.g., data where some dimensions take only categorical values (e.g. `0`, `1`, `2`, etc.). When using mlpack, string data and other non-numerical data must be mapped to categorical values and represented as part of an `arma::mat`. Category information is -stored in an auxiliary [`data::DatasetInfo`](core/data.md#datadatasetinfo) -object. +stored in an auxiliary `data::DatasetInfo` object. + +### `data::DatasetInfo` + + + +mlpack represents categorical data via the use of the auxiliary +`data::DatasetInfo` object, which stores information about which dimensions are +numeric or categorical and allows conversion from the original category values +to the numeric values used to represent those categories. + +--- + +#### Constructors + + - `info = data::DatasetInfo()` + * Create an empty `data::DatasetInfo` object. + * Use this constructor if you intend to populate the `data::DatasetInfo` via + a `data::Load()` call. + + - `info = data::DatasetInfo(dimensionality)` + * Create a `data::DatasetInfo` object with the given dimensionality + * All dimensions are assumed to be numeric (not categorical). + +--- + +#### Accessing and setting properties + + - `info.Type(d)` + * Get the type (categorical or numeric) of dimension `d`. + * Returns a `data::Datatype`, either `data::Datatype::numeric` or + `data::Datatype::categorical`. + * Calling `info.Type(d) = t` will set a dimension to type `t`, but this + should only be done before `info` is used with `data::Load()` or + `data::Save()`. + + - `info.NumMappings(d)` + * Get the number of categories in dimension `d` as a `size_t`. + * Returns `0` if dimension `d` is numeric. + + - `info.Dimensionality()` + * Return the dimensionality of the object as a `size_t`. + +--- + +#### Map to and from numeric values + + - `info.MapString(value, d)` + * Given `value` (a `std::string`), return the `double` representing the + categorical mapping (an integer value) of `value` in dimension `d`. + * If a mapping for `value` does not exist in dimension `d`, a new mapping is + created, and `info.NumMappings(d)` is increased by one. + * If dimension `d` is numeric and `value` cannot be parsed as a numeric + value, then dimension `d` is changed to categorical and a new mapping is + returned. + + - `info.UnmapString(mappedValue, d)` + * Given `mappedValue` (a `size_t`), return the `std::string` containing the + original category that mapped to the value `mappedValue` in dimension `d`. + * If dimension `d` is not categorical, a `std::invalid_argument` is thrown. --- @@ -121,9 +179,7 @@ variant. --- -### Examples of loading categorical data - -Load and manipulate an ARFF file. +Example usage to load and manipulate an ARFF file. ```c++ // Load a categorical dataset. @@ -174,7 +230,7 @@ for (size_t d = 0; d < info.Dimensionality(); ++d) --- -Manually create a `data::DatasetInfo` object. +Example usage to manually create a `data::DatasetInfo` object. ```c++ // This will manually create the following data matrix (shown as it would appear @@ -272,9 +328,45 @@ Supported formats for saving are `jpg`, `png`, `tga`, `bmp`, and `hdr`. When loading images, each image is represented as a flattened single column vector in a data matrix; each row of the resulting vector will correspond to a -single pixel value in a single channel. An auxiliary [`data::ImageInfo` -class](core/data.md#dataimageinfo) is used to store information about the -images. +single pixel value in a single channel. An auxiliary `data::ImageInfo` class is +used to store information about the images. + +### `data::ImageInfo` + +The `data::ImageInfo` class contains the metadata of the images. + +--- + +#### Constructors + + - `info = data::ImageInfo()` + * Create a `data::ImageInfo` object with no data. + * Use this constructor if you intend to populate the `data::ImageInfo` via a + `data::Load()` call. + + - `info = data::ImageInfo(width, height, channels)` + * Create a `data::ImageInfo` object with the given image specifications. + * `width` and `height` are specified as pixels. + +--- + +#### Accessing and modifying image metadata + + - `info.Quality() = q` will set the compression quality (e.g. for saving JPEGs) + to `q`. + * `q` should take values between `0` and `100`. + * The quality value is ignored unless calling `data::Save()` with `info`. + + - Calling `info.Channels() = 1` before loading will cause images to be loaded + in grayscale. + + - Metadata stored in the `data::ImageInfo` can be accessed with the following + members: + * `info.Width()` returns the image width in pixels. + * `info.Height()` returns the image height in pixels. + * `info.Channels()` returns the number of color channels in the image. + * `info.Quality()` returns the compression quality that will be used to save + images (between 0 and 100). --- @@ -357,9 +449,7 @@ Pixels take values between 0 and 255. --- -### Examples of loading and saving images - -Loading and saving a single image: +Example of loading and saving a single image: ```c++ // See https://www.mlpack.org/static/img/numfocus-logo.png. @@ -390,7 +480,7 @@ mlpack::data::Save("numfocus-logo-mod.png", matrix, info); --- -Loading and saving multiple images: +Example of loading and saving multiple images: ```c++ // Load some favicons from websites associated with mlpack. diff --git a/doc/user/methods/adaboost.md b/doc/user/methods/adaboost.md index 6a65d62284..302e893db7 100644 --- a/doc/user/methods/adaboost.md +++ b/doc/user/methods/adaboost.md @@ -84,7 +84,7 @@ std::cout << arma::accu(predictions == 3) << " test points classified as class " | **name** | **type** | **description** | **default** | |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `weakLearner` | `Perceptron` | An initialized weak learner whose hyperparameters will be used as settings for weak learners during training. | _(N/A)_ | | `maxIterations` | `size_t` | Maximum number of iterations of AdaBoost.MH to use. This is the maximum number of weak learners to train. (0 means no limit, and weak learners will be trained until the tolerance is met.) | `100` | diff --git a/doc/user/methods/decision_tree.md b/doc/user/methods/decision_tree.md index cec361d871..5b028a67a3 100644 --- a/doc/user/methods/decision_tree.md +++ b/doc/user/methods/decision_tree.md @@ -79,7 +79,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | | `datasetInfo` | [`data::DatasetInfo`](../load_save.md#loading-categorical-data) | Dataset information, specifying type information for each dimension. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `weights` | [`arma::rowvec`](../matrices.md) | Weights for each training point. Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `minLeafSize` | `size_t` | Minimum number of points in each leaf node. | `10` | diff --git a/doc/user/methods/hoeffding_tree.md b/doc/user/methods/hoeffding_tree.md index f679fd9acc..4ca6afeb8c 100644 --- a/doc/user/methods/hoeffding_tree.md +++ b/doc/user/methods/hoeffding_tree.md @@ -100,7 +100,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | | `datasetInfo` | [`data::DatasetInfo`](../load_save.md#loading-categorical-data) | Dataset information, specifying type information for each dimension. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `dimensionality` | `size_t` | When using on numeric-only data, this specifies the number of dimensions in the data. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `batchTraining` | `bool` | If `true`, a batch training algorithm is used, instead of the usual incremental algorithm. This is generally more efficient for larger datasets. | `true` | diff --git a/doc/user/methods/linear_svm.md b/doc/user/methods/linear_svm.md index c9c3604a72..18d3e37f95 100644 --- a/doc/user/methods/linear_svm.md +++ b/doc/user/methods/linear_svm.md @@ -81,7 +81,7 @@ std::cout << arma::accu(predictions == 1) << " test points classified as class " | **name** | **type** | **description** | **default** | |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `dimensionality` | `size_t` | Dimension of input data (if data is not specified). Should be equal to `data.n_rows`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `optimizer` | [any ensmallen optimizer](https://www.ensmallen.org) | Instantiated ensmallen optimizer for [differentiable functions](https://www.ensmallen.org/docs.html#differentiable-functions) or [differentiable separable functions](https://www.ensmallen.org/docs.html#differentiable-separable-functions). | `ens::L_BFGS()` | diff --git a/doc/user/methods/lmnn.md b/doc/user/methods/lmnn.md index d1b780843f..41e517ba06 100644 --- a/doc/user/methods/lmnn.md +++ b/doc/user/methods/lmnn.md @@ -159,7 +159,7 @@ See the [examples section](#simple-examples) for more details. | **name** | **type** | **description** | |----------|----------|-----------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | | `distance` | [`arma::mat`](../matrices.md) | Output matrix to store transformation matrix representing learned distance. | | `optimizer` | [any ensmallen optimizer](https://www.ensmallen.org) | Instantiated ensmallen optimizer for [differentiable functions](https://www.ensmallen.org/docs.html#differentiable-functions) or [differentiable separable functions](https://www.ensmallen.org/docs.html#differentiable-separable-functions). | `ens::AMSGrad()` | | `callbacks...` | [any set of ensmallen callbacks](https://www.ensmallen.org/docs.html#callback-documentation) | Optional callbacks for the ensmallen optimizer, such as e.g. `ens::ProgressBar()`, `ens::Report()`, or others. | _(N/A)_ | diff --git a/doc/user/methods/logistic_regression.md b/doc/user/methods/logistic_regression.md index c5928bebe1..6fec02564b 100644 --- a/doc/user/methods/logistic_regression.md +++ b/doc/user/methods/logistic_regression.md @@ -79,7 +79,7 @@ std::cout << arma::accu(predictions == 0) << " test points classified as class " | **name** | **type** | **description** | **default** | |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, either [`0` or `1`](../load_save.md#normalizing-labels). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, either [`0` or `1`](../core/normalizing_labels.md). Should have length `data.n_cols`. | _(N/A)_ | | `initialPoint` | `arma::rowvec` | Initial model weights to start optimization from. Should have length `data.n_rows + 1`. The first element is the bias. If not specified, a zero vector will be used. | zero vector | | `optimizer` | [any ensmallen optimizer](https://www.ensmallen.org) | Instantiated ensmallen optimizer for [differentiable functions](https://www.ensmallen.org/docs.html#differentiable-functions) or [differentiable separable functions](https://www.ensmallen.org/docs.html#differentiable-separable-functions). | `ens::L_BFGS()` | | `lambda` | `double` | L2 regularization penalty parameter. Must be nonnegative. | `0.0` | diff --git a/doc/user/methods/naive_bayes_classifier.md b/doc/user/methods/naive_bayes_classifier.md index f14c3f764b..d692508af8 100644 --- a/doc/user/methods/naive_bayes_classifier.md +++ b/doc/user/methods/naive_bayes_classifier.md @@ -73,7 +73,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " | **name** | **type** | **description** | **default** | |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `incremental` | `bool` | If `true`, then the model will not be reset before training, and will use a robust incremental algorithm for variance computation. | `true` | | `epsilon` | `double` | Initial small value for sample variances, to prevent underflow (via `log(0)`). | 1e-10 | diff --git a/doc/user/methods/nca.md b/doc/user/methods/nca.md index a7566fdfef..27fcaf4ce5 100644 --- a/doc/user/methods/nca.md +++ b/doc/user/methods/nca.md @@ -142,7 +142,7 @@ the negative distance between two points). When distances are very large, this | **name** | **type** | **description** | |----------|----------|-----------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | | `distance` | [`arma::mat`](../matrices.md) | Output matrix to store transformation matrix representing learned distance. | | `optimizer` | [any ensmallen optimizer](https://www.ensmallen.org) | Instantiated ensmallen optimizer for [differentiable functions](https://www.ensmallen.org/docs.html#differentiable-functions) or [differentiable separable functions](https://www.ensmallen.org/docs.html#differentiable-separable-functions). | `ens::StandardSGD()` | | `callbacks...` | [any set of ensmallen callbacks](https://www.ensmallen.org/docs.html#callback-documentation) | Optional callbacks for the ensmallen optimizer, such as e.g. `ens::ProgressBar()`, `ens::Report()`, or others. | _(N/A)_ | diff --git a/doc/user/methods/perceptron.md b/doc/user/methods/perceptron.md index d64fa0c476..019ce7d39e 100644 --- a/doc/user/methods/perceptron.md +++ b/doc/user/methods/perceptron.md @@ -90,7 +90,7 @@ section below. |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | | `datasetInfo` | [`data::DatasetInfo`](../load_save.md#mixed-categorical-data) | Dataset information, specifying type information for each dimension. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, between [`0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, between [`0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `weights` | [`arma::rowvec`](../matrices.md) | Weights for each training point. Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `dimensionality` | `size_t` | Dimensionality of data (only used if an initialized but untrained model is desired). | _(N/A)_ | diff --git a/doc/user/methods/random_forest.md b/doc/user/methods/random_forest.md index fb9a8ba639..fc272ed387 100644 --- a/doc/user/methods/random_forest.md +++ b/doc/user/methods/random_forest.md @@ -88,7 +88,7 @@ std::cout << arma::accu(predictions == 3) << " test points classified as class " |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | | `info` | [`data::DatasetInfo`](../load_save.md#loading-categorical-data) | Dataset information, specifying type information for each dimension. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `weights` | [`arma::rowvec`](../matrices.md) | Instance weights for each training point. Should have length `data.n_cols`. | _(N/A)_ | | `numTrees` | `size_t` | Number of trees to train in the random forest. | `20` diff --git a/doc/user/methods/softmax_regression.md b/doc/user/methods/softmax_regression.md index 539f7cd308..1826d03a36 100644 --- a/doc/user/methods/softmax_regression.md +++ b/doc/user/methods/softmax_regression.md @@ -79,7 +79,7 @@ std::cout << arma::accu(predictions == 2) << " test points classified as class " | **name** | **type** | **description** | **default** | |----------|----------|-----------------|-------------| | `data` | [`arma::mat`](../matrices.md) | [Column-major](../matrices.md#representing-data-in-mlpack) training matrix. | _(N/A)_ | -| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | +| `labels` | [`arma::Row`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../core/normalizing_labels.md) (inclusive). Should have length `data.n_cols`. | _(N/A)_ | | `numClasses` | `size_t` | Number of classes in the dataset. | _(N/A)_ | | `lambda` | `double` | L2 regularization penalty parameter. Must be nonnegative. | `0.0001` | | `fitIntercept` | `bool` | If true, an intercept term is fit to the model. | `true` |