apaam/mlpack
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix links in documentation.

Browse Source
This commit is contained in:
Ryan Curtin
2024-09-25 22:39:05 -04:00
parent 69fc1416f7
commit defe9df2a4
14 changed files with 117 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/index.md
+3 -3
View File
@@ -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
doc/user/core.md
-2
View File
@@ -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
doc/user/load_save.md
+103 -13
View File
@@ -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`
<!-- TODO: also document in core.md? -->
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<double>(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.
doc/user/methods/adaboost.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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` |
doc/user/methods/decision_tree.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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` |
doc/user/methods/hoeffding_tree.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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` |
doc/user/methods/linear_svm.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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()` |
doc/user/methods/lmnn.md
+1 -1
View File
@@ -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<size_t>`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. |
| `labels` | [`arma::Row<size_t>`](../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)_ |
doc/user/methods/logistic_regression.md
+1 -1
View File
@@ -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<size_t>`](../matrices.md) | Training labels, either [`0` or `1`](../load_save.md#normalizing-labels). Should have length `data.n_cols`. | _(N/A)_ |
| `labels` | [`arma::Row<size_t>`](../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` |
doc/user/methods/naive_bayes_classifier.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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 |
doc/user/methods/nca.md
+1 -1
View File
@@ -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<size_t>`](../matrices.md) | Training labels, [between `0` and `numClasses - 1`](../load_save.md#normalizing-labels) (inclusive). Should have length `data.n_cols`. |
| `labels` | [`arma::Row<size_t>`](../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)_ |
doc/user/methods/perceptron.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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)_ |
doc/user/methods/random_forest.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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`
doc/user/methods/softmax_regression.md
+1 -1
View File
@@ -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<size_t>`](../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<size_t>`](../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` |