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

Merge remote-tracking branch 'mlpack/master' into R-bindings

Browse Source
This commit is contained in:
Yashwant
2020-08-20 11:04:12 +05:30
parent 09b78bd74a e5d138a3b6
commit eaccc4e9d3
100 changed files with 2172 additions and 1334 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HISTORY.md
+5
View File
@@ -11,6 +11,9 @@
* Added macro for changing stream of printing and warnings/errors (#2556).
* Refactor `ProgramInfo()` to separate out all the different
information (#2558).
* Added Soft Actor-Critic to RL methods (#2487).
* Added Categorical DQN to q_networks (#2454).
@@ -31,6 +34,8 @@
version of linear regression where the regularization parameter is
automatically tuned (#2030).
* Fix incremental training of logistic regression models (#2560).
### mlpack 3.3.2
###### 2020-06-18
* Added Noisy DQN to q_networks (#2446).
doc/guide/bindings.hpp
+197 -54
View File
@@ -19,7 +19,7 @@ The document is split into several sections:
- @ref bindings_intro
- @ref bindings_code
- @ref bindings_general
- @ref bindings_general_program_info
- @ref bindings_general_program_doc
- @ref bindings_general_define_params
- @ref bindings_general_functions
- @ref bindings_general_more
@@ -128,12 +128,18 @@ using namespace std;
// being used. Note that the macros must have + on either side of them. We
// provide some extra references with the "SEE_ALSO()" macro, which is used to
// generate documentation for the website.
PROGRAM_INFO("Mean Shift Clustering",
// Short description.
// Program Name.
BINDING_NAME("Mean Shift Clustering");
// Short description.
BINDING_SHORT_DESC(
"A fast implementation of mean-shift clustering using dual-tree range "
"search. Given a dataset, this uses the mean shift algorithm to produce "
"and return a clustering of the data.",
// Long description.
"and return a clustering of the data.");
// Long description.
BINDING_LONG_DESC(
"This program performs mean shift clustering on the given dataset, storing "
"the learned cluster assignments either as a column of labels in the input "
"dataset or separately."
@@ -147,21 +153,26 @@ PROGRAM_INFO("Mean Shift Clustering",
"\n\n"
"The output labels may be saved with the " + PRINT_PARAM_STRING("output") +
" output parameter and the centroids of each cluster may be saved with the"
" " + PRINT_PARAM_STRING("centroid") + " output parameter.",
" " + PRINT_PARAM_STRING("centroid") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to run mean shift clustering on the dataset " +
PRINT_DATASET("data") + " and store the centroids to " +
PRINT_DATASET("centroids") + ", the following command may be used: "
"\n\n" +
PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"),
SEE_ALSO("@kmeans", "#kmeans"),
SEE_ALSO("@dbscan", "#dbscan"),
SEE_ALSO("Mean shift on Wikipedia",
"https://en.wikipedia.org/wiki/Mean_shift"),
SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)",
PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"));
// See also...
BINDING_SEE_ALSO("@kmeans", "#kmeans");
BINDING_SEE_ALSO("@dbscan", "#dbscan");
BINDING_SEE_ALSO("Mean shift on Wikipedia",
"https://en.wikipedia.org/wiki/Mean_shift");
BINDING_SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)",
"http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.510.1222"
"&rep=rep1&type=pdf"),
SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation",
"@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html"));
"&rep=rep1&type=pdf");
BINDING_SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation",
"@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html");
// Define parameters for the executable.
@@ -227,9 +238,10 @@ void mlpackMain()
@endcode
We can see that we have defined the basic program information in the
@c PROGRAM_INFO() macro. This is, for instance, what is displayed to describe
the binding if the user passed the <tt>\--help</tt> option for a
command-line program.
@c BINDING_NAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(),
@c BINDING_EXAMPLE() and @c BINDING_SEE_ALSO() macros. This is, for instance,
what is displayed to describe the binding if the user passed the
<tt>\--help</tt> option for a command-line program.
Then, we define five parameters, three input and two output, that define the
data and options that the mean shift clustering will function on. These
@@ -246,10 +258,12 @@ whether the parameter is input or output. Some examples:
Note that each of these macros may have slightly different syntax. See the
links above for further documentation.
In order to write a new binding, then, you simply must write a @c PROGRAM_INFO()
definition of the program with some docuentation, define the input and output
parameters as @c PARAM macros, and then write an @c mlpackMain() function that
actually performs the functionality of the binding. Inside of @c mlpackMain():
In order to write a new binding, then, you simply must write @c BINDING_NAME(),
@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), @c BINDING_EXAMPLE() and
@c BINDING_SEE_ALSO() definitions of the program with some docuentation, define
the input and output parameters as @c PARAM macros, and then write an
@c mlpackMain() function that actually performs the functionality of the binding.
Inside of @c mlpackMain():
- All input parameters are accessible through @c IO::GetParam<type>("name").
- All output parameters should be set by the end of the function with the
@@ -277,15 +291,27 @@ relatively clear how one could use the @c IO functionality along with CMake to
add a binding for a new mlpack machine learning method. If it is not clear,
then the examples in the following sections should clarify.
@subsection bindings_general_program_info Documenting a program with PROGRAM_INFO()
@subsection bindings_general_program_doc Documenting a program with
@c BINDING_NAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(),
@c BINDING_EXAMPLE() and @c BINDING_SEE_ALSO().
Any mlpack program should be documented with the @c PROGRAM_INFO() macro, which
is available from the @c <mlpack/core/util/mlpack_main.hpp> header. The macro
is of the form
Any mlpack program should be documented with the @c BINDING_NAME(),
@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC() , @c BINDING_EXAMPLE() and
@c BINDING_SEE_ALSO() macros, which is available from the
@c <mlpack/core/util/mlpack_main.hpp> header. The macros
are of the form
@code
PROGRAM_INFO("program name", "short documentation", "long documentation",
"examples", SEE_ALSO("link", "description"), ...)
BINDING_NAME("program name");
BINDING_SHORT_DESC("This is a short, two-sentence description of what the program does.");
BINDING_LONG_DESC("This is a long description of what the program does."
" It might be many lines long and have lots of details about different options.");
BINDING_EXAMPLE("This contains one example for this particular binding.\n" +
PROGRAM_CALL(...));
BINDING_EXAMPLE("This contains another example for this particular binding.\n" +
PROGRAM_CALL(...));
// There could be many of these "see alsos".
BINDING_SEE_ALSO("https://en.wikipedia.org/wiki/Machine_learning");
@endcode
The short documentation should be two sentences indicating what the program
@@ -367,6 +393,14 @@ Command-line program output (snippet):
Python binding output (snippet):
The parameter 'shuffle', if set, will shuffle the data before learning.
Julia binding output (snippet):
The parameter `shuffle`, if set, will shuffle the data before learning.
Go binding output (snippet):
The parameter "Shuffle", if set, will shuffle the data before learning.
@endcode
@code
@@ -382,6 +416,14 @@ Command-line program output (snippet):
Python binding output (snippet):
The output matrix can be saved with the 'output' output parameter.
Julia binding output (snippet):
The output matrix can be saved with the `output` output parameter.
Go binding output (snippet):
The output matrix can be saved with the "output" output parameter.
@endcode
@code
@@ -407,12 +449,38 @@ Python binding output (snippet):
>>> output = program(input=x)
>>> model = output['output_model']
Julia binding output (snippet):
For example, to train a model on the dataset `x` and save the output model to
`model`, the following command can be used:
julia> model = program(input=x)
Go binding output (snippet):
For example, to train a model on the dataset "x" and save the output model to
"model", the following command can be used:
// Initialize optional parameters for Program().
param := mlpack.ProgramOptions()
param.Input = x
model := mlpack.Program(param)
@endcode
@code
Input C++ (full program, 'random_numbers_main.cpp'):
PROGRAM_INFO("Random Numbers", "This program generates random numbers with a "
// Program Name.
BINDING_NAME("Random Numbers");
// Short description.
BINDING_SHORT_DESC("An implementation of Random Numbers");
// Long description.
BINDING_LONG_DESC(
"This program generates random numbers with a "
"variety of nonsensical techniques and example parameters. The input "
"dataset, which will be ignored, can be specified with the " +
PRINT_PARAM_STRING("input") + " parameter. If you would like to subtract"
@@ -424,7 +492,10 @@ Input C++ (full program, 'random_numbers_main.cpp'):
"The output random numbers can be saved with the " +
PRINT_PARAM_STRING("output") + " output parameter. In addition, a "
"randomly generated linear regression model can be saved with the " +
PRINT_PARAM_STRING("output_model") + " output parameter.",
PRINT_PARAM_STRING("output_model") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to generate 100 random numbers with 3 subtracted from them "
"and save the output to " + PRINT_DATASET("rand") + " and the random "
"model to " + PRINT_MODEL("rand_lr") + ", use the following "
@@ -477,17 +548,66 @@ Python binding output:
>>> output = random_numbers(num_values=100, subtract=3)
>>> rand = output['output']
>>> rand_lr = output['output_model']
Julia binding output:
Random Numbers
This program generates random numbers with a variety of nonsensical
techniques and example parameters. The input dataset, which will be
ignored, can be specified with the `input` parameter. If you would like to
subtract values from each number, specify the `subtract` parameter. The
number of random numbers to generate is specified with the `num_values`
parameter.
The output random numbers can be saved with the `output` output parameter.
In addition, a randomly generated linear regression model can be saved with
the `output_model` output parameter.
For example, to generate 100 random numbers with 3 subtracted from them and
save the output to `rand` and the random model to `rand_lr`, use the
following command:
```julia
julia> rand, rand_lr = random_numbers(num_values=100, subtract=3)
```
Go binding output:
Random Numbers
This program generates random numbers with a variety of nonsensical
techniques and example parameters. The input dataset, which will be
ignored, can be specified with the "Input" parameter. If you would like to
subtract values from each number, specify the "Subtract" parameter. The
number of random numbers to generate is specified with the "NumValues"
parameter.
The output random numbers can be saved with the "output" output parameter.
In addition, a randomly generated linear regression model can be saved with
the "outputModel" output parameter.
For example, to generate 100 random numbers with 3 subtracted from them and
save the output to "rand" and the random model to "randLr", use the
following command:
// Initialize optional parameters for RandomNumbers().
param := mlpack.RandomNumbersOptions()
param.NumValues = 100
param.Subtract=3
rand, randLr := mlpack.RandomNumbers(param)
@endcode
@subsection bindings_general_define_params Defining parameters for a program
There exist several macros that can be used after a @c PROGRAM_INFO() definition
to define the parameters that can be specified for a given mlpack program.
These macros all have the same general definition: the name of the macro
specifies the type of the parameter, whether or not the parameter is required,
and whether the parameter is an input or output parameter. Then as arguments to
the macro, the name, description, and sometimes the single-character alias and
the default value of the parameter.
There exist several macros that can be used after a @c BINDING_LONG_DESC() and
@c BINDING_EXAMPLE() definition to define the parameters that can be specified
for a given mlpack program. These macros all have the same general definition:
the name of the macro specifies the type of the parameter, whether or not the
parameter is required, and whether the parameter is an input or output parameter.
Then as arguments to the macros, the name, description, and sometimes the
single-character alias and the default value of the parameter.
To give a flavor of how these definitions look, the definition
@@ -618,10 +738,10 @@ Python interface to the user.
mlpack's @c IO module provides a unified abstract interface for getting input
from and providing output to users without needing to consider the language
(command-line, Python, MATLAB, etc.) that the user is running the program from.
This means that after the @c PROGRAM_INFO() macro and the @c PARAM_*() macros
have been defined, a language-agnostic @c mlpackMain() function can be written.
This function then can perform the actual computation that the entire program is
meant to.
This means that after the @c BINDING_LONG_DESC() and @c BINDING_EXAMPLE() macros
and the @c PARAM_*() macros have been defined, a language-agnostic
@c mlpackMain() function can be written. This function then can perform the
actual computation that the entire program is meant to.
Inside of an @c mlpackMain() function, the @c mlpack::IO module can be used to
access input parameters and set output parameters. There are two main functions
@@ -701,7 +821,8 @@ could be created for the "random_numbers" program from earlier sections.
@code
#include <mlpack/core/util/mlpack_main.hpp>
// The PROGRAM_INFO() and PARAM_*() definitions should go here:
// BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(),
// BINDING_SEE_ALSO() and PARAM_*() definitions should go here:
// ...
using namespace mlpack;
@@ -757,23 +878,43 @@ This section describes the internal functionality of the IO module and the
associated macros. If you are only interested in writing mlpack programs, this
section is probably not worth reading.
There are four main components involved with mlpack bindings:
There are eight main components involved with mlpack bindings:
- the IO module, a singleton class that stores parameter information
- the mlpackMain() function that defines the functionality of the binding
- the PROGRAM_INFO() macro that defines the binding name and documentation
- the BINDING_NAME() macro that defines the binding name
- the BINDING_SHORT_DESC() macro that defines the short description
- the BINDING_LONG_DESC() macro that defines the long description
- (optional) the BINDING_EXAMPLE() macro that defines example usages
- (optional) the BINDING_SEE_ALSO() macro that defines "see also" links
- the PARAM_*() macros that define parameters for the binding
The mlpack::IO module is a singleton class that stores, at runtime, the binding
name, the documentation, and the parameter information and values. In order to
do this, each parameter and the program documentation must make themselves known
to the IO singleton. This is accomplished by having the @c PROGRAM_INFO() and
@c PARAM_*() macros declare global variables that, in their constructors,
register themselves with the IO singleton.
to the IO singleton. This is accomplished by having the @c BINDING_NAME(),
@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), @c BINDING_EXAMPLE(),
@c BINDING_SEE_ALSO() and @c PARAM_*() macros declare global variables that,
in their constructors, register themselves with the IO singleton.
The @c PROGRAM_INFO() macro declares an object of type mlpack::util::ProgramDoc.
The @c ProgramDoc class constructor calls IO::RegisterProgramDoc() in order to
register the given program name and documentation.
The @c BINDING_NAME() macro declares an object of type mlpack::util::ProgramName.
The @c BINDING_SHORT_DESC() macro declares an object of type
mlpack::util::ShortDescription.
The @c BINDING_LONG_DESC() macro declares an object of type
mlpack::util::LongDescription.
The @c BINDING_EXAMPLE() macro declares an object of type mlpack::util::Example.
The @c BINDING_SEE_ALSO() macro declares an object of type
mlpack::util::SeeAlso.
The @c ProgramName class constructor calls IO::RegisterProgramName() in order to
register the given program name.
The @c ShortDescription class constructor calls IO::RegisterShortDescription() in order to
register the given short description.
The @c LongDescription class constructor calls IO::RegisterLongDescription() in order to
register the given long description.
The @c Example class constructor calls IO::RegisterExample() in order to
register the given example.
The @c SeeAlso class constructor calls IO::RegisterSeeAlso() in order to
register the given see-also link.
The @c PARAM_*() macros declare an object that will, in its constructor, call
IO::Add() to register that parameter with the IO singleton. The specific type
@@ -873,7 +1014,8 @@ binding:
- The options defined by @c PARAM_*() macros are of type
mlpack::bindings::cli::CLIOption.
- The parameter and value printing macros for @c PROGRAM_INFO() are set:
- The parameter and value printing macros for @c BINDING_LONG_DESC()
and BINDING_EXAMPLE() are set:
* The @c PRINT_PARAM_STRING() macro is defined as
mlpack::bindings::cli::ParamString().
* The @c PRINT_DATASET() macro is defined as
@@ -1045,9 +1187,10 @@ individually if you like). The file
the name of the program and the @c *_main.cpp file to include correctly, then
the @c mlpack::bindings::python::PrintPYX() function is called by the program.
The @c PrintPYX() function uses the parameters that have been set in the IO
singleton by the @c PROGRAM_INFO() and @c PARAM_*() macros in order to actually
print a fully-working .pyx file that can be compiled. The file has several
sections:
singleton by the @c BINDING_NAME(), @c BINDING_SHORT_DESC(),
@c BINDING_LONG_DESC(), @c BINDING_EXAMPLE(), @c BINDING_SEE_ALSO() and
@c PARAM_*() macros in order to actually print a fully-working .pyx file that
can be compiled. The file has several sections:
- Python imports (numpy/pandas/cython/etc.)
- Cython imports of C++ utility functions and Armadillo functionality
doc/guide/iodoc.hpp
+17 -11
View File
@@ -120,7 +120,8 @@ and debugging output for your mlpack program.
@section simpleio Simple IO Example
Through the mlpack::IO object, command-line parameters can be easily added
with the PROGRAM_INFO, PARAM_INT, PARAM_DOUBLE, PARAM_STRING, and PARAM_FLAG
with the BINDING_NAME, BINDING_SHORT_DESC, BINDING_LONG_DESC, BINDING_EXAMPLE,
BINDING_SEE_ALSO, PARAM_INT, PARAM_DOUBLE, PARAM_STRING, and PARAM_FLAG
macros.
Here is a sample use of those macros, extracted from methods/pca/pca_main.cpp.
@@ -131,23 +132,28 @@ Here is a sample use of those macros, extracted from methods/pca/pca_main.cpp.
#include <mlpack/core/util/io.hpp>
#include <mlpack/core/util/mlpack_main.hpp>
// Document program.
PROGRAM_INFO("Principal Components Analysis",
// Short description.
// Program Name.
BINDING_NAME("Principal Components Analysis");
// Short description.
BINDING_SHORT_DESC(
"An implementation of several strategies for principal components analysis "
"(PCA), a common preprocessing step. Given a dataset and a desired new "
"dimensionality, this can reduce the dimensionality of the data using the "
"linear transformation determined by PCA.",
// Long description.
"linear transformation determined by PCA.");
// Long description.
BINDING_LONG_DESC(
"This program performs principal components analysis on the given dataset "
"using the exact, randomized, randomized block Krylov, or QUIC SVD method. "
"It will transform the data onto its principal components, optionally "
"performing dimensionality reduction by ignoring the principal components "
"with the smallest eigenvalues."
// "See also" section for generated documentation.
SEE_ALSO("Principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Principal_component_analysis"),
SEE_ALSO("mlpack::pca::PCA C++ class documentation",
"with the smallest eigenvalues.");
// See also...
BINDING_SEE_ALSO("Principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Principal_component_analysis");
BINDING_SEE_ALSO("mlpack::pca::PCA C++ class documentation",
"@doxygen/classmlpack_1_1pca_1_1PCA.html"));
// Parameters for program.
src/mlpack/bindings/cli/cli_option.hpp
+1 -30
View File
@@ -3,7 +3,7 @@
* @author Matthew Amidon
*
* Definition of the Option class, which is used to define parameters which are
* used by CLI. The ProgramDoc class also resides here.
* used by CLI.
*
* 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
@@ -164,35 +164,6 @@ class CLIOption
}
};
/**
* A static object whose constructor registers program documentation with the
* CLI class. This should not be used outside of CLI itself, and you should use
* the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc
* object should ever exist.
*
* @see core/util/io.hpp, mlpack::IO
*/
class ProgramDoc
{
public:
/**
* Construct a ProgramDoc object. When constructed, it will register itself
* with IO.
*
* @param programName Short string representing the name of the program.
* @param documentation Long string containing documentation on how to use the
* program and what it is. No newline characters are necessary; this is
* taken care of by IO later.
*/
ProgramDoc(const std::string& programName,
const std::string& documentation);
//! The name of the program.
std::string programName;
//! Documentation for what the program does.
std::string documentation;
};
} // namespace cli
} // namespace bindings
} // namespace mlpack
src/mlpack/bindings/cli/print_doc_functions.hpp
+3 -2
View File
@@ -102,8 +102,9 @@ inline std::string ProgramCall(const std::string& programName);
/**
* Print what a user would type to invoke the given option name. Note that the
* name *must* exist in the CLI module. (Note that because of the way
* ProgramInfo is structured, this doesn't mean that all of the PARAM_*()
* declarataions need to come before the PROGRAM_INFO() declaration.)
* BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean
* that all of the PARAM_*() declarataions need to come before
* BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.)
*/
inline std::string ParamString(const std::string& paramName);
src/mlpack/bindings/cli/print_doc_functions_impl.hpp
+6 -5
View File
@@ -138,8 +138,8 @@ std::string ProcessOptions(const std::string& paramName,
else
{
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
std::string rest = ProcessOptions(args...);
@@ -229,8 +229,9 @@ inline std::string ProgramCall(const std::string& programName)
/**
* Print what a user would type to invoke the given option name. Note that the
* name *must* exist in the CLI module. (Note that because of the way
* ProgramInfo is structured, this doesn't mean that all of the PARAM_*()
* declarataions need to come before the PROGRAM_INFO() declaration.)
* BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean
* that all of the PARAM_*() declarataions need to come before
* BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.)
*/
inline std::string ParamString(const std::string& paramName)
{
@@ -252,7 +253,7 @@ inline std::string ParamString(const std::string& paramName)
else
{
throw std::runtime_error("Parameter '" + paramName + "' not known! Check "
"PROGRAM_INFO() definition.");
"BINDING_LONG_DESC() and BINDING_EXAMPLE() definition.");
}
}
src/mlpack/bindings/cli/print_help.cpp
+10 -6
View File
@@ -25,8 +25,7 @@ void PrintHelp(const std::string& param)
std::string usedParam = param;
std::map<std::string, util::ParamData>& parameters = IO::Parameters();
const std::map<char, std::string>& aliases = IO::Aliases();
util::ProgramDoc& docs = *IO::GetSingleton().doc;
util::BindingDetails& bindingDetails = IO::GetSingleton().doc;
// If we pass a single param, alias it if necessary.
if (usedParam.length() == 1 && aliases.count(usedParam[0]))
usedParam = aliases.at(usedParam[0]);
@@ -64,11 +63,16 @@ void PrintHelp(const std::string& param)
}
// Print out the descriptions.
if (docs.programName != "")
if (bindingDetails.programName != "")
{
std::cout << docs.programName << std::endl << std::endl;
std::cout << " " << util::HyphenateString(docs.documentation(), 2)
<< std::endl << std::endl;
std::cout << bindingDetails.programName << std::endl << std::endl;
std::cout << " " << util::HyphenateString(bindingDetails.longDescription(),
2) << std::endl << std::endl;
for (size_t j = 0; j < bindingDetails.example.size(); ++j)
{
std::cout << " " << util::HyphenateString(bindingDetails.example[j](), 2)
<< std::endl << std::endl;
}
}
else
std::cout << "[undocumented program]" << std::endl << std::endl;
src/mlpack/bindings/go/generate_go.cpp.in
+1 -1
View File
@@ -45,5 +45,5 @@ int main(int /* argc */, char** /* argv */)
// programName is defined in mlpack_main.hpp.
IO::RestoreSettings(programName);
PrintGo(*IO::GetSingleton().doc, "${PROGRAM_NAME}");
PrintGo(IO::GetSingleton().doc, "${PROGRAM_NAME}");
}
src/mlpack/bindings/go/print_doc_functions_impl.hpp
+6 -6
View File
@@ -154,8 +154,8 @@ std::string PrintOptionalInputs(const std::string& paramName,
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
// Continue recursion.
@@ -211,8 +211,8 @@ std::string PrintInputOptions(const std::string& paramName,
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
// Continue recursion.
@@ -256,8 +256,8 @@ void GetOptions(
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
}
src/mlpack/bindings/go/print_go.cpp
+14 -8
View File
@@ -27,14 +27,14 @@ namespace go {
* Given a list of parameter definition and program documentation, print a
* generated .go file to stdout.
*
* @param programInfo Documentation for the program.
* @param doc Documentation for the program.
* @param functionName Name of the function (i.e. "pca").
*/
void PrintGo(const util::ProgramDoc& programInfo,
const std::string& functionName)
void PrintGo(const util::BindingDetails& doc,
const std::string& functionName)
{
// Restore parameters.
IO::RestoreSettings(programInfo.programName);
IO::RestoreSettings(doc.programName);
std::map<std::string, util::ParamData>& parameters = IO::Parameters();
typedef std::map<std::string, util::ParamData>::iterator ParamIter;
@@ -124,8 +124,15 @@ void PrintGo(const util::ProgramDoc& programInfo,
// Print the comment describing the function and its parameters.
cout << "/*" << endl;
cout << " " << HyphenateString(programInfo.documentation(), 2) << endl;
cout << endl << endl;
cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl;
// Print the examples.
for (size_t j = 0; j < doc.example.size(); ++j)
{
cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl;
}
// Next, print information on the input options.
cout << " Input parameters:" << endl;
cout << endl;
for (size_t i = 0; i < inputOptions.size(); ++i)
@@ -216,8 +223,7 @@ void PrintGo(const util::ProgramDoc& programInfo,
cout << " " << "disableVerbose()" << endl;
// Restore the parameters.
cout << " " << "restoreSettings(\"" << programInfo.programName
<< "\")" << endl;
cout << " " << "restoreSettings(\"" << doc.programName << "\")" << endl;
cout << endl;
// Do any input processing.
src/mlpack/bindings/go/print_go.hpp
+2 -3
View File
@@ -22,11 +22,10 @@ namespace go {
/**
* Given a list of parameter definition and program documentation, print a
* generated .go file to stdout.
*
* @param programInfo Documentation for the program.
* @param doc Documentation for the program.
* @param functionName Name of the function (i.e. "pca").
*/
void PrintGo(const util::ProgramDoc& programInfo,
void PrintGo(const util::BindingDetails& doc,
const std::string& functionName);
src/mlpack/bindings/go/tests/test_go_binding_main.cpp
+10 -3
View File
@@ -18,9 +18,16 @@ using namespace std;
using namespace mlpack;
using namespace mlpack::kernel;
PROGRAM_INFO("Golang binding test",
"A simple program to test Golang binding functionality.",
"A simple program to test Golang binding functionality. You can build "
// Program Name.
BINDING_NAME("Golang binding test");
// Short description.
BINDING_SHORT_DESC(
"A simple program to test Go binding functionality.");
// Long description.
BINDING_LONG_DESC(
"A simple program to test Go binding functionality. You can build "
"mlpack with the BUILD_TESTS option set to off, and this binding will "
"no longer be built.", "");
src/mlpack/bindings/julia/generate_jl.cpp.in
+1 -1
View File
@@ -35,5 +35,5 @@ int main(int /* argc */, char** /* argv */)
// programName is defined in mlpack_main.hpp.
IO::RestoreSettings(programName);
PrintJL(*IO::GetSingleton().doc, "${NAME}", "${MLPACK_JL_LIB_SUFFIX}");
PrintJL(IO::GetSingleton().doc, "${NAME}", "${MLPACK_JL_LIB_SUFFIX}");
}
src/mlpack/bindings/julia/print_doc_functions_impl.hpp
+4 -4
View File
@@ -144,8 +144,8 @@ inline std::string CreateInputArguments(const std::string& paramName,
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
}
@@ -223,8 +223,8 @@ inline void GetOptions(
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
}
src/mlpack/bindings/julia/print_jl.cpp
+10 -5
View File
@@ -14,7 +14,7 @@
#include <set>
using namespace mlpack;
using namespace mlpack::util;
using namespace std;
namespace mlpack {
@@ -26,12 +26,12 @@ extern std::string programName;
/**
* Print the code for a .jl binding for an mlpack program to stdout.
*/
void PrintJL(const util::ProgramDoc& programInfo,
void PrintJL(const util::BindingDetails& doc,
const string& functionName,
const std::string& mlpackJuliaLibSuffix)
{
// Restore parameters.
IO::RestoreSettings(programInfo.programName);
IO::RestoreSettings(doc.programName);
map<string, util::ParamData>& parameters = IO::Parameters();
typedef map<string, util::ParamData>::iterator ParamIter;
@@ -167,10 +167,15 @@ void PrintJL(const util::ProgramDoc& programInfo,
cout << endl;
// Next print the description.
cout << util::HyphenateString(programInfo.documentation(), 0) << endl;
cout << HyphenateString(doc.longDescription(), 0) << endl << endl;
// Next print the examples.
for (size_t j = 0; j < doc.example.size(); ++j)
{
cout << util::HyphenateString(doc.example[j](), 0) << endl << endl;
}
// Next, print information on the input options.
cout << endl;
cout << "# Arguments" << endl;
cout << endl;
src/mlpack/bindings/julia/print_jl.hpp
+1 -1
View File
@@ -21,7 +21,7 @@ namespace julia {
/**
* Print the code for a .jl binding for an mlpack program to stdout.
*/
void PrintJL(const util::ProgramDoc& programInfo,
void PrintJL(const util::BindingDetails& doc,
const std::string& functionName,
const std::string& mlpackJuliaLibSuffix);
src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp
+9 -2
View File
@@ -18,8 +18,15 @@ using namespace std;
using namespace mlpack;
using namespace mlpack::kernel;
PROGRAM_INFO("Julia binding test",
"A simple program to test Julia binding functionality.",
// Program Name.
BINDING_NAME("Julia binding test");
// Short description.
BINDING_SHORT_DESC(
"A simple program to test Julia binding functionality.");
// Long description.
BINDING_LONG_DESC(
"A simple program to test Julia binding functionality. You can build "
"mlpack with the BUILD_TESTS option set to off, and this binding will "
"no longer be built.", "");
src/mlpack/bindings/markdown/binding_info.cpp
+2 -9
View File
@@ -17,7 +17,8 @@ namespace mlpack {
namespace bindings {
namespace markdown {
util::ProgramDoc& BindingInfo::GetProgramDoc(const std::string& bindingName)
util::BindingDetails& BindingInfo::GetBindingDetails(
const std::string& bindingName)
{
if (GetSingleton().map.count(bindingName) == 0)
{
@@ -28,14 +29,6 @@ util::ProgramDoc& BindingInfo::GetProgramDoc(const std::string& bindingName)
return GetSingleton().map.at(bindingName);
}
//! Register a ProgramDoc object with the given bindingName.
void BindingInfo::RegisterProgramDoc(const std::string& bindingName,
const util::ProgramDoc& programDoc)
{
GetSingleton().map[bindingName] = programDoc;
}
//! Get or modify the current language (don't set it to something invalid!).
std::string& BindingInfo::Language()
{
src/mlpack/bindings/markdown/binding_info.hpp
+12 -15
View File
@@ -4,7 +4,7 @@
*
* This file defines the BindingInfo singleton class that is used specifically
* for the Markdown bindings to map from a binding name (i.e. "knn") to
* multiple ProgramDoc objects, which are then used to generate the
* multiple documentation objects, which are then used to generate the
* documentation.
*
* mlpack is free software; you may redistribute it and/or modify it under the
@@ -16,7 +16,7 @@
#define MLPACK_BINDINGS_MARKDOWN_BINDING_NAME_HPP
#include <mlpack/prereqs.hpp>
#include <mlpack/core/util/program_doc.hpp>
#include <mlpack/core/util/binding_details.hpp>
namespace mlpack {
namespace bindings {
@@ -24,31 +24,28 @@ namespace markdown {
/**
* The BindingInfo class is used by the Markdown documentation generator to
* store multiple ProgramDoc objects, indexed by both the binding name (i.e.
* store multiple documentation objects, indexed by both the binding name (i.e.
* "knn") and the language (i.e. "cli").
*/
class BindingInfo
{
public:
//! Return a ProgramDoc object for a given bindingName.
static util::ProgramDoc& GetProgramDoc(const std::string& bindingName);
//! Register a ProgramDoc object with the given bindingName.
static void RegisterProgramDoc(const std::string& bindingName,
const util::ProgramDoc& programDoc);
//! Return a BindingDetails object for a given bindingName.
static util::BindingDetails& GetBindingDetails(
const std::string& bindingName);
//! Get or modify the current language (don't set it to something invalid!).
static std::string& Language();
private:
//! Private constructor, so that only one instance can be created.
BindingInfo() { }
//! Get the singleton.
static BindingInfo& GetSingleton();
//! Internally-held map for mapping a binding name to a ProgramDoc name.
std::unordered_map<std::string, util::ProgramDoc> map;
//! Internally-held map for mapping a binding name to a BindingDetails.
std::unordered_map<std::string, util::BindingDetails> map;
private:
//! Private constructor, so that only one instance can be created.
BindingInfo() { }
//! Holds the name of the language that we are currently printing. This is
//! modified before printing the documentation, and then used by
src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in
+1 -1
View File
@@ -12,7 +12,7 @@
* http://www.opensource.org/licenses/BSD-3-Clause for more information.
*/
#define BINDING_NAME "${BINDING}"
#define MARKDOWN_BINDING_NAME "${BINDING}"
#include <mlpack/core.hpp>
#include "generate_markdown.${BINDING}.hpp"
src/mlpack/bindings/markdown/print_doc_functions.hpp
+3 -2
View File
@@ -88,8 +88,9 @@ inline std::string ProgramCall(const std::string& programName);
/**
* Print what a user would type to invoke the given option name. Note that the
* name *must* exist in the IO module. (Note that because of the way
* ProgramInfo is structured, this doesn't mean that all of the PARAM_*()
* declarataions need to come before the PROGRAM_INFO() declaration.)
* BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean
* that all of the PARAM_*() declarataions need to come before
* BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.)
*/
inline std::string ParamString(const std::string& paramName);
src/mlpack/bindings/markdown/print_doc_functions_impl.hpp
+3 -2
View File
@@ -646,8 +646,9 @@ inline std::string ProgramCall(const std::string& programName)
/**
* Print what a user would type to invoke the given option name. Note that the
* name *must* exist in the CLI module. (Note that because of the way
* ProgramInfo is structured, this doesn't mean that all of the PARAM_*()
* declarataions need to come before the PROGRAM_INFO() declaration.)
* BINDING_LONG_DESC() and BINDING_EXAMPLE() is structured, this doesn't mean
* that all of the PARAM_*() declarataions need to come before
* BINDING_LONG_DESC() and BINDING_EXAMPLE() declaration.)
*/
inline std::string ParamString(const std::string& paramName)
{
src/mlpack/bindings/markdown/print_docs.cpp
+24 -17
View File
@@ -12,7 +12,7 @@
#include "print_docs.hpp"
#include <mlpack/core/util/io.hpp>
#include <mlpack/core/util/program_doc.hpp>
#include <mlpack/core/util/binding_details.hpp>
#include "binding_info.hpp"
#include "print_doc_functions.hpp"
@@ -45,7 +45,7 @@ void PrintHeaders(const std::string& bindingName,
void PrintDocs(const std::string& bindingName,
const vector<string>& languages)
{
ProgramDoc& programDoc = BindingInfo::GetProgramDoc(bindingName);
BindingDetails& doc = BindingInfo::GetBindingDetails(bindingName);
IO::RestoreSettings(bindingName);
@@ -64,7 +64,7 @@ void PrintDocs(const std::string& bindingName,
// Next, print the logical name of the binding (that's known by
// ProgramInfo).
cout << "#### " << programDoc.programName << endl;
cout << "#### " << doc.programName << endl;
cout << endl;
for (size_t i = 0; i < languages.size(); ++i)
@@ -78,7 +78,7 @@ void PrintDocs(const std::string& bindingName,
}
cout << endl;
cout << programDoc.shortDocumentation << " ";
cout << doc.shortDescription << " ";
for (size_t i = 0; i < languages.size(); ++i)
{
cout << "[Detailed documentation](#" << languages[i] << "_"
@@ -213,37 +213,44 @@ void PrintDocs(const std::string& bindingName,
cout << "{: #" << languages[i] << "_" << bindingName
<< "_detailed-documentation }" << endl;
cout << endl;
string doc = boost::replace_all_copy(programDoc.documentation(),
"|", "\\|");
cout << doc << endl;
cout << endl;
string desc = boost::replace_all_copy(doc.longDescription(),
"|", "\\|");
cout << desc << endl << endl;
if (doc.example.size() > 0)
cout << "### Example" << endl;
for (size_t j = 0; j < doc.example.size(); ++j)
{
string eg = boost::replace_all_copy(doc.example[j](),
"|", "\\|");
cout << eg << endl << endl;
}
cout << "### See also" << endl;
cout << endl;
for (size_t j = 0; j < programDoc.seeAlso.size(); ++j)
for (size_t j = 0; j < doc.seeAlso.size(); ++j)
{
cout << " - " << "[";
// We need special processing if the user has specified a binding name
// starting with @ (i.e., '@kfn' or similar).
if (programDoc.seeAlso[j].first[0] == '@')
cout << GetBindingName(programDoc.seeAlso[j].first.substr(1));
if (doc.seeAlso[j].first[0] == '@')
cout << GetBindingName(doc.seeAlso[j].first.substr(1));
else
cout << programDoc.seeAlso[j].first;
cout << doc.seeAlso[j].first;
cout << "](";
// We need special handling of Doxygen information.
if (programDoc.seeAlso[j].second.substr(0, 8) == "@doxygen")
if (doc.seeAlso[j].second.substr(0, 8) == "@doxygen")
{
cout << DOXYGEN_PREFIX << programDoc.seeAlso[j].second.substr(9);
cout << DOXYGEN_PREFIX << doc.seeAlso[j].second.substr(9);
}
else if (programDoc.seeAlso[j].second[0] == '#')
else if (doc.seeAlso[j].second[0] == '#')
{
cout << "#" << languages[i] << "_"
<< programDoc.seeAlso[j].second.substr(1);
<< doc.seeAlso[j].second.substr(1);
}
else
{
cout << programDoc.seeAlso[j].second;
cout << doc.seeAlso[j].second;
}
cout << ")" << endl;
src/mlpack/bindings/markdown/program_doc_wrapper.hpp
+65 -15
View File
@@ -2,8 +2,9 @@
* @file bindings/markdown/program_doc_wrapper.hpp
* @author Ryan Curtin
*
* A simple wrapper around ProgramDoc that also calls
* BindingInfo::RegisterProgramDoc() upon construction.
* A simple wrapper around programName, shortDescription, longDescription,
* example and seeAlso that also respectively register all the macros upon
* construction.
*
* 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
@@ -19,24 +20,73 @@ namespace mlpack {
namespace bindings {
namespace markdown {
class ProgramDocWrapper
class ProgramNameWrapper
{
public:
/**
* Construct a ProgramDoc object and register it with
* BindingInfo::RegisterProgramDoc().
* Register programName.
*/
ProgramDocWrapper(const std::string& bindingName,
const std::string& programName,
const std::string& shortDocumentation,
const std::function<std::string()>& documentation,
const std::function<std::string()>& example,
const std::vector<std::pair<std::string, std::string>>&
seeAlso)
ProgramNameWrapper(const std::string& bindingName,
const std::string& programName)
{
util::ProgramDoc pd(programName, shortDocumentation, documentation,
example, seeAlso);
BindingInfo::RegisterProgramDoc(bindingName, pd);
BindingInfo::GetSingleton().map[bindingName].programName =
std::move(programName);
}
};
class ShortDescriptionWrapper
{
public:
/**
* Register shortDescription.
*/
ShortDescriptionWrapper(const std::string& bindingName,
const std::string& shortDescription)
{
BindingInfo::GetSingleton().map[bindingName].shortDescription =
std::move(shortDescription);
}
};
class LongDescriptionWrapper
{
public:
/**
* Register longDescription.
*/
LongDescriptionWrapper(const std::string& bindingName,
const std::function<std::string()>& longDescription)
{
BindingInfo::GetSingleton().map[bindingName].longDescription =
std::move(longDescription);
}
};
class ExampleWrapper
{
public:
/**
* Register example.
*/
ExampleWrapper(const std::string& bindingName,
const std::function<std::string()>& example)
{
BindingInfo::GetSingleton().map[bindingName].example.push_back(
std::move(example));
}
};
class SeeAlsoWrapper
{
public:
/**
* Register seeAlso.
*/
SeeAlsoWrapper(const std::string& bindingName,
const std::string& description, const std::string& link)
{
BindingInfo::GetSingleton().map[bindingName].seeAlso.push_back(
std::move(std::make_pair(description, link)));
}
};
src/mlpack/bindings/python/generate_pyx.cpp.in
+1 -2
View File
@@ -45,6 +45,5 @@ int main(int /* argc */, char** /* argv */)
// programName is defined in mlpack_main.hpp.
IO::RestoreSettings(programName);
PrintPYX(*IO::GetSingleton().doc, "${PROGRAM_MAIN_FILE}",
"${PROGRAM_NAME}");
PrintPYX(IO::GetSingleton().doc, "${PROGRAM_MAIN_FILE}", "${PROGRAM_NAME}");
}
src/mlpack/bindings/python/print_doc_functions_impl.hpp
+4 -4
View File
@@ -133,8 +133,8 @@ std::string PrintInputOptions(const std::string& paramName,
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
// Continue recursion.
@@ -172,8 +172,8 @@ std::string PrintOutputOptions(const std::string& paramName,
{
// Unknown parameter!
throw std::runtime_error("Unknown parameter '" + paramName + "' " +
"encountered while assembling documentation! Check PROGRAM_INFO() " +
"declaration.");
"encountered while assembling documentation! Check BINDING_LONG_DESC()"
+ " and BINDING_EXAMPLE() declaration.");
}
// Continue recursion.
src/mlpack/bindings/python/print_pyx.cpp
+16 -8
View File
@@ -26,18 +26,17 @@ namespace python {
* Given a list of parameter definition and program documentation, print a
* generated .pyx file to stdout.
*
* @param parameters List of parameters the program will use (from IO).
* @param programInfo Documentation for the program.
* @param doc Documentation for the program.
* @param mainFilename Filename of the main program (i.e.
* "/path/to/pca_main.cpp").
* @param functionName Name of the function (i.e. "pca").
*/
void PrintPYX(const ProgramDoc& programInfo,
void PrintPYX(const util::BindingDetails& doc,
const string& mainFilename,
const string& functionName)
{
// Restore parameters.
IO::RestoreSettings(programInfo.programName);
IO::RestoreSettings(doc.programName);
std::map<std::string, util::ParamData>& parameters = IO::Parameters();
typedef std::map<std::string, util::ParamData>::iterator ParamIter;
@@ -143,10 +142,19 @@ void PrintPYX(const ProgramDoc& programInfo,
// Print the comment describing the function and its parameters.
cout << " \"\"\"" << endl;
cout << " " << programInfo.programName << endl;
cout << " " << doc.programName << endl;
cout << endl;
cout << " " << HyphenateString(programInfo.documentation(), 2) << endl;
cout << endl << endl;
// Print the description.
cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl;
// Next print the examples.
for (size_t j = 0; j < doc.example.size(); ++j)
{
cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl;
}
// Next, print information on the input options.
cout << " Input parameters:" << endl;
cout << endl;
for (size_t i = 0; i < inputOptions.size(); ++i)
@@ -184,7 +192,7 @@ void PrintPYX(const ProgramDoc& programInfo,
cout << " DisableVerbose()" << endl;
// Restore the parameters.
cout << " IO.RestoreSettings(\"" << programInfo.programName << "\")"
cout << " IO.RestoreSettings(\"" << doc.programName << "\")"
<< endl;
// Determine whether or not we need to copy parameters.
src/mlpack/bindings/python/print_pyx.hpp
+2 -2
View File
@@ -23,12 +23,12 @@ namespace python {
* Given a list of parameter definition and program documentation, print a
* generated .pyx file to stdout.
*
* @param programInfo Documentation for the program.
* @param doc Documentation for the program.
* @param mainFilename Filename of the main program (i.e.
* "/path/to/pca_main.cpp").
* @param functionName Name of the function (i.e. "pca").
*/
void PrintPYX(const util::ProgramDoc& programInfo,
void PrintPYX(const util::BindingDetails& doc,
const std::string& mainFilename,
const std::string& functionName);
src/mlpack/bindings/python/tests/test_python_binding_main.cpp
+9 -2
View File
@@ -18,8 +18,15 @@ using namespace std;
using namespace mlpack;
using namespace mlpack::kernel;
PROGRAM_INFO("Python binding test",
"A simple program to test Python binding functionality.",
// Program Name.
BINDING_NAME("Python binding test");
// Short description.
BINDING_SHORT_DESC(
"A simple program to test Python binding functionality.");
// Long description.
BINDING_LONG_DESC(
"A simple program to test Python binding functionality. You can build "
"mlpack with the BUILD_TESTS option set to off, and this binding will "
"no longer be built.", "");
src/mlpack/bindings/tests/test_option.hpp
-29
View File
@@ -108,35 +108,6 @@ class TestOption
}
};
/**
* A static object whose constructor registers program documentation with the
* IO class. This should not be used outside of IO itself, and you should use
* the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc
* object should ever exist.
*
* @see core/util/io.hpp, mlpack::IO
*/
class ProgramDoc
{
public:
/**
* Construct a ProgramDoc object. When constructed, it will register itself
* with IO.
*
* @param programName Short string representing the name of the program.
* @param documentation Long string containing documentation on how to use the
* program and what it is. No newline characters are necessary; this is
* taken care of by IO later.
*/
ProgramDoc(const std::string& programName,
const std::string& documentation);
//! The name of the program.
std::string programName;
//! Documentation for what the program does.
std::string documentation;
};
} // namespace tests
} // namespace bindings
} // namespace mlpack
src/mlpack/core/util/CMakeLists.txt
+1
View File
@@ -6,6 +6,7 @@ set(SOURCES
arma_config_check.hpp
backtrace.hpp
backtrace.cpp
binding_details.hpp
io.hpp
io.cpp
io_impl.hpp
src/mlpack/core/util/binding_details.hpp
+44
View File
@@ -0,0 +1,44 @@
/**
* @file core/util/binding_details.hpp
* @author Yashwant Singh Parihar
*
* This defines the structure that holds documentation details for bindings.
*
* 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_UTIL_BINDING_DETAILS_HPP
#define MLPACK_CORE_UTIL_BINDING_DETAILS_HPP
#include <mlpack/prereqs.hpp>
#include "program_doc.hpp"
namespace mlpack {
namespace util {
/**
* This structure holds all of the information about bindings documentation.
*/
struct BindingDetails
{
//! Name of the binding.
std::string programName;
//! A short two-sentence description of the binding, what it does, and what
//! it is useful for.
std::string shortDescription;
//! Long string containing documentation on what it is. No newline characters
//! are necessary; this is taken care of by IO later.
std::function<std::string()> longDescription;
//! Documentation on how to use the binding.
std::vector<std::function<std::string()>> example;
//! A set of pairs of strings with useful "see also" information; each pair
//! is <description, url>.
std::vector<std::pair<std::string, std::string>> seeAlso;
};
} // namespace util
} // namespace mlpack
#endif
src/mlpack/core/util/io.cpp
+4 -22
View File
@@ -17,19 +17,15 @@
using namespace mlpack;
using namespace mlpack::util;
// Fake ProgramDoc in case none is supplied.
static ProgramDoc emptyProgramDoc = ProgramDoc("", "", []() { return ""; },
[]() { return ""; }, {});
/* Constructors, Destructors, Copy */
/* Make the constructor private, to preclude unauthorized instances */
IO::IO() : didParse(false), doc(&emptyProgramDoc)
IO::IO() : didParse(false)
{
return;
}
// Private copy constructor; don't want copies floating around.
IO::IO(const IO& /* other */) : didParse(false), doc(&emptyProgramDoc)
IO::IO(const IO& /* other */) : didParse(false)
{
return;
}
@@ -154,20 +150,6 @@ IO& IO::GetSingleton()
return singleton;
}
/**
* Registers a ProgramDoc object, which contains documentation about the
* program.
*
* @param doc Pointer to the ProgramDoc object.
*/
void IO::RegisterProgramDoc(ProgramDoc* doc)
{
// Only register the doc if it is not the dummy object we created at the
// beginning of the file (as a default value in case this is never called).
if (doc != &emptyProgramDoc)
GetSingleton().doc = doc;
}
// Get the parameters that the IO object knows about.
std::map<std::string, ParamData>& IO::Parameters()
{
@@ -180,10 +162,10 @@ std::map<char, std::string>& IO::Aliases()
return GetSingleton().aliases;
}
// Get the program name as set by PROGRAM_INFO().
// Get the program name as set by BINDING_NAME().
std::string IO::ProgramName()
{
return GetSingleton().doc->programName;
return GetSingleton().doc.programName;
}
// Set a particular parameter as passed.
src/mlpack/core/util/io.hpp
+23 -29
View File
@@ -23,6 +23,7 @@
#include <mlpack/prereqs.hpp>
#include "timers.hpp"
#include "binding_details.hpp"
#include "program_doc.hpp"
#include "version.hpp"
@@ -32,13 +33,6 @@
#include <mlpack/core/data/save.hpp>
namespace mlpack {
namespace util {
// Externally defined in option.hpp, this class holds information about the
// program being run.
class ProgramDoc;
} // namespace util
/**
* @brief Parses the command line for parameters and holds user-specified
@@ -76,7 +70,7 @@ class ProgramDoc;
* merely as a flag on the command line (no '=true' is required).
*
* Here is an example of a few parameters being defined; this is for the KNN
* executable (methods/neighbor_search/knn_main.cpp):
* binding (methods/neighbor_search/knn_main.cpp):
*
* @code
* PARAM_STRING_REQ("reference_file", "File containing the reference dataset.",
@@ -99,14 +93,24 @@ class ProgramDoc;
* @section programinfo Documenting the program itself
*
* In addition to allowing documentation for each individual parameter and
* module, the PROGRAM_INFO() macro provides support for documenting the program
* itself. There should only be one instance of the PROGRAM_INFO() macro.
* module, the BINDING_NAME() macro provides support for documenting the
* programName, BINDING_SHORT_DESC() macro provides support for documenting the
* shortDescription, BINDING_LONG_DESC() macro provides support for documenting
* the longDescription, the BINDING_EXAMPLE() macro provides support for
* documenting the example and the BINDING_SEE_ALSO() macro provides support for
* documenting the seeAlso. There should only be one instance of the
* BINDING_NAME(), BINDING_SHORT_DESC() and BINDING_LONG_DESC() macros and there
* can be multiple instance of BINDING_EXAMPLE() and BINDING_SEE_ALSO() macro.
* Below is an example:
*
* @code
* PROGRAM_INFO("Maximum Variance Unfolding", "This program performs maximum "
* BINDING_NAME("Maximum Variance Unfolding");
* BINDING_SHORT_DESC("An implementation of Maximum Variance Unfolding");
* BINDING_LONG_DESC( "This program performs maximum "
* "variance unfolding on the given dataset, writing a lower-dimensional "
* "unfolded dataset to the given output file.");
* BINDING_EXAMPLE("mvu", "input", "dataset", "new_dim", 5, "output", "output");
* BINDING_SEE_ALSO("Perceptron", "#perceptron");
* @endcode
*
* This description should be verbose, and explain to a non-expert user what the
@@ -152,10 +156,10 @@ class ProgramDoc;
*
* @note
* Options should only be defined in files which define `main()` (that is, main
* executables). If options are defined elsewhere, they may be spuriously
* included into other executables and confuse users. Similarly, if your
* executable has options which you did not define, it is probably because the
* option is defined somewhere else and included in your executable.
* bindings). If options are defined elsewhere, they may be spuriously
* included into other bindings and confuse users. Similarly, if your
* binding has options which you did not define, it is probably because the
* option is defined somewhere else and included in your binding.
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -240,21 +244,12 @@ class IO
*/
static IO& GetSingleton();
/**
* Registers a ProgramDoc object, which contains documentation about the
* program. If this method has been called before (that is, if two
* ProgramDocs are instantiated in the program), a fatal error will occur.
*
* @param doc Pointer to the ProgramDoc object.
*/
static void RegisterProgramDoc(util::ProgramDoc* doc);
//! Return a modifiable list of parameters that IO knows about.
static std::map<std::string, util::ParamData>& Parameters();
//! Return a modifiable list of aliases that IO knows about.
static std::map<char, std::string>& Aliases();
//! Get the program name as set by the PROGRAM_INFO() macro.
//! Get the program name as set by the BINDING_NAME() macro.
static std::string ProgramName();
/**
@@ -313,7 +308,7 @@ class IO
bool didParse;
//! Holds the name of the program for --version. This is the true program
//! name (argv[0]) not what is given in ProgramDoc.
//! name (argv[0]) not what is given in BindingDetails.
std::string programName;
//! Holds the timer objects.
@@ -322,9 +317,8 @@ class IO
//! So that Timer::Start() and Timer::Stop() can access the timer variable.
friend class Timer;
//! Pointer to the ProgramDoc object.
util::ProgramDoc* doc;
//! Holds the bindingDetails objects.
util::BindingDetails doc;
private:
/**
* Make the constructor private, to preclude unauthorized instances.
src/mlpack/core/util/mlpack_main.hpp
+66 -35
View File
@@ -153,13 +153,6 @@ using Option = mlpack::bindings::tests::TestOption<T>;
// testName symbol should be defined in each binding test file
#include <mlpack/core/util/param.hpp>
#undef PROGRAM_INFO
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) static \
mlpack::util::ProgramDoc \
io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \
[]() { return std::string(DESC) + "\n\n" + std::string(EXAMPLE); }, []() \
{ return ""; }, { __VA_ARGS__ })
#elif(BINDING_TYPE == BINDING_TYPE_PYX) // This is a Python binding.
// Matrices are transposed on load/save.
@@ -219,12 +212,10 @@ using Option = mlpack::bindings::python::PyOption<T>;
static const std::string testName = "";
#include <mlpack/core/util/param.hpp>
#undef PROGRAM_INFO
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) static \
mlpack::util::ProgramDoc \
io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \
[]() { return std::string(DESC) + "\n\n" + std::string(EXAMPLE); }, []() \
{ return ""; }, { __VA_ARGS__ }); \
#undef BINDING_NAME
#define BINDING_NAME(NAME) static \
mlpack::util::ProgramName \
io_programname_dummy_object = mlpack::util::ProgramName(NAME); \
namespace mlpack { \
namespace bindings { \
namespace python { \
@@ -269,12 +260,10 @@ using Option = mlpack::bindings::julia::JuliaOption<T>;
static const std::string testName = "";
#include <mlpack/core/util/param.hpp>
#undef PROGRAM_INFO
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) static \
mlpack::util::ProgramDoc \
io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \
[]() { return std::string(DESC) + "\n\n" + std::string(EXAMPLE); }, []() \
{ return ""; }, { __VA_ARGS__ }); \
#undef BINDING_NAME
#define BINDING_NAME(NAME) static \
mlpack::util::ProgramName \
io_programname_dummy_object = mlpack::util::ProgramName(NAME); \
namespace mlpack { \
namespace bindings { \
namespace julia { \
@@ -315,12 +304,10 @@ using Option = mlpack::bindings::go::GoOption<T>;
static const std::string testName = "";
#include <mlpack/core/util/param.hpp>
#undef PROGRAM_INFO
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) static \
mlpack::util::ProgramDoc \
io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \
[]() { return std::string(DESC) + "\n\n" + std::string(EXAMPLE); }, []() \
{ return ""; }, { __VA_ARGS__ }); \
#undef BINDING_NAME
#define BINDING_NAME(NAME) static \
mlpack::util::ProgramName \
io_programname_dummy_object = mlpack::util::ProgramName(NAME); \
namespace mlpack { \
namespace bindings { \
namespace go { \
@@ -374,9 +361,11 @@ PARAM_FLAG("verbose", "Display informational messages and the full list of "
#elif BINDING_TYPE == BINDING_TYPE_MARKDOWN
// We use BINDING_NAME in PROGRAM_INFO() so it needs to be defined.
#ifndef BINDING_NAME
#error "BINDING_NAME must be defined when BINDING_TYPE is Markdown!"
// We use MARKDOWN_BINDING_NAME in BINDING_NAME(), BINDING_SHORT_DESC(),
// BINDING_LONG_DESC(), BINDING_EXAMPLE() and BINDING_SEE_ALSO()
// so it needs to be defined.
#ifndef MARKDOWN_BINDING_NAME
#error "MARKDOWN_BINDING_NAME must be defined when BINDING_TYPE is Markdown!"
#endif
// This value doesn't actually matter, but it needs to be defined as something.
@@ -439,13 +428,55 @@ using Option = mlpack::bindings::markdown::MDOption<T>;
#include <mlpack/core/util/param.hpp>
#include <mlpack/bindings/markdown/program_doc_wrapper.hpp>
#undef PROGRAM_INFO
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) static \
mlpack::bindings::markdown::ProgramDocWrapper \
io_programdoc_dummy_object = \
mlpack::bindings::markdown::ProgramDocWrapper(BINDING_NAME, NAME, \
SHORT_DESC, []() { return std::string(DESC) + "\n\n" + std::string( \
EXAMPLE); }, []() { return ""; }, { __VA_ARGS__ }); \
#undef BINDING_NAME
#undef BINDING_SHORT_DESC
#undef BINDING_LONG_DESC
#undef BINDING_EXAMPLE
#undef BINDING_SEE_ALSO
#define BINDING_NAME(NAME) static \
mlpack::bindings::markdown::ProgramNameWrapper \
io_programname_dummy_object = \
mlpack::bindings::markdown::ProgramNameWrapper( \
MARKDOWN_BINDING_NAME, NAME);
#define BINDING_SHORT_DESC(SHORT_DESC) static \
mlpack::bindings::markdown::ShortDescriptionWrapper \
io_programshort_desc_dummy_object = \
mlpack::bindings::markdown::ShortDescriptionWrapper( \
MARKDOWN_BINDING_NAME, SHORT_DESC);
#define BINDING_LONG_DESC(LONG_DESC) static \
mlpack::bindings::markdown::LongDescriptionWrapper \
io_programlong_desc_dummy_object = \
mlpack::bindings::markdown::LongDescriptionWrapper( \
MARKDOWN_BINDING_NAME, []() { return std::string(LONG_DESC); });
#ifdef __COUNTER__
#define BINDING_EXAMPLE(EXAMPLE) static \
mlpack::bindings::markdown::ExampleWrapper \
JOIN(io_programexample_dummy_object_, __COUNTER__) = \
mlpack::bindings::markdown::ExampleWrapper(MARKDOWN_BINDING_NAME, \
[]() { return(std::string(EXAMPLE)); });
#define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \
mlpack::bindings::markdown::SeeAlsoWrapper \
JOIN(io_programsee_also_dummy_object_, __COUNTER__) = \
mlpack::bindings::markdown::SeeAlsoWrapper(MARKDOWN_BINDING_NAME, \
DESCRIPTION, LINK);
#else
#define BINDING_EXAMPLE(EXAMPLE) static \
mlpack::bindings::markdown::ExampleWrapper \
JOIN(JOIN(io_programexample_dummy_object_, __LINE__), opt) = \
mlpack::bindings::markdown::ExampleWrapper(MARKDOWN_BINDING_NAME, \
[]() { return(std::string(EXAMPLE)); });
#define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \
mlpack::bindings::markdown::SeeAlsoWrapper \
JOIN(JOIN(io_programsee_also_dummy_object_, __LINE__), opt) = \
mlpack::bindings::markdown::SeeAlsoWrapper(MARKDOWN_BINDING_NAME, \
DESCRIPTION, LINK);
#endif
PARAM_FLAG("verbose", "Display informational messages and the full list of "
"parameters and timers at the end of execution.", "v");
src/mlpack/core/util/param.hpp
+155 -62
View File
@@ -4,8 +4,8 @@
* @author Ryan Curtin
*
* Definition of PARAM_*_IN() and PARAM_*_OUT() macros, as well as the
* PROGRAM_INFO() macro, which are used to define input and output parameters of
* command-line programs and bindings to other languages.
* Documentation related macro, which are used to define input and output
* parameters of command-line programs and bindings to other languages.
*
* 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
@@ -30,6 +30,118 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
} // namespace mlpack
/**
* @cond
* Don't document internal macros.
*/
// These are ugly, but necessary utility functions we must use to generate a
// unique identifier inside of the PARAM() module.
#define JOIN(x, y) JOIN_AGAIN(x, y)
#define JOIN_AGAIN(x, y) x ## y
/** @endcond */
/**
* Specify the program name of a binding. Only one instance of this macro
* should be present in your program! Therefore, use it in the main.cpp
* (or corresponding binding) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* @param NAME Short string representing the name of the program.
*/
#define BINDING_NAME(NAME) static \
mlpack::util::ProgramName \
io_programname_dummy_object = mlpack::util::ProgramName(NAME);
/**
* Specify the short description of a binding. Only one instance of this macro
* should be present in your program! Therefore, use it in the main.cpp
* (or corresponding binding) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* @param SHORT_DESC Short two-sentence description of the program; it should
* describe what the program implements and does, and a quick overview of
* how it can be used and what it should be used for.
*/
#define BINDING_SHORT_DESC(SHORT_DESC) static \
mlpack::util::ShortDescription \
io_programshort_desc_dummy_object = mlpack::util::ShortDescription( \
SHORT_DESC);
/**
* Specify the long description of a binding. Only one instance of this macro
* present in your program! Therefore, use it in the main.cpp
* (or corresponding binding) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* @param LONG_DESC Long string describing what the program does. Newlines
* should not be used here; this is taken care of by IO (however, you
* can explicitly specify newlines to denote new paragraphs). You can
* also use printing macros like PRINT_PARAM_STRING(), PRINT_DATASET(),
* and others.
*/
#define BINDING_LONG_DESC(LONG_DESC) static \
mlpack::util::LongDescription \
io_programlong_desc_dummy_object = mlpack::util::LongDescription( \
[]() { return std::string(LONG_DESC); });
/**
* Specify the example of a binding. Mutiple instance of this macro can be
* present in your program! Therefore, use it in the main.cpp
* (or corresponding binding) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* @param EXAMPLE Long string describing a simple usage example.. Newlines
* should not be used here; this is taken care of by IO (however, you
* can explicitly specify newlines to denote new paragraphs). You can
* also use printing macros like PRINT_CALL(), PRINT_DATASET(),
* and others.
*/
#ifdef __COUNTER__
#define BINDING_EXAMPLE(EXAMPLE) static \
mlpack::util::Example \
JOIN(io_programexample_dummy_object_, __COUNTER__) = \
mlpack::util::Example( \
[]() { return(std::string(EXAMPLE)); });
#else
#define BINDING_EXAMPLE(EXAMPLE) static \
mlpack::util::Example \
JOIN(JOIN(io_programexample_dummy_object_, __LINE__), opt) = \
mlpack::util::Example( \
[]() { return(std::string(EXAMPLE)); });
#endif
/**
* Specify the see-also of a binding. Mutiple instance of this macro can be
* present in your program! Therefore, use it in the main.cpp
* (or corresponding binding) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* Provide a link for a binding's "see also" documentation section, which is
* primarily (but not necessarily exclusively) used by the Markdown bindings
* This link can be specified by calling SEE_ALSO("description", "link"), where
@@ -42,39 +154,17 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* - A link to a Doxygen page, using the mangled Doxygen name after a
* '\@doxygen/', i.e., "@doxygen/mlpack1_1_adaboost1_1_AdaBoost".
*/
#define SEE_ALSO(DESCRIPTION, LINK) {DESCRIPTION, LINK}
/**
* Document an executable. Only one instance of this macro should be
* present in your program! Therefore, use it in the main.cpp
* (or corresponding executable) in your program.
*
* @see mlpack::IO, PARAM_FLAG(), PARAM_INT_IN(), PARAM_DOUBLE_IN(),
* PARAM_STRING_IN(), PARAM_VECTOR_IN(), PARAM_INT_OUT(), PARAM_DOUBLE_OUT(),
* PARAM_VECTOR_OUT(), PARAM_INT_IN_REQ(), PARAM_DOUBLE_IN_REQ(),
* PARAM_STRING_IN_REQ(), PARAM_VECTOR_IN_REQ(), PARAM_INT_OUT_REQ(),
* PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ().
*
* @param NAME Short string representing the name of the program.
* @param SHORT_DESC Short two-sentence description of the program; it should
* describe what the program implements and does, and a quick overview of
* how it can be used and what it should be used for.
* @param DESC Long string describing what the program does and possibly a
* simple usage example. Newlines should not be used here; this is taken
* care of by IO (however, you can explicitly specify newlines to denote
* new paragraphs). You can also use printing macros like
* PRINT_PARAM_STRING(), PRINT_DATASET(), and others.
* @param EXAMPLE A simple usage example. You can also use printing macros like
* PRINT_PARAM_STRING(), PRINT_CALL(), and others.
* @param ... A set of SEE_ALSO() macros that are used for generating
* documentation. See the SEE_ALSO() macro. This is a varargs argument, so
* you can add as many SEE_ALSO()s as you like.
*/
#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, EXAMPLE, ...) \
static mlpack::util::ProgramDoc \
io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \
[]() { return std::string(DESC) + std::string(EXAMPLE); }, []() \
{ return ""; }, { __VA_ARGS__ })
#ifdef __COUNTER__
#define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \
mlpack::util::SeeAlso \
JOIN(io_programsee_also_dummy_object_, __COUNTER__) = \
mlpack::util::SeeAlso(DESCRIPTION, LINK);
#else
#define BINDING_SEE_ALSO(DESCRIPTION, LINK) static \
mlpack::util::SeeAlso \
JOIN(JOIN(io_programsee_also_dummy_object_, __LINE__), opt) = \
mlpack::util::SeeAlso(DESCRIPTION, LINK);
#endif
/**
* Define a flag parameter.
@@ -85,7 +175,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -111,7 +202,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* @param ALIAS An alias for the parameter (one letter).
* @param DEF Default value of the parameter.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
// Use a forward declaration of the class.
@@ -142,7 +234,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others
* here---it will cause problems.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -168,7 +261,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* @param ALIAS An alias for the parameter (one letter).
* @param DEF Default value of the parameter.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -198,7 +292,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others
* here---it will cause problems.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -216,7 +311,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
*
* The parameter can then be specified on the command line with
* --ID=value. If ALIAS is equal to DEF_MOD (which is set using the
* PROGRAM_INFO() macro), the parameter can be specified with just --ID=value.
* BINDING_LONG_DESC() macro), the parameter can be specified with just
* --ID=value.
*
* @param ID Name of the parameter.
* @param DESC Quick description of the parameter (1-2 sentences). Don't use
@@ -225,7 +321,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* @param ALIAS An alias for the parameter (one letter).
* @param DEF Default value of the parameter.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -256,7 +353,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -830,7 +928,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -863,7 +962,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -902,7 +1002,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS One-character string representing the alias of the parameter.
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -1014,7 +1115,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -1038,7 +1140,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -1062,7 +1165,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -1088,7 +1192,8 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
* here---it will cause problems.
* @param ALIAS An alias for the parameter (one letter).
*
* @see mlpack::IO, PROGRAM_INFO()
* @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(),
* BINDING_EXAMPLE() and BINDING_SEE_ALSO().
*
* @bug
* The __COUNTER__ variable is used in most cases to guarantee a unique global
@@ -1101,18 +1206,6 @@ using DatasetInfo = DatasetMapper<IncrementPolicy, std::string>;
#define PARAM_VECTOR_IN_REQ(T, ID, DESC, ALIAS) \
PARAM_IN(std::vector<T>, ID, DESC, ALIAS, std::vector<T>(), true);
/**
* @cond
* Don't document internal macros.
*/
// These are ugly, but necessary utility functions we must use to generate a
// unique identifier inside of the PARAM() module.
#define JOIN(x, y) JOIN_AGAIN(x, y)
#define JOIN_AGAIN(x, y) x ## y
/** @endcond */
/**
* Define an input parameter. Don't use this function; use the other ones above
* that call it. Note that we are using the __LINE__ macro for naming these
src/mlpack/core/util/program_doc.cpp
+59 -27
View File
@@ -1,9 +1,10 @@
/**
* @file core/util/program_doc.cpp
* @author Yashwant Singh Parihar
* @author Ryan Curtin
*
* Implementation of the ProgramDoc class. The class registers itself with IO
* when constructed.
* Implementation of mutiple classes that store information related to a binding.
* The classes register themselves with IO when constructed.
*
* 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
@@ -20,39 +21,70 @@ using namespace mlpack::util;
using namespace std;
/**
* Construct a ProgramDoc object. When constructed, it will register itself
* Construct a ProgramName object. When constructed, it will register itself
* with IO. A fatal error will be thrown if more than one is constructed.
*
* @param defaultModule Name of the default module.
* @param shortDocumentation A short two-sentence description of the program,
* what it does, and what it is useful for.
* @param documentation Long string containing documentation on how to use the
* program and what it is. No newline characters are necessary; this is
* taken care of by IO later.
* @param example Documentation on how to use the program.
* @param seeAlso A set of pairs of strings with useful "see also"
* information; each pair is <description, url>.
* @param programName Name of the binding.
*/
ProgramDoc::ProgramDoc(
const std::string programName,
const std::string shortDocumentation,
const std::function<std::string()> documentation,
const std::function<std::string()> example,
const std::vector<std::pair<std::string, std::string>> seeAlso) :
programName(std::move(programName)),
shortDocumentation(std::move(shortDocumentation)),
documentation(std::move(documentation)),
example(std::move(example)),
seeAlso(std::move(seeAlso))
ProgramName::ProgramName(const std::string& programName)
{
// Register this with IO.
IO::RegisterProgramDoc(this);
IO::GetSingleton().doc.programName = std::move(programName);
}
/**
* Construct an empty ProgramDoc object.
* Construct a ShortDescription object. When constructed, it will register
* itself with IO. A fatal error will be thrown if more than one is
* constructed.
*
* @param shortDescription A short two-sentence description of the binding,
* what it does, and what it is useful for.
*/
ProgramDoc::ProgramDoc()
ShortDescription::ShortDescription(const std::string& shortDescription)
{
IO::RegisterProgramDoc(this);
// Register this with IO.
IO::GetSingleton().doc.shortDescription = std::move(shortDescription);
}
/**
* Construct a LongDescription object. When constructed, it will register itself
* with IO. A fatal error will be thrown if more than one is constructed.
*
* @param longDescription Long string containing documentation on
* what it is. No newline characters are necessary; this is
* taken care of by IO later.
*/
LongDescription::LongDescription(
const std::function<std::string()>& longDescription)
{
// Register this with IO.
IO::GetSingleton().doc.longDescription = std::move(longDescription);
}
/**
* Construct a Example object. When constructed, it will register itself
* with IO.
*
* @param example Documentation on how to use the binding.
*/
Example::Example(
const std::function<std::string()>& example)
{
// Register this with IO.
IO::GetSingleton().doc.example.push_back(std::move(example));
}
/**
* Construct a SeeAlso object. When constructed, it will register itself
* with IO.
*
* @param description Description of SeeAlso.
* @param link Link of SeeAlso.
*/
SeeAlso::SeeAlso(
const std::string& description, const std::string& link)
{
// Register this with IO.
IO::GetSingleton().doc.seeAlso.push_back(std::move(
make_pair(description, link)));
}
src/mlpack/core/util/program_doc.hpp
+57 -40
View File
@@ -1,8 +1,10 @@
/**
* @file core/util/program_doc.hpp
* @author Yashwant Singh Parihar
* @author Matthew Amidon
*
* The structure used to store a program's name and documentation.
* Implementation of mutiple classes that store information related to a binding.
* The classes register themselves with IO when constructed.
*
* 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
@@ -15,54 +17,69 @@
namespace mlpack {
namespace util {
/**
* A static object whose constructor registers program documentation with the
* IO class. This should not be used outside of IO itself, and you should use
* the PROGRAM_INFO() macro to declare these objects. Only one ProgramDoc
* object should ever exist.
*
* @see core/util/io.hpp, mlpack::IO
*/
class ProgramDoc
class ProgramName
{
public:
/**
* Construct a ProgramDoc object. When constructed, it will register itself
* with IO, and when the user calls --help (or whatever the option is named
* for the given binding type), the given function that returns a std::string
* will be returned.
* Construct a ProgramName object. When constructed, it will register itself
* with IO. A fatal error will be thrown if more than one is constructed.
*
* @param programName Short string representing the name of the program.
* @param shortDocumentation A short two-sentence description of the program,
* what it does, and what it is useful for.
* @param documentation Long string containing documentation on how to use the
* program and what it is. No newline characters are necessary; this is
* taken care of by IO later.
* @param example Documentation on how to use the program.
* @param seeAlso A set of pairs of strings with useful "see also"
* information; each pair is <description, url>.
* @param programName Name of the binding.
*/
ProgramDoc(const std::string programName,
const std::string shortDocumentation,
const std::function<std::string()> documentation,
const std::function<std::string()> example,
const std::vector<std::pair<std::string, std::string>> seeAlso);
ProgramName(const std::string& programName);
};
class ShortDescription
{
public:
/**
* Construct an empty ProgramDoc object. (This is not meant to be used!)
* Construct a ShortDescription object. When constructed, it will register
* itself with IO. A fatal error will be thrown if more than one is
* constructed.
*
* @param shortDescription A short two-sentence description of the binding,
* what it does, and what it is useful for.
*/
ProgramDoc();
ShortDescription(const std::string& shortDescription);
};
//! The name of the program.
std::string programName;
//! The short documentation for the program.
std::string shortDocumentation;
//! Documentation for what the program does.
std::function<std::string()> documentation;
//! Example for the program.
std::function<std::string()> example;
//! Set of see also information.
std::vector<std::pair<std::string, std::string>> seeAlso;
class LongDescription
{
public:
/**
* Construct a LongDescription object. When constructed, it will register itself
* with IO. A fatal error will be thrown if more than one is constructed.
*
* @param longDescription Long string containing documentation on
* what it is. No newline characters are necessary; this is
* taken care of by IO later.
*/
LongDescription(const std::function<std::string()>& longDescription);
};
class Example
{
public:
/**
* Construct a Example object. When constructed, it will register itself
* with IO.
*
* @param example Documentation on how to use the binding.
*/
Example(const std::function<std::string()>& example);
};
class SeeAlso
{
public:
/**
* Construct a SeeAlso object. When constructed, it will register itself
* with IO.
*
* @param description Description of SeeAlso.
* @param link Link of SeeAlso.
*/
SeeAlso(const std::string& description, const std::string& link);
};
} // namespace util
src/mlpack/methods/adaboost/adaboost_main.cpp
+24 -15
View File
@@ -46,13 +46,18 @@ using namespace mlpack::tree;
using namespace mlpack::perceptron;
using namespace mlpack::util;
PROGRAM_INFO("AdaBoost",
// Short description.
// Program Name.
BINDING_NAME("AdaBoost");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the AdaBoost.MH (Adaptive Boosting) algorithm for "
"classification. This can be used to train an AdaBoost model on labeled "
"data or use an existing AdaBoost model to predict the classes of new "
"points.",
// Long description.
"points.");
// Long description.
BINDING_LONG_DESC(
"This program implements the AdaBoost (or Adaptive "
"Boosting) algorithm. The variant of AdaBoost implemented here is "
"AdaBoost.MH. It uses a weak learner, either decision stumps or "
@@ -86,8 +91,10 @@ PROGRAM_INFO("AdaBoost",
"."
"\n"
"Use " + PRINT_PARAM_STRING("predictions") + " instead of " +
PRINT_PARAM_STRING("output") + '.',
// Example.
PRINT_PARAM_STRING("output") + '.');
// Example.
BINDING_EXAMPLE(
"For example, to run AdaBoost on an input dataset " +
PRINT_DATASET("data") + " with labels " + PRINT_DATASET("labels") +
"and perceptrons as the weak learner type, storing the trained model in " +
@@ -102,15 +109,17 @@ PROGRAM_INFO("AdaBoost",
PRINT_DATASET("predictions") + " with the following command: "
"\n\n" +
PRINT_CALL("adaboost", "input_model", "model", "test", "test_data",
"predictions", "predictions"),
// See also...
SEE_ALSO("AdaBoost on Wikipedia", "https://en.wikipedia.org/wiki/AdaBoost"),
SEE_ALSO("Improved boosting algorithms using confidence-rated predictions "
"(pdf)", "http://rob.schapire.net/papers/SchapireSi98.pdf"),
SEE_ALSO("Perceptron", "#perceptron"),
SEE_ALSO("Decision Stump", "#decision_stump"),
SEE_ALSO("mlpack::adaboost::AdaBoost C++ class documentation",
"@doxygen/classmlpack_1_1adaboost_1_1AdaBoost.html"));
"predictions", "predictions"));
// See also...
BINDING_SEE_ALSO("AdaBoost on Wikipedia", "https://en.wikipedia.org/wiki/"
"AdaBoost");
BINDING_SEE_ALSO("Improved boosting algorithms using confidence-rated "
"predictions (pdf)", "http://rob.schapire.net/papers/SchapireSi98.pdf");
BINDING_SEE_ALSO("Perceptron", "#perceptron");
BINDING_SEE_ALSO("Decision Stump", "#decision_stump");
BINDING_SEE_ALSO("mlpack::adaboost::AdaBoost C++ class documentation",
"@doxygen/classmlpack_1_1adaboost_1_1AdaBoost.html");
// Input for training.
PARAM_MATRIX_IN("training", "Dataset for training AdaBoost.", "t");
src/mlpack/methods/ann/rbm/rbm.hpp
+36 -36
View File
@@ -70,12 +70,12 @@ class RBM
const bool persistence = false);
// Reset the network.
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
Reset();
// Reset the network.
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
Reset();
@@ -116,9 +116,9 @@ class RBM
*
* @param input The visible neurons.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, double>::type
FreeEnergy(arma::Mat<ElemType>&& input);
FreeEnergy(const arma::Mat<ElemType>& input);
/**
* This function calculates the free energy of the SpikeSlabRBM.
@@ -130,10 +130,10 @@ class RBM
*
* @param input The visible layer neurons.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value,
double>::type
FreeEnergy(arma::Mat<ElemType>&& input);
FreeEnergy(const arma::Mat<ElemType>& input);
/**
* Calculates the gradient of the RBM network on the provided input.
@@ -141,9 +141,9 @@ class RBM
* @param input The provided input data.
* @param gradient Stores the gradient of the RBM network.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
Phase(DataType&& input, DataType&& gradient);
Phase(const InputType& input, DataType& gradient);
/**
* Calculates the gradient of the RBM network on the provided input.
@@ -151,9 +151,9 @@ class RBM
* @param input The provided input data.
* @param gradient Stores the gradient of the RBM network.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
Phase(DataType&& input, DataType&& gradient);
Phase(const InputType& input, DataType& gradient);
/**
* This function samples the hidden layer given the visible layer using
@@ -162,9 +162,9 @@ class RBM
* @param input Visible layer input.
* @param output The sampled hidden layer.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
SampleHidden(arma::Mat<ElemType>&& input, arma::Mat<ElemType>&& output);
SampleHidden(const arma::Mat<ElemType>& input, arma::Mat<ElemType>& output);
/**
* This function samples the slab outputs from the Normal distribution with
@@ -176,9 +176,9 @@ class RBM
* @param input Consists of both visible and spike variables.
* @param output Sampled slab neurons.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SampleHidden(arma::Mat<ElemType>&& input, arma::Mat<ElemType>&& output);
SampleHidden(const arma::Mat<ElemType>& input, arma::Mat<ElemType>& output);
/**
* This function samples the visible layer given the hidden layer using
@@ -187,9 +187,9 @@ class RBM
* @param input Hidden layer of the network.
* @param output The sampled visible layer.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
SampleVisible(arma::Mat<ElemType>&& input, arma::Mat<ElemType>&& output);
SampleVisible(arma::Mat<ElemType>& input, arma::Mat<ElemType>& output);
/**
* Sample Hidden function samples the slab outputs from the Normal
@@ -201,9 +201,9 @@ class RBM
* @param input Hidden layer of the network.
* @param output The sampled visible layer.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SampleVisible(arma::Mat<ElemType>&& input, arma::Mat<ElemType>&& output);
SampleVisible(arma::Mat<ElemType>& input, arma::Mat<ElemType>& output);
/**
* The function calculates the mean for the visible layer.
@@ -211,9 +211,9 @@ class RBM
* @param input Hidden neurons from the hidden layer of the network.
* @param output Visible neuron activations.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
VisibleMean(DataType&& input, DataType&& output);
VisibleMean(InputType& input, DataType& output);
/**
* The function calculates the mean of the Normal distribution of P(v|s, h).
@@ -223,9 +223,9 @@ class RBM
* @param input Consists of both the spike and slab variables.
* @param output Mean of the of the Normal distribution.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
VisibleMean(DataType&& input, DataType&& output);
VisibleMean(InputType& input, DataType& output);
/**
* The function calculates the mean for the hidden layer.
@@ -233,9 +233,9 @@ class RBM
* @param input Visible neurons.
* @param output Hidden neuron activations.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
HiddenMean(DataType&& input, DataType&& output);
HiddenMean(const InputType& input, DataType& output);
/**
* The function calculates the mean of the Normal distribution of P(s|v, h).
@@ -247,9 +247,9 @@ class RBM
* @param input Visible layer neurons.
* @param output Consists of both the spike samples and slab samples.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
HiddenMean(DataType&& input, DataType&& output);
HiddenMean(const InputType& input, DataType& output);
/**
* The function calculates the mean of the distribution P(h|v),
@@ -259,18 +259,18 @@ class RBM
* @param visible The visible layer neurons.
* @param spikeMean Indicates P(h|v).
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SpikeMean(DataType&& visible, DataType&& spikeMean);
SpikeMean(const InputType& visible, DataType& spikeMean);
/**
* The function samples the spike function using Bernoulli distribution.
* @param spikeMean Indicates P(h|v).
* @param spike Sampled binary spike variables.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SampleSpike(DataType&& spikeMean, DataType&& spike);
SampleSpike(InputType& spikeMean, DataType& spike);
/**
* The function calculates the mean of Normal distribution of P(s|v, h),
@@ -281,9 +281,9 @@ class RBM
* @param spike The spike variables from hidden layer.
* @param slabMean The mean of the Normal distribution of slab neurons.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SlabMean(DataType&& visible, DataType&& spike, DataType&& slabMean);
SlabMean(const DataType& visible, DataType& spike, DataType& slabMean);
/**
* The function samples from the Normal distribution of P(s|v, h),
@@ -295,9 +295,9 @@ class RBM
* @param slabMean Mean of the Normal distribution of the slab neurons.
* @param slab Sampled slab variable from the Normal distribution.
*/
template<typename Policy = PolicyType>
template<typename Policy = PolicyType, typename InputType = DataType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
SampleSlab(DataType&& slabMean, DataType&& slab);
SampleSlab(InputType& slabMean, DataType& slab);
/**
* This function does the k-step Gibbs Sampling.
@@ -306,8 +306,8 @@ class RBM
* @param output Used for storing the negative sample.
* @param steps Number of Gibbs Sampling steps taken.
*/
void Gibbs(arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output,
void Gibbs(const arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output,
const size_t steps = SIZE_MAX);
/**
src/mlpack/methods/ann/rbm/rbm_impl.hpp
+40 -38
View File
@@ -58,7 +58,7 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::Reset()
{
@@ -108,10 +108,10 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, double>::type
RBM<InitializationRuleType, DataType, PolicyType>::FreeEnergy(
arma::Mat<ElemType>&& input)
const arma::Mat<ElemType>& input)
{
preActivation = (weight.slice(0) * input);
preActivation.each_col() += hiddenBias;
@@ -124,11 +124,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::Phase(
DataType&& input,
DataType&& gradient)
const InputType& input,
DataType& gradient)
{
arma::Cube<ElemType> weightGrad = arma::Cube<ElemType>(gradient.memptr(),
hiddenSize, visibleSize, 1, false, false);
@@ -136,7 +136,7 @@ RBM<InitializationRuleType, DataType, PolicyType>::Phase(
DataType hiddenBiasGrad = DataType(gradient.memptr() + weightGrad.n_elem,
hiddenSize, 1, false, false);
HiddenMean(std::move(input), std::move(hiddenBiasGrad));
HiddenMean(input, hiddenBiasGrad);
weightGrad.slice(0) = hiddenBiasGrad * input.t();
}
@@ -150,10 +150,10 @@ double RBM<InitializationRuleType, DataType, PolicyType>::Evaluate(
const size_t i,
const size_t batchSize)
{
Gibbs(std::move(predictors.cols(i, i + batchSize - 1)),
std::move(negativeSamples));
return std::fabs(FreeEnergy(std::move(predictors.cols(i,
i + batchSize - 1))) - FreeEnergy(std::move(negativeSamples)));
Gibbs(predictors.cols(i, i + batchSize - 1),
negativeSamples);
return std::fabs(FreeEnergy(predictors.cols(i,
i + batchSize - 1)) - FreeEnergy(negativeSamples));
}
template<
@@ -161,13 +161,13 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleHidden(
arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output)
const arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output)
{
HiddenMean(std::move(input), std::move(output));
HiddenMean(input, output);
for (size_t i = 0; i < output.n_elem; ++i)
{
@@ -180,13 +180,13 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleVisible(
arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output)
arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output)
{
VisibleMean(std::move(input), std::move(output));
VisibleMean(input, output);
for (size_t i = 0; i < output.n_elem; ++i)
{
@@ -199,10 +199,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::VisibleMean(DataType&& input,
DataType&& output)
RBM<InitializationRuleType, DataType, PolicyType>::VisibleMean(
InputType& input,
DataType& output)
{
output = weight.slice(0).t() * input;
output.each_col() += visibleBias;
@@ -214,10 +215,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, BinaryRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::HiddenMean(DataType&& input,
DataType&& output)
RBM<InitializationRuleType, DataType, PolicyType>::HiddenMean(
const InputType& input,
DataType& output)
{
output = weight.slice(0) * input;
output.each_col() += hiddenBias;
@@ -230,27 +232,27 @@ template<
typename PolicyType
>
void RBM<InitializationRuleType, DataType, PolicyType>::Gibbs(
arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output,
const arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output,
const size_t steps)
{
this->steps = (steps == SIZE_MAX) ? this->numSteps : steps;
if (persistence && !state.is_empty())
{
SampleHidden(std::move(state), std::move(gibbsTemporary));
SampleVisible(std::move(gibbsTemporary), std::move(output));
SampleHidden(state, gibbsTemporary);
SampleVisible(gibbsTemporary, output);
}
else
{
SampleHidden(std::move(input), std::move(gibbsTemporary));
SampleVisible(std::move(gibbsTemporary), std::move(output));
SampleHidden(input, gibbsTemporary);
SampleVisible(gibbsTemporary, output);
}
for (size_t j = 1; j < this->steps; ++j)
{
SampleHidden(std::move(output), std::move(gibbsTemporary));
SampleVisible(std::move(gibbsTemporary), std::move(output));
SampleHidden(output, gibbsTemporary);
SampleVisible(gibbsTemporary, output);
}
if (persistence)
{
@@ -272,14 +274,14 @@ void RBM<InitializationRuleType, DataType, PolicyType>::Gradient(
positiveGradient.zeros();
negativeGradient.zeros();
Phase(std::move(predictors.cols(i, i + batchSize - 1)),
std::move(positiveGradient));
Phase(predictors.cols(i, i + batchSize - 1),
positiveGradient);
for (size_t i = 0; i < negSteps; ++i)
{
Gibbs(std::move(predictors.cols(i, i + batchSize - 1)),
std::move(negativeSamples));
Phase(std::move(negativeSamples), std::move(tempNegativeGradient));
Gibbs(predictors.cols(i, i + batchSize - 1),
negativeSamples);
Phase(negativeSamples, tempNegativeGradient);
negativeGradient += tempNegativeGradient;
}
src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp
+45 -48
View File
@@ -25,7 +25,7 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::Reset()
{
@@ -65,10 +65,10 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, double>::type
RBM<InitializationRuleType, DataType, PolicyType>::FreeEnergy(
arma::Mat<ElemType>&& input)
const arma::Mat<ElemType>& input)
{
ElemType freeEnergy = 0.5 * visiblePenalty(0) * arma::dot(input, input);
@@ -90,11 +90,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::Phase(
DataType&& input,
DataType&& gradient)
const InputType& input,
DataType& gradient)
{
arma::Cube<ElemType> weightGrad = arma::Cube<ElemType>
(gradient.memptr(), visibleSize, poolSize, hiddenSize, false, false);
@@ -102,12 +102,9 @@ RBM<InitializationRuleType, DataType, PolicyType>::Phase(
DataType spikeBiasGrad = DataType(gradient.memptr() + weightGrad.n_elem,
hiddenSize, 1, false, false);
DataType visiblePenaltyGrad = DataType(gradient.memptr() +
weightGrad.n_elem + spikeBiasGrad.n_elem, 1, 1, false, false);
SpikeMean(std::move(input), std::move(spikeMean));
SampleSpike(std::move(spikeMean), std::move(spikeSamples));
SlabMean(std::move(input), std::move(spikeSamples), std::move(slabMean));
SpikeMean(input, spikeMean);
SampleSpike(spikeMean, spikeSamples);
SlabMean(input, spikeSamples, slabMean);
for (size_t i = 0 ; i < hiddenSize; ++i)
{
@@ -116,9 +113,9 @@ RBM<InitializationRuleType, DataType, PolicyType>::Phase(
}
spikeBiasGrad = spikeMean;
visiblePenaltyGrad = -0.5 * arma::dot(input, input)
/ std::pow(input.n_cols, 2);
// Setting visiblePenaltyGrad.
gradient.row(weightGrad.n_elem + spikeBiasGrad.n_elem) = -0.5 * arma::dot(
input, input) / std::pow(input.n_cols, 2);
}
template<
@@ -126,11 +123,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleHidden(
arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output)
const arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output)
{
output.set_size(hiddenSize + poolSize * hiddenSize, 1);
@@ -138,10 +135,10 @@ RBM<InitializationRuleType, DataType, PolicyType>::SampleHidden(
DataType slab(output.memptr() + hiddenSize, poolSize, hiddenSize, false,
false);
SpikeMean(std::move(input), std::move(spike));
SampleSpike(std::move(spike), std::move(spike));
SlabMean(std::move(input), std::move(spike), std::move(slab));
SampleSlab(std::move(slab), std::move(slab));
SpikeMean(input, spike);
SampleSpike(spike, spike);
SlabMean(input, spike, slab);
SampleSlab(slab, slab);
}
template<
@@ -149,16 +146,16 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleVisible(
arma::Mat<ElemType>&& input,
arma::Mat<ElemType>&& output)
arma::Mat<ElemType>& input,
arma::Mat<ElemType>& output)
{
const size_t numMaxTrials = 10;
size_t k = 0;
VisibleMean(std::move(input), std::move(visibleMean));
VisibleMean(input, visibleMean);
output.set_size(visibleSize, 1);
for (k = 0; k < numMaxTrials; ++k)
@@ -187,11 +184,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::VisibleMean(
DataType&& input,
DataType&& output)
InputType& input,
DataType& output)
{
output.zeros(visibleSize, 1);
@@ -212,11 +209,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::HiddenMean(
DataType&& input,
DataType&& output)
const InputType& input,
DataType& output)
{
output.set_size(hiddenSize + poolSize * hiddenSize, 1);
@@ -224,9 +221,9 @@ RBM<InitializationRuleType, DataType, PolicyType>::HiddenMean(
DataType slab(output.memptr() + hiddenSize, poolSize, hiddenSize, false,
false);
SpikeMean(std::move(input), std::move(spike));
SampleSpike(std::move(spike), std::move(spikeSamples));
SlabMean(std::move(input), std::move(spikeSamples), std::move(slab));
SpikeMean(input, spike);
SampleSpike(spike, spikeSamples);
SlabMean(input, spikeSamples, slab);
}
template<
@@ -234,11 +231,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SpikeMean(
DataType&& visible,
DataType&& spikeMean)
const InputType& visible,
DataType& spikeMean)
{
for (size_t i = 0; i < hiddenSize; ++i)
{
@@ -253,11 +250,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleSpike(
DataType&& spikeMean,
DataType&& spike)
InputType& spikeMean,
DataType& spike)
{
for (size_t i = 0; i < hiddenSize; ++i)
{
@@ -270,12 +267,12 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SlabMean(
DataType&& visible,
DataType&& spike,
DataType&& slabMean)
const DataType& visible,
DataType& spike,
DataType& slabMean)
{
for (size_t i = 0; i < hiddenSize; ++i)
{
@@ -289,11 +286,11 @@ template<
typename DataType,
typename PolicyType
>
template<typename Policy>
template<typename Policy, typename InputType>
typename std::enable_if<std::is_same<Policy, SpikeSlabRBM>::value, void>::type
RBM<InitializationRuleType, DataType, PolicyType>::SampleSlab(
DataType&& slabMean,
DataType&& slab)
InputType& slabMean,
DataType& slab)
{
for (size_t i = 0; i < hiddenSize; ++i)
{
src/mlpack/methods/approx_kfn/approx_kfn_main.cpp
+26 -17
View File
@@ -21,13 +21,18 @@ using namespace mlpack::neighbor;
using namespace mlpack::util;
using namespace std;
PROGRAM_INFO("Approximate furthest neighbor search",
// Short description.
// Program Name.
BINDING_NAME("Approximate furthest neighbor search");
// Short description.
BINDING_SHORT_DESC(
"An implementation of two strategies for furthest neighbor search. This "
"can be used to compute the furthest neighbor of query point(s) from a set "
"of points; furthest neighbor models can be saved and reused with future "
"query point(s).",
// Long description.
"query point(s).");
// Long description.
BINDING_LONG_DESC(
"This program implements two strategies for furthest neighbor search. "
"These strategies are:"
"\n\n"
@@ -69,8 +74,10 @@ PROGRAM_INFO("Approximate furthest neighbor search",
PRINT_PARAM_STRING("neighbors") + " and " +
PRINT_PARAM_STRING("distances") + " output parameters. Each row of these "
"output matrices holds the k distances or neighbor indices for each query "
"point.",
// Example.
"point.");
// Example.
BINDING_EXAMPLE(
"For example, to find the 5 approximate furthest neighbors with " +
PRINT_DATASET("reference_set") + " as the reference set and " +
PRINT_DATASET("query_set") + " as the query set using DrusillaSelect, "
@@ -96,18 +103,20 @@ PROGRAM_INFO("Approximate furthest neighbor search",
PRINT_DATASET("neighbors") + " by calling"
"\n\n" +
PRINT_CALL("approx_kfn", "input_model", "model", "query", "new_query_set",
"k", 3, "neighbors", "neighbors"),
SEE_ALSO("k-furthest-neighbor search", "#kfn"),
SEE_ALSO("k-nearest-neighbor search", "#knn"),
SEE_ALSO("Fast approximate furthest neighbors with data-dependent candidate"
" selection (pdf)", "http://ratml.org/pub/pdf/2016fast.pdf"),
SEE_ALSO("Approximate furthest neighbor in high dimensions (pdf)",
"k", 3, "neighbors", "neighbors"));
// See also...
BINDING_SEE_ALSO("k-furthest-neighbor search", "#kfn");
BINDING_SEE_ALSO("k-nearest-neighbor search", "#knn");
BINDING_SEE_ALSO("Fast approximate furthest neighbors with data-dependent"
" candidate selection (pdf)", "http://ratml.org/pub/pdf/2016fast.pdf");
BINDING_SEE_ALSO("Approximate furthest neighbor in high dimensions (pdf)",
"https://pdfs.semanticscholar.org/a4b5/7b9cbf37201fb1d9a56c0f4eefad0466"
"9c20.pdf"),
SEE_ALSO("mlpack::neighbor::QDAFN class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1QDAFN.html"),
SEE_ALSO("mlpack::neighbor::DrusillaSelect class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1DrusillaSelect.html"));
"9c20.pdf");
BINDING_SEE_ALSO("mlpack::neighbor::QDAFN class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1QDAFN.html");
BINDING_SEE_ALSO("mlpack::neighbor::DrusillaSelect class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1DrusillaSelect.html");
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
PARAM_MATRIX_IN("query", "Matrix containing query points.", "q");
src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp
+22 -13
View File
@@ -21,10 +21,15 @@ using namespace mlpack;
using namespace mlpack::regression;
using namespace mlpack::util;
PROGRAM_INFO("BayesianLinearRegression",
// Short description.
"An implementation of the bayesian linear regression.",
// Long description.
// Program Name.
BINDING_NAME("BayesianLinearRegression");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the bayesian linear regression.");
// Long description.
BINDING_LONG_DESC(
"An implementation of the bayesian linear regression."
"\n"
"This model is a probabilistic view and implementation of the linear "
@@ -57,8 +62,10 @@ PROGRAM_INFO("BayesianLinearRegression",
"responses to the test points can be saved with the " +
PRINT_PARAM_STRING("predictions") + " output parameter. The "
"corresponding standard deviation can be save by precising the " +
PRINT_PARAM_STRING("stds") + " parameter.",
// Example.
PRINT_PARAM_STRING("stds") + " parameter.");
// Example.
BINDING_EXAMPLE(
"For example, the following command trains a model on the data " +
PRINT_DATASET("data") + " and responses " + PRINT_DATASET("responses") +
"with center set to true and scale set to false (so, Bayesian "
@@ -84,15 +91,17 @@ PROGRAM_INFO("BayesianLinearRegression",
"\n\n" +
PRINT_CALL("bayesian_linear_regression", "input_model",
"blr_model", "test", "test",
"predictions", "test_predictions", "stds", "stds"),
SEE_ALSO("Bayesian Interpolation",
"https://authors.library.caltech.edu/13792/1/MACnc92a.pdf"),
SEE_ALSO("Bayesian Linear Regression, Section 3.3",
"predictions", "test_predictions", "stds", "stds"));
// See also...
BINDING_SEE_ALSO("Bayesian Interpolation",
"https://authors.library.caltech.edu/13792/1/MACnc92a.pdf");
BINDING_SEE_ALSO("Bayesian Linear Regression, Section 3.3",
"MLA Bishop, Christopher M. Pattern Recognition and Machine "
"Learning. New York :Springer, 2006, section 3.3."),
SEE_ALSO("mlpack::regression::BayesianLinearRegression C++ class "
"Learning. New York :Springer, 2006, section 3.3.");
BINDING_SEE_ALSO("mlpack::regression::BayesianLinearRegression C++ class "
"documentation",
"@doxygen/classmlpack_1_1regression_1_1BayesianLinearRegression.html"));
"@doxygen/classmlpack_1_1regression_1_1BayesianLinearRegression.html");
PARAM_MATRIX_IN("input", "Matrix of covariates (X).", "i");
src/mlpack/methods/cf/cf_main.cpp
+29 -20
View File
@@ -41,13 +41,17 @@ using namespace mlpack::svd;
using namespace mlpack::util;
using namespace std;
// Document program.
PROGRAM_INFO("Collaborative Filtering",
// Short description.
// Program Name.
BINDING_NAME("Collaborative Filtering");
// Short description.
BINDING_SHORT_DESC(
"An implementation of several collaborative filtering (CF) techniques for "
"recommender systems. This can be used to train a new CF model, or use an"
" existing CF model to compute recommendations.",
// Long description.
" existing CF model to compute recommendations.");
// Long description.
BINDING_LONG_DESC(
"This program performs collaborative "
"filtering (CF) on the given dataset. Given a list of user, item and "
"preferences (the " + PRINT_PARAM_STRING("training") + " parameter), "
@@ -111,8 +115,10 @@ PROGRAM_INFO("Collaborative Filtering",
" - 'z_score' -- Z-Score Normalization\n"
"\n"
"A trained model may be saved to with the " +
PRINT_PARAM_STRING("output_model") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output_model") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"To train a CF model on a dataset " + PRINT_DATASET("training_set") + " "
"using NMF for decomposition and saving the trained model to " +
PRINT_MODEL("model") + ", one could call: "
@@ -126,20 +132,23 @@ PROGRAM_INFO("Collaborative Filtering",
"call "
"\n\n" +
PRINT_CALL("cf", "input_model", "model", "query", "users",
"recommendations", 5, "output", "recommendations"),
SEE_ALSO("Collaborative filtering tutorial", "@doxygen/cftutorial.html"),
SEE_ALSO("Alternating Matrix Factorization tutorial",
"@doxygen/amftutorial.html"),
SEE_ALSO("Collaborative Filtering on Wikipedia",
"https://en.wikipedia.org/wiki/Collaborative_filtering"),
SEE_ALSO("Matrix factorization on Wikipedia",
"recommendations", 5, "output", "recommendations"));
// See also...
BINDING_SEE_ALSO("Collaborative filtering tutorial",
"@doxygen/cftutorial.html");
BINDING_SEE_ALSO("Alternating Matrix Factorization tutorial",
"@doxygen/amftutorial.html");
BINDING_SEE_ALSO("Collaborative Filtering on Wikipedia",
"https://en.wikipedia.org/wiki/Collaborative_filtering");
BINDING_SEE_ALSO("Matrix factorization on Wikipedia",
"https://en.wikipedia.org/wiki/Matrix_factorization_"
"(recommender_systems)"),
SEE_ALSO("Matrix factorization techniques for recommender systems (pdf)",
"http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.441.3234"
"&rep=rep1&type=pdf"),
SEE_ALSO("mlpack::cf::CFType class documentation",
"@doxygen/classmlpack_1_1cf_1_1CFType.html"));
"(recommender_systems)");
BINDING_SEE_ALSO("Matrix factorization techniques for recommender systems"
" (pdf)", "http://citeseerx.ist.psu.edu/viewdoc/download?doi="
"10.1.1.441.3234&rep=rep1&type=pdf");
BINDING_SEE_ALSO("mlpack::cf::CFType class documentation",
"@doxygen/classmlpack_1_1cf_1_1CFType.html");
// Parameters for training a model.
PARAM_MATRIX_IN("training", "Input dataset to perform CF on.", "t");
src/mlpack/methods/dbscan/dbscan_main.cpp
+21 -12
View File
@@ -27,11 +27,16 @@ using namespace mlpack::tree;
using namespace mlpack::util;
using namespace std;
PROGRAM_INFO("DBSCAN clustering",
// Short description.
// Program Name.
BINDING_NAME("DBSCAN clustering");
// Short description.
BINDING_SHORT_DESC(
"An implementation of DBSCAN clustering. Given a dataset, this can "
"compute and return a clustering of that dataset.",
// Long description.
"compute and return a clustering of that dataset.");
// Long description.
BINDING_LONG_DESC(
"This program implements the DBSCAN algorithm for clustering using "
"accelerated tree-based range search. The type of tree that is used "
"may be parameterized, or brute-force range search may also be used."
@@ -58,19 +63,23 @@ PROGRAM_INFO("DBSCAN clustering",
" 'hilbert-r', 'r-plus', 'r-plus-plus', 'cover', 'ball'. The " +
PRINT_PARAM_STRING("single_mode") + " parameter will force single-tree "
"search (as opposed to the default dual-tree search), and '" +
PRINT_PARAM_STRING("naive") + " will force brute-force range search.",
// Example.
PRINT_PARAM_STRING("naive") + " will force brute-force range search.");
// Example.
BINDING_EXAMPLE(
"An example usage to run DBSCAN on the dataset in " +
PRINT_DATASET("input") + " with a radius of 0.5 and a minimum cluster size"
" of 5 is given below:"
"\n\n" +
PRINT_CALL("dbscan", "input", "input", "epsilon", 0.5, "min_size", 5),
SEE_ALSO("DBSCAN on Wikipedia", "https://en.wikipedia.org/wiki/DBSCAN"),
SEE_ALSO("A density-based algorithm for discovering clusters in large "
PRINT_CALL("dbscan", "input", "input", "epsilon", 0.5, "min_size", 5));
// See also...
BINDING_SEE_ALSO("DBSCAN on Wikipedia", "https://en.wikipedia.org/wiki/DBSCAN");
BINDING_SEE_ALSO("A density-based algorithm for discovering clusters in large "
"spatial databases with noise (pdf)",
"http://www.aaai.org/Papers/KDD/1996/KDD96-037.pdf"),
SEE_ALSO("mlpack::dbscan::DBSCAN class documentation",
"@doxygen/classmlpack_1_1dbscan_1_1DBSCAN.html"));
"http://www.aaai.org/Papers/KDD/1996/KDD96-037.pdf");
BINDING_SEE_ALSO("mlpack::dbscan::DBSCAN class documentation",
"@doxygen/classmlpack_1_1dbscan_1_1DBSCAN.html");
PARAM_MATRIX_IN_REQ("input", "Input dataset to cluster.", "i");
PARAM_UROW_OUT("assignments", "Output matrix for assignments of each "
src/mlpack/methods/decision_stump/decision_stump_main.cpp
+17 -12
View File
@@ -21,12 +21,17 @@ using namespace mlpack::util;
using namespace std;
using namespace arma;
PROGRAM_INFO("Decision Stump",
// Short description.
// Program Name.
BINDING_NAME("Decision Stump");
// Short description.
BINDING_SHORT_DESC(
"An implementation of a decision stump, which is a single-level decision "
"tree. Given labeled data, a new decision stump can be trained; or, an "
"existing decision stump can be used to classify points.",
// Long description.
"existing decision stump can be used to classify points.");
// Long description.
BINDING_LONG_DESC(
"This program implements a decision stump, which is a single-level decision"
" tree. The decision stump will split on one dimension of the input data, "
"and will split into multiple buckets. The dimension and bins are selected"
@@ -66,14 +71,14 @@ PROGRAM_INFO("Decision Stump",
"\n\n"
"After training, a decision stump can be saved with the " +
PRINT_PARAM_STRING("output_model") + " output parameter. That stump may "
"later be re-used in subsequent calls to this program (or others).",
// Example.
"",
SEE_ALSO("Decision tree", "#decision_tree"),
SEE_ALSO("Decision stumps on Wikipedia",
"https://en.wikipedia.org/wiki/Decision_stump"),
SEE_ALSO("mlpack::decision_stump::DecisionStump class documentation",
"@doxygen/classmlpack_1_1decision__stump_1_1DecisionStump.html"));
"later be re-used in subsequent calls to this program (or others).");
// See also...
BINDING_SEE_ALSO("Decision tree", "#decision_tree");
BINDING_SEE_ALSO("Decision stumps on Wikipedia",
"https://en.wikipedia.org/wiki/Decision_stump");
BINDING_SEE_ALSO("mlpack::decision_stump::DecisionStump class documentation",
"@doxygen/classmlpack_1_1decision__stump_1_1DecisionStump.html");
// Datasets we might load.
PARAM_MATRIX_IN("training", "The dataset to train on.", "t");
src/mlpack/methods/decision_tree/decision_tree_main.cpp
+24 -15
View File
@@ -20,13 +20,18 @@ using namespace mlpack::tree;
using namespace mlpack::data;
using namespace mlpack::util;
PROGRAM_INFO("Decision tree",
// Short description.
// Program Name.
BINDING_NAME("Decision tree");
// Short description.
BINDING_SHORT_DESC(
"An implementation of an ID3-style decision tree for classification, which"
" supports categorical data. Given labeled data with numeric or "
"categorical features, a decision tree can be trained and saved; or, an "
"existing decision tree can be used for classification on new points.",
// Long description.
"existing decision tree can be used for classification on new points.");
// Long description.
BINDING_LONG_DESC(
"Train and evaluate using a decision tree. Given a dataset containing "
"numeric or categorical features, and associated labels for each point in "
"the dataset, this program can train a decision tree on that data."
@@ -59,8 +64,10 @@ PROGRAM_INFO("Decision tree",
" parameter. Predictions for each test point may be saved via the " +
PRINT_PARAM_STRING("predictions") + " output parameter. Class "
"probabilities for each prediction may be saved with the " +
PRINT_PARAM_STRING("probabilities") + " output parameter.",
// Example.
PRINT_PARAM_STRING("probabilities") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to train a decision tree with a minimum leaf size of 20 on "
"the dataset contained in " + PRINT_DATASET("data") + " with labels " +
PRINT_DATASET("labels") + ", saving the output model to " +
@@ -78,15 +85,17 @@ PROGRAM_INFO("Decision tree",
PRINT_DATASET("predictions") + ", one could call "
"\n\n" +
PRINT_CALL("decision_tree", "input_model", "tree", "test", "test_set",
"test_labels", "test_labels", "predictions", "predictions"),
SEE_ALSO("Decision stump", "#decision_stump"),
SEE_ALSO("Random forest", "#random_forest"),
SEE_ALSO("Decision trees on Wikipedia",
"https://en.wikipedia.org/wiki/Decision_tree_learning"),
SEE_ALSO("Induction of Decision Trees (pdf)",
"https://link.springer.com/content/pdf/10.1007/BF00116251.pdf"),
SEE_ALSO("mlpack::tree::DecisionTree class documentation",
"@doxygen/classmlpack_1_1tree_1_1DecisionTree.html"));
"test_labels", "test_labels", "predictions", "predictions"));
// See also...
BINDING_SEE_ALSO("Decision stump", "#decision_stump");
BINDING_SEE_ALSO("Random forest", "#random_forest");
BINDING_SEE_ALSO("Decision trees on Wikipedia",
"https://en.wikipedia.org/wiki/Decision_tree_learning");
BINDING_SEE_ALSO("Induction of Decision Trees (pdf)",
"https://link.springer.com/content/pdf/10.1007/BF00116251.pdf");
BINDING_SEE_ALSO("mlpack::tree::DecisionTree class documentation",
"@doxygen/classmlpack_1_1tree_1_1DecisionTree.html");
// Datasets.
PARAM_MATRIX_AND_INFO_IN("training", "Training dataset (may be categorical).",
src/mlpack/methods/det/det_main.cpp
+20 -15
View File
@@ -19,12 +19,17 @@ using namespace mlpack::det;
using namespace mlpack::util;
using namespace std;
PROGRAM_INFO("Density Estimation With Density Estimation Trees",
// Short description.
// Program Name.
BINDING_NAME("Density Estimation With Density Estimation Trees");
// Short description.
BINDING_SHORT_DESC(
"An implementation of density estimation trees for the density estimation "
"task. Density estimation trees can be trained or used to predict the "
"density at locations given by query points.",
// Long description.
"density at locations given by query points.");
// Long description.
BINDING_LONG_DESC(
"This program performs a number of functions related to Density Estimation "
"Trees. The optimal Density Estimation Tree (DET) can be trained on a set "
"of data (specified by " + PRINT_PARAM_STRING("training") + ") using "
@@ -54,17 +59,17 @@ PROGRAM_INFO("Density Estimation With Density Estimation Trees",
"trained on the given training points, or a tree given as the parameter " +
PRINT_PARAM_STRING("input_model") + ". The density estimates for the test"
" points may be saved using the " +
PRINT_PARAM_STRING("test_set_estimates") + " output parameter.",
// Example.
"",
SEE_ALSO("Density estimation tree (DET) tutorial",
"@doxygen/dettutorial.html"),
SEE_ALSO("Density estimation on Wikipedia",
"https://en.wikipedia.org/wiki/Density_estimation"),
SEE_ALSO("Density estimation trees (pdf)",
"http://www.mlpack.org/papers/det.pdf"),
SEE_ALSO("mlpack::tree::DTree class documentation",
"@doxygen/classmlpack_1_1det_1_1DTree.html"));
PRINT_PARAM_STRING("test_set_estimates") + " output parameter.");
// See also...
BINDING_SEE_ALSO("Density estimation tree (DET) tutorial",
"@doxygen/dettutorial.html");
BINDING_SEE_ALSO("Density estimation on Wikipedia",
"https://en.wikipedia.org/wiki/Density_estimation");
BINDING_SEE_ALSO("Density estimation trees (pdf)",
"http://www.mlpack.org/papers/det.pdf");
BINDING_SEE_ALSO("mlpack::tree::DTree class documentation",
"@doxygen/classmlpack_1_1det_1_1DTree.html");
// Input data files.
PARAM_MATRIX_IN("training", "The data set on which to build a density "
src/mlpack/methods/emst/emst_main.cpp
+23 -14
View File
@@ -30,11 +30,16 @@
#include "dtb.hpp"
PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree",
// Short description.
// Program Name.
BINDING_NAME("Fast Euclidean Minimum Spanning Tree");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the Dual-Tree Boruvka algorithm for computing the "
"Euclidean minimum spanning tree of a set of input points.",
// Long description.
"Euclidean minimum spanning tree of a set of input points.");
// Long description.
BINDING_LONG_DESC(
"This program can compute the Euclidean minimum spanning tree of a set of "
"input points using the dual-tree Boruvka algorithm."
"\n\n"
@@ -47,8 +52,10 @@ PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree",
"and if the " + PRINT_PARAM_STRING("naive") + " option is given, then "
"brute-force search is used (this is typically much slower in low "
"dimensions). The leaf size does not affect the results, but it may have "
"some effect on the runtime of the algorithm.",
// Example.
"some effect on the runtime of the algorithm.");
// Example.
BINDING_EXAMPLE(
"For example, the minimum spanning tree of the input dataset " +
PRINT_DATASET("data") + " can be calculated with a leaf size of 20 and "
"stored as " + PRINT_DATASET("spanning_tree") + " using the following "
@@ -60,14 +67,16 @@ PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree",
"The output matrix is a three-dimensional matrix, where each row indicates "
"an edge. The first dimension corresponds to the lesser index of the edge;"
" the second dimension corresponds to the greater index of the edge; and "
"the third column corresponds to the distance between the two points.",
SEE_ALSO("EMST Tutorial", "@doxygen/emst_tutorial.html"),
SEE_ALSO("Minimum spanning tree on Wikipedia",
"https://en.wikipedia.org/wiki/Minimum_spanning_tree"),
SEE_ALSO("Fast Euclidean Minimum Spanning Tree: Algorithm, Analysis, and "
"Applications (pdf)", "http://www.mlpack.org/papers/emst.pdf"),
SEE_ALSO("mlpack::emst::DualTreeBoruvka class documentation",
"@doxygen/classmlpack_1_1emst_1_1DualTreeBoruvka.html"));
"the third column corresponds to the distance between the two points.");
// See also...
BINDING_SEE_ALSO("EMST Tutorial", "@doxygen/emst_tutorial.html");
BINDING_SEE_ALSO("Minimum spanning tree on Wikipedia",
"https://en.wikipedia.org/wiki/Minimum_spanning_tree");
BINDING_SEE_ALSO("Fast Euclidean Minimum Spanning Tree: Algorithm, Analysis,"
" and Applications (pdf)", "http://www.mlpack.org/papers/emst.pdf");
BINDING_SEE_ALSO("mlpack::emst::DualTreeBoruvka class documentation",
"@doxygen/classmlpack_1_1emst_1_1DualTreeBoruvka.html");
PARAM_MATRIX_IN_REQ("input", "Input data matrix.", "i");
PARAM_MATRIX_OUT("output", "Output data. Stored as an edge list.", "o");
src/mlpack/methods/fastmks/fastmks_main.cpp
+23 -14
View File
@@ -24,20 +24,27 @@ using namespace mlpack::tree;
using namespace mlpack::metric;
using namespace mlpack::util;
PROGRAM_INFO("FastMKS (Fast Max-Kernel Search)",
// Short description.
// Program Name.
BINDING_NAME("FastMKS (Fast Max-Kernel Search)");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the single-tree and dual-tree fast max-kernel search"
" (FastMKS) algorithm. Given a set of reference points and a set of query"
" points, this can find the reference point with maximum kernel value for "
"each query point; trained models can be reused for future queries.",
// Long description.
"each query point; trained models can be reused for future queries.");
// Long description.
BINDING_LONG_DESC(
"This program will find the k maximum kernels of a set of points, "
"using a query set and a reference set (which can optionally be the same "
"set). More specifically, for each point in the query set, the k points in"
" the reference set with maximum kernel evaluations are found. The kernel "
"function used is specified with the " + PRINT_PARAM_STRING("kernel") +
" parameter.",
// Example.
" parameter.");
// Example.
BINDING_EXAMPLE(
"For example, the following command will calculate, for each point in the "
"query set " + PRINT_DATASET("query") + ", the five points in the "
"reference set " + PRINT_DATASET("reference") + " with maximum kernel "
@@ -57,14 +64,16 @@ PROGRAM_INFO("FastMKS (Fast Max-Kernel Search)",
"\n\n"
"This program performs FastMKS using a cover tree. The base used to build "
"the cover tree can be specified with the " + PRINT_PARAM_STRING("base") +
" parameter.",
SEE_ALSO("Fast max-kernel search tutorial (fastmks)",
"@doxygen/fmkstutorial.html"),
SEE_ALSO("k-nearest-neighbor search", "#knn"),
SEE_ALSO("Dual-tree Fast Exact Max-Kernel Search (pdf)",
"http://mlpack.org/papers/fmks.pdf"),
SEE_ALSO("mlpack::fastmks::FastMKS class documentation",
"@doxygen/classmlpack_1_1fastmks_1_1FastMKS.html"));
" parameter.");
// See also...
BINDING_SEE_ALSO("Fast max-kernel search tutorial (fastmks)",
"@doxygen/fmkstutorial.html");
BINDING_SEE_ALSO("k-nearest-neighbor search", "#knn");
BINDING_SEE_ALSO("Dual-tree Fast Exact Max-Kernel Search (pdf)",
"http://mlpack.org/papers/fmks.pdf");
BINDING_SEE_ALSO("mlpack::fastmks::FastMKS class documentation",
"@doxygen/classmlpack_1_1fastmks_1_1FastMKS.html");
// Model-building parameters.
PARAM_MATRIX_IN("reference", "The reference dataset.", "r");
src/mlpack/methods/gmm/gmm_generate_main.cpp
+22 -13
View File
@@ -19,30 +19,39 @@ using namespace mlpack;
using namespace mlpack::gmm;
using namespace mlpack::util;
PROGRAM_INFO("GMM Sample Generator",
// Short description.
// Program Name.
BINDING_NAME("GMM Sample Generator");
// Short description.
BINDING_SHORT_DESC(
"A sample generator for pre-trained GMMs. Given a pre-trained GMM, this "
"can sample new points randomly from that distribution.",
// Long description.
"can sample new points randomly from that distribution.");
// Long description.
BINDING_LONG_DESC(
"This program is able to generate samples from a pre-trained GMM (use "
"gmm_train to train a GMM). The pre-trained GMM must be specified with "
"the " + PRINT_PARAM_STRING("input_model") + " parameter. The number "
"of samples to generate is specified by the " +
PRINT_PARAM_STRING("samples") + " parameter. Output samples may be "
"saved with the " + PRINT_PARAM_STRING("output") + " output parameter.",
// Example.
"saved with the " + PRINT_PARAM_STRING("output") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"The following command can be used to generate 100 samples from the pre-"
"trained GMM " + PRINT_MODEL("gmm") + " and store those generated "
"samples in " + PRINT_DATASET("samples") + ":"
"\n\n" +
PRINT_CALL("gmm_generate", "input_model", "gmm", "samples", 100, "output",
"samples"),
SEE_ALSO("@gmm_train", "#gmm_train"),
SEE_ALSO("@gmm_probability", "#gmm_probability"),
SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"),
SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html"));
"samples"));
// See also...
BINDING_SEE_ALSO("@gmm_train", "#gmm_train");
BINDING_SEE_ALSO("@gmm_probability", "#gmm_probability");
BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model");
BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html");
PARAM_MODEL_IN_REQ(GMM, "input_model", "Input GMM model to generate samples "
"from.", "m");
src/mlpack/methods/gmm/gmm_probability_main.cpp
+22 -13
View File
@@ -19,32 +19,41 @@ using namespace mlpack;
using namespace mlpack::gmm;
using namespace mlpack::util;
PROGRAM_INFO("GMM Probability Calculator",
// Short description.
// Program Name.
BINDING_NAME("GMM Probability Calculator");
// Short description.
BINDING_SHORT_DESC(
"A probability calculator for GMMs. Given a pre-trained GMM and a set of "
"points, this can compute the probability that each point is from the given"
" GMM.",
// Long description.
" GMM.");
// Long description.
BINDING_LONG_DESC(
"This program calculates the probability that given points came from a "
"given GMM (that is, P(X | gmm)). The GMM is specified with the " +
PRINT_PARAM_STRING("input_model") + " parameter, and the points are "
"specified with the " + PRINT_PARAM_STRING("input") + " parameter. The "
"output probabilities may be saved via the " +
PRINT_PARAM_STRING("output") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"So, for example, to calculate the probabilities of each point in " +
PRINT_DATASET("points") + " coming from the pre-trained GMM " +
PRINT_MODEL("gmm") + ", while storing those probabilities in " +
PRINT_DATASET("probs") + ", the following command could be used:"
"\n\n" +
PRINT_CALL("gmm_probability", "input_model", "gmm", "input", "points",
"output", "probs"),
SEE_ALSO("@gmm_train", "#gmm_train"),
SEE_ALSO("@gmm_generate", "#gmm_generate"),
SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"),
SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html"));
"output", "probs"));
// See also...
BINDING_SEE_ALSO("@gmm_train", "#gmm_train");
BINDING_SEE_ALSO("@gmm_generate", "#gmm_generate");
BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model");
BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html");
PARAM_MODEL_IN_REQ(GMM, "input_model", "Input GMM to use as model.", "m");
PARAM_MATRIX_IN_REQ("input", "Input matrix to calculate probabilities of.",
src/mlpack/methods/gmm/gmm_train_main.cpp
+22 -13
View File
@@ -26,12 +26,17 @@ using namespace mlpack::util;
using namespace mlpack::kmeans;
using namespace std;
PROGRAM_INFO("Gaussian Mixture Model (GMM) Training",
// Short description.
// Program Name.
BINDING_NAME("Gaussian Mixture Model (GMM) Training");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the EM algorithm for training Gaussian mixture "
"models (GMMs). Given a dataset, this can train a GMM for future use "
"with other tools.",
// Long description.
"with other tools.");
// Long description.
BINDING_LONG_DESC(
"This program takes a parametric estimate of a Gaussian mixture model (GMM)"
" using the EM algorithm to find the maximum likelihood estimate. The "
"model may be saved and reused by other mlpack GMM tools."
@@ -77,8 +82,10 @@ PROGRAM_INFO("Gaussian Mixture Model (GMM) Training",
"will avoid the checks after each iteration of the EM algorithm which "
"ensure that the covariance matrices are positive definite. Specifying "
"the flag can cause faster runtime, but may also cause non-positive "
"definite covariance matrices, which will cause the program to crash.",
// Example.
"definite covariance matrices, which will cause the program to crash.");
// Example.
BINDING_EXAMPLE(
"As an example, to train a 6-Gaussian GMM on the data in " +
PRINT_DATASET("data") + " with a maximum of 100 iterations of EM and 3 "
"trials, saving the trained GMM to " + PRINT_MODEL("gmm") + ", the "
@@ -91,13 +98,15 @@ PROGRAM_INFO("Gaussian Mixture Model (GMM) Training",
", the following command may be used: "
"\n\n" +
PRINT_CALL("gmm_train", "input_model", "gmm", "input", "data2",
"gaussians", 6, "output_model", "new_gmm"),
SEE_ALSO("@gmm_generate", "#gmm_generate"),
SEE_ALSO("@gmm_probability", "#gmm_probability"),
SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model"),
SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html"));
"gaussians", 6, "output_model", "new_gmm"));
// See also...
BINDING_SEE_ALSO("@gmm_generate", "#gmm_generate");
BINDING_SEE_ALSO("@gmm_probability", "#gmm_probability");
BINDING_SEE_ALSO("Gaussian Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Mixture_model#Gaussian_mixture_model");
BINDING_SEE_ALSO("mlpack::gmm::GMM class documentation",
"@doxygen/classmlpack_1_1gmm_1_1GMM.html");
// Parameters for training.
PARAM_MATRIX_IN_REQ("input", "The training data on which the model will be "
src/mlpack/methods/hmm/hmm_generate_main.cpp
+23 -14
View File
@@ -30,12 +30,17 @@ using namespace mlpack::math;
using namespace arma;
using namespace std;
PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Generator",
// Short description.
// Program Name.
BINDING_NAME("Hidden Markov Model (HMM) Sequence Generator");
// Short description.
BINDING_SHORT_DESC(
"A utility to generate random sequences from a pre-trained Hidden Markov "
"Model (HMM). The length of the desired sequence can be specified, and a "
"random sequence of observations is returned.",
// Long description.
"random sequence of observations is returned.");
// Long description.
BINDING_LONG_DESC(
"This utility takes an already-trained HMM, specified as the " +
PRINT_PARAM_STRING("model") + " parameter, and generates a random "
"observation sequence and hidden state sequence based on its parameters. "
@@ -45,22 +50,26 @@ PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Generator",
" parameter."
"\n\n"
"The state to start the sequence in may be specified with the " +
PRINT_PARAM_STRING("start_state") + " parameter.",
// Example.
PRINT_PARAM_STRING("start_state") + " parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to generate a sequence of length 150 from the HMM " +
PRINT_MODEL("hmm") + " and save the observation sequence to " +
PRINT_DATASET("observations") + " and the hidden state sequence to " +
PRINT_DATASET("states") + ", the following command may be used: "
"\n\n" +
PRINT_CALL("hmm_generate", "model", "hmm", "length", 150, "output",
"observations", "state", "states"),
SEE_ALSO("@hmm_train", "#hmm_train"),
SEE_ALSO("@hmm_loglik", "#hmm_loglik"),
SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"),
SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model"),
SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html"));
"observations", "state", "states"));
// See also...
BINDING_SEE_ALSO("@hmm_train", "#hmm_train");
BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik");
BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi");
BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model");
BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html");
PARAM_MODEL_IN_REQ(HMMModel, "model", "Trained HMM to generate sequences with.",
"m");
src/mlpack/methods/hmm/hmm_loglik_main.cpp
+23 -14
View File
@@ -27,31 +27,40 @@ using namespace mlpack::gmm;
using namespace arma;
using namespace std;
PROGRAM_INFO("Hidden Markov Model (HMM) Sequence Log-Likelihood",
// Short description.
// Program Name.
BINDING_NAME("Hidden Markov Model (HMM) Sequence Log-Likelihood");
// Short description.
BINDING_SHORT_DESC(
"A utility for computing the log-likelihood of a sequence for Hidden Markov"
" Models (HMMs). Given a pre-trained HMM and an observation sequence, this"
" computes and returns the log-likelihood of that sequence being observed "
"from that HMM.",
// Long description.
"from that HMM.");
// Long description.
BINDING_LONG_DESC(
"This utility takes an already-trained HMM, specified with the " +
PRINT_PARAM_STRING("input_model") + " parameter, and evaluates the "
"log-likelihood of a sequence of observations, given with the " +
PRINT_PARAM_STRING("input") + " parameter. The computed log-likelihood is"
" given as output.",
// Example.
" given as output.");
// Example.
BINDING_EXAMPLE(
"For example, to compute the log-likelihood of the sequence " +
PRINT_DATASET("seq") + " with the pre-trained HMM " + PRINT_MODEL("hmm") +
", the following command may be used: "
"\n\n" +
PRINT_CALL("hmm_loglik", "input", "seq", "input_model", "hmm"),
SEE_ALSO("@hmm_train", "#hmm_train"),
SEE_ALSO("@hmm_generate", "#hmm_generate"),
SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"),
SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model"),
SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html"));
PRINT_CALL("hmm_loglik", "input", "seq", "input_model", "hmm"));
// See also...
BINDING_SEE_ALSO("@hmm_train", "#hmm_train");
BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate");
BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi");
BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model");
BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html");
PARAM_MATRIX_IN_REQ("input", "File containing observations,", "i");
PARAM_MODEL_IN_REQ(HMMModel, "input_model", "File containing HMM.", "m");
src/mlpack/methods/hmm/hmm_train_main.cpp
+19 -14
View File
@@ -28,12 +28,17 @@ using namespace mlpack::math;
using namespace arma;
using namespace std;
PROGRAM_INFO("Hidden Markov Model (HMM) Training",
// Short description.
// Program Name.
BINDING_NAME("Hidden Markov Model (HMM) Training");
// Short description.
BINDING_SHORT_DESC(
"An implementation of training algorithms for Hidden Markov Models (HMMs). "
"Given labeled or unlabeled data, an HMM can be trained for further use "
"with other mlpack HMM tools.",
// Long description.
"with other mlpack HMM tools.");
// Long description.
BINDING_LONG_DESC(
"This program allows a Hidden Markov Model to be trained on labeled or "
"unlabeled data. It supports four types of HMMs: Discrete HMMs, "
"Gaussian HMMs, GMM HMMs, or Diagonal GMM HMMs"
@@ -57,16 +62,16 @@ PROGRAM_INFO("Hidden Markov Model (HMM) Training",
"\n\n"
"Optionally, a pre-created HMM model can be used as a guess for the "
"transition matrix and emission probabilities; this is specifiable with " +
PRINT_PARAM_STRING("output_model") + ".",
// Example.
"",
SEE_ALSO("@hmm_generate", "#hmm_generate"),
SEE_ALSO("@hmm_loglik", "#hmm_loglik"),
SEE_ALSO("@hmm_viterbi", "#hmm_viterbi"),
SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model"),
SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html"));
PRINT_PARAM_STRING("output_model") + ".");
// See also...
BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate");
BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik");
BINDING_SEE_ALSO("@hmm_viterbi", "#hmm_viterbi");
BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model");
BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html");
PARAM_STRING_IN_REQ("input_file", "File containing input observations.", "i");
PARAM_STRING_IN("type", "Type of HMM: discrete | gaussian | diag_gmm | gmm.",
src/mlpack/methods/hmm/hmm_viterbi_main.cpp
+23 -14
View File
@@ -28,34 +28,43 @@ using namespace mlpack::gmm;
using namespace arma;
using namespace std;
PROGRAM_INFO("Hidden Markov Model (HMM) Viterbi State Prediction",
// Short description.
// Program Name.
BINDING_NAME("Hidden Markov Model (HMM) Viterbi State Prediction");
// Short description.
BINDING_SHORT_DESC(
"A utility for computing the most probable hidden state sequence for Hidden"
" Markov Models (HMMs). Given a pre-trained HMM and an observed sequence, "
"this uses the Viterbi algorithm to compute and return the most probable "
"hidden state sequence.",
// Long description.
"hidden state sequence.");
// Long description.
BINDING_LONG_DESC(
"This utility takes an already-trained HMM, specified as " +
PRINT_PARAM_STRING("input_model") + ", and evaluates the most probable "
"hidden state sequence of a given sequence of observations (specified as "
"'" + PRINT_PARAM_STRING("input") + ", using the Viterbi algorithm. The "
"computed state sequence may be saved using the " +
PRINT_PARAM_STRING("output") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to predict the state sequence of the observations " +
PRINT_DATASET("obs") + " using the HMM " + PRINT_MODEL("hmm") + ", "
"storing the predicted state sequence to " + PRINT_DATASET("states") +
", the following command could be used:"
"\n\n" +
PRINT_CALL("hmm_viterbi", "input", "obs", "input_model", "hmm", "output",
"states"),
SEE_ALSO("@hmm_train", "#hmm_train"),
SEE_ALSO("@hmm_generate", "#hmm_generate"),
SEE_ALSO("@hmm_loglik", "#hmm_loglik"),
SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model"),
SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html"));
"states"));
// See also...
BINDING_SEE_ALSO("@hmm_train", "#hmm_train");
BINDING_SEE_ALSO("@hmm_generate", "#hmm_generate");
BINDING_SEE_ALSO("@hmm_loglik", "#hmm_loglik");
BINDING_SEE_ALSO("Hidden Mixture Models on Wikipedia",
"https://en.wikipedia.org/wiki/Hidden_Markov_model");
BINDING_SEE_ALSO("mlpack::hmm::HMM class documentation",
"@doxygen/classmlpack_1_1hmm_1_1HMM.html");
PARAM_MATRIX_IN_REQ("input", "Matrix containing observations,", "i");
PARAM_MODEL_IN_REQ(HMMModel, "input_model", "Trained HMM to use.", "m");
src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp
+22 -13
View File
@@ -25,13 +25,18 @@ using namespace mlpack::tree;
using namespace mlpack::data;
using namespace mlpack::util;
PROGRAM_INFO("Hoeffding trees",
// Short description.
// Program Name.
BINDING_NAME("Hoeffding trees");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Hoeffding trees, a form of streaming decision tree "
"for classification. Given labeled data, a Hoeffding tree can be trained "
"and saved for later use, or a pre-trained Hoeffding tree can be used for "
"predicting the classifications of new points.",
// Long description.
"predicting the classifications of new points.");
// Long description.
BINDING_LONG_DESC(
"This program implements Hoeffding trees, a form of streaming decision tree"
" suited best for large (or streaming) datasets. This program supports "
"both categorical and numeric data. Given an input dataset, this program "
@@ -61,8 +66,10 @@ PROGRAM_INFO("Hoeffding trees",
" parameter. Predictions for each test point may be saved with the " +
PRINT_PARAM_STRING("predictions") + " output parameter, and class "
"probabilities for each prediction may be saved with the " +
PRINT_PARAM_STRING("probabilities") + " output parameter.",
// Example.
PRINT_PARAM_STRING("probabilities") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to train a Hoeffding tree with confidence 0.99 with data " +
PRINT_DATASET("dataset") + ", saving the trained tree to " +
PRINT_MODEL("tree") + ", the following command may be used:"
@@ -76,13 +83,15 @@ PROGRAM_INFO("Hoeffding trees",
PRINT_DATASET("class_probs") + " with the following command: "
"\n\n" +
PRINT_CALL("hoeffding_tree", "input_model", "tree", "test", "test_set",
"predictions", "predictions", "probabilities", "class_probs"),
SEE_ALSO("@decision_tree", "#decision_tree"),
SEE_ALSO("@random_forest", "#random_forest"),
SEE_ALSO("Mining High-Speed Data Streams (pdf)",
"http://dm.cs.washington.edu/papers/vfdt-kdd00.pdf"),
SEE_ALSO("mlpack::tree::HoeffdingTree class documentation",
"@doxygen/classmlpack_1_1tree_1_1HoeffdingTree.html"));
"predictions", "predictions", "probabilities", "class_probs"));
// See also...
BINDING_SEE_ALSO("@decision_tree", "#decision_tree");
BINDING_SEE_ALSO("@random_forest", "#random_forest");
BINDING_SEE_ALSO("Mining High-Speed Data Streams (pdf)",
"http://dm.cs.washington.edu/papers/vfdt-kdd00.pdf");
BINDING_SEE_ALSO("mlpack::tree::HoeffdingTree class documentation",
"@doxygen/classmlpack_1_1tree_1_1HoeffdingTree.html");
PARAM_MATRIX_AND_INFO_IN("training", "Training dataset (may be categorical).",
"t");
src/mlpack/methods/kde/kde_main.cpp
+26 -18
View File
@@ -22,14 +22,18 @@ using namespace mlpack::kde;
using namespace mlpack::util;
using namespace std;
// Define parameters for the executable.
PROGRAM_INFO("Kernel Density Estimation",
// Short description.
// Program Name.
BINDING_NAME("Kernel Density Estimation");
// Short description.
BINDING_SHORT_DESC(
"An implementation of kernel density estimation with dual-tree algorithms. "
"Given a set of reference points and query points and a kernel function, "
"this can estimate the density function at the location of each query point"
" using trees; trees that are built can be saved for later use.",
// Long description.
" using trees; trees that are built can be saved for later use.");
// Long description.
BINDING_LONG_DESC(
"This program performs a Kernel Density Estimation. KDE is a "
"non-parametric way of estimating probability density function. "
"For each query point the program will estimate its probability density "
@@ -68,8 +72,10 @@ PROGRAM_INFO("Kernel Density Estimation",
"computations an exact approach would take, this program recurses the tree "
"whenever a fraction of the amount of the node's descendant points have "
"already been computed. This fraction is set using " +
PRINT_PARAM_STRING("mc_break_coef") + ".",
// Example.
PRINT_PARAM_STRING("mc_break_coef") + ".");
// Example.
BINDING_EXAMPLE(
"For example, the following will run KDE using the data in " +
PRINT_DATASET("ref_data") + " for training and the data in " +
PRINT_DATASET("qu_data") + " as query data. It will apply an Epanechnikov "
@@ -108,18 +114,20 @@ PROGRAM_INFO("Kernel Density Estimation",
0.2, "kernel", "gaussian", "tree", "kd-tree", "rel_error",
0.05, "predictions", "out_data", "monte_carlo", "", "mc_probability",
0.95, "initial_sample_size", 200, "mc_entry_coef", 3.5, "mc_break_coef",
0.6),
SEE_ALSO("@knn", "#knn"),
SEE_ALSO("Kernel density estimation on Wikipedia",
"https://en.wikipedia.org/wiki/Kernel_density_estimation"),
SEE_ALSO("Tree-Independent Dual-Tree Algorithms",
"https://arxiv.org/pdf/1304.4327.pdf"),
SEE_ALSO("Fast High-dimensional Kernel Summations Using the Monte Carlo "
"Multipole Method", "http://papers.nips.cc/paper/3539-fast-high-"
0.6));
// See also...
BINDING_SEE_ALSO("@knn", "#knn");
BINDING_SEE_ALSO("Kernel density estimation on Wikipedia",
"https://en.wikipedia.org/wiki/Kernel_density_estimation");
BINDING_SEE_ALSO("Tree-Independent Dual-Tree Algorithms",
"https://arxiv.org/pdf/1304.4327.pdf");
BINDING_SEE_ALSO("Fast High-dimensional Kernel Summations Using the Monte Carlo"
" Multipole Method", "http://papers.nips.cc/paper/3539-fast-high-"
"dimensional-kernel-summations-using-the-monte-carlo-multipole-method."
"pdf"),
SEE_ALSO("mlpack::kde::KDE C++ class documentation",
"@doxygen/classmlpack_1_1kde_1_1KDE.html"));
"pdf");
BINDING_SEE_ALSO("mlpack::kde::KDE C++ class documentation",
"@doxygen/classmlpack_1_1kde_1_1KDE.html");
// Required options.
PARAM_MATRIX_IN("reference", "Input reference dataset use for KDE.", "r");
src/mlpack/methods/kernel_pca/kernel_pca_main.cpp
+22 -14
View File
@@ -40,12 +40,17 @@ using namespace mlpack::util;
using namespace std;
using namespace arma;
PROGRAM_INFO("Kernel Principal Components Analysis",
// Short description.
// Program Name.
BINDING_NAME("Kernel Principal Components Analysis");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Kernel Principal Components Analysis (KPCA). This "
"can be used to perform nonlinear dimensionality reduction or preprocessing"
" on a given dataset.",
// Long description.
" on a given dataset.");
// Long description.
BINDING_LONG_DESC(
"This program performs Kernel Principal Components Analysis (KPCA) on the "
"specified dataset with the specified kernel. This will transform the "
"data onto the kernel principal components, and optionally reduce the "
@@ -91,21 +96,24 @@ PROGRAM_INFO("Kernel Principal Components Analysis",
"the kernel matrix; to specify the sampling scheme, the " +
PRINT_PARAM_STRING("sampling") + " parameter is used. The "
"sampling scheme for the Nystroem method can be chosen from the "
"following list: 'kmeans', 'random', 'ordered'.",
// Example.
"following list: 'kmeans', 'random', 'ordered'.");
// Example.
BINDING_EXAMPLE(
"For example, the following command will perform KPCA on the dataset " +
PRINT_DATASET("input") + " using the Gaussian kernel, and saving the "
"transformed data to " + PRINT_DATASET("transformed") + ": "
"\n\n" +
PRINT_CALL("kernel_pca", "input", "input", "kernel", "gaussian", "output",
"transformed"),
// See also...
SEE_ALSO("Kernel principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Kernel_principal_component_analysis"),
SEE_ALSO("Kernel Principal Component Analysis (pdf)",
"http://pca.narod.ru/scholkopf_kernel.pdf"),
SEE_ALSO("mlpack::kpca::KernelPCA class documentation",
"@doxygen/classmlpack_1_1kpca_1_1KernelPCA.html"));
"transformed"));
// See also...
BINDING_SEE_ALSO("Kernel principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Kernel_principal_component_analysis");
BINDING_SEE_ALSO("Kernel Principal Component Analysis (pdf)",
"http://pca.narod.ru/scholkopf_kernel.pdf");
BINDING_SEE_ALSO("mlpack::kpca::KernelPCA class documentation",
"@doxygen/classmlpack_1_1kpca_1_1KernelPCA.html");
PARAM_MATRIX_IN_REQ("input", "Input dataset to perform KPCA on.", "i");
PARAM_MATRIX_OUT("output", "Matrix to save modified dataset to.", "o");
src/mlpack/methods/kmeans/kmeans_main.cpp
+29 -21
View File
@@ -27,13 +27,17 @@ using namespace mlpack::kmeans;
using namespace mlpack::util;
using namespace std;
// Define parameters for the executable.
PROGRAM_INFO("K-Means Clustering",
// Short description.
// Program Name.
BINDING_NAME("K-Means Clustering");
// Short description.
BINDING_SHORT_DESC(
"An implementation of several strategies for efficient k-means clustering. "
"Given a dataset and a value of k, this computes and returns a k-means "
"clustering on that data.",
// Long description.
"clustering on that data.");
// Long description.
BINDING_LONG_DESC(
"This program performs K-Means clustering on the given dataset. It can "
"return the learned cluster assignments, and the centroids of the clusters."
" Empty clusters are not allowed by default; when a cluster becomes empty,"
@@ -74,8 +78,10 @@ PROGRAM_INFO("K-Means Clustering",
"Initial clustering assignments may be specified using the " +
PRINT_PARAM_STRING("initial_centroids") + " parameter, and the maximum "
"number of iterations may be specified with the " +
PRINT_PARAM_STRING("max_iterations") + " parameter.",
// Example.
PRINT_PARAM_STRING("max_iterations") + " parameter.");
// Example.
BINDING_EXAMPLE(
"As an example, to use Hamerly's algorithm to perform k-means clustering "
"with k=10 on the dataset " + PRINT_DATASET("data") + ", saving the "
"centroids to " + PRINT_DATASET("centroids") + " and the assignments for "
@@ -91,21 +97,23 @@ PROGRAM_INFO("K-Means Clustering",
"following command may be used:"
"\n\n" +
PRINT_CALL("kmeans", "input", "data", "initial_centroids", "initial",
"clusters", 10, "max_iterations", 500, "centroid", "final"),
SEE_ALSO("K-Means tutorial", "@doxygen/kmtutorial.html"),
SEE_ALSO("@dbscan", "#dbscan"),
SEE_ALSO("Using the triangle inequality to accelerate k-means (pdf)",
"http://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf"),
SEE_ALSO("Making k-means even faster (pdf)",
"clusters", 10, "max_iterations", 500, "centroid", "final"));
// See also...
BINDING_SEE_ALSO("K-Means tutorial", "@doxygen/kmtutorial.html");
BINDING_SEE_ALSO("@dbscan", "#dbscan");
BINDING_SEE_ALSO("Using the triangle inequality to accelerate k-means (pdf)",
"http://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf");
BINDING_SEE_ALSO("Making k-means even faster (pdf)",
"http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.586.2554"
"&rep=rep1&type=pdf"),
SEE_ALSO("Accelerating exact k-means algorithms with geometric reasoning "
"(pdf)", "http://reports-archive.adm.cs.cmu.edu/anon/anon/usr/ftp/"
"usr0/ftp/2000/CMU-CS-00-105.pdf"),
SEE_ALSO("A dual-tree algorithm for fast k-means clustering with large k "
"(pdf)", "http://www.ratml.org/pub/pdf/2017dual.pdf"),
SEE_ALSO("mlpack::kmeans::KMeans class documentation",
"@doxygen/classmlpack_1_1kmeans_1_1KMeans.html"));
"&rep=rep1&type=pdf");
BINDING_SEE_ALSO("Accelerating exact k-means algorithms with geometric"
" reasoning (pdf)", "http://reports-archive.adm.cs.cmu.edu/anon/anon"
"/usr/ftp/usr0/ftp/2000/CMU-CS-00-105.pdf");
BINDING_SEE_ALSO("A dual-tree algorithm for fast k-means clustering with large "
"k (pdf)", "http://www.ratml.org/pub/pdf/2017dual.pdf");
BINDING_SEE_ALSO("mlpack::kmeans::KMeans class documentation",
"@doxygen/classmlpack_1_1kmeans_1_1KMeans.html");
// Required options.
PARAM_MATRIX_IN_REQ("input", "Input dataset to perform clustering on.", "i");
src/mlpack/methods/lars/lars_main.cpp
+21 -12
View File
@@ -21,13 +21,18 @@ using namespace mlpack;
using namespace mlpack::regression;
using namespace mlpack::util;
PROGRAM_INFO("LARS",
// Short description.
// Program Name.
BINDING_NAME("LARS");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Least Angle Regression (Stagewise/laSso), also known"
" as LARS. This can train a LARS/LASSO/Elastic Net model and use that "
"model or a pre-trained model to output regression predictions for a test "
"set.",
// Long description.
"set.");
// Long description.
BINDING_LONG_DESC(
"An implementation of LARS: Least Angle Regression (Stagewise/laSso). "
"This is a stage-wise homotopy-based algorithm for L1-regularized linear "
"regression (LASSO) and L1+L2-regularized linear regression (Elastic Net)."
@@ -70,8 +75,10 @@ PROGRAM_INFO("LARS",
"trained model or the given input model. Test points can be specified with"
" the " + PRINT_PARAM_STRING("test") + " parameter. Predicted responses "
"to the test points can be saved with the " +
PRINT_PARAM_STRING("output_predictions") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output_predictions") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, the following command trains a model on the data " +
PRINT_DATASET("data") + " and responses " + PRINT_DATASET("responses") +
" with lambda1 set to 0.4 and lambda2 set to 0 (so, LASSO is being "
@@ -86,12 +93,14 @@ PROGRAM_INFO("LARS",
"and save those responses to " + PRINT_DATASET("test_predictions") + ": "
"\n\n" +
PRINT_CALL("lars", "input_model", "lasso_model", "test", "test",
"output_predictions", "test_predictions"),
SEE_ALSO("@linear_regression", "#linear_regression"),
SEE_ALSO("Least angle regression (pdf)",
"http://mlpack.org/papers/lars.pdf"),
SEE_ALSO("mlpack::regression::LARS C++ class documentation",
"@doxygen/classmlpack_1_1regression_1_1LARS.html"));
"output_predictions", "test_predictions"));
// See also...
BINDING_SEE_ALSO("@linear_regression", "#linear_regression");
BINDING_SEE_ALSO("Least angle regression (pdf)",
"http://mlpack.org/papers/lars.pdf");
BINDING_SEE_ALSO("mlpack::regression::LARS C++ class documentation",
"@doxygen/classmlpack_1_1regression_1_1LARS.html");
PARAM_TMATRIX_IN("input", "Matrix of covariates (X).", "i");
PARAM_MATRIX_IN("responses", "Matrix of responses/observations (y).", "r");
src/mlpack/methods/linear_regression/linear_regression_main.cpp
+24 -13
View File
@@ -21,13 +21,18 @@ using namespace mlpack::util;
using namespace arma;
using namespace std;
PROGRAM_INFO("Simple Linear Regression and Prediction",
// Short description.
// Program Name.
BINDING_NAME("Simple Linear Regression and Prediction");
// Short description.
BINDING_SHORT_DESC(
"An implementation of simple linear regression and ridge regression using "
"ordinary least squares. Given a dataset and responses, a model can be "
"trained and saved for later use, or a pre-trained model can be used to "
"output regression predictions for a test set.",
// Long description.
"output regression predictions for a test set.");
// Long description.
BINDING_LONG_DESC(
"An implementation of simple linear regression and simple ridge regression "
"using ordinary least squares. This solves the problem"
"\n\n"
@@ -53,8 +58,10 @@ PROGRAM_INFO("Simple Linear Regression and Prediction",
"and the predicted responses y' may be saved with the " +
PRINT_PARAM_STRING("output_predictions") + " output parameter. This type "
"of regression is related to least-angle regression, which mlpack "
"implements as the 'lars' program.",
// Example.
"implements as the 'lars' program.");
// Example.
BINDING_EXAMPLE(
"For example, to run a linear regression on the dataset " +
PRINT_DATASET("X") + " with responses " + PRINT_DATASET("y") + ", saving "
"the trained model to " + PRINT_MODEL("lr_model") + ", the following "
@@ -69,13 +76,17 @@ PROGRAM_INFO("Simple Linear Regression and Prediction",
"used:"
"\n\n" +
PRINT_CALL("linear_regression", "input_model", "lr_model", "test", "X_test",
"output_predictions", "X_test_responses"),
SEE_ALSO("Linear/ridge regression tutorial", "@doxygen/lrtutorial.html"),
SEE_ALSO("@lars", "#lars"),
SEE_ALSO("Linear regression on Wikipedia",
"https://en.wikipedia.org/wiki/Linear_regression"),
SEE_ALSO("mlpack::regression::LinearRegression C++ class documentation",
"@doxygen/classmlpack_1_1regression_1_1LinearRegression.html"));
"output_predictions", "X_test_responses"));
// See also...
BINDING_SEE_ALSO("Linear/ridge regression tutorial",
"@doxygen/lrtutorial.html");
BINDING_SEE_ALSO("@lars", "#lars");
BINDING_SEE_ALSO("Linear regression on Wikipedia",
"https://en.wikipedia.org/wiki/Linear_regression");
BINDING_SEE_ALSO("mlpack::regression::LinearRegression C++ class "
"documentation",
"@doxygen/classmlpack_1_1regression_1_1LinearRegression.html");
PARAM_MATRIX_IN("training", "Matrix containing training set X (regressors).",
"t");
src/mlpack/methods/linear_svm/linear_svm_main.cpp
+22 -13
View File
@@ -23,12 +23,17 @@ using namespace mlpack;
using namespace mlpack::svm;
using namespace mlpack::util;
PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.",
// Short description.
// Program Name.
BINDING_NAME("Linear SVM is an L2-regularized support vector machine.");
// Short description.
BINDING_SHORT_DESC(
"An implementation of linear SVM for multiclass classification. "
"Given labeled data, a model can be trained and saved for "
"future use; or, a pre-trained model can be used to classify new points.",
// Long description.
"future use; or, a pre-trained model can be used to classify new points.");
// Long description.
BINDING_LONG_DESC(
"An implementation of linear SVMs that uses either L-BFGS or parallel SGD"
" (stochastic gradient descent) to train the model."
"\n\n"
@@ -77,8 +82,10 @@ PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.",
"so long as an existing linear SVM model is given with the " +
PRINT_PARAM_STRING("input_model") + " parameter. The output predictions "
"from the linear SVM model may be saved with the " +
PRINT_PARAM_STRING("predictions") + " parameter.",
// Example.
PRINT_PARAM_STRING("predictions") + " parameter.");
// Example.
BINDING_EXAMPLE(
"As an example, to train a LinaerSVM on the data '" +
PRINT_DATASET("data") + "' with labels '" + PRINT_DATASET("labels") + "' "
"with L2 regularization of 0.1, saving the model to '" +
@@ -93,13 +100,15 @@ PROGRAM_INFO("Linear SVM is an L2-regularized support vector machine.",
PRINT_DATASET("predictions") + "', the following command may be used: "
"\n\n" +
PRINT_CALL("linear_svm", "input_model", "lsvm_model", "test", "test",
"predictions", "predictions"),
SEE_ALSO("@random_forest", "#random_forest"),
SEE_ALSO("@logistic_regression", "#logistic_regression"),
SEE_ALSO("LinearSVM on Wikipedia",
"https://en.wikipedia.org/wiki/Support-vector_machine"),
SEE_ALSO("mlpack::svm::LinearSVM C++ class documentation",
"@doxygen/classmlpack_1_1svm_1_1LinearSVM.html"));
"predictions", "predictions"));
// See also...
BINDING_SEE_ALSO("@random_forest", "#random_forest");
BINDING_SEE_ALSO("@logistic_regression", "#logistic_regression");
BINDING_SEE_ALSO("LinearSVM on Wikipedia",
"https://en.wikipedia.org/wiki/Support-vector_machine");
BINDING_SEE_ALSO("mlpack::svm::LinearSVM C++ class documentation",
"@doxygen/classmlpack_1_1svm_1_1LinearSVM.html");
// Training parameters.
PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix "
src/mlpack/methods/lmnn/lmnn_main.cpp
+23 -15
View File
@@ -21,14 +21,18 @@
#include <ensmallen.hpp>
// Define parameters.
PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)",
// Short description.
// Program Name.
BINDING_NAME("Large Margin Nearest Neighbors (LMNN)");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Large Margin Nearest Neighbors (LMNN), a distance "
"learning technique. Given a labeled dataset, this learns a transformation"
" of the data that improves k-nearest-neighbor performance; this can be "
"useful as a preprocessing step.",
// Long description.
"useful as a preprocessing step.");
// Long description.
BINDING_LONG_DESC(
"This program implements Large Margin Nearest Neighbors, a distance "
"learning technique. The method seeks to improve k-nearest-neighbor "
"classification on a dataset. The method employes the strategy of "
@@ -111,8 +115,10 @@ PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)",
"literature on L-BFGS. In addition, a normalized starting point can be "
"used by specifying the " + PRINT_PARAM_STRING("normalize") + " parameter."
"\n\n"
"By default, the AMSGrad optimizer is used.",
// Example.
"By default, the AMSGrad optimizer is used.");
// Example.
BINDING_EXAMPLE(
"Example - Let's say we want to learn distance on iris dataset with "
"number of targets as 3 using BigBatch_SGD optimizer. A simple call for "
"the same will look like: "
@@ -124,15 +130,17 @@ PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)",
"with dataset having labels as last column can be made as: "
"\n\n" +
PRINT_CALL("mlpack_lmnn", "input", "letter_recognition", "k", 5,
"range", 10, "regularization", 0.4, "output", "output"),
SEE_ALSO("@nca", "#nca"),
SEE_ALSO("Large margin nearest neighbor on Wikipedia",
"https://en.wikipedia.org/wiki/Large_margin_nearest_neighbor"),
SEE_ALSO("Distance metric learning for large margin nearest neighbor "
"range", 10, "regularization", 0.4, "output", "output"));
// See also...
BINDING_SEE_ALSO("@nca", "#nca");
BINDING_SEE_ALSO("Large margin nearest neighbor on Wikipedia",
"https://en.wikipedia.org/wiki/Large_margin_nearest_neighbor");
BINDING_SEE_ALSO("Distance metric learning for large margin nearest neighbor "
"classification (pdf)", "http://papers.nips.cc/paper/2795-distance-"
"metric-learning-for-large-margin-nearest-neighbor-classification.pdf"),
SEE_ALSO("mlpack::lmnn::LMNN C++ class documentation",
"@doxygen/classmlpack_1_1lmnn_1_1LMNN.html"));
"metric-learning-for-large-margin-nearest-neighbor-classification.pdf");
BINDING_SEE_ALSO("mlpack::lmnn::LMNN C++ class documentation",
"@doxygen/classmlpack_1_1lmnn_1_1LMNN.html");
PARAM_MATRIX_IN_REQ("input", "Input dataset to run LMNN on.", "i");
PARAM_MATRIX_IN("distance", "Initial distance matrix to be used as "
src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp
+21 -12
View File
@@ -23,13 +23,18 @@ using namespace mlpack::lcc;
using namespace mlpack::sparse_coding; // For NothingInitializer.
using namespace mlpack::util;
PROGRAM_INFO("Local Coordinate Coding",
// Short description.
// Program Name.
BINDING_NAME("Local Coordinate Coding");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Local Coordinate Coding (LCC), a data transformation "
"technique. Given input data, this transforms each point to be expressed "
"as a linear combination of a few points in the dataset; once an LCC model "
"is trained, it can be used to transform points later also.",
// Long description.
"is trained, it can be used to transform points later also.");
// Long description.
BINDING_LONG_DESC(
"An implementation of Local Coordinate Coding (LCC), which "
"codes data that approximately lives on a manifold using a variation of l1-"
"norm regularized sparse coding. Given a dense data matrix X with n points"
@@ -44,8 +49,10 @@ PROGRAM_INFO("Local Coordinate Coding",
"\n\n"
"The coding is found with an algorithm which alternates between a "
"dictionary step, which updates the dictionary D, and a coding step, which "
"updates the coding matrix Z."
"\n\n"
"updates the coding matrix Z.");
// Example.
BINDING_EXAMPLE(
"To run this program, the input matrix X must be specified (with -i), along"
" with the number of atoms in the dictionary (-k). An initial dictionary "
"may also be specified with the " +
@@ -75,13 +82,15 @@ PROGRAM_INFO("Local Coordinate Coding",
"be used:"
"\n\n" +
PRINT_CALL("local_coordinate_coding", "input_model", "lcc_model", "test",
"points", "codes", "new_codes"),
SEE_ALSO("@sparse_coding", "#sparse_coding"),
SEE_ALSO("Nonlinear learning using local coordinate coding (pdf)",
"points", "codes", "new_codes"));
// See also...
BINDING_SEE_ALSO("@sparse_coding", "#sparse_coding");
BINDING_SEE_ALSO("Nonlinear learning using local coordinate coding (pdf)",
"https://papers.nips.cc/paper/3875-nonlinear-learning-using-local-"
"coordinate-coding.pdf"),
SEE_ALSO("mlpack::lcc::LocalCoordinateCoding C++ class documentation",
"@doxygen/classmlpack_1_1lcc_1_1LocalCoordinateCoding.html"));
"coordinate-coding.pdf");
BINDING_SEE_ALSO("mlpack::lcc::LocalCoordinateCoding C++ class documentation",
"@doxygen/classmlpack_1_1lcc_1_1LocalCoordinateCoding.html");
// Training parameters.
PARAM_MATRIX_IN("training", "Matrix of training data (X).", "t");
src/mlpack/methods/logistic_regression/logistic_regression.hpp
+3 -6
View File
@@ -140,12 +140,9 @@ class LogisticRegression
* Using this overload allows configuring the instantiated optimizer before
* training is performed.
*
* Note that the initial point of the optimizer
* (optimizer.Function().GetInitialPoint()) will be used as the initial point
* of the optimization, overwriting any existing trained model. If you don't
* want to overwrite the existing model, set
* optimizer.Function().GetInitialPoint() to the current parameters vector,
* accessible via Parameters().
* This will use the existing model parameters as a starting point for the
* optimization. If this is not what you want, then you should access the
* parameters vector directly with Parameters() and modify it as desired.
*
* @tparam OptimizerType Type of optimizer to use to train the model.
* @tparam CallbackTypes Types of Callback Functions.
src/mlpack/methods/logistic_regression/logistic_regression_function.hpp
-23
View File
@@ -41,24 +41,6 @@ class LogisticRegressionFunction
const arma::Row<size_t>& responses,
const double lambda = 0);
/**
* Creates the LogisticRegressionFunction with initialPoint.
*
* @param predictors The matrix of data points.
* @param responses The measured data for each point in predictors.
* @param initialPoint Point from which to start the optimization.
* @param lambda Regularization constant for ridge regression.
*/
LogisticRegressionFunction(const MatType& predictors,
const arma::Row<size_t>& responses,
const arma::vec& initialPoint,
const double lambda = 0);
//! Return the initial point for the optimization.
const arma::mat& InitialPoint() const { return initialPoint; }
//! Modify the initial point for the optimization.
arma::mat& InitialPoint() { return initialPoint; }
//! Return the regularization parameter (lambda).
const double& Lambda() const { return lambda; }
//! Modify the regularization parameter (lambda).
@@ -170,9 +152,6 @@ class LogisticRegressionFunction
GradType& gradient,
const size_t batchSize = 1) const;
//! Return the initial point for the optimization.
const arma::mat& GetInitialPoint() const { return initialPoint; }
//! Return the number of separable functions (the number of predictor points).
size_t NumFunctions() const { return predictors.n_cols; }
@@ -180,8 +159,6 @@ class LogisticRegressionFunction
size_t NumFeatures() const { return predictors.n_rows + 1; }
private:
//! The initial point, from which to start the optimization.
arma::mat initialPoint;
//! The matrix of data points (predictors). This is an alias until shuffling
//! is done.
MatType predictors;
src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp
-21
View File
@@ -31,8 +31,6 @@ LogisticRegressionFunction<MatType>::LogisticRegressionFunction(
false)),
lambda(lambda)
{
initialPoint = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros);
// Sanity check.
if (responses.n_elem != predictors.n_cols)
{
@@ -43,25 +41,6 @@ LogisticRegressionFunction<MatType>::LogisticRegressionFunction(
}
}
template<typename MatType>
LogisticRegressionFunction<MatType>::LogisticRegressionFunction(
const MatType& predictors,
const arma::Row<size_t>& responses,
const arma::vec& initialPoint,
const double lambda) :
initialPoint(initialPoint),
// We promise to be well-behaved... the elements won't be modified.
predictors(math::MakeAlias(const_cast<MatType&>(predictors), false)),
responses(math::MakeAlias(const_cast<arma::Row<size_t>&>(responses),
false)),
lambda(lambda)
{
// To check if initialPoint is compatible with predictors.
if (initialPoint.n_rows != (predictors.n_rows + 1) ||
initialPoint.n_cols != 1)
this->initialPoint = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros);
}
/**
* Shuffle the datapoints.
*/
src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp
+2 -2
View File
@@ -87,8 +87,8 @@ double LogisticRegression<MatType>::Train(
lambda);
// Set size of parameters vector according to the input data received.
parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros);
errorFunction.InitialPoint() = parameters;
if (parameters.n_elem != predictors.n_rows + 1)
parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros);
Timer::Start("logistic_regression_optimization");
const double out = optimizer.Optimize(errorFunction, parameters,
src/mlpack/methods/logistic_regression/logistic_regression_main.cpp
+24 -13
View File
@@ -22,12 +22,17 @@ using namespace mlpack;
using namespace mlpack::regression;
using namespace mlpack::util;
PROGRAM_INFO("L2-regularized Logistic Regression and Prediction",
// Short description.
// Program Name.
BINDING_NAME("L2-regularized Logistic Regression and Prediction");
// Short description.
BINDING_SHORT_DESC(
"An implementation of L2-regularized logistic regression for two-class "
"classification. Given labeled data, a model can be trained and saved for "
"future use; or, a pre-trained model can be used to classify new points.",
// Long description.
"future use; or, a pre-trained model can be used to classify new points.");
// Long description.
BINDING_LONG_DESC(
"An implementation of L2-regularized logistic regression using either the "
"L-BFGS optimizer or SGD (stochastic gradient descent). This solves the "
"regression problem"
@@ -92,8 +97,11 @@ PROGRAM_INFO("L2-regularized Logistic Regression and Prediction",
"\n\n"
"This implementation of logistic regression does not support the general "
"multi-class case but instead only the two-class case. Any labels must "
"be either 0 or 1. For more classes, see the softmax_regression program.",
// Example.
"be either 0 or 1. For more classes, see the softmax_regression "
"program.");
// Example.
BINDING_EXAMPLE(
"As an example, to train a logistic regression model on the data '" +
PRINT_DATASET("data") + "' with labels '" + PRINT_DATASET("labels") + "' "
"with L2 regularization of 0.1, saving the model to '" +
@@ -107,13 +115,16 @@ PROGRAM_INFO("L2-regularized Logistic Regression and Prediction",
PRINT_DATASET("predictions") + "', the following command may be used: "
"\n\n" +
PRINT_CALL("logistic_regression", "input_model", "lr_model", "test", "test",
"output", "predictions"),
SEE_ALSO("@softmax_regression", "#softmax_regression"),
SEE_ALSO("@random_forest", "#random_forest"),
SEE_ALSO("Logistic regression on Wikipedia",
"https://en.wikipedia.org/wiki/Logistic_regression"),
SEE_ALSO("mlpack::regression::LogisticRegression C++ class documentation",
"@doxygen/classmlpack_1_1regression_1_1LogisticRegression.html"));
"output", "predictions"));
// See also...
BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression");
BINDING_SEE_ALSO("@random_forest", "#random_forest");
BINDING_SEE_ALSO("Logistic regression on Wikipedia",
"https://en.wikipedia.org/wiki/Logistic_regression");
BINDING_SEE_ALSO("mlpack::regression::LogisticRegression C++ class "
"documentation",
"@doxygen/classmlpack_1_1regression_1_1LogisticRegression.html");
// Training parameters.
PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix "
src/mlpack/methods/lsh/lsh_main.cpp
+24 -16
View File
@@ -23,20 +23,26 @@ using namespace mlpack;
using namespace mlpack::neighbor;
using namespace mlpack::util;
// Information about the program itself.
PROGRAM_INFO("K-Approximate-Nearest-Neighbor Search with LSH",
// Short description.
// Program Name.
BINDING_NAME("K-Approximate-Nearest-Neighbor Search with LSH");
// Short description.
BINDING_SHORT_DESC(
"An implementation of approximate k-nearest-neighbor search with "
"locality-sensitive hashing (LSH). Given a set of reference points and a "
"set of query points, this will compute the k approximate nearest neighbors"
" of each query point in the reference set; models can be saved for future "
"use.",
// Long description.
"use.");
// Long description.
BINDING_LONG_DESC(
"This program will calculate the k approximate-nearest-neighbors of a set "
"of points using locality-sensitive hashing. You may specify a separate set"
" of reference points and query points, or just a reference set which will "
"be used as both the reference and query set. ",
// Example.
"be used as both the reference and query set. ");
// Example.
BINDING_EXAMPLE(
"For example, the following will return 5 neighbors from the data for each "
"point in " + PRINT_DATASET("input") + " and store the distances in " +
PRINT_DATASET("distances") + " and the neighbors in " +
@@ -56,15 +62,17 @@ PROGRAM_INFO("K-Approximate-Nearest-Neighbor Search with LSH",
" parameter can be specified to set the random seed."
"\n\n"
"This program also has many other parameters to control its functionality;"
" see the parameter-specific documentation for more information.",
SEE_ALSO("@knn", "#knn"),
SEE_ALSO("@krann", "#krann"),
SEE_ALSO("Locality-sensitive hashing on Wikipedia",
"https://en.wikipedia.org/wiki/Locality-sensitive_hashing"),
SEE_ALSO("Locality-sensitive hashing scheme based on p-stable distributions"
" (pdf)", "http://mlpack.org/papers/lsh.pdf"),
SEE_ALSO("mlpack::neighbor::LSHSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1LSHSearch.html"));
" see the parameter-specific documentation for more information.");
// See also...
BINDING_SEE_ALSO("@knn", "#knn");
BINDING_SEE_ALSO("@krann", "#krann");
BINDING_SEE_ALSO("Locality-sensitive hashing on Wikipedia",
"https://en.wikipedia.org/wiki/Locality-sensitive_hashing");
BINDING_SEE_ALSO("Locality-sensitive hashing scheme based on p-stable"
" distributions(pdf)", "http://mlpack.org/papers/lsh.pdf");
BINDING_SEE_ALSO("mlpack::neighbor::LSHSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1LSHSearch.html");
// Define our input parameters that this program will take.
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
src/mlpack/methods/mean_shift/mean_shift_main.cpp
+24 -16
View File
@@ -22,13 +22,17 @@ using namespace mlpack::kernel;
using namespace mlpack::util;
using namespace std;
// Define parameters for the executable.
PROGRAM_INFO("Mean Shift Clustering",
// Short description.
// Program Name.
BINDING_NAME("Mean Shift Clustering");
// Short description.
BINDING_SHORT_DESC(
"A fast implementation of mean-shift clustering using dual-tree range "
"search. Given a dataset, this uses the mean shift algorithm to produce "
"and return a clustering of the data.",
// Long description.
"and return a clustering of the data.");
// Long description.
BINDING_LONG_DESC(
"This program performs mean shift clustering on the given dataset, storing "
"the learned cluster assignments either as a column of labels in the input "
"dataset or separately."
@@ -42,22 +46,26 @@ PROGRAM_INFO("Mean Shift Clustering",
"\n\n"
"The output labels may be saved with the " + PRINT_PARAM_STRING("output") +
" output parameter and the centroids of each cluster may be saved with the"
" " + PRINT_PARAM_STRING("centroid") + " output parameter.",
// Example.
" " + PRINT_PARAM_STRING("centroid") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to run mean shift clustering on the dataset " +
PRINT_DATASET("data") + " and store the centroids to " +
PRINT_DATASET("centroids") + ", the following command may be used: "
"\n\n" +
PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"),
SEE_ALSO("@kmeans", "#kmeans"),
SEE_ALSO("@dbscan", "#dbscan"),
SEE_ALSO("Mean shift on Wikipedia",
"https://en.wikipedia.org/wiki/Mean_shift"),
SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)",
PRINT_CALL("mean_shift", "input", "data", "centroid", "centroids"));
// See also...
BINDING_SEE_ALSO("@kmeans", "#kmeans");
BINDING_SEE_ALSO("@dbscan", "#dbscan");
BINDING_SEE_ALSO("Mean shift on Wikipedia",
"https://en.wikipedia.org/wiki/Mean_shift");
BINDING_SEE_ALSO("Mean Shift, Mode Seeking, and Clustering (pdf)",
"http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.510.1222"
"&rep=rep1&type=pdf"),
SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation",
"@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html"));
"&rep=rep1&type=pdf");
BINDING_SEE_ALSO("mlpack::mean_shift::MeanShift C++ class documentation",
"@doxygen/classmlpack_1_1meanshift_1_1MeanShift.html");
// Required options.
PARAM_MATRIX_IN_REQ("input", "Input dataset to perform clustering on.", "i");
src/mlpack/methods/mvu/mvu_main.cpp
+5 -1
View File
@@ -15,7 +15,11 @@
#include <mlpack/core/util/io.hpp>
#include "mvu.hpp"
PROGRAM_INFO("Maximum Variance Unfolding (MVU)", "This program implements "
// Program Name.
BINDING_NAME("Maximum Variance Unfolding (MVU)");
// Long description.
BINDING_LONG_DESC("This program implements "
"Maximum Variance Unfolding, a nonlinear dimensionality reduction "
"technique. The method minimizes dimensionality by unfolding a manifold "
"such that the distances to the nearest neighbors of each point are held "
src/mlpack/methods/naive_bayes/nbc_main.cpp
+22 -13
View File
@@ -25,12 +25,17 @@ using namespace mlpack::util;
using namespace std;
using namespace arma;
PROGRAM_INFO("Parametric Naive Bayes Classifier",
// Short description.
// Program Name.
BINDING_NAME("Parametric Naive Bayes Classifier");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the Naive Bayes Classifier, used for classification. "
"Given labeled data, an NBC model can be trained and saved, or, a "
"pre-trained model can be used for classification.",
// Long description.
"pre-trained model can be used for classification.");
// Long description.
BINDING_LONG_DESC(
"This program trains the Naive Bayes classifier on the given labeled "
"training set, or loads a model from the given model file, and then may use"
" that trained model to classify the points in a given test set."
@@ -60,8 +65,10 @@ PROGRAM_INFO("Parametric Naive Bayes Classifier",
"Note: the " + PRINT_PARAM_STRING("output") + " and " +
PRINT_PARAM_STRING("output_probs") + " parameters are deprecated and will "
"be removed in mlpack 4.0.0. Use " + PRINT_PARAM_STRING("predictions") +
" and " + PRINT_PARAM_STRING("probabilities") + " instead.",
// Example.
" and " + PRINT_PARAM_STRING("probabilities") + " instead.");
// Example.
BINDING_EXAMPLE(
"For example, to train a Naive Bayes classifier on the dataset " +
PRINT_DATASET("data") + " with labels " + PRINT_DATASET("labels") + " "
"and save the model to " + PRINT_MODEL("nbc_model") + ", the following "
@@ -76,14 +83,16 @@ PROGRAM_INFO("Parametric Naive Bayes Classifier",
"may be used:"
"\n\n" +
PRINT_CALL("nbc", "input_model", "nbc_model", "test", "test_set", "output",
"predictions"),
SEE_ALSO("@softmax_regression", "#softmax_regression"),
SEE_ALSO("@random_forest", "#random_forest"),
SEE_ALSO("Naive Bayes classifier on Wikipedia",
"https://en.wikipedia.org/wiki/Naive_Bayes_classifier"),
SEE_ALSO("mlpack::naive_bayes::NaiveBayesClassifier C++ class "
"predictions"));
// See also...
BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression");
BINDING_SEE_ALSO("@random_forest", "#random_forest");
BINDING_SEE_ALSO("Naive Bayes classifier on Wikipedia",
"https://en.wikipedia.org/wiki/Naive_Bayes_classifier");
BINDING_SEE_ALSO("mlpack::naive_bayes::NaiveBayesClassifier C++ class "
"documentation", "@doxygen/classmlpack_1_1naive__bayes_1_1"
"NaiveBayesClassifier.html"));
"NaiveBayesClassifier.html");
// A struct for saving the model with mappings.
struct NBCModel
src/mlpack/methods/nca/nca_main.cpp
+19 -15
View File
@@ -20,14 +20,18 @@
#include <ensmallen.hpp>
// Define parameters.
PROGRAM_INFO("Neighborhood Components Analysis (NCA)",
// Short description.
// Program Name.
BINDING_NAME("Neighborhood Components Analysis (NCA)");
// Short description.
BINDING_SHORT_DESC(
"An implementation of neighborhood components analysis, a distance learning"
" technique that can be used for preprocessing. Given a labeled dataset, "
"this uses NCA, which seeks to improve the k-nearest-neighbor "
"classification, and returns the learned distance metric.",
// Long description.
"classification, and returns the learned distance metric.");
// Long description.
BINDING_LONG_DESC(
"This program implements Neighborhood Components Analysis, both a linear "
"dimensionality reduction technique and a distance learning technique. The"
" method seeks to improve k-nearest-neighbor classification on a dataset "
@@ -88,17 +92,17 @@ PROGRAM_INFO("Neighborhood Components Analysis (NCA)",
"mlpack L-BFGS documentation (in lbfgs.hpp) or the vast set of published "
"literature on L-BFGS."
"\n\n"
"By default, the SGD optimizer is used.",
// Example.
"",
SEE_ALSO("@lmnn", "#lmnn"),
SEE_ALSO("Neighbourhood components analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Neighbourhood_components_analysis"),
SEE_ALSO("Neighbourhood components analysis (pdf)",
"By default, the SGD optimizer is used.");
// See also...
BINDING_SEE_ALSO("@lmnn", "#lmnn");
BINDING_SEE_ALSO("Neighbourhood components analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Neighbourhood_components_analysis");
BINDING_SEE_ALSO("Neighbourhood components analysis (pdf)",
"http://papers.nips.cc/paper/2566-neighbourhood-components-"
"analysis.pdf"),
SEE_ALSO("mlpack::nca::NCA C++ class documentation",
"@doxygen/classmlpack_1_1nca_1_1NCA.html"));
"analysis.pdf");
BINDING_SEE_ALSO("mlpack::nca::NCA C++ class documentation",
"@doxygen/classmlpack_1_1nca_1_1NCA.html");
PARAM_MATRIX_IN_REQ("input", "Input dataset to run NCA on.", "i");
PARAM_MATRIX_OUT("output", "Output matrix for learned distance matrix.", "o");
src/mlpack/methods/neighbor_search/kfn_main.cpp
+22 -14
View File
@@ -32,19 +32,25 @@ using namespace mlpack::util;
// Convenience typedef.
typedef NSModel<FurthestNS> KFNModel;
// Information about the program itself.
PROGRAM_INFO("k-Furthest-Neighbors Search",
// Short description.
// Program Name.
BINDING_NAME("k-Furthest-Neighbors Search");
// Short description.
BINDING_SHORT_DESC(
"An implementation of k-furthest-neighbor search using single-tree and "
"dual-tree algorithms. Given a set of reference points and query points, "
"this can find the k furthest neighbors in the reference set of each query"
" point using trees; trees that are built can be saved for future use.",
// Long description.
" point using trees; trees that are built can be saved for future use.");
// Long description.
BINDING_LONG_DESC(
"This program will calculate the k-furthest-neighbors of a set of "
"points. You may specify a separate set of reference points and query "
"points, or just a reference set which will be used as both the reference "
"and query set.",
// Example.
"and query set.");
// Example.
BINDING_EXAMPLE(
"For example, the following will calculate the 5 furthest neighbors of each"
"point in " + PRINT_DATASET("input") + " and store the distances in " +
PRINT_DATASET("distances") + " and the neighbors in " +
@@ -57,13 +63,15 @@ PROGRAM_INFO("k-Furthest-Neighbors Search",
"neighbors output matrix corresponds to the index of the point in the "
"reference set which is the j'th furthest neighbor from the point in the "
"query set with index i. Row i and column j in the distances output file "
"corresponds to the distance between those two points.",
SEE_ALSO("@approx_kfn", "#approx_kfn"),
SEE_ALSO("@knn", "#knn"),
SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf"),
SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html"));
"corresponds to the distance between those two points.");
// See also...
BINDING_SEE_ALSO("@approx_kfn", "#approx_kfn");
BINDING_SEE_ALSO("@knn", "#knn");
BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf");
BINDING_SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html");
// Define our input parameters that this program will take.
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
src/mlpack/methods/neighbor_search/knn_main.cpp
+25 -17
View File
@@ -34,20 +34,26 @@ using namespace mlpack::util;
// Convenience typedef.
typedef NSModel<NearestNeighborSort> KNNModel;
// Information about the program itself.
PROGRAM_INFO("k-Nearest-Neighbors Search",
// Short description.
// Program Name.
BINDING_NAME("k-Nearest-Neighbors Search");
// Short description.
BINDING_SHORT_DESC(
"An implementation of k-nearest-neighbor search using single-tree and "
"dual-tree algorithms. Given a set of reference points and query points, "
"this can find the k nearest neighbors in the reference set of each query "
"point using trees; trees that are built can be saved for future use.",
// Long description.
"point using trees; trees that are built can be saved for future use.");
// Long description.
BINDING_LONG_DESC(
"This program will calculate the k-nearest-neighbors of a set of "
"points using kd-trees or cover trees (cover tree support is experimental "
"and may be slow). You may specify a separate set of "
"reference points and query points, or just a reference set which will be "
"used as both the reference and query set.",
// Example.
"used as both the reference and query set.");
// Example.
BINDING_EXAMPLE(
"For example, the following command will calculate the 5 nearest neighbors "
"of each point in " + PRINT_DATASET("input") + " and store the distances "
"in " + PRINT_DATASET("distances") + " and the neighbors in " +
@@ -60,16 +66,18 @@ PROGRAM_INFO("k-Nearest-Neighbors Search",
"output matrix corresponds to the index of the point in the reference set "
"which is the j'th nearest neighbor from the point in the query set with "
"index i. Row j and column i in the distances output matrix corresponds to"
" the distance between those two points.",
SEE_ALSO("@lsh", "#lsh"),
SEE_ALSO("@krann", "#krann"),
SEE_ALSO("@kfn", "#kfn"),
SEE_ALSO("NeighborSearch tutorial (k-nearest-neighbors)",
"@doxygen/nstutorial.html"),
SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf"),
SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html"));
" the distance between those two points.");
// See also...
BINDING_SEE_ALSO("@lsh", "#lsh");
BINDING_SEE_ALSO("@krann", "#krann");
BINDING_SEE_ALSO("@kfn", "#kfn");
BINDING_SEE_ALSO("NeighborSearch tutorial (k-nearest-neighbors)",
"@doxygen/nstutorial.html");
BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf");
BINDING_SEE_ALSO("mlpack::neighbor::NeighborSearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1NeighborSearch.html");
// Define our input parameters that this program will take.
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
src/mlpack/methods/nmf/nmf_main.cpp
+25 -17
View File
@@ -27,12 +27,16 @@ using namespace mlpack::amf;
using namespace mlpack::util;
using namespace std;
// Document program.
PROGRAM_INFO("Non-negative Matrix Factorization",
// Short description.
// Program Name.
BINDING_NAME("Non-negative Matrix Factorization");
// Short description.
BINDING_SHORT_DESC(
"An implementation of non-negative matrix factorization. This can be used "
"to decompose an input dataset into two low-rank non-negative components.",
// Long description.
"to decompose an input dataset into two low-rank non-negative components.");
// Long description.
BINDING_LONG_DESC(
"This program performs non-negative matrix factorization on the given "
"dataset, storing the resulting decomposed matrices in the specified "
"files. For an input dataset V, NMF decomposes V into two matrices W "
@@ -57,25 +61,29 @@ PROGRAM_INFO("Non-negative Matrix Factorization",
"The maximum number of iterations is specified with " +
PRINT_PARAM_STRING("max_iterations") + ", and the minimum residue "
"required for algorithm termination is specified with the " +
PRINT_PARAM_STRING("min_residue") + " parameter.",
// Example.
PRINT_PARAM_STRING("min_residue") + " parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to run NMF on the input matrix " + PRINT_DATASET("V") + " "
"using the 'multdist' update rules with a rank-10 decomposition and "
"storing the decomposed matrices into " + PRINT_DATASET("W") + " and " +
PRINT_DATASET("H") + ", the following command could be used: "
"\n\n" +
PRINT_CALL("nmf", "input", "V", "w", "W", "h", "H", "rank", 10,
"update_rules", "multdist"),
SEE_ALSO("@cf", "#cf"),
SEE_ALSO("Alternating matrix factorization tutorial",
"@doxygen/amftutorial.html"),
SEE_ALSO("Non-negative matrix factorization on Wikipedia",
"https://en.wikipedia.org/wiki/Non-negative_matrix_factorization"),
SEE_ALSO("Algorithms for non-negative matrix factorization (pdf)",
"update_rules", "multdist"));
// See also...
BINDING_SEE_ALSO("@cf", "#cf");
BINDING_SEE_ALSO("Alternating matrix factorization tutorial",
"@doxygen/amftutorial.html");
BINDING_SEE_ALSO("Non-negative matrix factorization on Wikipedia",
"https://en.wikipedia.org/wiki/Non-negative_matrix_factorization");
BINDING_SEE_ALSO("Algorithms for non-negative matrix factorization (pdf)",
"http://papers.nips.cc/paper/1861-algorithms-for-non-negative-matrix-"
"factorization.pdf"),
SEE_ALSO("mlpack::amf::AMF C++ class documentation",
"@doxygen/classmlpack_1_1amf_1_1AMF.html"));
"factorization.pdf");
BINDING_SEE_ALSO("mlpack::amf::AMF C++ class documentation",
"@doxygen/classmlpack_1_1amf_1_1AMF.html");
// Parameters for program.
PARAM_MATRIX_IN_REQ("input", "Input dataset to perform NMF on.", "i");
src/mlpack/methods/pca/pca_main.cpp
+20 -12
View File
@@ -25,14 +25,18 @@ using namespace mlpack::pca;
using namespace mlpack::util;
using namespace std;
// Document program.
PROGRAM_INFO("Principal Components Analysis",
// Short description.
// Program Name.
BINDING_NAME("Principal Components Analysis");
// Short description.
BINDING_SHORT_DESC(
"An implementation of several strategies for principal components analysis "
"(PCA), a common preprocessing step. Given a dataset and a desired new "
"dimensionality, this can reduce the dimensionality of the data using the "
"linear transformation determined by PCA.",
// Long description.
"linear transformation determined by PCA.");
// Long description.
BINDING_LONG_DESC(
"This program performs principal components analysis on the given dataset "
"using the exact, randomized, randomized block Krylov, or QUIC SVD method. "
"It will transform the data onto its principal components, optionally "
@@ -50,19 +54,23 @@ PROGRAM_INFO("Principal Components Analysis",
"Multiple different decomposition techniques can be used. The method to "
"use can be specified with the " +
PRINT_PARAM_STRING("decomposition_method") + " parameter, and it may take "
"the values 'exact', 'randomized', or 'quic'.",
// Example.
"the values 'exact', 'randomized', or 'quic'.");
// Example.
BINDING_EXAMPLE(
"For example, to reduce the dimensionality of the matrix " +
PRINT_DATASET("data") + " to 5 dimensions using randomized SVD for the "
"decomposition, storing the output matrix to " +
PRINT_DATASET("data_mod") + ", the following command can be used:"
"\n\n" +
PRINT_CALL("pca", "input", "data", "new_dimensionality", 5,
"decomposition_method", "randomized", "output", "data_mod"),
SEE_ALSO("Principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Principal_component_analysis"),
SEE_ALSO("mlpack::pca::PCA C++ class documentation",
"@doxygen/classmlpack_1_1pca_1_1PCA.html"));
"decomposition_method", "randomized", "output", "data_mod"));
// See also...
BINDING_SEE_ALSO("Principal component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Principal_component_analysis");
BINDING_SEE_ALSO("mlpack::pca::PCA C++ class documentation",
"@doxygen/classmlpack_1_1pca_1_1PCA.html");
// Parameters for program.
PARAM_MATRIX_IN_REQ("input", "Input dataset to perform PCA on.", "i");
src/mlpack/methods/perceptron/perceptron_main.cpp
+21 -12
View File
@@ -25,13 +25,18 @@ using namespace mlpack::util;
using namespace std;
using namespace arma;
PROGRAM_INFO("Perceptron",
// Short description.
// Program Name.
BINDING_NAME("Perceptron");
// Short description.
BINDING_SHORT_DESC(
"An implementation of a perceptron---a single level neural network--=for "
"classification. Given labeled data, a perceptron can be trained and saved"
" for future use; or, a pre-trained perceptron can be used for "
"classification on new points.",
// Long description.
"classification on new points.");
// Long description.
BINDING_LONG_DESC(
"This program implements a perceptron, which is a single level neural "
"network. The perceptron makes its predictions based on a linear predictor "
"function combining a set of weights with the feature vector. The "
@@ -63,8 +68,10 @@ PROGRAM_INFO("Perceptron",
" 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, "
"the " + PRINT_PARAM_STRING("labels") + " parameter may be used to specify "
"a separate matrix of labels."
"\n\n"
"a separate matrix of labels.");
// Example.
BINDING_EXAMPLE(
"All these options make it easy to train a perceptron, and then re-use that"
" perceptron for later classification. The invocation below trains a "
"perceptron on " + PRINT_DATASET("training_data") + " with labels " +
@@ -89,12 +96,14 @@ PROGRAM_INFO("Perceptron",
"cannot pass a perceptron model trained on 2 classes and then re-train with"
" a 4-class dataset. Similarly, attempting classification on a "
"3-dimensional dataset with a perceptron that has been trained on 8 "
"dimensions will cause an error.",
SEE_ALSO("@adaboost", "#adaboost"),
SEE_ALSO("Perceptron on Wikipedia",
"https://en.wikipedia.org/wiki/Perceptron"),
SEE_ALSO("mlpack::perceptron::Perceptron C++ class documentation",
"@doxygen/classmlpack_1_1perceptron_1_1Perceptron.html"));
"dimensions will cause an error.");
// See also...
BINDING_SEE_ALSO("@adaboost", "#adaboost");
BINDING_SEE_ALSO("Perceptron on Wikipedia",
"https://en.wikipedia.org/wiki/Perceptron");
BINDING_SEE_ALSO("mlpack::perceptron::Perceptron C++ class documentation",
"@doxygen/classmlpack_1_1perceptron_1_1Perceptron.html");
// When we save a model, we must also save the class mappings. So we use this
// auxiliary structure to store both the perceptron and the mapping, and we'll
src/mlpack/methods/preprocess/image_converter_main.cpp
+22 -13
View File
@@ -20,13 +20,18 @@ using namespace arma;
using namespace std;
using namespace mlpack::data;
PROGRAM_INFO("Image Converter",
// Short description.
// Program Name.
BINDING_NAME("Image Converter");
// Short description.
BINDING_SHORT_DESC(
"A utility to load an image or set of images into a single dataset that"
" can then be used by other mlpack methods and utilities. This can also"
" unpack an image dataset into individual files, for instance after mlpack"
" methods have been used.",
// Long description.
" methods have been used.");
// Long description.
BINDING_LONG_DESC(
"This utility takes an image or an array of images and loads them to a"
" matrix. You can optionally specify the height " +
PRINT_PARAM_STRING("height") + " width " + PRINT_PARAM_STRING("width")
@@ -39,20 +44,24 @@ PROGRAM_INFO("Image Converter",
+ ".\n\n" +
"You can also provide a dataset and save them as images using " +
PRINT_PARAM_STRING("dataset") + " and " + PRINT_PARAM_STRING("save") +
" as an parameter.",
// Example.
"An example to load an image : "
" as an parameter.");
// Example.
BINDING_EXAMPLE(
" An example to load an image : "
"\n\n" +
PRINT_CALL("image_converter", "input", "X", "height", 256, "width", 256,
"channels", 3, "output", "Y") +
"\n\n"
"An example to save an image is :" +
"\n\n" +
" An example to save an image is :"
"\n\n" +
PRINT_CALL("image_converter", "input", "X", "height", 256, "width", 256,
"channels", 3, "dataset", "Y", "save", true),
SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"),
SEE_ALSO("@preprocess_describe", "#preprocess_describe"),
SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"));
"channels", 3, "dataset", "Y", "save", true));
// See also...
BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize");
BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe");
BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer");
// DEFINE PARAM
PARAM_VECTOR_IN_REQ(string, "input", "Image filenames which have to "
src/mlpack/methods/preprocess/preprocess_binarize_main.cpp
+19 -10
View File
@@ -14,12 +14,17 @@
#include <mlpack/core/util/mlpack_main.hpp>
#include <mlpack/core/data/binarize.hpp>
PROGRAM_INFO("Binarize Data",
// Short description.
// Program Name.
BINDING_NAME("Binarize Data");
// Short description.
BINDING_SHORT_DESC(
"A utility to binarize a dataset. Given a dataset, this utility converts "
"each value in the desired dimension(s) to 0 or 1; this can be a useful "
"preprocessing step.",
// Long description.
"preprocessing step.");
// Long description.
BINDING_LONG_DESC(
"This utility takes a dataset and binarizes the "
"variables into either 0 or 1 given threshold. User can apply binarization "
"on a dimension or the whole dataset. The dimension to apply binarization "
@@ -30,8 +35,10 @@ PROGRAM_INFO("Binarize Data",
"0.0."
"\n\n"
"The binarized matrix may be saved with the " +
PRINT_PARAM_STRING("output") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, if we want to set all variables greater than 5 in the "
"dataset " + PRINT_DATASET("X") + " to 1 and variables less than or equal "
"to 5.0 to 0, and save the result to " + PRINT_DATASET("Y") + ", we could "
@@ -44,10 +51,12 @@ PROGRAM_INFO("Binarize Data",
PRINT_DATASET("X") + ", we could instead run"
"\n\n" +
PRINT_CALL("preprocess_binarize", "input", "X", "threshold", 5.0,
"dimension", 0, "output", "Y"),
SEE_ALSO("@preprocess_describe", "#preprocess_describe"),
SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"),
SEE_ALSO("@preprocess_split", "#preprocess_split"));
"dimension", 0, "output", "Y"));
// See also...
BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe");
BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer");
BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split");
// Define parameters for data.
PARAM_MATRIX_IN_REQ("input", "Input data matrix.", "i");
src/mlpack/methods/preprocess/preprocess_describe_main.cpp
+19 -10
View File
@@ -22,11 +22,16 @@ using namespace mlpack::util;
using namespace std;
using namespace boost;
PROGRAM_INFO("Descriptive Statistics",
// Short description.
// Program Name.
BINDING_NAME("Descriptive Statistics");
// Short description.
BINDING_SHORT_DESC(
"A utility for printing descriptive statistics about a dataset. This "
"prints a number of details about a dataset in a tabular format.",
// Long description.
"prints a number of details about a dataset in a tabular format.");
// Long description.
BINDING_LONG_DESC(
"This utility takes a dataset and prints out the descriptive statistics "
"of the data. Descriptive statistics is the discipline of quantitatively "
"describing the main features of a collection of information, or the "
@@ -40,8 +45,10 @@ PROGRAM_INFO("Descriptive Statistics",
"specific dimension to analyze if there are too many dimensions. The " +
PRINT_PARAM_STRING("population") + " parameter can be specified when the "
"dataset should be considered as a population. Otherwise, the dataset "
"will be considered as a sample.",
// Example.
"will be considered as a sample.");
// Example.
BINDING_EXAMPLE(
"So, a simple example where we want to print out statistical facts about "
"the dataset " + PRINT_DATASET("X") + " using the default settings, we "
"could run "
@@ -52,10 +59,12 @@ PROGRAM_INFO("Descriptive Statistics",
"the dataset as a population, we could run"
"\n\n" +
PRINT_CALL("preprocess_describe", "input", "X", "width", 10, "precision", 5,
"verbose", true),
SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"),
SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"),
SEE_ALSO("@preprocess_split", "#preprocess_split"));
"verbose", true));
// See also...
BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize");
BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer");
BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split");
// Define parameters for data.
PARAM_MATRIX_IN_REQ("input", "Matrix containing data,", "i");
src/mlpack/methods/preprocess/preprocess_imputer_main.cpp
+19 -10
View File
@@ -22,19 +22,26 @@
#include <mlpack/core/data/imputation_methods/custom_imputation.hpp>
#include <mlpack/core/data/imputation_methods/listwise_deletion.hpp>
PROGRAM_INFO("Impute Data",
// Short description.
// Program Name.
BINDING_NAME("Impute Data");
// Short description.
BINDING_SHORT_DESC(
"This utility provides several imputation strategies for missing data. "
"Given a dataset with missing values, this can impute according to several "
"strategies, including user-defined values.",
// Long description.
"strategies, including user-defined values.");
// Long description.
BINDING_LONG_DESC(
"This utility takes a dataset and converts a user-defined missing variable "
"to another to provide more meaningful analysis."
"\n\n"
"The program does not modify the original file, but instead makes a "
"separate file to save the output data; You can save the output by "
"specifying the file name with" + PRINT_PARAM_STRING("output_file") + ".",
// Example.
"specifying the file name with" + PRINT_PARAM_STRING("output_file") + ".");
// Example.
BINDING_EXAMPLE(
"For example, if we consider 'NULL' in dimension 0 to be a missing "
"variable and want to delete whole row containing the NULL in the "
"column-wise" + PRINT_DATASET("dataset") + ", and save the result to " +
@@ -42,10 +49,12 @@ PROGRAM_INFO("Impute Data",
"\n\n" +
PRINT_CALL("mlpack_preprocess_imputer", "input_file", "dataset",
"output_file", "result", "missing_value", "NULL", "dimension", "0",
"strategy", "listwise_deletion"),
SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"),
SEE_ALSO("@preprocess_describe", "#preprocess_describe"),
SEE_ALSO("@preprocess_split", "#preprocess_split"));
"strategy", "listwise_deletion");
// See also...
BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize");
BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe");
BINDING_SEE_ALSO("@preprocess_split", "#preprocess_split");
PARAM_STRING_IN_REQ("input_file", "File containing data.", "i");
PARAM_STRING_OUT("output_file", "File to save output into.", "o");
src/mlpack/methods/preprocess/preprocess_scale_main.cpp
+19 -10
View File
@@ -28,12 +28,17 @@ using namespace mlpack::data;
using namespace arma;
using namespace std;
PROGRAM_INFO("Scale Data",
// Short description.
// Program Name.
BINDING_NAME("Scale Data");
// Short description.
BINDING_SHORT_DESC(
"A utility to perform feature scaling on datasets using one of six"
"techniques. Both scaling and inverse scaling are supported, and"
"scalers can be saved and then applied to other datasets.",
// Long description.
"scalers can be saved and then applied to other datasets.");
// Long description.
BINDING_LONG_DESC(
"This utility takes a dataset and performs feature scaling using one of "
"the six scaler methods namely: 'max_abs_scaler', 'mean_normalization', "
"'min_max_scaler' ,'standard_scaler', 'pca_whitening' and 'zca_whitening'."
@@ -47,8 +52,10 @@ PROGRAM_INFO("Scale Data",
"\n\n"
"The model to scale features can be saved using " +
PRINT_PARAM_STRING("output_model") + " and later can be loaded back using"
+ PRINT_PARAM_STRING("input_model") + ".",
// Example.
+ PRINT_PARAM_STRING("input_model") + ".");
// Example.
BINDING_EXAMPLE(
"So, a simple example where we want to scale the dataset " +
PRINT_DATASET("X") + " into " + PRINT_DATASET("X_scaled")+ " with "
" standard_scaler as scaler_method, we could run "
@@ -78,10 +85,12 @@ PROGRAM_INFO("Scale Data",
" of default 0 to 1. We could run "
"\n\n" +
PRINT_CALL("preprocess_scale", "input", "X", "output", "X_scaled",
"scaler_method", "min_max_scaler", "min_value", 1, "max_value", 3),
SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"),
SEE_ALSO("@preprocess_describe", "#preprocess_describe"),
SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"));
"scaler_method", "min_max_scaler", "min_value", 1, "max_value", 3));
// See also...
BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize");
BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe");
BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer");
// Define parameters for data.
PARAM_MATRIX_IN_REQ("input", "Matrix containing data.", "i");
src/mlpack/methods/preprocess/preprocess_split_main.cpp
+19 -10
View File
@@ -15,11 +15,16 @@
#include <mlpack/core/math/random.hpp>
#include <mlpack/core/data/split_data.hpp>
PROGRAM_INFO("Split Data",
// Short description.
// Program Name.
BINDING_NAME("Split Data");
// Short description.
BINDING_SHORT_DESC(
"A utility to split data into a training and testing dataset. This can "
"also split labels according to the same split.",
// Long description.
"also split labels according to the same split.");
// Long description.
BINDING_LONG_DESC(
"This utility takes a dataset and optionally labels and splits them into a "
"training set and a test set. Before the split, the points in the dataset "
"are randomly reordered. The percentage of the dataset to be used as the "
@@ -35,8 +40,10 @@ PROGRAM_INFO("Split Data",
"labels works the same way as splitting the data. The output training and "
"test labels may be saved with the " +
PRINT_PARAM_STRING("training_labels") + " and " +
PRINT_PARAM_STRING("test_labels") + " output parameters, respectively.",
// Example.
PRINT_PARAM_STRING("test_labels") + " output parameters, respectively.");
// Example.
BINDING_EXAMPLE(
"So, a simple example where we want to split the dataset " +
PRINT_DATASET("X") + " into " + PRINT_DATASET("X_train") + " and " +
PRINT_DATASET("X_test") + " with 60% of the data in the training set and "
@@ -60,10 +67,12 @@ PROGRAM_INFO("Split Data",
"\n\n" +
PRINT_CALL("preprocess_split", "input", "X", "input_labels", "y",
"test_ratio", 0.3, "training", "X_train", "training_labels", "y_train",
"test", "X_test", "test_labels", "y_test"),
SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"),
SEE_ALSO("@preprocess_describe", "#preprocess_describe"),
SEE_ALSO("@preprocess_imputer", "#preprocess_imputer"));
"test", "X_test", "test_labels", "y_test"));
// See also...
BINDING_SEE_ALSO("@preprocess_binarize", "#preprocess_binarize");
BINDING_SEE_ALSO("@preprocess_describe", "#preprocess_describe");
BINDING_SEE_ALSO("@preprocess_imputer", "#preprocess_imputer");
// Define parameters for data.
PARAM_MATRIX_IN_REQ("input", "Matrix containing data.", "i");
src/mlpack/methods/radical/radical_main.cpp
+22 -13
View File
@@ -16,13 +16,18 @@
#include <mlpack/core/math/random.hpp>
#include "radical.hpp"
PROGRAM_INFO("RADICAL",
// Short description.
// Program Name.
BINDING_NAME("RADICAL");
// Short description.
BINDING_SHORT_DESC(
"An implementation of RADICAL, a method for independent component analysis "
"(ICA). Given a dataset, this can decompose the dataset into an unmixing "
"matrix and an independent component matrix; this can be useful for "
"preprocessing.",
// Long description.
"preprocessing.");
// Long description.
BINDING_LONG_DESC(
"An implementation of RADICAL, a method for independent component analysis "
"(ICA). Assuming that we have an input matrix X, the goal is to find a "
"square unmixing matrix W such that Y = W * X and the dimensions of Y are "
@@ -33,20 +38,24 @@ PROGRAM_INFO("RADICAL",
PRINT_PARAM_STRING("input") + " parameter. The output matrix Y may be "
"saved with the " + PRINT_PARAM_STRING("output_ic") + " output parameter, "
"and the output unmixing matrix W may be saved with the " +
PRINT_PARAM_STRING("output_unmixing") + " output parameter.",
// Example.
PRINT_PARAM_STRING("output_unmixing") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to perform ICA on the matrix " + PRINT_DATASET("X") + " with "
"40 replicates, saving the independent components to " +
PRINT_DATASET("ic") + ", the following command may be used: "
"\n\n" +
PRINT_CALL("radical", "input", "X", "replicates", 40, "output_ic", "ic"),
SEE_ALSO("Independent component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Independent_component_analysis"),
SEE_ALSO("ICA using spacings estimates of entropy (pdf)",
PRINT_CALL("radical", "input", "X", "replicates", 40, "output_ic", "ic"));
// See also...
BINDING_SEE_ALSO("Independent component analysis on Wikipedia",
"https://en.wikipedia.org/wiki/Independent_component_analysis");
BINDING_SEE_ALSO("ICA using spacings estimates of entropy (pdf)",
"http://www.jmlr.org/papers/volume4/learned-miller03a/"
"learned-miller03a.pdf"),
SEE_ALSO("mlpack::radical::Radical C++ class documentation",
"@doxygen/classmlpack_1_1radical_1_1Radical.html"));
"learned-miller03a.pdf");
BINDING_SEE_ALSO("mlpack::radical::Radical C++ class documentation",
"@doxygen/classmlpack_1_1radical_1_1Radical.html");
PARAM_MATRIX_IN_REQ("input", "Input dataset for ICA.", "i");
src/mlpack/methods/random_forest/random_forest_main.cpp
+25 -16
View File
@@ -19,13 +19,18 @@ using namespace mlpack::tree;
using namespace mlpack::util;
using namespace std;
PROGRAM_INFO("Random forests",
// Short description.
// Program Name.
BINDING_NAME("Random forests");
// Short description.
BINDING_SHORT_DESC(
"An implementation of the standard random forest algorithm by Leo Breiman "
"for classification. Given labeled data, a random forest can be trained "
"and saved for future use; or, a pre-trained random forest can be used for "
"classification.",
// Long description.
"classification.");
// Long description.
BINDING_LONG_DESC(
"This program is an implementation of the standard random forest "
"classification algorithm by Leo Breiman. A random forest can be "
"trained and saved for later use, or a random forest may be loaded "
@@ -64,8 +69,10 @@ PROGRAM_INFO("Random forests",
PRINT_PARAM_STRING("test_labels") + " parameter. Predictions for each "
"test point may be saved via the " + PRINT_PARAM_STRING("predictions") +
"output parameter. Class probabilities for each prediction may be saved "
"with the " + PRINT_PARAM_STRING("probabilities") + " output parameter.",
// Example.
"with the " + PRINT_PARAM_STRING("probabilities") + " output parameter.");
// Example.
BINDING_EXAMPLE(
"For example, to train a random forest with a minimum leaf size of 20 "
"using 10 trees on the dataset contained in " + PRINT_DATASET("data") +
"with labels " + PRINT_DATASET("labels") + ", saving the output random "
@@ -83,16 +90,18 @@ PROGRAM_INFO("Random forests",
"could call "
"\n\n" +
PRINT_CALL("random_forest", "input_model", "rf_model", "test", "test_set",
"test_labels", "test_labels", "predictions", "predictions"),
SEE_ALSO("@decision_tree", "#decision_tree"),
SEE_ALSO("@hoeffding_tree", "#hoeffding_tree"),
SEE_ALSO("@softmax_regression", "#softmax_regression"),
SEE_ALSO("Random forest on Wikipedia",
"https://en.wikipedia.org/wiki/Random_forest"),
SEE_ALSO("Random forests (pdf)",
"https://link.springer.com/content/pdf/10.1023/A:1010933404324.pdf"),
SEE_ALSO("mlpack::tree::RandomForest C++ class documentation",
"@doxygen/classmlpack_1_1tree_1_1RandomForest.html"));
"test_labels", "test_labels", "predictions", "predictions"));
// See also...
BINDING_SEE_ALSO("@decision_tree", "#decision_tree");
BINDING_SEE_ALSO("@hoeffding_tree", "#hoeffding_tree");
BINDING_SEE_ALSO("@softmax_regression", "#softmax_regression");
BINDING_SEE_ALSO("Random forest on Wikipedia",
"https://en.wikipedia.org/wiki/Random_forest");
BINDING_SEE_ALSO("Random forests (pdf)",
"https://link.springer.com/content/pdf/10.1023/A:1010933404324.pdf");
BINDING_SEE_ALSO("mlpack::tree::RandomForest C++ class documentation",
"@doxygen/classmlpack_1_1tree_1_1RandomForest.html");
PARAM_MATRIX_IN("training", "Training dataset.", "t");
PARAM_UROW_IN("labels", "Labels for training dataset.", "l");
src/mlpack/methods/range_search/range_search_main.cpp
+23 -15
View File
@@ -27,15 +27,19 @@ using namespace mlpack::tree;
using namespace mlpack::metric;
using namespace mlpack::util;
// Information about the program itself.
PROGRAM_INFO("Range Search",
// Short description.
// Program Name.
BINDING_NAME("Range Search");
// Short description.
BINDING_SHORT_DESC(
"An implementation of range search with single-tree and dual-tree "
"algorithms. Given a set of reference points and a set of query points and"
" a range, this can find the set of reference points within the desired "
"range for each query point, and any trees built during the computation can"
" be saved for reuse with future range searches.",
// Long description.
" be saved for reuse with future range searches.");
// Long description.
BINDING_LONG_DESC(
"This program implements range search with a Euclidean distance metric. "
"For a given query point, a given range, and a given set of reference "
"points, the program will return all of the reference points with distance "
@@ -44,8 +48,10 @@ PROGRAM_INFO("Range Search",
" points, or only a reference set -- which is then used as both the "
"reference and query set. The given range is taken to be inclusive (that "
"is, points with a distance exactly equal to the minimum and maximum of the"
" range are included in the results).",
// Example.
" range are included in the results).");
// Example.
BINDING_EXAMPLE(
"For example, the following will calculate the points within the range [2, "
"5] of each point in "+ PRINT_DATASET("input") + " and store the"
" distances in" + PRINT_DATASET("distances") + " and the neighbors in "
@@ -63,14 +69,16 @@ PROGRAM_INFO("Range Search",
" resultant CSV-like files may not be loadable by many programs. However, "
"at this time a better way to store this non-square result is not known. "
"As a result, any output files will be written as CSVs in this manner, "
"regardless of the given extension.",
SEE_ALSO("@knn", "#knn"),
SEE_ALSO("Range searching on Wikipedia",
"https://en.wikipedia.org/wiki/Range_searching"),
SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf"),
SEE_ALSO("mlpack::range::RangeSearch C++ class documentation",
"@doxygen/classmlpack_1_1range_1_1RangeSearch.html"));
"regardless of the given extension.");
// See also...
BINDING_SEE_ALSO("@knn", "#knn");
BINDING_SEE_ALSO("Range searching on Wikipedia",
"https://en.wikipedia.org/wiki/Range_searching");
BINDING_SEE_ALSO("Tree-independent dual-tree algorithms (pdf)",
"http://proceedings.mlr.press/v28/curtin13.pdf");
BINDING_SEE_ALSO("mlpack::range::RangeSearch C++ class documentation",
"@doxygen/classmlpack_1_1range_1_1RangeSearch.html");
// Define our input parameters that this program will take.
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
src/mlpack/methods/rann/krann_main.cpp
+24 -16
View File
@@ -28,21 +28,27 @@ using namespace mlpack::util;
// Convenience typedef.
typedef RAModel<NearestNeighborSort> RANNModel;
// Information about the program itself.
PROGRAM_INFO("K-Rank-Approximate-Nearest-Neighbors (kRANN)",
// Short description.
// Program Name.
BINDING_NAME("K-Rank-Approximate-Nearest-Neighbors (kRANN)");
// Short description.
BINDING_SHORT_DESC(
"An implementation of rank-approximate k-nearest-neighbor search (kRANN) "
" using single-tree and dual-tree algorithms. Given a set of reference "
"points and query points, this can find the k nearest neighbors in the "
"reference set of each query point using trees; trees that are built can "
"be saved for future use.",
// Long description.
"be saved for future use.");
// Long description.
BINDING_LONG_DESC(
"This program will calculate the k rank-approximate-nearest-neighbors of a "
"set of points. You may specify a separate set of reference points and "
"query points, or just a reference set which will be used as both the "
"reference and query set. You must specify the rank approximation (in %) "
"(and optionally the success probability).",
// Example.
"(and optionally the success probability).");
// Example.
BINDING_EXAMPLE(
"For example, the following will return 5 neighbors from the top 0.1% of "
"the data (with probability 0.95) for each point in " +
PRINT_DATASET("input") + " and store the distances in " +
@@ -62,15 +68,17 @@ PROGRAM_INFO("K-Rank-Approximate-Nearest-Neighbors (kRANN)",
"neighbors output file corresponds to the index of the point in the "
"reference set which is the i'th nearest neighbor from the point in the "
"query set with index j. Row i and column j in the distances output file "
"corresponds to the distance between those two points.",
SEE_ALSO("@knn", "#knn"),
SEE_ALSO("@lsh", "#lsh"),
SEE_ALSO("Rank-approximate nearest neighbor search: Retaining meaning and "
"speed in high dimensions (pdf)", "https://papers.nips.cc/paper/3864-"
"rank-approximate-nearest-neighbor-search-retaining-meaning-and-speed-"
"in-high-dimensions.pdf"),
SEE_ALSO("mlpack::neighbor::RASearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1RASearch.html"));
"corresponds to the distance between those two points.");
// See also...
BINDING_SEE_ALSO("@knn", "#knn");
BINDING_SEE_ALSO("@lsh", "#lsh");
BINDING_SEE_ALSO("Rank-approximate nearest neighbor search: Retaining meaning"
" and speed in high dimensions (pdf)", "https://papers.nips.cc/paper/"
"3864-rank-approximate-nearest-neighbor-search-retaining-meaning-and"
"-speed-in-high-dimensions.pdf");
BINDING_SEE_ALSO("mlpack::neighbor::RASearch C++ class documentation",
"@doxygen/classmlpack_1_1neighbor_1_1RASearch.html");
// Define our input parameters that this program will take.
PARAM_MATRIX_IN("reference", "Matrix containing the reference dataset.", "r");
src/mlpack/methods/reinforcement_learning/environment/env_type.hpp
+7 -1
View File
@@ -163,9 +163,15 @@ class ContinuousActionEnv
class Action
{
public:
double action[1];
std::vector<double> action;
// Storing degree of freedom.
static size_t size;
/**
* Construct an action instance.
*/
Action() : action(ContinuousActionEnv::Action::size)
{ /* Nothing to do here */ }
};
/**
src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp
+6 -1
View File
@@ -95,7 +95,12 @@ class Pendulum
class Action
{
public:
double action[1];
/**
* Construct an action instance.
*/
Action() : action(1)
{ /* Nothing to do here */ }
std::vector<double> action;
// Storing degree of freedom.
static const size_t size = 1;
};
src/mlpack/methods/reinforcement_learning/sac_impl.hpp
+12 -11
View File
@@ -176,7 +176,8 @@ void SAC<
arma::mat sampledActionValues(action.size, sampledActions.size());
for (size_t i = 0; i < sampledActions.size(); i++)
sampledActionValues.col(i) = sampledActions[i].action[0];
sampledActionValues.col(i) = arma::conv_to<arma::colvec>::from
(sampledActions[i].action);
arma::mat learningQInput = arma::join_vert(sampledActionValues,
sampledStates);
learningQ1Network.Forward(learningQInput, Q1);
@@ -207,7 +208,7 @@ void SAC<
// Actor network update.
arma::rowvec pi;
arma::mat pi;
policyNetwork.Predict(sampledStates, pi);
arma::mat qInput = arma::join_vert(pi, sampledStates);
@@ -226,26 +227,26 @@ void SAC<
arma::colvec singlePi;
policyNetwork.Forward(singleState, singlePi);
arma::colvec input = arma::join_vert(singlePi, singleState);
arma::rowvec weightLastLayer;
arma::mat weightLastLayer;
if (Q1(i) < Q2(i))
{
learningQ1Network.Forward(input, q);
learningQ1Network.Backward(input, -1, gradQ);
weightLastLayer = learningQ1Network.Parameters().
rows(0, hidden1 - 1).t();
weightLastLayer = arma::reshape(learningQ1Network.Parameters().
rows(0, hidden1 * singlePi.n_rows - 1), hidden1, singlePi.n_rows);
}
else
{
learningQ2Network.Forward(input, q);
learningQ2Network.Backward(input, -1, gradQ);
weightLastLayer = learningQ2Network.Parameters().
rows(0, hidden1 - 1).t();
weightLastLayer = arma::reshape(learningQ2Network.Parameters().
rows(0, hidden1 * singlePi.n_rows - 1), hidden1, singlePi.n_rows);
}
arma::colvec gradQBias = gradQ(input.n_rows * hidden1, 0,
arma::size(hidden1, 1));
arma::mat gradPolicy = weightLastLayer * gradQBias;
arma::mat gradPolicy = weightLastLayer.t() * gradQBias;
policyNetwork.Backward(singleState, gradPolicy, grad);
if (i == 0)
{
@@ -284,16 +285,16 @@ void SAC<
>::SelectAction()
{
// Get the action at current state, from policy.
arma::rowvec outputAction;
arma::colvec outputAction;
policyNetwork.Predict(state.Encode(), outputAction);
if (!deterministic)
{
arma::rowvec noise = arma::randn<arma::rowvec>(outputAction.n_rows) * 0.1;
arma::colvec noise = arma::randn<arma::colvec>(outputAction.n_rows) * 0.1;
noise = arma::clamp(noise, -0.25, 0.25);
outputAction = outputAction + noise;
}
action.action[0] = outputAction[0];
action.action = arma::conv_to<std::vector<double>>::from(outputAction);
}
template <
src/mlpack/methods/softmax_regression/softmax_regression_main.cpp
+23 -14
View File
@@ -23,15 +23,19 @@ using namespace mlpack;
using namespace mlpack::regression;
using namespace mlpack::util;
// Define parameters for the executable.
PROGRAM_INFO("Softmax Regression",
// Short description.
// Program Name.
BINDING_NAME("Softmax Regression");
// Short description.
BINDING_SHORT_DESC(
"An implementation of softmax regression for classification, which is a "
"multiclass generalization of logistic regression. Given labeled data, a "
"softmax regression model can be trained and saved for future use, or, a "
"pre-trained softmax regression model can be used for classification of "
"new points.",
// Long description.
"new points.");
// Long description.
BINDING_LONG_DESC(
"This program performs softmax regression, a generalization of logistic "
"regression to the multiclass case, and has support for L2 regularization. "
" The program is able to train a model, load an existing model, and give "
@@ -63,8 +67,10 @@ PROGRAM_INFO("Softmax Regression",
"specified for the test data with the " +
PRINT_PARAM_STRING("test_labels") + " parameter, then the program will "
"print the accuracy of the predictions on the given test set and its "
"corresponding labels.",
// Example.
"corresponding labels.");
// Example.
BINDING_EXAMPLE(
"For example, to train a softmax regression model on the data " +
PRINT_DATASET("dataset") + " with labels " + PRINT_DATASET("labels") +
" with a maximum of 1000 iterations for training, saving the trained model "
@@ -78,14 +84,17 @@ PROGRAM_INFO("Softmax Regression",
" " + PRINT_DATASET("predictions") + ", the following command can be used:"
"\n\n" +
PRINT_CALL("softmax_regression", "input_model", "sr_model", "test",
"test_points", "predictions", "predictions"),
SEE_ALSO("@logistic_regression", "#logistic_regression"),
SEE_ALSO("@random_forest", "#random_forest"),
SEE_ALSO("Multinomial logistic regression (softmax regression) on "
"test_points", "predictions", "predictions"));
// See also...
BINDING_SEE_ALSO("@logistic_regression", "#logistic_regression");
BINDING_SEE_ALSO("@random_forest", "#random_forest");
BINDING_SEE_ALSO("Multinomial logistic regression (softmax regression) on "
"Wikipedia",
"https://en.wikipedia.org/wiki/Multinomial_logistic_regression"),
SEE_ALSO("mlpack::regression::SoftmaxRegression C++ class documentation",
"@doxygen/classmlpack_1_1regression_1_1SoftmaxRegression.html"));
"https://en.wikipedia.org/wiki/Multinomial_logistic_regression");
BINDING_SEE_ALSO("mlpack::regression::SoftmaxRegression C++ class "
"documentation",
"@doxygen/classmlpack_1_1regression_1_1SoftmaxRegression.html");
// Required options.
PARAM_MATRIX_IN("training", "A matrix containing the training set (the matrix "
src/mlpack/methods/sparse_coding/sparse_coding_main.cpp
+25 -16
View File
@@ -22,14 +22,19 @@ using namespace mlpack::math;
using namespace mlpack::sparse_coding;
using namespace mlpack::util;
PROGRAM_INFO("Sparse Coding",
// Short description.
// Program Name.
BINDING_NAME("Sparse Coding");
// Short description.
BINDING_SHORT_DESC(
"An implementation of Sparse Coding with Dictionary Learning. Given a "
"dataset, this will decompose the dataset into a sparse combination of a "
"few dictionary elements, where the dictionary is learned during "
"computation; a dictionary can be reused for future sparse coding of new "
"points.",
// Long description.
"points.");
// Long description.
BINDING_LONG_DESC(
"An implementation of Sparse Coding with Dictionary Learning, which "
"achieves sparsity via an l1-norm regularizer on the codes (LASSO) or an "
"(l1+l2)-norm regularizer on the codes (the Elastic Net). Given a dense "
@@ -56,8 +61,10 @@ PROGRAM_INFO("Sparse Coding",
" an initial dictionary for the optimization, with the " +
PRINT_PARAM_STRING("initial_dictionary") + " parameter. An input model may"
" be specified with the " + PRINT_PARAM_STRING("input_model") +
" parameter.",
// Example.
" parameter.");
// Example.
BINDING_EXAMPLE(
"As an example, to build a sparse coding model on the dataset " +
PRINT_DATASET("data") + " using 200 atoms and an l1-regularization "
"parameter of 0.1, saving the model into " + PRINT_MODEL("model") + ", use "
@@ -70,18 +77,20 @@ PROGRAM_INFO("Sparse Coding",
PRINT_DATASET("codes") + ": "
"\n\n" +
PRINT_CALL("sparse_coding", "input_model", "model", "test", "otherdata",
"codes", "codes"),
SEE_ALSO("@local_coordinate_coding", "#local_coordinate_coding"),
SEE_ALSO("Sparse dictionary learning on Wikipedia",
"https://en.wikipedia.org/wiki/Sparse_dictionary_learning"),
SEE_ALSO("Efficient sparse coding algorithms (pdf)",
"codes", "codes"));
// See also...
BINDING_SEE_ALSO("@local_coordinate_coding", "#local_coordinate_coding");
BINDING_SEE_ALSO("Sparse dictionary learning on Wikipedia",
"https://en.wikipedia.org/wiki/Sparse_dictionary_learning");
BINDING_SEE_ALSO("Efficient sparse coding algorithms (pdf)",
"http://papers.nips.cc/paper/2979-efficient-sparse-coding-"
"algorithms.pdf"),
SEE_ALSO("Regularization and variable selection via the elastic net",
"algorithms.pdf");
BINDING_SEE_ALSO("Regularization and variable selection via the elastic net",
"http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.124.4696&"
"rep=rep1&type=pdf"),
SEE_ALSO("mlpack::sparse_coding::SparseCoding C++ class documentation",
"@doxygen/classmlpack_1_1sparse__coding_1_1SparseCoding.html"));
"rep=rep1&type=pdf");
BINDING_SEE_ALSO("mlpack::sparse_coding::SparseCoding C++ class documentation",
"@doxygen/classmlpack_1_1sparse__coding_1_1SparseCoding.html");
// Train the model.
PARAM_MATRIX_IN("training", "Matrix of training data (X).", "t");
src/mlpack/tests/logistic_regression_test.cpp
+34
View File
@@ -1023,4 +1023,38 @@ BOOST_AUTO_TEST_CASE(ConstructionThenTraining)
BOOST_REQUIRE_NO_THROW(lr.Train(myMatrix, myTargets));
}
/**
* Make sure that incremental training works.
*/
BOOST_AUTO_TEST_CASE(IncrementalTraining)
{
// Generate a two-Gaussian dataset.
GaussianDistribution g1(arma::vec("1.0 1.0 1.0"), arma::eye<arma::mat>(3, 3));
GaussianDistribution g2(arma::vec("9.0 9.0 9.0"), arma::eye<arma::mat>(3, 3));
arma::mat data(3, 1000);
arma::Row<size_t> responses(1000);
for (size_t i = 0; i < 500; ++i)
{
data.col(i) = g1.Random();
responses[i] = 0;
}
for (size_t i = 500; i < 1000; ++i)
{
data.col(i) = g2.Random();
responses[i] = 1;
}
// Now train a logistic regression object on it.
LogisticRegression<> lr(data.n_rows, 0.5);
for (size_t epoch = 0; epoch < 10; ++epoch)
for (size_t i = 0; i < data.n_cols; ++i)
lr.Train<ens::StandardSGD>(data, responses);
// Ensure that the error is close to zero.
const double acc = lr.ComputeAccuracy(data, responses);
BOOST_REQUIRE_CLOSE(acc, 100.0, 3.0); // 3% error tolerance.
}
BOOST_AUTO_TEST_SUITE_END();
src/mlpack/tests/q_learning_test.cpp
+51 -2
View File
@@ -22,8 +22,9 @@
#include <mlpack/methods/reinforcement_learning/sac.hpp>
#include <mlpack/methods/reinforcement_learning/q_networks/simple_dqn.hpp>
#include <mlpack/methods/reinforcement_learning/q_networks/dueling_dqn.hpp>
#include <mlpack/methods/reinforcement_learning/environment/pendulum.hpp>
#include <mlpack/methods/reinforcement_learning/q_networks/categorical_dqn.hpp>
#include <mlpack/methods/reinforcement_learning/environment/env_type.hpp>
#include <mlpack/methods/reinforcement_learning/environment/pendulum.hpp>
#include <mlpack/methods/reinforcement_learning/environment/mountain_car.hpp>
#include <mlpack/methods/reinforcement_learning/environment/acrobot.hpp>
#include <mlpack/methods/reinforcement_learning/environment/cart_pole.hpp>
@@ -515,7 +516,7 @@ BOOST_AUTO_TEST_CASE(PendulumWithSAC)
for (size_t trial = 0; trial < 3; ++trial)
{
Log::Debug << "Trial number: " << trial << std::endl;
// Set up the policy and replay method.
// Set up the replay method.
RandomReplay<Pendulum> replayMethod(32, 10000);
TrainingConfig config;
@@ -547,4 +548,52 @@ BOOST_AUTO_TEST_CASE(PendulumWithSAC)
BOOST_REQUIRE(converged);
}
//! A test to ensure SAC works with multiple actions in action space.
BOOST_AUTO_TEST_CASE(SACForMultipleActions)
{
ContinuousActionEnv::State::dimension = 3;
ContinuousActionEnv::Action::size = 4;
FFN<EmptyLoss<>, GaussianInitialization>
policyNetwork(EmptyLoss<>(), GaussianInitialization(0, 0.1));
policyNetwork.Add(new Linear<>(ContinuousActionEnv::State::dimension, 128));
policyNetwork.Add(new ReLULayer<>());
policyNetwork.Add(new Linear<>(128, ContinuousActionEnv::Action::size));
policyNetwork.Add(new TanHLayer<>());
FFN<EmptyLoss<>, GaussianInitialization>
qNetwork(EmptyLoss<>(), GaussianInitialization(0, 0.1));
qNetwork.Add(new Linear<>(ContinuousActionEnv::State::dimension +
ContinuousActionEnv::Action::size, 128));
qNetwork.Add(new ReLULayer<>());
qNetwork.Add(new Linear<>(128, 1));
// Set up the replay method.
RandomReplay<ContinuousActionEnv> replayMethod(32, 10000);
TrainingConfig config;
config.StepSize() = 0.001;
config.TargetNetworkSyncInterval() = 1;
config.UpdateInterval() = 3;
// Set up Soft actor-critic agent.
SAC<ContinuousActionEnv, decltype(qNetwork), decltype(policyNetwork),
AdamUpdate>
agent(config, qNetwork, policyNetwork, replayMethod);
agent.State().Data() = arma::randu<arma::colvec>
(ContinuousActionEnv::State::dimension, 1);
agent.SelectAction();
// Test to check if the action dimension given by the agent is correct.
BOOST_REQUIRE_EQUAL(agent.Action().action.size(),
ContinuousActionEnv::Action::size);
replayMethod.Store(agent.State(), agent.Action(), 1, agent.State(), 1, 0.99);
agent.TotalSteps()++;
agent.Update();
// If the agent is able to reach till this point of the test, it is assured
// that the agent can handle multiple actions in continuous space.
}
BOOST_AUTO_TEST_SUITE_END();
src/mlpack/tests/rbm_network_test.cpp
+5 -8
View File
@@ -88,14 +88,13 @@ BOOST_AUTO_TEST_CASE(BinaryRBMClassificationTest)
for (size_t i = 0; i < trainData.n_cols; ++i)
{
model.HiddenMean(std::move(trainData.col(i)), std::move(output));
model.HiddenMean(trainData.col(i), output);
XRbm.col(i) = output;
}
for (size_t i = 0; i < testData.n_cols; ++i)
{
model.HiddenMean(std::move(testData.col(i)),
std::move(output));
model.HiddenMean(testData.col(i), output);
YRbm.col(i) = output;
}
const size_t numClasses = 10; // Number of classes.
@@ -189,15 +188,13 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest)
for (size_t i = 0; i < trainData.n_cols; ++i)
{
modelssRBM.HiddenMean(std::move(trainData.col(i)),
std::move(output));
modelssRBM.HiddenMean(trainData.col(i), output);
XRbm.col(i) = output;
}
for (size_t i = 0; i < testData.n_cols; ++i)
{
modelssRBM.HiddenMean(std::move(testData.col(i)),
std::move(output));
modelssRBM.HiddenMean(testData.col(i), output);
YRbm.col(i) = output;
}
const size_t numClasses = 10; // Number of classes.
@@ -238,7 +235,7 @@ void BuildVanillaNetwork(MatType& trainData,
arma::vec calculatedFreeEnergy(4, arma::fill::zeros);
for (size_t i = 0; i < trainData.n_cols; ++i)
{
calculatedFreeEnergy(i) = model.FreeEnergy(std::move(trainData.col(i)));
calculatedFreeEnergy(i) = model.FreeEnergy(trainData.col(i));
}
for (size_t i = 0; i < freeEnergy.n_elem; ++i)