From f0945a8500524db5b5f1a5b9ef3cbc4aafcd39fd Mon Sep 17 00:00:00 2001 From: Yashwant Date: Sun, 9 Aug 2020 13:17:09 +0530 Subject: [PATCH 01/25] Initial Commit. --- doc/guide/bindings.hpp | 252 ++++++++++++++---- doc/guide/iodoc.hpp | 28 +- src/mlpack/bindings/cli/cli_option.hpp | 31 +-- .../bindings/cli/print_doc_functions.hpp | 5 +- .../bindings/cli/print_doc_functions_impl.hpp | 11 +- src/mlpack/bindings/cli/print_help.cpp | 17 +- src/mlpack/bindings/go/generate_go.cpp.in | 2 +- .../bindings/go/print_doc_functions_impl.hpp | 12 +- src/mlpack/bindings/go/print_go.cpp | 20 +- src/mlpack/bindings/go/print_go.hpp | 4 +- .../go/tests/test_go_binding_main.cpp | 13 +- src/mlpack/bindings/julia/generate_jl.cpp.in | 2 +- .../julia/print_doc_functions_impl.hpp | 8 +- src/mlpack/bindings/julia/print_jl.cpp | 16 +- src/mlpack/bindings/julia/print_jl.hpp | 3 +- .../julia/tests/test_julia_binding_main.cpp | 11 +- src/mlpack/bindings/markdown/binding_info.cpp | 98 ++++++- src/mlpack/bindings/markdown/binding_info.hpp | 62 ++++- .../bindings/markdown/print_doc_functions.hpp | 5 +- .../markdown/print_doc_functions_impl.hpp | 5 +- src/mlpack/bindings/markdown/print_docs.cpp | 45 ++-- .../bindings/markdown/program_doc_wrapper.hpp | 86 +++++- .../bindings/python/generate_pyx.cpp.in | 3 +- .../python/print_doc_functions_impl.hpp | 8 +- src/mlpack/bindings/python/print_pyx.cpp | 22 +- src/mlpack/bindings/python/print_pyx.hpp | 4 +- .../python/tests/test_python_binding_main.cpp | 11 +- src/mlpack/bindings/tests/test_option.hpp | 29 -- src/mlpack/core/util/io.cpp | 104 +++++++- src/mlpack/core/util/io.hpp | 107 +++++++- src/mlpack/core/util/mlpack_main.hpp | 92 +++++-- src/mlpack/core/util/param.hpp | 200 ++++++++++---- src/mlpack/core/util/program_doc.cpp | 126 +++++++-- src/mlpack/core/util/program_doc.hpp | 121 ++++++--- src/mlpack/methods/adaboost/adaboost_main.cpp | 39 +-- .../methods/approx_kfn/approx_kfn_main.cpp | 43 +-- .../bayesian_linear_regression_main.cpp | 35 ++- src/mlpack/methods/cf/cf_main.cpp | 49 ++-- src/mlpack/methods/dbscan/dbscan_main.cpp | 33 ++- .../decision_stump/decision_stump_main.cpp | 27 +- .../decision_tree/decision_tree_main.cpp | 39 +-- src/mlpack/methods/det/det_main.cpp | 33 ++- src/mlpack/methods/emst/emst_main.cpp | 37 ++- src/mlpack/methods/fastmks/fastmks_main.cpp | 37 ++- src/mlpack/methods/gmm/gmm_generate_main.cpp | 35 ++- .../methods/gmm/gmm_probability_main.cpp | 35 ++- src/mlpack/methods/gmm/gmm_train_main.cpp | 35 ++- src/mlpack/methods/hmm/hmm_generate_main.cpp | 37 ++- src/mlpack/methods/hmm/hmm_loglik_main.cpp | 37 ++- src/mlpack/methods/hmm/hmm_train_main.cpp | 31 ++- src/mlpack/methods/hmm/hmm_viterbi_main.cpp | 37 ++- .../hoeffding_trees/hoeffding_tree_main.cpp | 35 ++- src/mlpack/methods/kde/kde_main.cpp | 45 ++-- .../methods/kernel_pca/kernel_pca_main.cpp | 45 ++-- src/mlpack/methods/kmeans/kmeans_main.cpp | 50 ++-- src/mlpack/methods/lars/lars_main.cpp | 33 ++- .../linear_regression_main.cpp | 37 ++- .../methods/linear_svm/linear_svm_main.cpp | 35 ++- src/mlpack/methods/lmnn/lmnn_main.cpp | 38 +-- .../local_coordinate_coding_main.cpp | 33 ++- .../logistic_regression_main.cpp | 37 ++- src/mlpack/methods/lsh/lsh_main.cpp | 40 +-- .../methods/mean_shift/mean_shift_main.cpp | 40 +-- src/mlpack/methods/mvu/mvu_main.cpp | 6 +- src/mlpack/methods/naive_bayes/nbc_main.cpp | 35 ++- src/mlpack/methods/nca/nca_main.cpp | 32 ++- .../methods/neighbor_search/kfn_main.cpp | 36 ++- .../methods/neighbor_search/knn_main.cpp | 42 +-- src/mlpack/methods/nmf/nmf_main.cpp | 42 +-- src/mlpack/methods/pca/pca_main.cpp | 32 ++- .../methods/perceptron/perceptron_main.cpp | 33 ++- .../preprocess/image_converter_main.cpp | 31 ++- .../preprocess/preprocess_binarize_main.cpp | 29 +- .../preprocess/preprocess_describe_main.cpp | 29 +- .../preprocess/preprocess_imputer_main.cpp | 28 +- .../preprocess/preprocess_scale_main.cpp | 29 +- .../preprocess/preprocess_split_main.cpp | 29 +- src/mlpack/methods/radical/radical_main.cpp | 35 ++- .../random_forest/random_forest_main.cpp | 41 +-- .../range_search/range_search_main.cpp | 38 +-- src/mlpack/methods/rann/krann_main.cpp | 40 +-- .../softmax_regression_main.cpp | 37 ++- .../sparse_coding/sparse_coding_main.cpp | 41 +-- 83 files changed, 2248 insertions(+), 1067 deletions(-) diff --git a/doc/guide/bindings.hpp b/doc/guide/bindings.hpp index 96e57a01b7..31b59e3d54 100644 --- a/doc/guide/bindings.hpp +++ b/doc/guide/bindings.hpp @@ -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_PNAME("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,22 +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." - "\n\n" + " " + 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. @@ -228,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 \--help option for a -command-line program. +@c BINDING_PNAME(), @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 +\--help 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 @@ -247,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_PNAME(), +@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("name"). - All output parameters should be set by the end of the function with the @@ -278,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_PNAME(), @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 header. The macro +Any mlpack program should be documented with the @c BINDING_PNAME(), +@c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC() , @c BINDING_EXAMPLE() and +@c BINDING_SEE_ALSO() macros, which is available from the +@c header. The macro is of the form @code -PROGRAM_INFO("program name", "short documentation", "long documentation", - 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 @@ -368,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 @@ -383,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 @@ -408,12 +449,39 @@ 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_PNAME("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" @@ -425,8 +493,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." - "\n\n" + 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 " @@ -479,17 +549,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 macro, 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 @@ -620,10 +739,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() 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. 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 @@ -703,7 +822,8 @@ could be created for the "random_numbers" program from earlier sections. @code #include -// The PROGRAM_INFO() and PARAM_*() definitions should go here: +// BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(), +// BINDING_SEE_ALSO() and PARAM_*() definitions should go here: // ... using namespace mlpack; @@ -759,23 +879,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_PNAME() 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 + - the BINDING_EXAMPLE() macro that defines the example + - the BINDING_SEE_ALSO() macro that defines the see also - 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_PNAME(), +@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_PNAME() 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 seealso. 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 @@ -875,7 +1015,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 @@ -1047,9 +1188,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_PNAME(), @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 diff --git a/doc/guide/iodoc.hpp b/doc/guide/iodoc.hpp index 3282268f88..9a25188e7d 100644 --- a/doc/guide/iodoc.hpp +++ b/doc/guide/iodoc.hpp @@ -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_PNAME, 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 #include -// Document program. -PROGRAM_INFO("Principal Components Analysis", - // Short description. +// Program Name. +BINDING_PNAME("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. diff --git a/src/mlpack/bindings/cli/cli_option.hpp b/src/mlpack/bindings/cli/cli_option.hpp index f09f324ea0..eeebc2d7cc 100644 --- a/src/mlpack/bindings/cli/cli_option.hpp +++ b/src/mlpack/bindings/cli/cli_option.hpp @@ -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 diff --git a/src/mlpack/bindings/cli/print_doc_functions.hpp b/src/mlpack/bindings/cli/print_doc_functions.hpp index 3b027f8720..1f7e9390bb 100644 --- a/src/mlpack/bindings/cli/print_doc_functions.hpp +++ b/src/mlpack/bindings/cli/print_doc_functions.hpp @@ -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); diff --git a/src/mlpack/bindings/cli/print_doc_functions_impl.hpp b/src/mlpack/bindings/cli/print_doc_functions_impl.hpp index fbfa22c33b..68339e5912 100644 --- a/src/mlpack/bindings/cli/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/cli/print_doc_functions_impl.hpp @@ -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."); } } diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index 5cfa1bf57e..2b2cf7bb58 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -25,7 +25,8 @@ void PrintHelp(const std::string& param) std::string usedParam = param; std::map& parameters = IO::Parameters(); const std::map& aliases = IO::Aliases(); - util::ProgramDoc& docs = *IO::GetSingleton().doc; + util::ProgramName& pname = *IO::GetSingleton().pname; + util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // If we pass a single param, alias it if necessary. if (usedParam.length() == 1 && aliases.count(usedParam[0])) @@ -64,11 +65,17 @@ void PrintHelp(const std::string& param) } // Print out the descriptions. - if (docs.programName != "") + if (pname.programName != "") { - std::cout << docs.programName << std::endl << std::endl; - std::cout << " " << util::HyphenateString(docs.documentation(), 2) - << std::endl << std::endl; + std::cout << pname.programName << std::endl << std::endl; + std::cout << " " << util::HyphenateString(longDesc.longDescription(), + 2) << std::endl << std::endl; + for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + { + util::Example& example = *IO::GetSingleton().examples[j]; + std::cout << " " << util::HyphenateString(example.example(), 2) + << std::endl << std::endl; + } } else std::cout << "[undocumented program]" << std::endl << std::endl; diff --git a/src/mlpack/bindings/go/generate_go.cpp.in b/src/mlpack/bindings/go/generate_go.cpp.in index 5a07bc5573..086783e3e2 100644 --- a/src/mlpack/bindings/go/generate_go.cpp.in +++ b/src/mlpack/bindings/go/generate_go.cpp.in @@ -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("${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/go/print_doc_functions_impl.hpp b/src/mlpack/bindings/go/print_doc_functions_impl.hpp index 80971f6fda..eb7c508e38 100644 --- a/src/mlpack/bindings/go/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/go/print_doc_functions_impl.hpp @@ -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."); } } diff --git a/src/mlpack/bindings/go/print_go.cpp b/src/mlpack/bindings/go/print_go.cpp index 2d9e19c421..d69e82e6fd 100644 --- a/src/mlpack/bindings/go/print_go.cpp +++ b/src/mlpack/bindings/go/print_go.cpp @@ -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 functionName Name of the function (i.e. "pca"). */ -void PrintGo(const util::ProgramDoc& programInfo, - const std::string& functionName) +void PrintGo(const std::string& functionName) { + util::ProgramName& pname = *IO::GetSingleton().pname; + util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(pname.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -124,8 +124,14 @@ 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(longDesc.longDescription(), 2) << endl; + cout << endl; + for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + { + util::Example& example = *IO::GetSingleton().examples[j]; + cout << " " << util::HyphenateString(example.example(), 2) + << endl << endl; + } cout << " Input parameters:" << endl; cout << endl; for (size_t i = 0; i < inputOptions.size(); ++i) @@ -216,7 +222,7 @@ void PrintGo(const util::ProgramDoc& programInfo, cout << " " << "disableVerbose()" << endl; // Restore the parameters. - cout << " " << "restoreSettings(\"" << programInfo.programName + cout << " " << "restoreSettings(\"" << pname.programName << "\")" << endl; cout << endl; diff --git a/src/mlpack/bindings/go/print_go.hpp b/src/mlpack/bindings/go/print_go.hpp index 4b6bfdbed6..3a9da298c2 100644 --- a/src/mlpack/bindings/go/print_go.hpp +++ b/src/mlpack/bindings/go/print_go.hpp @@ -23,11 +23,9 @@ 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 functionName Name of the function (i.e. "pca"). */ -void PrintGo(const util::ProgramDoc& programInfo, - const std::string& functionName); +void PrintGo(const std::string& functionName); } // namespace go diff --git a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp index e255f3345e..d3f4d922f3 100644 --- a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp +++ b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp @@ -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_PNAME("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."); diff --git a/src/mlpack/bindings/julia/generate_jl.cpp.in b/src/mlpack/bindings/julia/generate_jl.cpp.in index 289342f7a7..4afceb02c5 100644 --- a/src/mlpack/bindings/julia/generate_jl.cpp.in +++ b/src/mlpack/bindings/julia/generate_jl.cpp.in @@ -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("${NAME}", "${MLPACK_JL_LIB_SUFFIX}"); } diff --git a/src/mlpack/bindings/julia/print_doc_functions_impl.hpp b/src/mlpack/bindings/julia/print_doc_functions_impl.hpp index 2c1ef7fe9f..3e8b69b845 100644 --- a/src/mlpack/bindings/julia/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/julia/print_doc_functions_impl.hpp @@ -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."); } } diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index bc68a8fc83..fd8c468d3c 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -27,12 +27,13 @@ extern std::string programName; /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const util::ProgramDoc& programInfo, - const string& functionName, +void PrintJL(const string& functionName, const std::string& mlpackJuliaLibSuffix) { + util::ProgramName& pname = *IO::GetSingleton().pname; + util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(pname.programName); map& parameters = IO::Parameters(); typedef map::iterator ParamIter; @@ -168,8 +169,13 @@ void PrintJL(const util::ProgramDoc& programInfo, cout << endl; // Next print the description. - cout << util::HyphenateString(programInfo.documentation(), 0) << endl; - + cout << util::HyphenateString(longDesc.longDescription(), 0) << endl; + for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + { + util::Example& example = *IO::GetSingleton().examples[j]; + cout << util::HyphenateString(example.example(), 0) + << endl; + } // Next, print information on the input options. cout << endl; cout << "# Arguments" << endl; diff --git a/src/mlpack/bindings/julia/print_jl.hpp b/src/mlpack/bindings/julia/print_jl.hpp index 39b84295d2..b8d813c559 100644 --- a/src/mlpack/bindings/julia/print_jl.hpp +++ b/src/mlpack/bindings/julia/print_jl.hpp @@ -21,8 +21,7 @@ namespace julia { /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const util::ProgramDoc& programInfo, - const std::string& functionName, +void PrintJL(const std::string& functionName, const std::string& mlpackJuliaLibSuffix); } // namespace julia diff --git a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp index a91d6e0f6a..5bd5c73a7b 100644 --- a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp +++ b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp @@ -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_PNAME("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."); diff --git a/src/mlpack/bindings/markdown/binding_info.cpp b/src/mlpack/bindings/markdown/binding_info.cpp index e76ee2eb39..d23505f96e 100644 --- a/src/mlpack/bindings/markdown/binding_info.cpp +++ b/src/mlpack/bindings/markdown/binding_info.cpp @@ -17,23 +17,101 @@ namespace mlpack { namespace bindings { namespace markdown { -util::ProgramDoc& BindingInfo::GetProgramDoc(const std::string& bindingName) +util::ProgramName& BindingInfo::GetProgramName(const std::string& bindingName) { - if (GetSingleton().map.count(bindingName) == 0) + if (GetSingleton().mapProgramName.count(bindingName) == 0) { - throw std::invalid_argument("Binding name '" + bindingName + - "' not known!"); + throw std::invalid_argument("No program name associated with'" + bindingName + + "'!"); } - return GetSingleton().map.at(bindingName); + return GetSingleton().mapProgramName.at(bindingName); } - -//! Register a ProgramDoc object with the given bindingName. -void BindingInfo::RegisterProgramDoc(const std::string& bindingName, - const util::ProgramDoc& programDoc) +util::ShortDescription& BindingInfo::GetShortDescription( + const std::string& bindingName) { - GetSingleton().map[bindingName] = programDoc; + if (GetSingleton().mapShortDescription.count(bindingName) == 0) + { + throw std::invalid_argument("No short description associated with'" + + bindingName + "'!"); + } + + return GetSingleton().mapShortDescription.at(bindingName); +} + +util::LongDescription& BindingInfo::GetLongDescription( + const std::string& bindingName) +{ + if (GetSingleton().mapLongDescription.count(bindingName) == 0) + { + throw std::invalid_argument("No long description associated with'" + + bindingName + "'!"); + } + + return GetSingleton().mapLongDescription.at(bindingName); +} + +std::vector& BindingInfo::GetExample(const std::string& + bindingName) +{ + // Some bindings may not have examples. + if (GetSingleton().mapExample.count(bindingName) == 0) + { + static std::vector empty; + return empty; + } + + return GetSingleton().mapExample.at(bindingName); +} + +std::vector& BindingInfo::GetSeeAlso(const std::string& + bindingName) +{ + if (GetSingleton().mapSeeAlso.count(bindingName) == 0) + { + throw std::invalid_argument("No see also associated with'" + bindingName + + "'!"); + } + + return GetSingleton().mapSeeAlso.at(bindingName); +} + +//! Register a ProgramName object with the given bindingName. +void BindingInfo::RegisterProgramName(const std::string& bindingName, + const util::ProgramName& programName) +{ + GetSingleton().mapProgramName[bindingName] = programName; +} + +//! Register a ShortDescription object with the given bindingName. +void BindingInfo::RegisterShortDescription(const std::string& bindingName, + const util::ShortDescription& + shortDescription) +{ + GetSingleton().mapShortDescription[bindingName] = shortDescription; +} + +//! Register a LongDescription object with the given bindingName. +void BindingInfo::RegisterLongDescription(const std::string& bindingName, + const util::LongDescription& + longDescription) +{ + GetSingleton().mapLongDescription[bindingName] = longDescription; +} + +//! Register a Example object with the given bindingName. +void BindingInfo::RegisterExample(const std::string& bindingName, + const util::Example& example) +{ + GetSingleton().mapExample[bindingName].push_back(example); +} + +//! Register a SeeAlso object with the given bindingName. +void BindingInfo::RegisterSeeAlso(const std::string& bindingName, + const util::SeeAlso& seeAlso) +{ + GetSingleton().mapSeeAlso[bindingName].push_back(seeAlso); } //! Get or modify the current language (don't set it to something invalid!). diff --git a/src/mlpack/bindings/markdown/binding_info.hpp b/src/mlpack/bindings/markdown/binding_info.hpp index b93738b26e..b076d7d8bb 100644 --- a/src/mlpack/bindings/markdown/binding_info.hpp +++ b/src/mlpack/bindings/markdown/binding_info.hpp @@ -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 @@ -24,18 +24,50 @@ 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); + //! Return a ProgramName object for a given bindingName. + static util::ProgramName& GetProgramName(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 ShortDescription object for a given bindingName. + static util::ShortDescription& GetShortDescription( + const std::string& bindingName); + + //! Return a LongDescription object for a given bindingName. + static util::LongDescription& GetLongDescription( + const std::string& bindingName); + + //! Return a Example object for a given bindingName. + static std::vector& GetExample(const std::string& bindingName); + + //! Return a SeeAlso object for a given bindingName. + static std::vector& GetSeeAlso(const std::string& bindingName); + + //! Register a ProgramName object with the given bindingName. + static void RegisterProgramName(const std::string& bindingName, + const util::ProgramName& programName); + + //! Register a ShortDescription object with the given bindingName. + static void RegisterShortDescription(const std::string& bindingName, + const util::ShortDescription& + shortDescription); + + //! Register a LongDescription object with the given bindingName. + static void RegisterLongDescription(const std::string& bindingName, + const util::LongDescription& + longDescription); + + //! Register a Example object with the given bindingName. + static void RegisterExample(const std::string& bindingName, + const util::Example& example); + + //! Register a SeeAlso object with the given bindingName. + static void RegisterSeeAlso(const std::string& bindingName, + const util::SeeAlso& seeAlso); //! Get or modify the current language (don't set it to something invalid!). static std::string& Language(); @@ -47,8 +79,20 @@ class BindingInfo //! Get the singleton. static BindingInfo& GetSingleton(); - //! Internally-held map for mapping a binding name to a ProgramDoc name. - std::unordered_map map; + //! Internally-held map for mapping a binding name to a ProgramName name. + std::unordered_map mapProgramName; + + //! Internally-held map for mapping a binding name to a ShortDescription name. + std::unordered_map mapShortDescription; + + //! Internally-held map for mapping a binding name to a LongDescription name. + std::unordered_map mapLongDescription; + + //! Internally-held map for mapping a binding name to a Example name. + std::unordered_map> mapExample; + + //! Internally-held map for mapping a binding name to a SeeAlso name. + std::unordered_map> mapSeeAlso; //! Holds the name of the language that we are currently printing. This is //! modified before printing the documentation, and then used by diff --git a/src/mlpack/bindings/markdown/print_doc_functions.hpp b/src/mlpack/bindings/markdown/print_doc_functions.hpp index 35e60e0934..c122339b95 100644 --- a/src/mlpack/bindings/markdown/print_doc_functions.hpp +++ b/src/mlpack/bindings/markdown/print_doc_functions.hpp @@ -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); diff --git a/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp b/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp index da4718487a..968b30486b 100644 --- a/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/markdown/print_doc_functions_impl.hpp @@ -596,8 +596,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) { diff --git a/src/mlpack/bindings/markdown/print_docs.cpp b/src/mlpack/bindings/markdown/print_docs.cpp index 2ffacfd6cb..f188728128 100644 --- a/src/mlpack/bindings/markdown/print_docs.cpp +++ b/src/mlpack/bindings/markdown/print_docs.cpp @@ -45,7 +45,13 @@ void PrintHeaders(const std::string& bindingName, void PrintDocs(const std::string& bindingName, const vector& languages) { - ProgramDoc& programDoc = BindingInfo::GetProgramDoc(bindingName); + ProgramName& programName = BindingInfo::GetProgramName(bindingName); + ShortDescription& shortDescription = + BindingInfo::GetShortDescription(bindingName); + LongDescription& longDescription = + BindingInfo::GetLongDescription(bindingName); + std::vector& examples = BindingInfo::GetExample(bindingName); + std::vector& seeAlsos = BindingInfo::GetSeeAlso(bindingName); IO::RestoreSettings(bindingName); @@ -63,8 +69,8 @@ void PrintDocs(const std::string& bindingName, cout << endl; // Next, print the logical name of the binding (that's known by - // ProgramInfo). - cout << "#### " << programDoc.programName << endl; + // BINDING_PNAME()). + cout << "#### " << programName.programName << endl; cout << endl; for (size_t i = 0; i < languages.size(); ++i) @@ -78,7 +84,7 @@ void PrintDocs(const std::string& bindingName, } cout << endl; - cout << programDoc.shortDocumentation << " "; + cout << shortDescription.shortDescription << " "; for (size_t i = 0; i < languages.size(); ++i) { cout << "[Detailed documentation](#" << languages[i] << "_" @@ -87,7 +93,7 @@ void PrintDocs(const std::string& bindingName, } cout << "." << endl; - // Next, print the PROGRAM_INFO() documentation for each language. + // Next, print the documentation for each language. for (size_t i = 0; i < languages.size(); ++i) { BindingInfo::Language() = languages[i]; @@ -213,37 +219,44 @@ void PrintDocs(const std::string& bindingName, cout << "{: #" << languages[i] << "_" << bindingName << "_detailed-documentation }" << endl; cout << endl; - string doc = boost::replace_all_copy(programDoc.documentation(), + string desc = boost::replace_all_copy(longDescription.longDescription(), "|", "\\|"); - cout << doc << endl; + cout << desc << endl; + for (size_t j = 0; j < examples.size(); ++j) + { + util::Example& example = examples[j]; + string eg = boost::replace_all_copy(example.example(), "|", "\\|"); + cout << eg << endl; + } cout << endl; cout << "### See also" << endl; cout << endl; - for (size_t j = 0; j < programDoc.seeAlso.size(); ++j) + for (size_t j = 0; j < seeAlsos.size(); ++j) { + util::SeeAlso& seeAlso = seeAlsos[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 (seeAlso.description[0] == '@') + cout << GetBindingName(seeAlso.description.substr(1)); else - cout << programDoc.seeAlso[j].first; + cout << seeAlso.description; cout << "]("; // We need special handling of Doxygen information. - if (programDoc.seeAlso[j].second.substr(0, 8) == "@doxygen") + if (seeAlso.link.substr(0, 8) == "@doxygen") { - cout << DOXYGEN_PREFIX << programDoc.seeAlso[j].second.substr(9); + cout << DOXYGEN_PREFIX << seeAlso.link.substr(9); } - else if (programDoc.seeAlso[j].second[0] == '#') + else if (seeAlso.link[0] == '#') { cout << "#" << languages[i] << "_" - << programDoc.seeAlso[j].second.substr(1); + << seeAlso.link.substr(1); } else { - cout << programDoc.seeAlso[j].second; + cout << seeAlso.link; } cout << ")" << endl; diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index 5811f54115..500aa79e2c 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -2,8 +2,11 @@ * @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 calls + * BindingInfo::RegisterProgramName(), BindingInfo::RegisterShortDescription(), + * BindingInfo::RegisterLongDescription(), BindingInfo::RegisterExample() and + * BindingInfo::RegisterSeeAlso() 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,23 +22,78 @@ namespace mlpack { namespace bindings { namespace markdown { -class ProgramDocWrapper +class ProgramNameWrapper { public: /** - * Construct a ProgramDoc object and register it with - * BindingInfo::RegisterProgramDoc(). + * Construct a ProgramName object and register it with + * BindingInfo::RegisterProgramName(). */ - ProgramDocWrapper(const std::string& bindingName, - const std::string& programName, - const std::string& shortDocumentation, - const std::function& documentation, - const std::vector>& - seeAlso) + ProgramNameWrapper(const std::string& bindingName, + const std::string& programName) { - util::ProgramDoc pd(programName, shortDocumentation, documentation, - seeAlso); - BindingInfo::RegisterProgramDoc(bindingName, pd); + util::ProgramName pd(programName); + BindingInfo::RegisterProgramName(bindingName, pd); + } +}; + +class ShortDescriptionWrapper +{ + public: + /** + * Construct a ShortDescription object and register it with + * BindingInfo::RegisterShortDescription(). + */ + ShortDescriptionWrapper(const std::string& bindingName, + const std::string shortDescription) + { + util::ShortDescription pd(shortDescription); + BindingInfo::RegisterShortDescription(bindingName, pd); + } +}; + +class LongDescriptionWrapper +{ + public: + /** + * Construct a LongDescription object and register it with + * BindingInfo::RegisterLongDescription(). + */ + LongDescriptionWrapper(const std::string& bindingName, + const std::function longDescription) + { + util::LongDescription pd(longDescription); + BindingInfo::RegisterLongDescription(bindingName, pd); + } +}; + +class ExampleWrapper +{ + public: + /** + * Construct a Example object and register it with + * BindingInfo::RegisterExample(). + */ + ExampleWrapper(const std::string& bindingName, + const std::function example) + { + util::Example pd(example); + BindingInfo::RegisterExample(bindingName, pd); + } +}; + +class SeeAlsoWrapper +{ + public: + /** + * Construct a SeeAlso object and register it with + * BindingInfo::RegisterSeeAlso(). + */ + SeeAlsoWrapper(const std::string& bindingName, + const std::string description, const std::string link) + { + util::SeeAlso pd(description, link); + BindingInfo::RegisterSeeAlso(bindingName, pd); } }; diff --git a/src/mlpack/bindings/python/generate_pyx.cpp.in b/src/mlpack/bindings/python/generate_pyx.cpp.in index 7eb2824969..00ff566b9d 100644 --- a/src/mlpack/bindings/python/generate_pyx.cpp.in +++ b/src/mlpack/bindings/python/generate_pyx.cpp.in @@ -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("${PROGRAM_MAIN_FILE}", "${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/python/print_doc_functions_impl.hpp b/src/mlpack/bindings/python/print_doc_functions_impl.hpp index 9e6bebd987..4f282e2a68 100644 --- a/src/mlpack/bindings/python/print_doc_functions_impl.hpp +++ b/src/mlpack/bindings/python/print_doc_functions_impl.hpp @@ -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. diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 72b895697b..5db4129eab 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -27,17 +27,17 @@ namespace python { * generated .pyx file to stdout. * * @param parameters List of parameters the program will use (from IO). - * @param programInfo 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, - const string& mainFilename, +void PrintPYX(const string& mainFilename, const string& functionName) { + util::ProgramName& pname = *IO::GetSingleton().pname; + util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(programInfo.programName); + IO::RestoreSettings(pname.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -143,10 +143,16 @@ void PrintPYX(const ProgramDoc& programInfo, // Print the comment describing the function and its parameters. cout << " \"\"\"" << endl; - cout << " " << programInfo.programName << endl; + cout << " " << pname.programName << endl; cout << endl; - cout << " " << HyphenateString(programInfo.documentation(), 2) << endl; - cout << endl << endl; + cout << " " << HyphenateString(longDesc.longDescription(), 2) << endl; + cout << endl; + for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + { + util::Example& example = *IO::GetSingleton().examples[j]; + cout << " " << util::HyphenateString(example.example(), 2) + << endl << endl; + } cout << " Input parameters:" << endl; cout << endl; for (size_t i = 0; i < inputOptions.size(); ++i) @@ -184,7 +190,7 @@ void PrintPYX(const ProgramDoc& programInfo, cout << " DisableVerbose()" << endl; // Restore the parameters. - cout << " IO.RestoreSettings(\"" << programInfo.programName << "\")" + cout << " IO.RestoreSettings(\"" << pname.programName << "\")" << endl; // Determine whether or not we need to copy parameters. diff --git a/src/mlpack/bindings/python/print_pyx.hpp b/src/mlpack/bindings/python/print_pyx.hpp index 896840e3c8..789fba2446 100644 --- a/src/mlpack/bindings/python/print_pyx.hpp +++ b/src/mlpack/bindings/python/print_pyx.hpp @@ -23,13 +23,11 @@ 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 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, - const std::string& mainFilename, +void PrintPYX(const std::string& mainFilename, const std::string& functionName); diff --git a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp index eca99cdff2..d9eaa89bff 100644 --- a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp +++ b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp @@ -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_PNAME("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."); diff --git a/src/mlpack/bindings/tests/test_option.hpp b/src/mlpack/bindings/tests/test_option.hpp index 95332019f3..206126f958 100644 --- a/src/mlpack/bindings/tests/test_option.hpp +++ b/src/mlpack/bindings/tests/test_option.hpp @@ -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 diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index b5e5fe9de7..2102786055 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -17,19 +17,43 @@ using namespace mlpack; using namespace mlpack::util; -// Fake ProgramDoc in case none is supplied. -static ProgramDoc emptyProgramDoc = ProgramDoc("", "", []() { return ""; }, - {}); +// Fake ProgramName in case none is supplied. +static ProgramName emptyProgramName = ProgramName(""); + +// Fake ShortDescription in case none is supplied. +static ShortDescription emptyShortDescription = ShortDescription(""); + +// Fake LongDescription in case none is supplied. +static LongDescription emptyLongDescription = LongDescription( + []() { return ""; }); + +// Fake Example in case none is supplied. +static Example emptyExample = Example([]() { return ""; }); + +// Fake SeeAlso in case none is supplied. +static SeeAlso emptySeeAlso = SeeAlso("", ""); /* Constructors, Destructors, Copy */ /* Make the constructor private, to preclude unauthorized instances */ -IO::IO() : didParse(false), doc(&emptyProgramDoc) +IO::IO() : + didParse(false), + pname(&emptyProgramName), + shortDesc(&emptyShortDescription), + longDesc(&emptyLongDescription), + examples({}), + seeAlsos({}) { 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), + pname(&emptyProgramName), + shortDesc(&emptyShortDescription), + longDesc(&emptyLongDescription), + examples({}), + seeAlsos({}) { return; } @@ -155,17 +179,73 @@ IO& IO::GetSingleton() } /** - * Registers a ProgramDoc object, which contains documentation about the + * Registers a ProgramName object, which contains documentation about the * program. * - * @param doc Pointer to the ProgramDoc object. + * @param pname Pointer to the ProgramName object. */ -void IO::RegisterProgramDoc(ProgramDoc* doc) +void IO::RegisterProgramName(util::ProgramName* pname) +{ + // Only register the pname 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 (pname != &emptyProgramName) + GetSingleton().pname = pname; +} + +/** + * Registers a ShortDescription object, which contains documentation about + * the program. + * + * @param shortDesc Pointer to the ShortDescription object. + */ +void IO::RegisterShortDescription(ShortDescription* shortDesc) +{ + // Only register the shortDesc 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 (shortDesc != &emptyShortDescription) + GetSingleton().shortDesc = shortDesc; +} + +/** + * Registers a LongDescription object, which contains documentation about + * the program. + * + * @param longDesc Pointer to the LongDescription object. + */ +void IO::RegisterLongDescription(LongDescription* longDesc) +{ + // Only register the longDesc 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 (longDesc != &emptyLongDescription) + GetSingleton().longDesc = longDesc; +} + +/** + * Registers a Example object, which contains documentation about the + * program. + * + * @param example Pointer to the Example object. + */ +void IO::RegisterExample(Example* example) +{ + // Only register the example 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 (example != &emptyExample) + GetSingleton().examples.push_back(example); +} + +/** + * Registers a SeeAlso object, which contains documentation about the + * program. + * + * @param seeAlso Pointer to the SeeAlso object. + */ +void IO::RegisterSeeAlso(SeeAlso* seeAlso) { // 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; + if (seeAlso != &emptySeeAlso) + GetSingleton().seeAlsos.push_back(seeAlso); } // Get the parameters that the IO object knows about. @@ -180,10 +260,10 @@ std::map& IO::Aliases() return GetSingleton().aliases; } -// Get the program name as set by PROGRAM_INFO(). +// Get the program name as set by BINDING_PNAME(). std::string IO::ProgramName() { - return GetSingleton().doc->programName; + return GetSingleton().pname->programName; } // Set a particular parameter as passed. diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index c0da36f8ae..f47abba96d 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -35,8 +35,24 @@ namespace mlpack { namespace util { // Externally defined in option.hpp, this class holds information about the -// program being run. -class ProgramDoc; +// name of the program being run. +class ProgramName; + +// Externally defined in option.hpp, this class holds information about the +// short description of the program being run. +class ShortDescription; + +// Externally defined in option.hpp, this class holds information about the +// long description of the program being run. +class LongDescription; + +// Externally defined in option.hpp, this class holds information about the +// examples of the program being run. +class Example; + +// Externally defined in option.hpp, this class holds information about see +// also of the program being run. +class SeeAlso; } // namespace util @@ -96,17 +112,31 @@ class ProgramDoc; * More documentation is available on the PARAM_*() macros in the documentation * for core/io/io.hpp. * - * @section programinfo Documenting the program itself + * @section bindingpname Documenting the programName. + * @section bindingshortdescription Documenting the shortDescription. + * @section bindinglongdescription Documenting the longDescription. + * @section bindingexample Documenting the example. + * @section bindingseealso Documenting the seeAlso. * * 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_PNAME() 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_PNAME(), 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_PNAME("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 @@ -241,20 +271,58 @@ class IO static IO& GetSingleton(); /** - * Registers a ProgramDoc object, which contains documentation about the + * Registers a ProgramName 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. + * ProgramNames are instantiated in the program), a fatal error will occur. * - * @param doc Pointer to the ProgramDoc object. + * @param pname Pointer to the ProgramName object. */ - static void RegisterProgramDoc(util::ProgramDoc* doc); + static void RegisterProgramName(util::ProgramName* pname); + + /** + * Registers a ShortDescription object, which contains documentation about the + * program. If this method has been called before (that is, if two + * ShortDescriptions are instantiated in the program), a fatal error will + * occur. + * + * @param shortDesc Pointer to the ShortDescription object. + */ + static void RegisterShortDescription(util::ShortDescription* shortDesc); + + /** + * Registers a LongDescription object, which contains documentation about the + * program. If this method has been called before (that is, if two + * LongDescriptions are instantiated in the program), a fatal error will + * occur. + * + * @param longDesc Pointer to the LongDescription object. + */ + static void RegisterLongDescription(util::LongDescription* longDesc); + + /** + * Registers a Example object, which contains documentation about the + * program. If this method has been called before (that is, if two + * Examples are instantiated in the program), a fatal error will occur. + * + * @param examples Pointer to the Example object. + */ + static void RegisterExample(util::Example* examples); + + /** + * Registers a SeeAlso object, which contains documentation about the + * program. If this method has been called before (that is, if two + * SeeAlsos are instantiated in the program), a fatal error will occur. + * + * @param seeAlsos Pointer to the SeeAlso object. + */ + static void RegisterSeeAlso(util::SeeAlso* seeAlsos); //! Return a modifiable list of parameters that IO knows about. static std::map& Parameters(); //! Return a modifiable list of aliases that IO knows about. static std::map& Aliases(); - //! Get the program name as set by the PROGRAM_INFO() macro. + //! Get the program name as set by the BINDING_PNAME() macro. static std::string ProgramName(); /** @@ -313,7 +381,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 ProgramName(). std::string programName; //! Holds the timer objects. @@ -322,9 +390,20 @@ 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; + //! Pointer to the ProgramName object. + util::ProgramName* pname; + //! Pointer to the ShortDescription object. + util::ShortDescription* shortDesc; + + //! Pointer to the LongDescription object. + util::LongDescription* longDesc; + + //! Pointer to the Example object. + std::vector examples; + + //! Pointer to the SeeAlso object. + std::vector seeAlsos; private: /** * Make the constructor private, to preclude unauthorized instances. diff --git a/src/mlpack/core/util/mlpack_main.hpp b/src/mlpack/core/util/mlpack_main.hpp index 35cc9ae090..f2976046eb 100644 --- a/src/mlpack/core/util/mlpack_main.hpp +++ b/src/mlpack/core/util/mlpack_main.hpp @@ -152,12 +152,6 @@ using Option = mlpack::bindings::tests::TestOption; // testName symbol should be defined in each binding test file #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }) - #elif(BINDING_TYPE == BINDING_TYPE_PYX) // This is a Python binding. // Matrices are transposed on load/save. @@ -217,11 +211,10 @@ using Option = mlpack::bindings::python::PyOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_PNAME +#define BINDING_PNAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace python { \ @@ -266,11 +259,10 @@ using Option = mlpack::bindings::julia::JuliaOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) static \ - mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_PNAME +#define BINDING_PNAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace julia { \ @@ -311,11 +303,10 @@ using Option = mlpack::bindings::go::GoOption; static const std::string testName = ""; #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_PNAME +#define BINDING_PNAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ namespace bindings { \ namespace go { \ @@ -331,7 +322,9 @@ 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. +// We use BINDING_NAME in BINDING_PNAME(), BINDING_SHORT_DESC(), +// BINDING_LONG_DESC(), BINDING_EXAMPLE() and BINDING_SEE_ALSO() +// so it needs to be defined. #ifndef BINDING_NAME #error "BINDING_NAME must be defined when BINDING_TYPE is Markdown!" #endif @@ -396,12 +389,55 @@ using Option = mlpack::bindings::markdown::MDOption; #include #include -#undef PROGRAM_INFO -#define PROGRAM_INFO(NAME, SHORT_DESC, DESC, ...) static \ - mlpack::bindings::markdown::ProgramDocWrapper \ - io_programdoc_dummy_object = \ - mlpack::bindings::markdown::ProgramDocWrapper(BINDING_NAME, NAME, \ - SHORT_DESC, []() { return DESC; }, { __VA_ARGS__ }); \ +#undef BINDING_PNAME +#undef BINDING_SHORT_DESC +#undef BINDING_LONG_DESC +#undef BINDING_EXAMPLE +#undef BINDING_SEE_ALSO + +#define BINDING_PNAME(NAME) static \ + mlpack::bindings::markdown::ProgramNameWrapper \ + io_programname_dummy_object = \ + mlpack::bindings::markdown::ProgramNameWrapper( \ + BINDING_NAME, NAME); + +#define BINDING_SHORT_DESC(SHORT_DESC) static \ + mlpack::bindings::markdown::ShortDescriptionWrapper \ + io_programshort_desc_dummy_object = \ + mlpack::bindings::markdown::ShortDescriptionWrapper( \ + BINDING_NAME, SHORT_DESC); + +#define BINDING_LONG_DESC(LONG_DESC) static \ + mlpack::bindings::markdown::LongDescriptionWrapper \ + io_programlong_desc_dummy_object = \ + mlpack::bindings::markdown::LongDescriptionWrapper( \ + 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(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(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(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(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"); diff --git a/src/mlpack/core/util/param.hpp b/src/mlpack/core/util/param.hpp index b346c20400..14f2e04c22 100644 --- a/src/mlpack/core/util/param.hpp +++ b/src/mlpack/core/util/param.hpp @@ -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,19 +30,16 @@ using DatasetInfo = DatasetMapper; } // namespace mlpack /** - * 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 - * "description" is the description of the link and "link" may be one of the - * following: - * - * - A direct URL, starting with http:// or https://. - * - A page anchor for documentation, referencing another binding by its CMake - * binding name, i.e. "#knn". - * - A link to a Doxygen page, using the mangled Doxygen name after a - * '\@doxygen/', i.e., "@doxygen/mlpack1_1_adaboost1_1_AdaBoost". + * @cond + * Don't document internal macros. */ -#define SEE_ALSO(DESCRIPTION, LINK) {DESCRIPTION, LINK} + +// 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 */ /** * Document an executable. Only one instance of this macro should be @@ -56,23 +53,117 @@ using DatasetInfo = DatasetMapper; * PARAM_DOUBLE_OUT_REQ(), PARAM_VECTOR_OUT_REQ(), PARAM_STRING_OUT_REQ(). * * @param NAME Short string representing the name of the program. + */ +#define BINDING_PNAME(NAME) static \ + mlpack::util::ProgramName \ + io_programname_dummy_object = mlpack::util::ProgramName(NAME); + +/** + * 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 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 ... 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, ...) \ - static mlpack::util::ProgramDoc \ - io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, SHORT_DESC, \ - []() { return DESC; }, { __VA_ARGS__ } ) +#define BINDING_SHORT_DESC(SHORT_DESC) static \ + mlpack::util::ShortDescription \ + io_programshort_desc_dummy_object = mlpack::util::ShortDescription( \ + SHORT_DESC); +/** + * 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 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); }); + +/** + * Document an executable. Mutiple instance of this macro can 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 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 +/** + * Document an executable. Mutiple instance of this macro can 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(). + * + * 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 + * "description" is the description of the link and "link" may be one of the + * following: + * + * - A direct URL, starting with http:// or https://. + * - A page anchor for documentation, referencing another binding by its CMake + * binding name, i.e. "#knn". + * - A link to a Doxygen page, using the mangled Doxygen name after a + * '\@doxygen/', i.e., "@doxygen/mlpack1_1_adaboost1_1_AdaBoost". + */ +#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. * @@ -82,7 +173,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -108,7 +200,8 @@ using DatasetInfo = DatasetMapper; * @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_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug // Use a forward declaration of the class. @@ -139,7 +232,8 @@ using DatasetInfo = DatasetMapper; * 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_PNAME(), 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 @@ -165,7 +259,8 @@ using DatasetInfo = DatasetMapper; * @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_PNAME(), 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 @@ -195,7 +290,8 @@ using DatasetInfo = DatasetMapper; * 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_PNAME(), 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 @@ -213,7 +309,8 @@ using DatasetInfo = DatasetMapper; * * 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 @@ -222,7 +319,8 @@ using DatasetInfo = DatasetMapper; * @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_PNAME(), 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 @@ -253,7 +351,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -827,7 +926,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -860,7 +960,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -899,7 +1000,8 @@ using DatasetInfo = DatasetMapper; * 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_PNAME(), 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 @@ -1011,7 +1113,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -1035,7 +1138,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -1059,7 +1163,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -1085,7 +1190,8 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, PROGRAM_INFO() + * @see mlpack::IO, BINDING_PNAME(), 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 @@ -1098,18 +1204,6 @@ using DatasetInfo = DatasetMapper; #define PARAM_VECTOR_IN_REQ(T, ID, DESC, ALIAS) \ PARAM_IN(std::vector, ID, DESC, ALIAS, std::vector(), 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 diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 0dc52bf13d..ec06af5b58 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -1,8 +1,9 @@ /** * @file core/util/program_doc.cpp + * @author Yashwant Singh Parihar * @author Ryan Curtin * - * Implementation of the ProgramDoc class. The class registers itself with IO + * Implementation of the mutiple classes. The classes registers itself with IO * when constructed. * * mlpack is free software; you may redistribute it and/or modify it under the @@ -20,36 +21,117 @@ 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 seeAlso A set of pairs of strings with useful "see also" - * information; each pair is . */ -ProgramDoc::ProgramDoc( - const std::string programName, - const std::string shortDocumentation, - const std::function documentation, - const std::vector> seeAlso) : - programName(std::move(programName)), - shortDocumentation(std::move(shortDocumentation)), - documentation(std::move(documentation)), - seeAlso(std::move(seeAlso)) +ProgramName::ProgramName( + const std::string programName) : + programName(std::move(programName)) { // Register this with IO. - IO::RegisterProgramDoc(this); + IO::RegisterProgramName(this); } /** - * Construct an empty ProgramDoc object. + * Construct an empty ProgramName object. */ -ProgramDoc::ProgramDoc() +ProgramName::ProgramName() { - IO::RegisterProgramDoc(this); + IO::RegisterProgramName(this); +} + +/** + * 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 program, + * what it does, and what it is useful for. + */ +ShortDescription::ShortDescription( + const std::string shortDescription) : + shortDescription(std::move(shortDescription)) +{ + // Register this with IO. + IO::RegisterShortDescription(this); +} + +/** + * Construct an empty ShortDescription object. + */ +ShortDescription::ShortDescription() +{ + IO::RegisterShortDescription(this); +} + +/** + * 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 longDescription) : + longDescription(std::move(longDescription)) +{ + // Register this with IO. + IO::RegisterLongDescription(this); +} + +/** + * Construct an empty LongDescription object. + */ +LongDescription::LongDescription() +{ + IO::RegisterLongDescription(this); +} + +/** + * Construct a Example object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param example Documentation on how to use the program. + */ +Example::Example( + const std::function example) : + example(std::move(example)) +{ + // Register this with IO. + IO::RegisterExample(this); +} + +/** + * Construct an empty Example object. + */ +Example::Example() +{ + IO::RegisterExample(this); +} + +/** + * Construct a SeeAlso object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param seeAlso A set of pairs of strings with useful "see also" + * information; each pair is . + */ +SeeAlso::SeeAlso( + const std::string description, const std::string link) : + description(std::move(description)), + link(std::move(link)) +{ + // Register this with IO. + IO::RegisterSeeAlso(this); +} + +/** + * Construct an empty SeeAlso object. + */ +SeeAlso::SeeAlso() +{ + IO::RegisterSeeAlso(this); } diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index 2e9ee6e533..84696118e8 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -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. + * The structure used to store a program's name, documentation, example and + * see also. * * 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 @@ -18,49 +20,108 @@ 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. + * these BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * BINDING_EXAMPLE() and BINDING_SEE_ALSO() macros to declare these objects. + * Only correspond 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 seeAlso A set of pairs of strings with useful "see also" - * information; each pair is . + * @param programName Name of the default module. */ - ProgramDoc(const std::string programName, - const std::string shortDocumentation, - const std::function documentation, - const std::vector> seeAlso); + ProgramName(const std::string programName); /** - * Construct an empty ProgramDoc object. (This is not meant to be used!) + * Construct an empty ProgramName object. (This is not meant to be used!) */ - ProgramDoc(); - - //! The name of the program. + ProgramName(); std::string programName; - //! The short documentation for the program. - std::string shortDocumentation; - //! Documentation for what the program does. - std::function documentation; - //! Set of see also information. - std::vector> seeAlso; }; +class ShortDescription +{ + public: + /** + * 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 program, + * what it does, and what it is useful for. + */ + ShortDescription(const std::string shortDescription); + + /** + * Construct an empty ShortDescription object. + * (This is not meant to be used!) + */ + ShortDescription(); + std::string shortDescription; +}; + +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 longDescription); + + /** + * Construct an empty LongDescription object. (This is not meant to be used!) + */ + LongDescription(); + std::function longDescription; +}; + +class Example +{ + public: + /** + * Construct a Example object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param example Documentation on how to use the program. + */ + Example(const std::function example); + + /** + * Construct an empty Example object. (This is not meant to be used!) + */ + Example(); + std::function example; +}; + +class SeeAlso +{ + public: + /** + * Construct a SeeAlso object. When constructed, it will register itself + * with IO. A fatal error will be thrown if more than one is constructed. + * + * @param description Description of SeeAlso. + * @param link Link of SeeAlso. + */ + SeeAlso(const std::string description, const std::string link); + + /** + * Construct an empty SeeAlso object. (This is not meant to be used!) + */ + SeeAlso(); + std::string description; + std::string link; +}; } // namespace util } // namespace mlpack diff --git a/src/mlpack/methods/adaboost/adaboost_main.cpp b/src/mlpack/methods/adaboost/adaboost_main.cpp index 1f347d9ff3..26e3ff0cb5 100644 --- a/src/mlpack/methods/adaboost/adaboost_main.cpp +++ b/src/mlpack/methods/adaboost/adaboost_main.cpp @@ -46,13 +46,18 @@ using namespace mlpack::tree; using namespace mlpack::perceptron; using namespace mlpack::util; -PROGRAM_INFO("AdaBoost", - // Short description. +// Program Name. +BINDING_PNAME("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") + '.' + - "\n\n" + 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"); diff --git a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp index 99696793f6..ae715b47c1 100644 --- a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp +++ b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp @@ -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_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp index 86fc946fe2..aa5ef19526 100644 --- a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp +++ b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp @@ -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_PNAME("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." - "\n\n" + 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", "bayesian_linear_regression_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"); diff --git a/src/mlpack/methods/cf/cf_main.cpp b/src/mlpack/methods/cf/cf_main.cpp index 68f9bdaaba..60ac16a9df 100644 --- a/src/mlpack/methods/cf/cf_main.cpp +++ b/src/mlpack/methods/cf/cf_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/dbscan/dbscan_main.cpp b/src/mlpack/methods/dbscan/dbscan_main.cpp index 1cc598a048..8b0ca0766a 100644 --- a/src/mlpack/methods/dbscan/dbscan_main.cpp +++ b/src/mlpack/methods/dbscan/dbscan_main.cpp @@ -27,11 +27,16 @@ using namespace mlpack::tree; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("DBSCAN clustering", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + 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 " diff --git a/src/mlpack/methods/decision_stump/decision_stump_main.cpp b/src/mlpack/methods/decision_stump/decision_stump_main.cpp index ff7b8bde18..27c38e8591 100644 --- a/src/mlpack/methods/decision_stump/decision_stump_main.cpp +++ b/src/mlpack/methods/decision_stump/decision_stump_main.cpp @@ -21,12 +21,17 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Decision Stump", - // Short description. +// Program Name. +BINDING_PNAME("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,12 +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).", - 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"); diff --git a/src/mlpack/methods/decision_tree/decision_tree_main.cpp b/src/mlpack/methods/decision_tree/decision_tree_main.cpp index f7b9d55568..8e9c2299a2 100644 --- a/src/mlpack/methods/decision_tree/decision_tree_main.cpp +++ b/src/mlpack/methods/decision_tree/decision_tree_main.cpp @@ -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_PNAME("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." - "\n\n" + 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).", diff --git a/src/mlpack/methods/det/det_main.cpp b/src/mlpack/methods/det/det_main.cpp index e12c7c3995..d01741b6a8 100644 --- a/src/mlpack/methods/det/det_main.cpp +++ b/src/mlpack/methods/det/det_main.cpp @@ -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_PNAME("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,15 +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.", - 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 " diff --git a/src/mlpack/methods/emst/emst_main.cpp b/src/mlpack/methods/emst/emst_main.cpp index 179e40f292..58b2a87385 100644 --- a/src/mlpack/methods/emst/emst_main.cpp +++ b/src/mlpack/methods/emst/emst_main.cpp @@ -30,11 +30,16 @@ #include "dtb.hpp" -PROGRAM_INFO("Fast Euclidean Minimum Spanning Tree", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/fastmks/fastmks_main.cpp b/src/mlpack/methods/fastmks/fastmks_main.cpp index 04ca22dace..a00ac04527 100644 --- a/src/mlpack/methods/fastmks/fastmks_main.cpp +++ b/src/mlpack/methods/fastmks/fastmks_main.cpp @@ -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_PNAME("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." - "\n\n" + " 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"); diff --git a/src/mlpack/methods/gmm/gmm_generate_main.cpp b/src/mlpack/methods/gmm/gmm_generate_main.cpp index 4d7c47b74f..c3d73bf6ca 100644 --- a/src/mlpack/methods/gmm/gmm_generate_main.cpp +++ b/src/mlpack/methods/gmm/gmm_generate_main.cpp @@ -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_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/gmm/gmm_probability_main.cpp b/src/mlpack/methods/gmm/gmm_probability_main.cpp index 15a870ffef..279585478d 100644 --- a/src/mlpack/methods/gmm/gmm_probability_main.cpp +++ b/src/mlpack/methods/gmm/gmm_probability_main.cpp @@ -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_PNAME("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." - "\n\n" + 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.", diff --git a/src/mlpack/methods/gmm/gmm_train_main.cpp b/src/mlpack/methods/gmm/gmm_train_main.cpp index 2c0f1724d0..f6538462fe 100644 --- a/src/mlpack/methods/gmm/gmm_train_main.cpp +++ b/src/mlpack/methods/gmm/gmm_train_main.cpp @@ -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_PNAME("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." - "\n\n" + "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 " diff --git a/src/mlpack/methods/hmm/hmm_generate_main.cpp b/src/mlpack/methods/hmm/hmm_generate_main.cpp index 0dfe36241b..70257059e5 100644 --- a/src/mlpack/methods/hmm/hmm_generate_main.cpp +++ b/src/mlpack/methods/hmm/hmm_generate_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/hmm/hmm_loglik_main.cpp b/src/mlpack/methods/hmm/hmm_loglik_main.cpp index c25213b7ad..803d3870b8 100644 --- a/src/mlpack/methods/hmm/hmm_loglik_main.cpp +++ b/src/mlpack/methods/hmm/hmm_loglik_main.cpp @@ -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_PNAME("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." - "\n\n" + " 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"); diff --git a/src/mlpack/methods/hmm/hmm_train_main.cpp b/src/mlpack/methods/hmm/hmm_train_main.cpp index 6d185f752a..79912d80ad 100644 --- a/src/mlpack/methods/hmm/hmm_train_main.cpp +++ b/src/mlpack/methods/hmm/hmm_train_main.cpp @@ -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_PNAME("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" @@ -53,14 +58,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 " - "--model_file.", - 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")); + "--model_file."); + +// 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.", diff --git a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp index 14db1b6395..f0b82c8690 100644 --- a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp +++ b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp index 1c016bfb9a..471f273416 100644 --- a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp +++ b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/kde/kde_main.cpp b/src/mlpack/methods/kde/kde_main.cpp index bca333dace..b8db2b6b03 100644 --- a/src/mlpack/methods/kde/kde_main.cpp +++ b/src/mlpack/methods/kde/kde_main.cpp @@ -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_PNAME("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") + "." - "\n\n" + 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,19 +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) + - "\n\n", - 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"); diff --git a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp index 73f2b043f4..00a894ae16 100644 --- a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp +++ b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp @@ -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_PNAME("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 " @@ -55,13 +60,6 @@ PROGRAM_INFO("Kernel Principal Components Analysis", "For the case where a linear kernel is used, this reduces to regular " "PCA." "\n\n" - "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") + - "\n\n" "The kernels that are supported are listed below:" "\n\n" " * 'linear': the standard linear dot product (same as normal PCA):\n" @@ -98,13 +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'.", - 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")); + "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... +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"); diff --git a/src/mlpack/methods/kmeans/kmeans_main.cpp b/src/mlpack/methods/kmeans/kmeans_main.cpp index 8748ede726..3520521131 100644 --- a/src/mlpack/methods/kmeans/kmeans_main.cpp +++ b/src/mlpack/methods/kmeans/kmeans_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/lars/lars_main.cpp b/src/mlpack/methods/lars/lars_main.cpp index 281b5ee705..2be7925455 100644 --- a/src/mlpack/methods/lars/lars_main.cpp +++ b/src/mlpack/methods/lars/lars_main.cpp @@ -21,13 +21,18 @@ using namespace mlpack; using namespace mlpack::regression; using namespace mlpack::util; -PROGRAM_INFO("LARS", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/linear_regression/linear_regression_main.cpp b/src/mlpack/methods/linear_regression/linear_regression_main.cpp index befe22f351..c3d7b74432 100644 --- a/src/mlpack/methods/linear_regression/linear_regression_main.cpp +++ b/src/mlpack/methods/linear_regression/linear_regression_main.cpp @@ -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_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/linear_svm/linear_svm_main.cpp b/src/mlpack/methods/linear_svm/linear_svm_main.cpp index 1857902008..b2026db0de 100644 --- a/src/mlpack/methods/linear_svm/linear_svm_main.cpp +++ b/src/mlpack/methods/linear_svm/linear_svm_main.cpp @@ -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_PNAME("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." + - "\n\n" + 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 " diff --git a/src/mlpack/methods/lmnn/lmnn_main.cpp b/src/mlpack/methods/lmnn/lmnn_main.cpp index 0410e458f2..eec7456e4a 100644 --- a/src/mlpack/methods/lmnn/lmnn_main.cpp +++ b/src/mlpack/methods/lmnn/lmnn_main.cpp @@ -21,14 +21,18 @@ #include -// Define parameters. -PROGRAM_INFO("Large Margin Nearest Neighbors (LMNN)", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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 " diff --git a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp index 7b92945902..97057d0a63 100644 --- a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp +++ b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp @@ -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_PNAME("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 " + @@ -73,13 +80,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"); diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp index 76254bf704..bf0b0cfb56 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp @@ -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_PNAME("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." - "\n\n" + "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 " diff --git a/src/mlpack/methods/lsh/lsh_main.cpp b/src/mlpack/methods/lsh/lsh_main.cpp index 7a4203eb0c..9f572cb71b 100644 --- a/src/mlpack/methods/lsh/lsh_main.cpp +++ b/src/mlpack/methods/lsh/lsh_main.cpp @@ -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_PNAME("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. " - "\n\n" + "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"); diff --git a/src/mlpack/methods/mean_shift/mean_shift_main.cpp b/src/mlpack/methods/mean_shift/mean_shift_main.cpp index acf503f750..e9a4ea717f 100644 --- a/src/mlpack/methods/mean_shift/mean_shift_main.cpp +++ b/src/mlpack/methods/mean_shift/mean_shift_main.cpp @@ -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_PNAME("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." - "\n\n" + " " + 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"); diff --git a/src/mlpack/methods/mvu/mvu_main.cpp b/src/mlpack/methods/mvu/mvu_main.cpp index a62dfd9d5c..c0c879f1c7 100644 --- a/src/mlpack/methods/mvu/mvu_main.cpp +++ b/src/mlpack/methods/mvu/mvu_main.cpp @@ -15,7 +15,11 @@ #include #include "mvu.hpp" -PROGRAM_INFO("Maximum Variance Unfolding (MVU)", "This program implements " +// Program Name. +BINDING_PNAME("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 " diff --git a/src/mlpack/methods/naive_bayes/nbc_main.cpp b/src/mlpack/methods/naive_bayes/nbc_main.cpp index 5d04c5434f..f9c4b85b7b 100644 --- a/src/mlpack/methods/naive_bayes/nbc_main.cpp +++ b/src/mlpack/methods/naive_bayes/nbc_main.cpp @@ -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_PNAME("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." - "\n\n" + " 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 diff --git a/src/mlpack/methods/nca/nca_main.cpp b/src/mlpack/methods/nca/nca_main.cpp index 2dee1c4def..1343c7ed98 100644 --- a/src/mlpack/methods/nca/nca_main.cpp +++ b/src/mlpack/methods/nca/nca_main.cpp @@ -20,14 +20,18 @@ #include -// Define parameters. -PROGRAM_INFO("Neighborhood Components Analysis (NCA)", - // Short description. +// Program Name. +BINDING_PNAME("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,15 +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.", - 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"); diff --git a/src/mlpack/methods/neighbor_search/kfn_main.cpp b/src/mlpack/methods/neighbor_search/kfn_main.cpp index c152eb10a2..8bfc18b860 100644 --- a/src/mlpack/methods/neighbor_search/kfn_main.cpp +++ b/src/mlpack/methods/neighbor_search/kfn_main.cpp @@ -32,19 +32,25 @@ using namespace mlpack::util; // Convenience typedef. typedef NSModel KFNModel; -// Information about the program itself. -PROGRAM_INFO("k-Furthest-Neighbors Search", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/neighbor_search/knn_main.cpp b/src/mlpack/methods/neighbor_search/knn_main.cpp index e184469732..d2ae2c5c53 100644 --- a/src/mlpack/methods/neighbor_search/knn_main.cpp +++ b/src/mlpack/methods/neighbor_search/knn_main.cpp @@ -34,20 +34,26 @@ using namespace mlpack::util; // Convenience typedef. typedef NSModel KNNModel; -// Information about the program itself. -PROGRAM_INFO("k-Nearest-Neighbors Search", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/nmf/nmf_main.cpp b/src/mlpack/methods/nmf/nmf_main.cpp index d5548ae136..d3401e6745 100644 --- a/src/mlpack/methods/nmf/nmf_main.cpp +++ b/src/mlpack/methods/nmf/nmf_main.cpp @@ -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_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/pca/pca_main.cpp b/src/mlpack/methods/pca/pca_main.cpp index 749b23d253..9b86fc3f47 100644 --- a/src/mlpack/methods/pca/pca_main.cpp +++ b/src/mlpack/methods/pca/pca_main.cpp @@ -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_PNAME("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'." - "\n\n" + "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"); diff --git a/src/mlpack/methods/perceptron/perceptron_main.cpp b/src/mlpack/methods/perceptron/perceptron_main.cpp index fa90b8b2c5..de067c73d5 100644 --- a/src/mlpack/methods/perceptron/perceptron_main.cpp +++ b/src/mlpack/methods/perceptron/perceptron_main.cpp @@ -25,13 +25,18 @@ using namespace mlpack::util; using namespace std; using namespace arma; -PROGRAM_INFO("Perceptron", - // Short description. +// Program Name. +BINDING_PNAME("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 diff --git a/src/mlpack/methods/preprocess/image_converter_main.cpp b/src/mlpack/methods/preprocess/image_converter_main.cpp index cdb9b3c1bb..9251b27f34 100644 --- a/src/mlpack/methods/preprocess/image_converter_main.cpp +++ b/src/mlpack/methods/preprocess/image_converter_main.cpp @@ -20,13 +20,18 @@ using namespace arma; using namespace std; using namespace mlpack::data; -PROGRAM_INFO("Image Converter", - // Short description. +// Program Name. +BINDING_PNAME("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,18 +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. 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 :" + + " 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 " diff --git a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp index 321399c76e..44d2c7219a 100644 --- a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp @@ -14,12 +14,17 @@ #include #include -PROGRAM_INFO("Binarize Data", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp index acb9f9002c..20b29e9125 100644 --- a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp @@ -22,11 +22,16 @@ using namespace mlpack::util; using namespace std; using namespace boost; -PROGRAM_INFO("Descriptive Statistics", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp index 85189d68f6..489117b088 100644 --- a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp @@ -22,28 +22,38 @@ #include #include -PROGRAM_INFO("Impute Data", - // Short description. +// Program Name. +BINDING_PNAME("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 --output_file (-o)." - "\n\n" + "\n\n"); + +// 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 dataset, and save the result to result.csv, we could run" "\n\n" "$ mlpack_preprocess_imputer -i dataset.csv -o result.csv -m NULL -d 0 \n" - "> -s listwise_deletion", - SEE_ALSO("@preprocess_binarize", "#preprocess_binarize"), - SEE_ALSO("@preprocess_describe", "#preprocess_describe"), - SEE_ALSO("@preprocess_split", "#preprocess_split")); + "> -s 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"); diff --git a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp index dfcecc9ad2..3080b4198e 100644 --- a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp @@ -28,12 +28,17 @@ using namespace mlpack::data; using namespace arma; using namespace std; -PROGRAM_INFO("Scale Data", - // Short description. +// Program Name. +BINDING_PNAME("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") + "." - "\n\n" + + 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"); diff --git a/src/mlpack/methods/preprocess/preprocess_split_main.cpp b/src/mlpack/methods/preprocess/preprocess_split_main.cpp index 401a55d855..11417bed4c 100644 --- a/src/mlpack/methods/preprocess/preprocess_split_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_split_main.cpp @@ -15,11 +15,16 @@ #include #include -PROGRAM_INFO("Split Data", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/radical/radical_main.cpp b/src/mlpack/methods/radical/radical_main.cpp index f474433b58..61d0a7037c 100644 --- a/src/mlpack/methods/radical/radical_main.cpp +++ b/src/mlpack/methods/radical/radical_main.cpp @@ -16,13 +16,18 @@ #include #include "radical.hpp" -PROGRAM_INFO("RADICAL", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + 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"); diff --git a/src/mlpack/methods/random_forest/random_forest_main.cpp b/src/mlpack/methods/random_forest/random_forest_main.cpp index 1d599805e9..1acedf67dc 100644 --- a/src/mlpack/methods/random_forest/random_forest_main.cpp +++ b/src/mlpack/methods/random_forest/random_forest_main.cpp @@ -19,13 +19,18 @@ using namespace mlpack::tree; using namespace mlpack::util; using namespace std; -PROGRAM_INFO("Random forests", - // Short description. +// Program Name. +BINDING_PNAME("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." - "\n\n" + "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"); diff --git a/src/mlpack/methods/range_search/range_search_main.cpp b/src/mlpack/methods/range_search/range_search_main.cpp index e171341e1b..29d9cbdec0 100644 --- a/src/mlpack/methods/range_search/range_search_main.cpp +++ b/src/mlpack/methods/range_search/range_search_main.cpp @@ -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_PNAME("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)." - "\n\n" + " 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 'input.csv' and store the distances in 'distances.csv'" " and the neighbors in 'neighbors.csv':" @@ -62,14 +68,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"); diff --git a/src/mlpack/methods/rann/krann_main.cpp b/src/mlpack/methods/rann/krann_main.cpp index 69f403c4d9..7f9ac067b9 100644 --- a/src/mlpack/methods/rann/krann_main.cpp +++ b/src/mlpack/methods/rann/krann_main.cpp @@ -28,21 +28,27 @@ using namespace mlpack::util; // Convenience typedef. typedef RAModel RANNModel; -// Information about the program itself. -PROGRAM_INFO("K-Rank-Approximate-Nearest-Neighbors (kRANN)", - // Short description. +// Program Name. +BINDING_PNAME("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)." - "\n\n" + "(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"); diff --git a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp index 0344baf7aa..2673ba66d8 100644 --- a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp +++ b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp @@ -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_PNAME("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." - "\n\n" + "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 " diff --git a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp index c6977a73f7..8f1881100e 100644 --- a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp +++ b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp @@ -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_PNAME("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." - "\n\n" + " 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"); From 242822774fbf6b9f3a1fd9da8a2516959aeb534b Mon Sep 17 00:00:00 2001 From: Yashwant Date: Sun, 9 Aug 2020 19:23:58 +0530 Subject: [PATCH 02/25] Fix static code analysis. --- src/mlpack/bindings/markdown/program_doc_wrapper.hpp | 8 ++++---- src/mlpack/core/util/program_doc.cpp | 10 +++++----- src/mlpack/core/util/program_doc.hpp | 10 +++++----- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index 500aa79e2c..57637a4b12 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -45,7 +45,7 @@ class ShortDescriptionWrapper * BindingInfo::RegisterShortDescription(). */ ShortDescriptionWrapper(const std::string& bindingName, - const std::string shortDescription) + const std::string& shortDescription) { util::ShortDescription pd(shortDescription); BindingInfo::RegisterShortDescription(bindingName, pd); @@ -60,7 +60,7 @@ class LongDescriptionWrapper * BindingInfo::RegisterLongDescription(). */ LongDescriptionWrapper(const std::string& bindingName, - const std::function longDescription) + const std::function& longDescription) { util::LongDescription pd(longDescription); BindingInfo::RegisterLongDescription(bindingName, pd); @@ -75,7 +75,7 @@ class ExampleWrapper * BindingInfo::RegisterExample(). */ ExampleWrapper(const std::string& bindingName, - const std::function example) + const std::function& example) { util::Example pd(example); BindingInfo::RegisterExample(bindingName, pd); @@ -90,7 +90,7 @@ class SeeAlsoWrapper * BindingInfo::RegisterSeeAlso(). */ SeeAlsoWrapper(const std::string& bindingName, - const std::string description, const std::string link) + const std::string& description, const std::string& link) { util::SeeAlso pd(description, link); BindingInfo::RegisterSeeAlso(bindingName, pd); diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index ec06af5b58..0ff5bf34a1 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -27,7 +27,7 @@ using namespace std; * @param defaultModule Name of the default module. */ ProgramName::ProgramName( - const std::string programName) : + const std::string& programName) : programName(std::move(programName)) { // Register this with IO. @@ -51,7 +51,7 @@ ProgramName::ProgramName() * what it does, and what it is useful for. */ ShortDescription::ShortDescription( - const std::string shortDescription) : + const std::string& shortDescription) : shortDescription(std::move(shortDescription)) { // Register this with IO. @@ -75,7 +75,7 @@ ShortDescription::ShortDescription() * taken care of by IO later. */ LongDescription::LongDescription( - const std::function longDescription) : + const std::function& longDescription) : longDescription(std::move(longDescription)) { // Register this with IO. @@ -97,7 +97,7 @@ LongDescription::LongDescription() * @param example Documentation on how to use the program. */ Example::Example( - const std::function example) : + const std::function& example) : example(std::move(example)) { // Register this with IO. @@ -120,7 +120,7 @@ Example::Example() * information; each pair is . */ SeeAlso::SeeAlso( - const std::string description, const std::string link) : + const std::string& description, const std::string& link) : description(std::move(description)), link(std::move(link)) { diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index 84696118e8..a0bd2d8bbf 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -35,7 +35,7 @@ class ProgramName * * @param programName Name of the default module. */ - ProgramName(const std::string programName); + ProgramName(const std::string& programName); /** * Construct an empty ProgramName object. (This is not meant to be used!) @@ -55,7 +55,7 @@ class ShortDescription * @param shortDescription A short two-sentence description of the program, * what it does, and what it is useful for. */ - ShortDescription(const std::string shortDescription); + ShortDescription(const std::string& shortDescription); /** * Construct an empty ShortDescription object. @@ -76,7 +76,7 @@ class LongDescription * what it is. No newline characters are necessary; this is * taken care of by IO later. */ - LongDescription(const std::function longDescription); + LongDescription(const std::function& longDescription); /** * Construct an empty LongDescription object. (This is not meant to be used!) @@ -94,7 +94,7 @@ class Example * * @param example Documentation on how to use the program. */ - Example(const std::function example); + Example(const std::function& example); /** * Construct an empty Example object. (This is not meant to be used!) @@ -113,7 +113,7 @@ class SeeAlso * @param description Description of SeeAlso. * @param link Link of SeeAlso. */ - SeeAlso(const std::string description, const std::string link); + SeeAlso(const std::string& description, const std::string& link); /** * Construct an empty SeeAlso object. (This is not meant to be used!) From e9adce8e5dedcc41e45c8adb2459ace1557562a0 Mon Sep 17 00:00:00 2001 From: Yashwant Date: Sun, 9 Aug 2020 19:24:29 +0530 Subject: [PATCH 03/25] Update `HISTORY.md`. --- HISTORY.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/HISTORY.md b/HISTORY.md index 67d39452d2..81746f67f0 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,5 +1,8 @@ ### mlpack ?.?.? ###### ????-??-?? + * Refactor ProgramInfo() to separate out all the different + information. (#2558) + * Added N-step DQN to q_networks (#2461). * Add Silhoutte Score metric and Pairwise Distances (#2406). From 6832a26ac2d2dc5c73082943e341bf2f8e9b5f25 Mon Sep 17 00:00:00 2001 From: himanshupathak21061998 Date: Mon, 10 Aug 2020 07:41:01 +0530 Subject: [PATCH 04/25] Removing r-value reference from RBM --- src/mlpack/methods/ann/rbm/rbm.hpp | 38 +++---- src/mlpack/methods/ann/rbm/rbm_impl.hpp | 100 ++++++++++-------- .../methods/ann/rbm/spike_slab_rbm_impl.hpp | 95 +++++++++-------- src/mlpack/tests/rbm_network_test.cpp | 20 ++-- src/mlpack/tests/serialization_test.cpp | 24 ++--- 5 files changed, 152 insertions(+), 125 deletions(-) diff --git a/src/mlpack/methods/ann/rbm/rbm.hpp b/src/mlpack/methods/ann/rbm/rbm.hpp index 51faa83eaa..d05f6e6321 100644 --- a/src/mlpack/methods/ann/rbm/rbm.hpp +++ b/src/mlpack/methods/ann/rbm/rbm.hpp @@ -27,11 +27,13 @@ namespace ann /** Artificial Neural Network. */ { * machines, with the restriction that the neurons must form a bipartite graph. * * @tparam InitializationRuleType Rule used to initialize the network. + * @tparam InputType The type of matrix to be used as input type. * @tparam DataType The type of matrix to be used. * @tparam PolicyType The RBM variant to be used (BinaryRBM or SpikeSlabRBM). */ template< typename InitializationRuleType, + typename InputType = arma::mat, typename DataType = arma::mat, typename PolicyType = BinaryRBM > @@ -118,7 +120,7 @@ class RBM */ template typename std::enable_if::value, double>::type - FreeEnergy(arma::Mat&& input); + FreeEnergy(const arma::Mat& input); /** * This function calculates the free energy of the SpikeSlabRBM. @@ -133,7 +135,7 @@ class RBM template typename std::enable_if::value, double>::type - FreeEnergy(arma::Mat&& input); + FreeEnergy(const arma::Mat& input); /** * Calculates the gradient of the RBM network on the provided input. @@ -143,7 +145,7 @@ class RBM */ template typename std::enable_if::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. @@ -153,7 +155,7 @@ class RBM */ template typename std::enable_if::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 @@ -164,7 +166,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SampleHidden(arma::Mat&& input, arma::Mat&& output); + SampleHidden(const arma::Mat& input, arma::Mat& output); /** * This function samples the slab outputs from the Normal distribution with @@ -178,7 +180,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SampleHidden(arma::Mat&& input, arma::Mat&& output); + SampleHidden(const arma::Mat& input, arma::Mat& output); /** * This function samples the visible layer given the hidden layer using @@ -189,7 +191,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SampleVisible(arma::Mat&& input, arma::Mat&& output); + SampleVisible(arma::Mat& input, arma::Mat& output); /** * Sample Hidden function samples the slab outputs from the Normal @@ -203,7 +205,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SampleVisible(arma::Mat&& input, arma::Mat&& output); + SampleVisible(arma::Mat& input, arma::Mat& output); /** * The function calculates the mean for the visible layer. @@ -213,7 +215,7 @@ class RBM */ template typename std::enable_if::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). @@ -225,7 +227,7 @@ class RBM */ template typename std::enable_if::value, void>::type - VisibleMean(DataType&& input, DataType&& output); + VisibleMean(InputType& input, DataType& output); /** * The function calculates the mean for the hidden layer. @@ -235,7 +237,7 @@ class RBM */ template typename std::enable_if::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). @@ -249,7 +251,7 @@ class RBM */ template typename std::enable_if::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), @@ -261,7 +263,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SpikeMean(DataType&& visible, DataType&& spikeMean); + SpikeMean(const InputType& visible, DataType& spikeMean); /** * The function samples the spike function using Bernoulli distribution. @@ -270,7 +272,7 @@ class RBM */ template typename std::enable_if::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), @@ -283,7 +285,7 @@ class RBM */ template typename std::enable_if::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), @@ -297,7 +299,7 @@ class RBM */ template typename std::enable_if::value, void>::type - SampleSlab(DataType&& slabMean, DataType&& slab); + SampleSlab(InputType& slabMean, DataType& slab); /** * This function does the k-step Gibbs Sampling. @@ -306,8 +308,8 @@ class RBM * @param output Used for storing the negative sample. * @param steps Number of Gibbs Sampling steps taken. */ - void Gibbs(arma::Mat&& input, - arma::Mat&& output, + void Gibbs(const arma::Mat& input, + arma::Mat& output, const size_t steps = SIZE_MAX); /** diff --git a/src/mlpack/methods/ann/rbm/rbm_impl.hpp b/src/mlpack/methods/ann/rbm/rbm_impl.hpp index 79122b12d0..c1b51c36ed 100644 --- a/src/mlpack/methods/ann/rbm/rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/rbm_impl.hpp @@ -21,10 +21,11 @@ namespace ann /** Artificial neural networks. */ { template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > -RBM::RBM( +RBM::RBM( arma::Mat predictors, InitializationRuleType initializeRule, const size_t visibleSize, @@ -55,12 +56,13 @@ RBM::RBM( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::Reset() +RBM::Reset() { size_t shape = (visibleSize * hiddenSize) + visibleSize + hiddenSize; @@ -88,11 +90,12 @@ RBM::Reset() template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template -double RBM::Train( +double RBM::Train( OptimizerType& optimizer, CallbackType&&... callbacks) { if (!reset) @@ -105,13 +108,14 @@ double RBM::Train( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, double>::type -RBM::FreeEnergy( - arma::Mat&& input) +RBM::FreeEnergy( + const arma::Mat& input) { preActivation = (weight.slice(0) * input); preActivation.each_col() += hiddenBias; @@ -121,14 +125,15 @@ RBM::FreeEnergy( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::Phase( - DataType&& input, - DataType&& gradient) +RBM::Phase( + const InputType& input, + DataType& gradient) { arma::Cube weightGrad = arma::Cube(gradient.memptr(), hiddenSize, visibleSize, 1, false, false); @@ -136,38 +141,40 @@ RBM::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(); } template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > -double RBM::Evaluate( +double RBM::Evaluate( const arma::Mat& /* parameters*/, 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< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleHidden( - arma::Mat&& input, - arma::Mat&& output) +RBM::SampleHidden( + const arma::Mat& input, + arma::Mat& output) { - HiddenMean(std::move(input), std::move(output)); + HiddenMean(input, output); for (size_t i = 0; i < output.n_elem; ++i) { @@ -177,16 +184,17 @@ RBM::SampleHidden( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleVisible( - arma::Mat&& input, - arma::Mat&& output) +RBM::SampleVisible( + arma::Mat& input, + arma::Mat& output) { - VisibleMean(std::move(input), std::move(output)); + VisibleMean(input, output); for (size_t i = 0; i < output.n_elem; ++i) { @@ -196,13 +204,14 @@ RBM::SampleVisible( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::VisibleMean(DataType&& input, - DataType&& output) +RBM::VisibleMean(InputType& input, + DataType& output) { output = weight.slice(0).t() * input; output.each_col() += visibleBias; @@ -211,13 +220,14 @@ RBM::VisibleMean(DataType&& input, template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::HiddenMean(DataType&& input, - DataType&& output) +RBM::HiddenMean(const InputType& input, + DataType& output) { output = weight.slice(0) * input; output.each_col() += hiddenBias; @@ -226,31 +236,32 @@ RBM::HiddenMean(DataType&& input, template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > -void RBM::Gibbs( - arma::Mat&& input, - arma::Mat&& output, +void RBM::Gibbs( + const arma::Mat& input, + arma::Mat& 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) { @@ -260,10 +271,11 @@ void RBM::Gibbs( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > -void RBM::Gradient( +void RBM::Gradient( const arma::Mat& /*parameters*/, const size_t i, arma::Mat& gradient, @@ -272,14 +284,14 @@ void RBM::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; } @@ -289,10 +301,11 @@ void RBM::Gradient( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > -void RBM::Shuffle() +void RBM::Shuffle() { predictors = predictors.cols(arma::shuffle(arma::linspace(0, predictors.n_cols - 1, predictors.n_cols))); @@ -300,11 +313,12 @@ void RBM::Shuffle() template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template -void RBM::serialize( +void RBM::serialize( Archive& ar, const unsigned int /* version */) { ar & BOOST_SERIALIZATION_NVP(parameter); diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index a116e813fc..ca6f5b7bc6 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -22,12 +22,13 @@ namespace ann { template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::Reset() +RBM::Reset() { size_t shape = (visibleSize * hiddenSize * poolSize) + visibleSize + hiddenSize; @@ -62,13 +63,14 @@ RBM::Reset() template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, double>::type -RBM::FreeEnergy( - arma::Mat&& input) +RBM::FreeEnergy( + const arma::Mat& input) { ElemType freeEnergy = 0.5 * visiblePenalty(0) * arma::dot(input, input); @@ -87,14 +89,15 @@ RBM::FreeEnergy( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::Phase( - DataType&& input, - DataType&& gradient) +RBM::Phase( + const InputType& input, + DataType& gradient) { arma::Cube weightGrad = arma::Cube (gradient.memptr(), visibleSize, poolSize, hiddenSize, false, false); @@ -105,9 +108,9 @@ RBM::Phase( 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) { @@ -123,14 +126,15 @@ RBM::Phase( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleHidden( - arma::Mat&& input, - arma::Mat&& output) +RBM::SampleHidden( + const arma::Mat& input, + arma::Mat& output) { output.set_size(hiddenSize + poolSize * hiddenSize, 1); @@ -138,27 +142,28 @@ RBM::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< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleVisible( - arma::Mat&& input, - arma::Mat&& output) +RBM::SampleVisible( + arma::Mat& input, + arma::Mat& 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) @@ -184,14 +189,15 @@ RBM::SampleVisible( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::VisibleMean( - DataType&& input, - DataType&& output) +RBM::VisibleMean( + InputType& input, + DataType& output) { output.zeros(visibleSize, 1); @@ -209,14 +215,15 @@ RBM::VisibleMean( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::HiddenMean( - DataType&& input, - DataType&& output) +RBM::HiddenMean( + const InputType& input, + DataType& output) { output.set_size(hiddenSize + poolSize * hiddenSize, 1); @@ -224,21 +231,22 @@ RBM::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< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SpikeMean( - DataType&& visible, - DataType&& spikeMean) +RBM::SpikeMean( + const InputType& visible, + DataType& spikeMean) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -250,14 +258,15 @@ RBM::SpikeMean( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleSpike( - DataType&& spikeMean, - DataType&& spike) +RBM::SampleSpike( + InputType& spikeMean, + DataType& spike) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -267,15 +276,16 @@ RBM::SampleSpike( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SlabMean( - DataType&& visible, - DataType&& spike, - DataType&& slabMean) +RBM::SlabMean( + const DataType& visible, + DataType& spike, + DataType& slabMean) { for (size_t i = 0; i < hiddenSize; ++i) { @@ -286,14 +296,15 @@ RBM::SlabMean( template< typename InitializationRuleType, + typename InputType, typename DataType, typename PolicyType > template typename std::enable_if::value, void>::type -RBM::SampleSlab( - DataType&& slabMean, - DataType&& slab) +RBM::SampleSlab( + InputType& slabMean, + DataType& slab) { for (size_t i = 0; i < hiddenSize; ++i) { diff --git a/src/mlpack/tests/rbm_network_test.cpp b/src/mlpack/tests/rbm_network_test.cpp index 0cf8ff2316..4c15a4b1b1 100644 --- a/src/mlpack/tests/rbm_network_test.cpp +++ b/src/mlpack/tests/rbm_network_test.cpp @@ -88,14 +88,14 @@ 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. @@ -170,7 +170,7 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) YRbm.zeros(); double slabPenalty = 8; - RBM modelssRBM(trainData, + RBM modelssRBM(trainData, gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, 1, poolSize, slabPenalty, radius); @@ -189,15 +189,15 @@ 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. @@ -223,7 +223,7 @@ void BuildVanillaNetwork(MatType& trainData, { MatType output; GaussianInitialization gaussian(0, 0.1); - RBM model(trainData, gaussian, + RBM model(trainData, gaussian, trainData.n_rows, hiddenLayerSize, 1, 1, 1, 2, 8, 1, true); model.Reset(); @@ -238,7 +238,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) diff --git a/src/mlpack/tests/serialization_test.cpp b/src/mlpack/tests/serialization_test.cpp index e30fcc4dc9..6d504bdebb 100644 --- a/src/mlpack/tests/serialization_test.cpp +++ b/src/mlpack/tests/serialization_test.cpp @@ -1569,18 +1569,18 @@ BOOST_AUTO_TEST_CASE(ssRBMTest) size_t poolSize = 1; GaussianInitialization gaussian(0, 0.1); - RBM Rbm(data, gaussian, - data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, - true); - RBM RbmXml(data, gaussian, - data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, - true); - RBM RbmText(data, gaussian, - data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, - true); - RBM RbmBinary(data, gaussian, - data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, - true); + RBM Rbm(data, + gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, + radius, true); + RBM RbmXml(data, + gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, + radius, true); + RBM RbmText(data, + gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, + radius, true); + RBM RbmBinary(data, + gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, + radius, true); Rbm.Reset(); Rbm.VisiblePenalty().fill(15); Rbm.SpikeBias().ones(); From e9ad541e03cdd44994cff84aa3b74989610bb3d6 Mon Sep 17 00:00:00 2001 From: himanshupathak21061998 Date: Mon, 10 Aug 2020 07:53:52 +0530 Subject: [PATCH 05/25] style fix --- src/mlpack/methods/ann/rbm/rbm_impl.hpp | 6 ++++-- src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp | 2 +- src/mlpack/tests/rbm_network_test.cpp | 11 ++++++----- src/mlpack/tests/serialization_test.cpp | 6 +++--- 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/src/mlpack/methods/ann/rbm/rbm_impl.hpp b/src/mlpack/methods/ann/rbm/rbm_impl.hpp index c1b51c36ed..1597140c37 100644 --- a/src/mlpack/methods/ann/rbm/rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/rbm_impl.hpp @@ -210,7 +210,8 @@ template< > template typename std::enable_if::value, void>::type -RBM::VisibleMean(InputType& input, +RBM::VisibleMean( + InputType& input, DataType& output) { output = weight.slice(0).t() * input; @@ -226,7 +227,8 @@ template< > template typename std::enable_if::value, void>::type -RBM::HiddenMean(const InputType& input, +RBM::HiddenMean( + const InputType& input, DataType& output) { output = weight.slice(0) * input; diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index ca6f5b7bc6..d95efbcb50 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -70,7 +70,7 @@ template< template typename std::enable_if::value, double>::type RBM::FreeEnergy( - const arma::Mat& input) + const arma::Mat& input) { ElemType freeEnergy = 0.5 * visiblePenalty(0) * arma::dot(input, input); diff --git a/src/mlpack/tests/rbm_network_test.cpp b/src/mlpack/tests/rbm_network_test.cpp index 4c15a4b1b1..374512ab26 100644 --- a/src/mlpack/tests/rbm_network_test.cpp +++ b/src/mlpack/tests/rbm_network_test.cpp @@ -170,9 +170,9 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) YRbm.zeros(); double slabPenalty = 8; - RBM modelssRBM(trainData, - gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, 1, poolSize, - slabPenalty, radius); + RBM modelssRBM( + trainData, gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, + 1, poolSize, slabPenalty, radius); size_t numRBMIterations = trainData.n_cols * numEpoches; numRBMIterations /= batchSize; @@ -223,8 +223,9 @@ void BuildVanillaNetwork(MatType& trainData, { MatType output; GaussianInitialization gaussian(0, 0.1); - RBM model(trainData, gaussian, - trainData.n_rows, hiddenLayerSize, 1, 1, 1, 2, 8, 1, true); + RBM model( + trainData, gaussian, trainData.n_rows, hiddenLayerSize, + 1, 1, 1, 2, 8, 1, true); model.Reset(); // Set the parameters from a learned RBM Sklearn random state 23. diff --git a/src/mlpack/tests/serialization_test.cpp b/src/mlpack/tests/serialization_test.cpp index 6d504bdebb..17896f789c 100644 --- a/src/mlpack/tests/serialization_test.cpp +++ b/src/mlpack/tests/serialization_test.cpp @@ -1578,9 +1578,9 @@ BOOST_AUTO_TEST_CASE(ssRBMTest) RBM RbmText(data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, true); - RBM RbmBinary(data, - gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, - radius, true); + RBM RbmBinary( + data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, + slabPenalty, radius, true); Rbm.Reset(); Rbm.VisiblePenalty().fill(15); Rbm.SpikeBias().ones(); From dba8fa919e7fe76e02752f0aa679b738c88da304 Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Mon, 10 Aug 2020 20:04:18 -0400 Subject: [PATCH 06/25] Clarify documentation for incremental optimization. --- .../logistic_regression.hpp | 9 ++--- .../logistic_regression_impl.hpp | 3 +- src/mlpack/tests/logistic_regression_test.cpp | 34 +++++++++++++++++++ 3 files changed, 39 insertions(+), 7 deletions(-) diff --git a/src/mlpack/methods/logistic_regression/logistic_regression.hpp b/src/mlpack/methods/logistic_regression/logistic_regression.hpp index ba03114757..677f3faf84 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression.hpp @@ -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. diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp index cdbad518fb..41bf890e1f 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp @@ -87,7 +87,8 @@ double LogisticRegression::Train( lambda); // Set size of parameters vector according to the input data received. - parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); + if (parameters.n_elem != predictors.n_rows + 1) + parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); errorFunction.InitialPoint() = parameters; Timer::Start("logistic_regression_optimization"); diff --git a/src/mlpack/tests/logistic_regression_test.cpp b/src/mlpack/tests/logistic_regression_test.cpp index d34b92e093..38f7a966c8 100644 --- a/src/mlpack/tests/logistic_regression_test.cpp +++ b/src/mlpack/tests/logistic_regression_test.cpp @@ -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(3, 3)); + GaussianDistribution g2(arma::vec("9.0 9.0 9.0"), arma::eye(3, 3)); + + arma::mat data(3, 1000); + arma::Row 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(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(); From e82aad55ef15efbe0828836a94072c21347e5458 Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Mon, 10 Aug 2020 20:14:10 -0400 Subject: [PATCH 07/25] Update HISTORY.md. --- HISTORY.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/HISTORY.md b/HISTORY.md index 67d39452d2..def32079cd 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -16,6 +16,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). From 57cc548a53046f20b3f6bfbac2ee5c299ad73c8a Mon Sep 17 00:00:00 2001 From: Yashwant Date: Tue, 11 Aug 2020 09:14:09 +0530 Subject: [PATCH 08/25] Regex replace "BINDING_PNAME" with "BINDING_NAME". --- doc/guide/bindings.hpp | 22 ++++++------ doc/guide/iodoc.hpp | 4 +-- .../go/tests/test_go_binding_main.cpp | 2 +- .../julia/tests/test_julia_binding_main.cpp | 2 +- .../markdown/generate_markdown.binding.cpp.in | 2 +- src/mlpack/bindings/markdown/print_docs.cpp | 2 +- .../python/tests/test_python_binding_main.cpp | 2 +- src/mlpack/core/util/io.cpp | 2 +- src/mlpack/core/util/io.hpp | 8 ++--- src/mlpack/core/util/mlpack_main.hpp | 36 +++++++++---------- src/mlpack/core/util/param.hpp | 30 ++++++++-------- src/mlpack/core/util/program_doc.hpp | 2 +- src/mlpack/methods/adaboost/adaboost_main.cpp | 2 +- .../methods/approx_kfn/approx_kfn_main.cpp | 2 +- .../bayesian_linear_regression_main.cpp | 2 +- src/mlpack/methods/cf/cf_main.cpp | 2 +- src/mlpack/methods/dbscan/dbscan_main.cpp | 2 +- .../decision_stump/decision_stump_main.cpp | 2 +- .../decision_tree/decision_tree_main.cpp | 2 +- src/mlpack/methods/det/det_main.cpp | 2 +- src/mlpack/methods/emst/emst_main.cpp | 2 +- src/mlpack/methods/fastmks/fastmks_main.cpp | 2 +- src/mlpack/methods/gmm/gmm_generate_main.cpp | 2 +- .../methods/gmm/gmm_probability_main.cpp | 2 +- src/mlpack/methods/gmm/gmm_train_main.cpp | 2 +- src/mlpack/methods/hmm/hmm_generate_main.cpp | 2 +- src/mlpack/methods/hmm/hmm_loglik_main.cpp | 2 +- src/mlpack/methods/hmm/hmm_train_main.cpp | 2 +- src/mlpack/methods/hmm/hmm_viterbi_main.cpp | 2 +- .../hoeffding_trees/hoeffding_tree_main.cpp | 2 +- src/mlpack/methods/kde/kde_main.cpp | 2 +- .../methods/kernel_pca/kernel_pca_main.cpp | 2 +- src/mlpack/methods/kmeans/kmeans_main.cpp | 2 +- src/mlpack/methods/lars/lars_main.cpp | 2 +- .../linear_regression_main.cpp | 2 +- .../methods/linear_svm/linear_svm_main.cpp | 2 +- src/mlpack/methods/lmnn/lmnn_main.cpp | 2 +- .../local_coordinate_coding_main.cpp | 2 +- .../logistic_regression_main.cpp | 2 +- src/mlpack/methods/lsh/lsh_main.cpp | 2 +- .../methods/mean_shift/mean_shift_main.cpp | 2 +- src/mlpack/methods/mvu/mvu_main.cpp | 2 +- src/mlpack/methods/naive_bayes/nbc_main.cpp | 2 +- src/mlpack/methods/nca/nca_main.cpp | 2 +- .../methods/neighbor_search/kfn_main.cpp | 2 +- .../methods/neighbor_search/knn_main.cpp | 2 +- src/mlpack/methods/nmf/nmf_main.cpp | 2 +- src/mlpack/methods/pca/pca_main.cpp | 2 +- .../methods/perceptron/perceptron_main.cpp | 2 +- .../preprocess/image_converter_main.cpp | 2 +- .../preprocess/preprocess_binarize_main.cpp | 2 +- .../preprocess/preprocess_describe_main.cpp | 2 +- .../preprocess/preprocess_imputer_main.cpp | 2 +- .../preprocess/preprocess_scale_main.cpp | 2 +- .../preprocess/preprocess_split_main.cpp | 2 +- src/mlpack/methods/radical/radical_main.cpp | 2 +- .../random_forest/random_forest_main.cpp | 2 +- .../range_search/range_search_main.cpp | 2 +- src/mlpack/methods/rann/krann_main.cpp | 2 +- .../softmax_regression_main.cpp | 2 +- .../sparse_coding/sparse_coding_main.cpp | 2 +- 61 files changed, 106 insertions(+), 106 deletions(-) diff --git a/doc/guide/bindings.hpp b/doc/guide/bindings.hpp index 31b59e3d54..d8d477955d 100644 --- a/doc/guide/bindings.hpp +++ b/doc/guide/bindings.hpp @@ -130,7 +130,7 @@ using namespace std; // generate documentation for the website. // Program Name. -BINDING_PNAME("Mean Shift Clustering"); +BINDING_NAME("Mean Shift Clustering"); // Short description. BINDING_SHORT_DESC( @@ -238,7 +238,7 @@ void mlpackMain() @endcode We can see that we have defined the basic program information in the -@c BINDING_PNAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), +@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 \--help option for a command-line program. @@ -258,7 +258,7 @@ 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 @c BINDING_PNAME(), +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 @@ -292,10 +292,10 @@ 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_doc Documenting a program with -@c BINDING_PNAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC(), +@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 BINDING_PNAME(), +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 header. The macro @@ -473,7 +473,7 @@ Go binding output (snippet): Input C++ (full program, 'random_numbers_main.cpp'): // Program Name. -BINDING_PNAME("Random Numbers"); +BINDING_NAME("Random Numbers"); // Short description. BINDING_SHORT_DESC( @@ -822,7 +822,7 @@ could be created for the "random_numbers" program from earlier sections. @code #include -// BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(), +// BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(), // BINDING_SEE_ALSO() and PARAM_*() definitions should go here: // ... @@ -883,7 +883,7 @@ 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 BINDING_PNAME() macro that defines the binding name + - 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 - the BINDING_EXAMPLE() macro that defines the example @@ -893,12 +893,12 @@ There are eight main components involved with mlpack bindings: 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 BINDING_PNAME(), +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 BINDING_PNAME() macro declares an object of type mlpack::util::ProgramName. +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 @@ -1188,7 +1188,7 @@ 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 BINDING_PNAME(), @c BINDING_SHORT_DESC(), +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: diff --git a/doc/guide/iodoc.hpp b/doc/guide/iodoc.hpp index 9a25188e7d..b60f6fc937 100644 --- a/doc/guide/iodoc.hpp +++ b/doc/guide/iodoc.hpp @@ -120,7 +120,7 @@ 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 BINDING_PNAME, BINDING_SHORT_DESC, BINDING_LONG_DESC, BINDING_EXAMPLE, +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. @@ -133,7 +133,7 @@ Here is a sample use of those macros, extracted from methods/pca/pca_main.cpp. #include // Program Name. -BINDING_PNAME("Principal Components Analysis"); +BINDING_NAME("Principal Components Analysis"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp index d3f4d922f3..3aeb255906 100644 --- a/src/mlpack/bindings/go/tests/test_go_binding_main.cpp +++ b/src/mlpack/bindings/go/tests/test_go_binding_main.cpp @@ -19,7 +19,7 @@ using namespace mlpack; using namespace mlpack::kernel; // Program Name. -BINDING_PNAME("Golang binding test"); +BINDING_NAME("Golang binding test"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp index 5bd5c73a7b..5ba385cf2b 100644 --- a/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp +++ b/src/mlpack/bindings/julia/tests/test_julia_binding_main.cpp @@ -19,7 +19,7 @@ using namespace mlpack; using namespace mlpack::kernel; // Program Name. -BINDING_PNAME("Julia binding test"); +BINDING_NAME("Julia binding test"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in b/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in index b6ac08952a..a6286faeab 100644 --- a/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in +++ b/src/mlpack/bindings/markdown/generate_markdown.binding.cpp.in @@ -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 #include "generate_markdown.${BINDING}.hpp" diff --git a/src/mlpack/bindings/markdown/print_docs.cpp b/src/mlpack/bindings/markdown/print_docs.cpp index f188728128..8762f41b7b 100644 --- a/src/mlpack/bindings/markdown/print_docs.cpp +++ b/src/mlpack/bindings/markdown/print_docs.cpp @@ -69,7 +69,7 @@ void PrintDocs(const std::string& bindingName, cout << endl; // Next, print the logical name of the binding (that's known by - // BINDING_PNAME()). + // BINDING_NAME()). cout << "#### " << programName.programName << endl; cout << endl; diff --git a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp index d9eaa89bff..ec24202d8e 100644 --- a/src/mlpack/bindings/python/tests/test_python_binding_main.cpp +++ b/src/mlpack/bindings/python/tests/test_python_binding_main.cpp @@ -19,7 +19,7 @@ using namespace mlpack; using namespace mlpack::kernel; // Program Name. -BINDING_PNAME("Python binding test"); +BINDING_NAME("Python binding test"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index 2102786055..32e3d48b7a 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -260,7 +260,7 @@ std::map& IO::Aliases() return GetSingleton().aliases; } -// Get the program name as set by BINDING_PNAME(). +// Get the program name as set by BINDING_NAME(). std::string IO::ProgramName() { return GetSingleton().pname->programName; diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index f47abba96d..844fb87a6e 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -119,18 +119,18 @@ class SeeAlso; * @section bindingseealso Documenting the seeAlso. * * In addition to allowing documentation for each individual parameter and - * module, the BINDING_PNAME() macro provides support for documenting the + * 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_PNAME(), BINDING_SHORT_DESC() and BINDING_LONG_DESC() macros and there + * 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 - * BINDING_PNAME("Maximum Variance Unfolding"); + * 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 " @@ -322,7 +322,7 @@ class IO //! Return a modifiable list of aliases that IO knows about. static std::map& Aliases(); - //! Get the program name as set by the BINDING_PNAME() macro. + //! Get the program name as set by the BINDING_NAME() macro. static std::string ProgramName(); /** diff --git a/src/mlpack/core/util/mlpack_main.hpp b/src/mlpack/core/util/mlpack_main.hpp index f2976046eb..1bcf2a8915 100644 --- a/src/mlpack/core/util/mlpack_main.hpp +++ b/src/mlpack/core/util/mlpack_main.hpp @@ -211,8 +211,8 @@ using Option = mlpack::bindings::python::PyOption; static const std::string testName = ""; #include -#undef BINDING_PNAME -#define BINDING_PNAME(NAME) static \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ mlpack::util::ProgramName \ io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ @@ -259,8 +259,8 @@ using Option = mlpack::bindings::julia::JuliaOption; static const std::string testName = ""; #include -#undef BINDING_PNAME -#define BINDING_PNAME(NAME) static \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ mlpack::util::ProgramName \ io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ @@ -303,8 +303,8 @@ using Option = mlpack::bindings::go::GoOption; static const std::string testName = ""; #include -#undef BINDING_PNAME -#define BINDING_PNAME(NAME) static \ +#undef BINDING_NAME +#define BINDING_NAME(NAME) static \ mlpack::util::ProgramName \ io_programname_dummy_object = mlpack::util::ProgramName(NAME); \ namespace mlpack { \ @@ -322,11 +322,11 @@ PARAM_FLAG("verbose", "Display informational messages and the full list of " #elif BINDING_TYPE == BINDING_TYPE_MARKDOWN -// We use BINDING_NAME in BINDING_PNAME(), BINDING_SHORT_DESC(), +// 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 BINDING_NAME - #error "BINDING_NAME must be defined when BINDING_TYPE is Markdown!" +#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. @@ -389,53 +389,53 @@ using Option = mlpack::bindings::markdown::MDOption; #include #include -#undef BINDING_PNAME +#undef BINDING_NAME #undef BINDING_SHORT_DESC #undef BINDING_LONG_DESC #undef BINDING_EXAMPLE #undef BINDING_SEE_ALSO -#define BINDING_PNAME(NAME) static \ +#define BINDING_NAME(NAME) static \ mlpack::bindings::markdown::ProgramNameWrapper \ io_programname_dummy_object = \ mlpack::bindings::markdown::ProgramNameWrapper( \ - BINDING_NAME, NAME); + MARKDOWN_BINDING_NAME, NAME); #define BINDING_SHORT_DESC(SHORT_DESC) static \ mlpack::bindings::markdown::ShortDescriptionWrapper \ io_programshort_desc_dummy_object = \ mlpack::bindings::markdown::ShortDescriptionWrapper( \ - BINDING_NAME, SHORT_DESC); + 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( \ - BINDING_NAME, []() { return std::string(LONG_DESC); }); + 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(BINDING_NAME, \ + 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(BINDING_NAME, \ + 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(BINDING_NAME, \ + 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(BINDING_NAME, \ + mlpack::bindings::markdown::SeeAlsoWrapper(MARKDOWN_BINDING_NAME, \ DESCRIPTION, LINK); #endif diff --git a/src/mlpack/core/util/param.hpp b/src/mlpack/core/util/param.hpp index 14f2e04c22..2c11e4d1cd 100644 --- a/src/mlpack/core/util/param.hpp +++ b/src/mlpack/core/util/param.hpp @@ -54,7 +54,7 @@ using DatasetInfo = DatasetMapper; * * @param NAME Short string representing the name of the program. */ -#define BINDING_PNAME(NAME) static \ +#define BINDING_NAME(NAME) static \ mlpack::util::ProgramName \ io_programname_dummy_object = mlpack::util::ProgramName(NAME); @@ -173,7 +173,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -200,7 +200,7 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -232,7 +232,7 @@ using DatasetInfo = DatasetMapper; * printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others * here---it will cause problems. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -259,7 +259,7 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -290,7 +290,7 @@ using DatasetInfo = DatasetMapper; * printing macros like PRINT_PARAM_STRING() or PRINT_DATASET() or others * here---it will cause problems. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -319,7 +319,7 @@ using DatasetInfo = DatasetMapper; * @param ALIAS An alias for the parameter (one letter). * @param DEF Default value of the parameter. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -351,7 +351,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -926,7 +926,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -960,7 +960,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -1000,7 +1000,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS One-character string representing the alias of the parameter. * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -1113,7 +1113,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -1138,7 +1138,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -1163,7 +1163,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug @@ -1190,7 +1190,7 @@ using DatasetInfo = DatasetMapper; * here---it will cause problems. * @param ALIAS An alias for the parameter (one letter). * - * @see mlpack::IO, BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * @see mlpack::IO, BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO(). * * @bug diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index a0bd2d8bbf..90b8e8c38d 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -20,7 +20,7 @@ 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 - * these BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), + * these BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), * BINDING_EXAMPLE() and BINDING_SEE_ALSO() macros to declare these objects. * Only correspond object should ever exist. * diff --git a/src/mlpack/methods/adaboost/adaboost_main.cpp b/src/mlpack/methods/adaboost/adaboost_main.cpp index 26e3ff0cb5..4635d438f6 100644 --- a/src/mlpack/methods/adaboost/adaboost_main.cpp +++ b/src/mlpack/methods/adaboost/adaboost_main.cpp @@ -47,7 +47,7 @@ using namespace mlpack::perceptron; using namespace mlpack::util; // Program Name. -BINDING_PNAME("AdaBoost"); +BINDING_NAME("AdaBoost"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp index ae715b47c1..792a53042e 100644 --- a/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp +++ b/src/mlpack/methods/approx_kfn/approx_kfn_main.cpp @@ -22,7 +22,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Approximate furthest neighbor search"); +BINDING_NAME("Approximate furthest neighbor search"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp index aa5ef19526..a9cf1cff75 100644 --- a/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp +++ b/src/mlpack/methods/bayesian_linear_regression/bayesian_linear_regression_main.cpp @@ -22,7 +22,7 @@ using namespace mlpack::regression; using namespace mlpack::util; // Program Name. -BINDING_PNAME("BayesianLinearRegression"); +BINDING_NAME("BayesianLinearRegression"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/cf/cf_main.cpp b/src/mlpack/methods/cf/cf_main.cpp index 60ac16a9df..760ddf107d 100644 --- a/src/mlpack/methods/cf/cf_main.cpp +++ b/src/mlpack/methods/cf/cf_main.cpp @@ -42,7 +42,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Collaborative Filtering"); +BINDING_NAME("Collaborative Filtering"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/dbscan/dbscan_main.cpp b/src/mlpack/methods/dbscan/dbscan_main.cpp index 8b0ca0766a..a9b2bcb435 100644 --- a/src/mlpack/methods/dbscan/dbscan_main.cpp +++ b/src/mlpack/methods/dbscan/dbscan_main.cpp @@ -28,7 +28,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("DBSCAN clustering"); +BINDING_NAME("DBSCAN clustering"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/decision_stump/decision_stump_main.cpp b/src/mlpack/methods/decision_stump/decision_stump_main.cpp index 27c38e8591..b928887c8e 100644 --- a/src/mlpack/methods/decision_stump/decision_stump_main.cpp +++ b/src/mlpack/methods/decision_stump/decision_stump_main.cpp @@ -22,7 +22,7 @@ using namespace std; using namespace arma; // Program Name. -BINDING_PNAME("Decision Stump"); +BINDING_NAME("Decision Stump"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/decision_tree/decision_tree_main.cpp b/src/mlpack/methods/decision_tree/decision_tree_main.cpp index 8e9c2299a2..61329c9294 100644 --- a/src/mlpack/methods/decision_tree/decision_tree_main.cpp +++ b/src/mlpack/methods/decision_tree/decision_tree_main.cpp @@ -21,7 +21,7 @@ using namespace mlpack::data; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Decision tree"); +BINDING_NAME("Decision tree"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/det/det_main.cpp b/src/mlpack/methods/det/det_main.cpp index d01741b6a8..97193c19e2 100644 --- a/src/mlpack/methods/det/det_main.cpp +++ b/src/mlpack/methods/det/det_main.cpp @@ -20,7 +20,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Density Estimation With Density Estimation Trees"); +BINDING_NAME("Density Estimation With Density Estimation Trees"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/emst/emst_main.cpp b/src/mlpack/methods/emst/emst_main.cpp index 58b2a87385..c078af4381 100644 --- a/src/mlpack/methods/emst/emst_main.cpp +++ b/src/mlpack/methods/emst/emst_main.cpp @@ -31,7 +31,7 @@ #include "dtb.hpp" // Program Name. -BINDING_PNAME("Fast Euclidean Minimum Spanning Tree"); +BINDING_NAME("Fast Euclidean Minimum Spanning Tree"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/fastmks/fastmks_main.cpp b/src/mlpack/methods/fastmks/fastmks_main.cpp index a00ac04527..3b784f6d04 100644 --- a/src/mlpack/methods/fastmks/fastmks_main.cpp +++ b/src/mlpack/methods/fastmks/fastmks_main.cpp @@ -25,7 +25,7 @@ using namespace mlpack::metric; using namespace mlpack::util; // Program Name. -BINDING_PNAME("FastMKS (Fast Max-Kernel Search)"); +BINDING_NAME("FastMKS (Fast Max-Kernel Search)"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/gmm/gmm_generate_main.cpp b/src/mlpack/methods/gmm/gmm_generate_main.cpp index c3d73bf6ca..aa6e995567 100644 --- a/src/mlpack/methods/gmm/gmm_generate_main.cpp +++ b/src/mlpack/methods/gmm/gmm_generate_main.cpp @@ -20,7 +20,7 @@ using namespace mlpack::gmm; using namespace mlpack::util; // Program Name. -BINDING_PNAME("GMM Sample Generator"); +BINDING_NAME("GMM Sample Generator"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/gmm/gmm_probability_main.cpp b/src/mlpack/methods/gmm/gmm_probability_main.cpp index 279585478d..54597696e4 100644 --- a/src/mlpack/methods/gmm/gmm_probability_main.cpp +++ b/src/mlpack/methods/gmm/gmm_probability_main.cpp @@ -20,7 +20,7 @@ using namespace mlpack::gmm; using namespace mlpack::util; // Program Name. -BINDING_PNAME("GMM Probability Calculator"); +BINDING_NAME("GMM Probability Calculator"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/gmm/gmm_train_main.cpp b/src/mlpack/methods/gmm/gmm_train_main.cpp index f6538462fe..0f46816d23 100644 --- a/src/mlpack/methods/gmm/gmm_train_main.cpp +++ b/src/mlpack/methods/gmm/gmm_train_main.cpp @@ -27,7 +27,7 @@ using namespace mlpack::kmeans; using namespace std; // Program Name. -BINDING_PNAME("Gaussian Mixture Model (GMM) Training"); +BINDING_NAME("Gaussian Mixture Model (GMM) Training"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/hmm/hmm_generate_main.cpp b/src/mlpack/methods/hmm/hmm_generate_main.cpp index 70257059e5..579524e36c 100644 --- a/src/mlpack/methods/hmm/hmm_generate_main.cpp +++ b/src/mlpack/methods/hmm/hmm_generate_main.cpp @@ -31,7 +31,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Hidden Markov Model (HMM) Sequence Generator"); +BINDING_NAME("Hidden Markov Model (HMM) Sequence Generator"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/hmm/hmm_loglik_main.cpp b/src/mlpack/methods/hmm/hmm_loglik_main.cpp index 803d3870b8..ed5b587abe 100644 --- a/src/mlpack/methods/hmm/hmm_loglik_main.cpp +++ b/src/mlpack/methods/hmm/hmm_loglik_main.cpp @@ -28,7 +28,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Hidden Markov Model (HMM) Sequence Log-Likelihood"); +BINDING_NAME("Hidden Markov Model (HMM) Sequence Log-Likelihood"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/hmm/hmm_train_main.cpp b/src/mlpack/methods/hmm/hmm_train_main.cpp index 79912d80ad..ab51f8e50b 100644 --- a/src/mlpack/methods/hmm/hmm_train_main.cpp +++ b/src/mlpack/methods/hmm/hmm_train_main.cpp @@ -29,7 +29,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Hidden Markov Model (HMM) Training"); +BINDING_NAME("Hidden Markov Model (HMM) Training"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp index f0b82c8690..ccc9aaa4fd 100644 --- a/src/mlpack/methods/hmm/hmm_viterbi_main.cpp +++ b/src/mlpack/methods/hmm/hmm_viterbi_main.cpp @@ -29,7 +29,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Hidden Markov Model (HMM) Viterbi State Prediction"); +BINDING_NAME("Hidden Markov Model (HMM) Viterbi State Prediction"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp index 471f273416..3a02d4c02b 100644 --- a/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp +++ b/src/mlpack/methods/hoeffding_trees/hoeffding_tree_main.cpp @@ -26,7 +26,7 @@ using namespace mlpack::data; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Hoeffding trees"); +BINDING_NAME("Hoeffding trees"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/kde/kde_main.cpp b/src/mlpack/methods/kde/kde_main.cpp index b8db2b6b03..3a9bd919f8 100644 --- a/src/mlpack/methods/kde/kde_main.cpp +++ b/src/mlpack/methods/kde/kde_main.cpp @@ -23,7 +23,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Kernel Density Estimation"); +BINDING_NAME("Kernel Density Estimation"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp index 00a894ae16..a70c70ef08 100644 --- a/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp +++ b/src/mlpack/methods/kernel_pca/kernel_pca_main.cpp @@ -41,7 +41,7 @@ using namespace std; using namespace arma; // Program Name. -BINDING_PNAME("Kernel Principal Components Analysis"); +BINDING_NAME("Kernel Principal Components Analysis"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/kmeans/kmeans_main.cpp b/src/mlpack/methods/kmeans/kmeans_main.cpp index 3520521131..4c7a689aec 100644 --- a/src/mlpack/methods/kmeans/kmeans_main.cpp +++ b/src/mlpack/methods/kmeans/kmeans_main.cpp @@ -28,7 +28,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("K-Means Clustering"); +BINDING_NAME("K-Means Clustering"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/lars/lars_main.cpp b/src/mlpack/methods/lars/lars_main.cpp index 2be7925455..202daf4af7 100644 --- a/src/mlpack/methods/lars/lars_main.cpp +++ b/src/mlpack/methods/lars/lars_main.cpp @@ -22,7 +22,7 @@ using namespace mlpack::regression; using namespace mlpack::util; // Program Name. -BINDING_PNAME("LARS"); +BINDING_NAME("LARS"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/linear_regression/linear_regression_main.cpp b/src/mlpack/methods/linear_regression/linear_regression_main.cpp index c3d7b74432..13fcacc386 100644 --- a/src/mlpack/methods/linear_regression/linear_regression_main.cpp +++ b/src/mlpack/methods/linear_regression/linear_regression_main.cpp @@ -22,7 +22,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Simple Linear Regression and Prediction"); +BINDING_NAME("Simple Linear Regression and Prediction"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/linear_svm/linear_svm_main.cpp b/src/mlpack/methods/linear_svm/linear_svm_main.cpp index b2026db0de..bd328fe419 100644 --- a/src/mlpack/methods/linear_svm/linear_svm_main.cpp +++ b/src/mlpack/methods/linear_svm/linear_svm_main.cpp @@ -24,7 +24,7 @@ using namespace mlpack::svm; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Linear SVM is an L2-regularized support vector machine."); +BINDING_NAME("Linear SVM is an L2-regularized support vector machine."); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/lmnn/lmnn_main.cpp b/src/mlpack/methods/lmnn/lmnn_main.cpp index eec7456e4a..2aa49b6321 100644 --- a/src/mlpack/methods/lmnn/lmnn_main.cpp +++ b/src/mlpack/methods/lmnn/lmnn_main.cpp @@ -22,7 +22,7 @@ #include // Program Name. -BINDING_PNAME("Large Margin Nearest Neighbors (LMNN)"); +BINDING_NAME("Large Margin Nearest Neighbors (LMNN)"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp index 97057d0a63..54dd2d73e5 100644 --- a/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp +++ b/src/mlpack/methods/local_coordinate_coding/local_coordinate_coding_main.cpp @@ -24,7 +24,7 @@ using namespace mlpack::sparse_coding; // For NothingInitializer. using namespace mlpack::util; // Program Name. -BINDING_PNAME("Local Coordinate Coding"); +BINDING_NAME("Local Coordinate Coding"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp index bf0b0cfb56..408385875e 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_main.cpp @@ -23,7 +23,7 @@ using namespace mlpack::regression; using namespace mlpack::util; // Program Name. -BINDING_PNAME("L2-regularized Logistic Regression and Prediction"); +BINDING_NAME("L2-regularized Logistic Regression and Prediction"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/lsh/lsh_main.cpp b/src/mlpack/methods/lsh/lsh_main.cpp index 9f572cb71b..7f36100311 100644 --- a/src/mlpack/methods/lsh/lsh_main.cpp +++ b/src/mlpack/methods/lsh/lsh_main.cpp @@ -24,7 +24,7 @@ using namespace mlpack::neighbor; using namespace mlpack::util; // Program Name. -BINDING_PNAME("K-Approximate-Nearest-Neighbor Search with LSH"); +BINDING_NAME("K-Approximate-Nearest-Neighbor Search with LSH"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/mean_shift/mean_shift_main.cpp b/src/mlpack/methods/mean_shift/mean_shift_main.cpp index e9a4ea717f..b38a86a364 100644 --- a/src/mlpack/methods/mean_shift/mean_shift_main.cpp +++ b/src/mlpack/methods/mean_shift/mean_shift_main.cpp @@ -23,7 +23,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Mean Shift Clustering"); +BINDING_NAME("Mean Shift Clustering"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/mvu/mvu_main.cpp b/src/mlpack/methods/mvu/mvu_main.cpp index c0c879f1c7..e61fc9eacf 100644 --- a/src/mlpack/methods/mvu/mvu_main.cpp +++ b/src/mlpack/methods/mvu/mvu_main.cpp @@ -16,7 +16,7 @@ #include "mvu.hpp" // Program Name. -BINDING_PNAME("Maximum Variance Unfolding (MVU)"); +BINDING_NAME("Maximum Variance Unfolding (MVU)"); // Long description. BINDING_LONG_DESC("This program implements " diff --git a/src/mlpack/methods/naive_bayes/nbc_main.cpp b/src/mlpack/methods/naive_bayes/nbc_main.cpp index f9c4b85b7b..d3b5934490 100644 --- a/src/mlpack/methods/naive_bayes/nbc_main.cpp +++ b/src/mlpack/methods/naive_bayes/nbc_main.cpp @@ -26,7 +26,7 @@ using namespace std; using namespace arma; // Program Name. -BINDING_PNAME("Parametric Naive Bayes Classifier"); +BINDING_NAME("Parametric Naive Bayes Classifier"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/nca/nca_main.cpp b/src/mlpack/methods/nca/nca_main.cpp index 1343c7ed98..ba4447b831 100644 --- a/src/mlpack/methods/nca/nca_main.cpp +++ b/src/mlpack/methods/nca/nca_main.cpp @@ -21,7 +21,7 @@ #include // Program Name. -BINDING_PNAME("Neighborhood Components Analysis (NCA)"); +BINDING_NAME("Neighborhood Components Analysis (NCA)"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/neighbor_search/kfn_main.cpp b/src/mlpack/methods/neighbor_search/kfn_main.cpp index 8bfc18b860..73b9dbd64f 100644 --- a/src/mlpack/methods/neighbor_search/kfn_main.cpp +++ b/src/mlpack/methods/neighbor_search/kfn_main.cpp @@ -33,7 +33,7 @@ using namespace mlpack::util; typedef NSModel KFNModel; // Program Name. -BINDING_PNAME("k-Furthest-Neighbors Search"); +BINDING_NAME("k-Furthest-Neighbors Search"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/neighbor_search/knn_main.cpp b/src/mlpack/methods/neighbor_search/knn_main.cpp index d2ae2c5c53..9f643ecd61 100644 --- a/src/mlpack/methods/neighbor_search/knn_main.cpp +++ b/src/mlpack/methods/neighbor_search/knn_main.cpp @@ -35,7 +35,7 @@ using namespace mlpack::util; typedef NSModel KNNModel; // Program Name. -BINDING_PNAME("k-Nearest-Neighbors Search"); +BINDING_NAME("k-Nearest-Neighbors Search"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/nmf/nmf_main.cpp b/src/mlpack/methods/nmf/nmf_main.cpp index d3401e6745..56066a673b 100644 --- a/src/mlpack/methods/nmf/nmf_main.cpp +++ b/src/mlpack/methods/nmf/nmf_main.cpp @@ -28,7 +28,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Non-negative Matrix Factorization"); +BINDING_NAME("Non-negative Matrix Factorization"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/pca/pca_main.cpp b/src/mlpack/methods/pca/pca_main.cpp index 9b86fc3f47..8f5e78d68f 100644 --- a/src/mlpack/methods/pca/pca_main.cpp +++ b/src/mlpack/methods/pca/pca_main.cpp @@ -26,7 +26,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Principal Components Analysis"); +BINDING_NAME("Principal Components Analysis"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/perceptron/perceptron_main.cpp b/src/mlpack/methods/perceptron/perceptron_main.cpp index de067c73d5..95649c6a12 100644 --- a/src/mlpack/methods/perceptron/perceptron_main.cpp +++ b/src/mlpack/methods/perceptron/perceptron_main.cpp @@ -26,7 +26,7 @@ using namespace std; using namespace arma; // Program Name. -BINDING_PNAME("Perceptron"); +BINDING_NAME("Perceptron"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/image_converter_main.cpp b/src/mlpack/methods/preprocess/image_converter_main.cpp index 9251b27f34..22bc727a59 100644 --- a/src/mlpack/methods/preprocess/image_converter_main.cpp +++ b/src/mlpack/methods/preprocess/image_converter_main.cpp @@ -21,7 +21,7 @@ using namespace std; using namespace mlpack::data; // Program Name. -BINDING_PNAME("Image Converter"); +BINDING_NAME("Image Converter"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp index 44d2c7219a..f47e623e27 100644 --- a/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_binarize_main.cpp @@ -15,7 +15,7 @@ #include // Program Name. -BINDING_PNAME("Binarize Data"); +BINDING_NAME("Binarize Data"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp index 20b29e9125..316cdd2ef9 100644 --- a/src/mlpack/methods/preprocess/preprocess_describe_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_describe_main.cpp @@ -23,7 +23,7 @@ using namespace std; using namespace boost; // Program Name. -BINDING_PNAME("Descriptive Statistics"); +BINDING_NAME("Descriptive Statistics"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp index 489117b088..236b339832 100644 --- a/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_imputer_main.cpp @@ -23,7 +23,7 @@ #include // Program Name. -BINDING_PNAME("Impute Data"); +BINDING_NAME("Impute Data"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp index 3080b4198e..1c4759f0a9 100644 --- a/src/mlpack/methods/preprocess/preprocess_scale_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_scale_main.cpp @@ -29,7 +29,7 @@ using namespace arma; using namespace std; // Program Name. -BINDING_PNAME("Scale Data"); +BINDING_NAME("Scale Data"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/preprocess/preprocess_split_main.cpp b/src/mlpack/methods/preprocess/preprocess_split_main.cpp index 11417bed4c..b6a36967a1 100644 --- a/src/mlpack/methods/preprocess/preprocess_split_main.cpp +++ b/src/mlpack/methods/preprocess/preprocess_split_main.cpp @@ -16,7 +16,7 @@ #include // Program Name. -BINDING_PNAME("Split Data"); +BINDING_NAME("Split Data"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/radical/radical_main.cpp b/src/mlpack/methods/radical/radical_main.cpp index 61d0a7037c..1d520d2bcb 100644 --- a/src/mlpack/methods/radical/radical_main.cpp +++ b/src/mlpack/methods/radical/radical_main.cpp @@ -17,7 +17,7 @@ #include "radical.hpp" // Program Name. -BINDING_PNAME("RADICAL"); +BINDING_NAME("RADICAL"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/random_forest/random_forest_main.cpp b/src/mlpack/methods/random_forest/random_forest_main.cpp index 1acedf67dc..ade8957c81 100644 --- a/src/mlpack/methods/random_forest/random_forest_main.cpp +++ b/src/mlpack/methods/random_forest/random_forest_main.cpp @@ -20,7 +20,7 @@ using namespace mlpack::util; using namespace std; // Program Name. -BINDING_PNAME("Random forests"); +BINDING_NAME("Random forests"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/range_search/range_search_main.cpp b/src/mlpack/methods/range_search/range_search_main.cpp index 29d9cbdec0..3dfb87155f 100644 --- a/src/mlpack/methods/range_search/range_search_main.cpp +++ b/src/mlpack/methods/range_search/range_search_main.cpp @@ -28,7 +28,7 @@ using namespace mlpack::metric; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Range Search"); +BINDING_NAME("Range Search"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/rann/krann_main.cpp b/src/mlpack/methods/rann/krann_main.cpp index 7f9ac067b9..9d830f5fff 100644 --- a/src/mlpack/methods/rann/krann_main.cpp +++ b/src/mlpack/methods/rann/krann_main.cpp @@ -29,7 +29,7 @@ using namespace mlpack::util; typedef RAModel RANNModel; // Program Name. -BINDING_PNAME("K-Rank-Approximate-Nearest-Neighbors (kRANN)"); +BINDING_NAME("K-Rank-Approximate-Nearest-Neighbors (kRANN)"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp index 2673ba66d8..571b239187 100644 --- a/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp +++ b/src/mlpack/methods/softmax_regression/softmax_regression_main.cpp @@ -24,7 +24,7 @@ using namespace mlpack::regression; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Softmax Regression"); +BINDING_NAME("Softmax Regression"); // Short description. BINDING_SHORT_DESC( diff --git a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp index 8f1881100e..15753327b8 100644 --- a/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp +++ b/src/mlpack/methods/sparse_coding/sparse_coding_main.cpp @@ -23,7 +23,7 @@ using namespace mlpack::sparse_coding; using namespace mlpack::util; // Program Name. -BINDING_PNAME("Sparse Coding"); +BINDING_NAME("Sparse Coding"); // Short description. BINDING_SHORT_DESC( From 0dbc7b42a8b55b9f34dd0343f8eb43d2a0f32470 Mon Sep 17 00:00:00 2001 From: himanshupathak21061998 Date: Wed, 12 Aug 2020 02:14:17 +0530 Subject: [PATCH 09/25] Adding some suggestions --- src/mlpack/methods/ann/rbm/rbm.hpp | 37 ++++++------ src/mlpack/methods/ann/rbm/rbm_impl.hpp | 56 +++++++------------ .../methods/ann/rbm/spike_slab_rbm_impl.hpp | 55 ++++++++---------- src/mlpack/tests/rbm_network_test.cpp | 13 ++--- src/mlpack/tests/serialization_test.cpp | 8 +-- 5 files changed, 70 insertions(+), 99 deletions(-) diff --git a/src/mlpack/methods/ann/rbm/rbm.hpp b/src/mlpack/methods/ann/rbm/rbm.hpp index d05f6e6321..0da3cff493 100644 --- a/src/mlpack/methods/ann/rbm/rbm.hpp +++ b/src/mlpack/methods/ann/rbm/rbm.hpp @@ -33,7 +33,6 @@ namespace ann /** Artificial Neural Network. */ { */ template< typename InitializationRuleType, - typename InputType = arma::mat, typename DataType = arma::mat, typename PolicyType = BinaryRBM > @@ -72,12 +71,12 @@ class RBM const bool persistence = false); // Reset the network. - template + template typename std::enable_if::value, void>::type Reset(); // Reset the network. - template + template typename std::enable_if::value, void>::type Reset(); @@ -118,7 +117,7 @@ class RBM * * @param input The visible neurons. */ - template + template typename std::enable_if::value, double>::type FreeEnergy(const arma::Mat& input); @@ -132,7 +131,7 @@ class RBM * * @param input The visible layer neurons. */ - template + template typename std::enable_if::value, double>::type FreeEnergy(const arma::Mat& input); @@ -143,7 +142,7 @@ class RBM * @param input The provided input data. * @param gradient Stores the gradient of the RBM network. */ - template + template typename std::enable_if::value, void>::type Phase(const InputType& input, DataType& gradient); @@ -153,7 +152,7 @@ class RBM * @param input The provided input data. * @param gradient Stores the gradient of the RBM network. */ - template + template typename std::enable_if::value, void>::type Phase(const InputType& input, DataType& gradient); @@ -164,7 +163,7 @@ class RBM * @param input Visible layer input. * @param output The sampled hidden layer. */ - template + template typename std::enable_if::value, void>::type SampleHidden(const arma::Mat& input, arma::Mat& output); @@ -178,7 +177,7 @@ class RBM * @param input Consists of both visible and spike variables. * @param output Sampled slab neurons. */ - template + template typename std::enable_if::value, void>::type SampleHidden(const arma::Mat& input, arma::Mat& output); @@ -189,7 +188,7 @@ class RBM * @param input Hidden layer of the network. * @param output The sampled visible layer. */ - template + template typename std::enable_if::value, void>::type SampleVisible(arma::Mat& input, arma::Mat& output); @@ -203,7 +202,7 @@ class RBM * @param input Hidden layer of the network. * @param output The sampled visible layer. */ - template + template typename std::enable_if::value, void>::type SampleVisible(arma::Mat& input, arma::Mat& output); @@ -213,7 +212,7 @@ class RBM * @param input Hidden neurons from the hidden layer of the network. * @param output Visible neuron activations. */ - template + template typename std::enable_if::value, void>::type VisibleMean(InputType& input, DataType& output); @@ -225,7 +224,7 @@ class RBM * @param input Consists of both the spike and slab variables. * @param output Mean of the of the Normal distribution. */ - template + template typename std::enable_if::value, void>::type VisibleMean(InputType& input, DataType& output); @@ -235,7 +234,7 @@ class RBM * @param input Visible neurons. * @param output Hidden neuron activations. */ - template + template typename std::enable_if::value, void>::type HiddenMean(const InputType& input, DataType& output); @@ -249,7 +248,7 @@ class RBM * @param input Visible layer neurons. * @param output Consists of both the spike samples and slab samples. */ - template + template typename std::enable_if::value, void>::type HiddenMean(const InputType& input, DataType& output); @@ -261,7 +260,7 @@ class RBM * @param visible The visible layer neurons. * @param spikeMean Indicates P(h|v). */ - template + template typename std::enable_if::value, void>::type SpikeMean(const InputType& visible, DataType& spikeMean); @@ -270,7 +269,7 @@ class RBM * @param spikeMean Indicates P(h|v). * @param spike Sampled binary spike variables. */ - template + template typename std::enable_if::value, void>::type SampleSpike(InputType& spikeMean, DataType& spike); @@ -283,7 +282,7 @@ class RBM * @param spike The spike variables from hidden layer. * @param slabMean The mean of the Normal distribution of slab neurons. */ - template + template typename std::enable_if::value, void>::type SlabMean(const DataType& visible, DataType& spike, DataType& slabMean); @@ -297,7 +296,7 @@ class RBM * @param slabMean Mean of the Normal distribution of the slab neurons. * @param slab Sampled slab variable from the Normal distribution. */ - template + template typename std::enable_if::value, void>::type SampleSlab(InputType& slabMean, DataType& slab); diff --git a/src/mlpack/methods/ann/rbm/rbm_impl.hpp b/src/mlpack/methods/ann/rbm/rbm_impl.hpp index 1597140c37..76014848b0 100644 --- a/src/mlpack/methods/ann/rbm/rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/rbm_impl.hpp @@ -21,11 +21,10 @@ namespace ann /** Artificial neural networks. */ { template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -RBM::RBM( +RBM::RBM( arma::Mat predictors, InitializationRuleType initializeRule, const size_t visibleSize, @@ -56,13 +55,12 @@ RBM::RBM( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::Reset() +RBM::Reset() { size_t shape = (visibleSize * hiddenSize) + visibleSize + hiddenSize; @@ -90,12 +88,11 @@ RBM::Reset() template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > template -double RBM::Train( +double RBM::Train( OptimizerType& optimizer, CallbackType&&... callbacks) { if (!reset) @@ -108,13 +105,12 @@ double RBM::Train( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, double>::type -RBM::FreeEnergy( +RBM::FreeEnergy( const arma::Mat& input) { preActivation = (weight.slice(0) * input); @@ -125,13 +121,12 @@ RBM::FreeEnergy( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::Phase( +RBM::Phase( const InputType& input, DataType& gradient) { @@ -147,11 +142,10 @@ RBM::Phase( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -double RBM::Evaluate( +double RBM::Evaluate( const arma::Mat& /* parameters*/, const size_t i, const size_t batchSize) @@ -164,13 +158,12 @@ double RBM::Evaluate( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleHidden( +RBM::SampleHidden( const arma::Mat& input, arma::Mat& output) { @@ -184,13 +177,12 @@ RBM::SampleHidden( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleVisible( +RBM::SampleVisible( arma::Mat& input, arma::Mat& output) { @@ -204,13 +196,12 @@ RBM::SampleVisible( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::VisibleMean( +RBM::VisibleMean( InputType& input, DataType& output) { @@ -221,13 +212,12 @@ RBM::VisibleMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::HiddenMean( +RBM::HiddenMean( const InputType& input, DataType& output) { @@ -238,11 +228,10 @@ RBM::HiddenMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -void RBM::Gibbs( +void RBM::Gibbs( const arma::Mat& input, arma::Mat& output, const size_t steps) @@ -273,11 +262,10 @@ void RBM::Gibbs( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -void RBM::Gradient( +void RBM::Gradient( const arma::Mat& /*parameters*/, const size_t i, arma::Mat& gradient, @@ -303,11 +291,10 @@ void RBM::Gradient( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -void RBM::Shuffle() +void RBM::Shuffle() { predictors = predictors.cols(arma::shuffle(arma::linspace(0, predictors.n_cols - 1, predictors.n_cols))); @@ -315,12 +302,11 @@ void RBM::Shuffle() template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > template -void RBM::serialize( +void RBM::serialize( Archive& ar, const unsigned int /* version */) { ar & BOOST_SERIALIZATION_NVP(parameter); diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index d95efbcb50..b2bdc10026 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -22,13 +22,12 @@ namespace ann { template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::Reset() +RBM::Reset() { size_t shape = (visibleSize * hiddenSize * poolSize) + visibleSize + hiddenSize; @@ -63,13 +62,12 @@ RBM::Reset() template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, double>::type -RBM::FreeEnergy( +RBM::FreeEnergy( const arma::Mat& input) { ElemType freeEnergy = 0.5 * visiblePenalty(0) * arma::dot(input, input); @@ -89,13 +87,12 @@ RBM::FreeEnergy( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::Phase( +RBM::Phase( const InputType& input, DataType& gradient) { @@ -126,13 +123,12 @@ RBM::Phase( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleHidden( +RBM::SampleHidden( const arma::Mat& input, arma::Mat& output) { @@ -150,13 +146,12 @@ RBM::SampleHidden( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleVisible( +RBM::SampleVisible( arma::Mat& input, arma::Mat& output) { @@ -189,13 +184,12 @@ RBM::SampleVisible( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::VisibleMean( +RBM::VisibleMean( InputType& input, DataType& output) { @@ -215,13 +209,12 @@ RBM::VisibleMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::HiddenMean( +RBM::HiddenMean( const InputType& input, DataType& output) { @@ -238,13 +231,12 @@ RBM::HiddenMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SpikeMean( +RBM::SpikeMean( const InputType& visible, DataType& spikeMean) { @@ -258,13 +250,12 @@ RBM::SpikeMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleSpike( +RBM::SampleSpike( InputType& spikeMean, DataType& spike) { @@ -276,13 +267,12 @@ RBM::SampleSpike( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SlabMean( +RBM::SlabMean( const DataType& visible, DataType& spike, DataType& slabMean) @@ -296,13 +286,12 @@ RBM::SlabMean( template< typename InitializationRuleType, - typename InputType, typename DataType, typename PolicyType > -template +template typename std::enable_if::value, void>::type -RBM::SampleSlab( +RBM::SampleSlab( InputType& slabMean, DataType& slab) { diff --git a/src/mlpack/tests/rbm_network_test.cpp b/src/mlpack/tests/rbm_network_test.cpp index 374512ab26..21995785e3 100644 --- a/src/mlpack/tests/rbm_network_test.cpp +++ b/src/mlpack/tests/rbm_network_test.cpp @@ -94,8 +94,7 @@ BOOST_AUTO_TEST_CASE(BinaryRBMClassificationTest) for (size_t i = 0; i < testData.n_cols; ++i) { - model.HiddenMean(testData.col(i), - output); + model.HiddenMean(testData.col(i), output); YRbm.col(i) = output; } const size_t numClasses = 10; // Number of classes. @@ -170,7 +169,7 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) YRbm.zeros(); double slabPenalty = 8; - RBM modelssRBM( + RBM modelssRBM( trainData, gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, 1, poolSize, slabPenalty, radius); @@ -189,15 +188,13 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) for (size_t i = 0; i < trainData.n_cols; ++i) { - modelssRBM.HiddenMean(trainData.col(i), - output); + modelssRBM.HiddenMean(trainData.col(i), output); XRbm.col(i) = output; } for (size_t i = 0; i < testData.n_cols; ++i) { - modelssRBM.HiddenMean(testData.col(i), - output); + modelssRBM.HiddenMean(testData.col(i), output); YRbm.col(i) = output; } const size_t numClasses = 10; // Number of classes. @@ -223,7 +220,7 @@ void BuildVanillaNetwork(MatType& trainData, { MatType output; GaussianInitialization gaussian(0, 0.1); - RBM model( + RBM model( trainData, gaussian, trainData.n_rows, hiddenLayerSize, 1, 1, 1, 2, 8, 1, true); diff --git a/src/mlpack/tests/serialization_test.cpp b/src/mlpack/tests/serialization_test.cpp index 17896f789c..279b1ec1af 100644 --- a/src/mlpack/tests/serialization_test.cpp +++ b/src/mlpack/tests/serialization_test.cpp @@ -1569,16 +1569,16 @@ BOOST_AUTO_TEST_CASE(ssRBMTest) size_t poolSize = 1; GaussianInitialization gaussian(0, 0.1); - RBM Rbm(data, + RBM Rbm(data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, true); - RBM RbmXml(data, + RBM RbmXml(data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, true); - RBM RbmText(data, + RBM RbmText(data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, true); - RBM RbmBinary( + RBM RbmBinary( data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, true); Rbm.Reset(); From c97676716645f5eb0e913915bdf7066eff7a8ec5 Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Tue, 11 Aug 2020 17:53:54 -0400 Subject: [PATCH 10/25] Remove unnecessary and unused initialPoint from LogisticRegressionFunction<>. --- .../logistic_regression_function.hpp | 23 ------------------- .../logistic_regression_function_impl.hpp | 21 ----------------- .../logistic_regression_impl.hpp | 1 - 3 files changed, 45 deletions(-) diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp index 692796d7a0..636aa4d601 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_function.hpp @@ -41,24 +41,6 @@ class LogisticRegressionFunction const arma::Row& 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& 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; diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp index 1b37ba070b..a28a1d38d4 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_function_impl.hpp @@ -31,8 +31,6 @@ LogisticRegressionFunction::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::LogisticRegressionFunction( } } -template -LogisticRegressionFunction::LogisticRegressionFunction( - const MatType& predictors, - const arma::Row& 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(predictors), false)), - responses(math::MakeAlias(const_cast&>(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. */ diff --git a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp index 41bf890e1f..738e0b1355 100644 --- a/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp +++ b/src/mlpack/methods/logistic_regression/logistic_regression_impl.hpp @@ -89,7 +89,6 @@ double LogisticRegression::Train( // Set size of parameters vector according to the input data received. if (parameters.n_elem != predictors.n_rows + 1) parameters = arma::rowvec(predictors.n_rows + 1, arma::fill::zeros); - errorFunction.InitialPoint() = parameters; Timer::Start("logistic_regression_optimization"); const double out = optimizer.Optimize(errorFunction, parameters, From c7779e873ec76759dd668d3723cdd80b38a82e67 Mon Sep 17 00:00:00 2001 From: himanshupathak21061998 Date: Wed, 12 Aug 2020 07:52:22 +0530 Subject: [PATCH 11/25] Removing some unnecesary changes --- src/mlpack/methods/ann/rbm/rbm.hpp | 1 - src/mlpack/tests/rbm_network_test.cpp | 11 +++++------ src/mlpack/tests/serialization_test.cpp | 24 ++++++++++++------------ 3 files changed, 17 insertions(+), 19 deletions(-) diff --git a/src/mlpack/methods/ann/rbm/rbm.hpp b/src/mlpack/methods/ann/rbm/rbm.hpp index 0da3cff493..be8d939169 100644 --- a/src/mlpack/methods/ann/rbm/rbm.hpp +++ b/src/mlpack/methods/ann/rbm/rbm.hpp @@ -27,7 +27,6 @@ namespace ann /** Artificial Neural Network. */ { * machines, with the restriction that the neurons must form a bipartite graph. * * @tparam InitializationRuleType Rule used to initialize the network. - * @tparam InputType The type of matrix to be used as input type. * @tparam DataType The type of matrix to be used. * @tparam PolicyType The RBM variant to be used (BinaryRBM or SpikeSlabRBM). */ diff --git a/src/mlpack/tests/rbm_network_test.cpp b/src/mlpack/tests/rbm_network_test.cpp index 21995785e3..820f9616f5 100644 --- a/src/mlpack/tests/rbm_network_test.cpp +++ b/src/mlpack/tests/rbm_network_test.cpp @@ -169,9 +169,9 @@ BOOST_AUTO_TEST_CASE(ssRBMClassificationTest) YRbm.zeros(); double slabPenalty = 8; - RBM modelssRBM( - trainData, gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, - 1, poolSize, slabPenalty, radius); + RBM modelssRBM(trainData, + gaussian, trainData.n_rows, hiddenLayerSize, batchSize, 1, 1, poolSize, + slabPenalty, radius); size_t numRBMIterations = trainData.n_cols * numEpoches; numRBMIterations /= batchSize; @@ -220,9 +220,8 @@ void BuildVanillaNetwork(MatType& trainData, { MatType output; GaussianInitialization gaussian(0, 0.1); - RBM model( - trainData, gaussian, trainData.n_rows, hiddenLayerSize, - 1, 1, 1, 2, 8, 1, true); + RBM model(trainData, gaussian, + trainData.n_rows, hiddenLayerSize, 1, 1, 1, 2, 8, 1, true); model.Reset(); // Set the parameters from a learned RBM Sklearn random state 23. diff --git a/src/mlpack/tests/serialization_test.cpp b/src/mlpack/tests/serialization_test.cpp index 279b1ec1af..e30fcc4dc9 100644 --- a/src/mlpack/tests/serialization_test.cpp +++ b/src/mlpack/tests/serialization_test.cpp @@ -1569,18 +1569,18 @@ BOOST_AUTO_TEST_CASE(ssRBMTest) size_t poolSize = 1; GaussianInitialization gaussian(0, 0.1); - RBM Rbm(data, - gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, - radius, true); - RBM RbmXml(data, - gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, - radius, true); - RBM RbmText(data, - gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, - radius, true); - RBM RbmBinary( - data, gaussian, data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, - slabPenalty, radius, true); + RBM Rbm(data, gaussian, + data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, + true); + RBM RbmXml(data, gaussian, + data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, + true); + RBM RbmText(data, gaussian, + data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, + true); + RBM RbmBinary(data, gaussian, + data.n_rows, hiddenLayerSize, 1, 1, 1, poolSize, slabPenalty, radius, + true); Rbm.Reset(); Rbm.VisiblePenalty().fill(15); Rbm.SpikeBias().ones(); From 4e04bb13d22b1009654608ebfe284a6013e9c34b Mon Sep 17 00:00:00 2001 From: Yashwant Singh Parihar Date: Wed, 12 Aug 2020 09:03:34 +0530 Subject: [PATCH 12/25] Apply suggestions from code review Thanks for the suggestion @rcurtin. Co-authored-by: Ryan Curtin --- doc/guide/bindings.hpp | 33 ++++++++++++------------ src/mlpack/bindings/python/print_pyx.cpp | 2 +- src/mlpack/core/util/param.hpp | 2 ++ src/mlpack/core/util/program_doc.cpp | 4 +-- src/mlpack/core/util/program_doc.hpp | 6 +++++ 5 files changed, 27 insertions(+), 20 deletions(-) diff --git a/doc/guide/bindings.hpp b/doc/guide/bindings.hpp index 31b59e3d54..f2b9d434a5 100644 --- a/doc/guide/bindings.hpp +++ b/doc/guide/bindings.hpp @@ -298,8 +298,8 @@ then the examples in the following sections should clarify. Any mlpack program should be documented with the @c BINDING_PNAME(), @c BINDING_SHORT_DESC(), @c BINDING_LONG_DESC() , @c BINDING_EXAMPLE() and @c BINDING_SEE_ALSO() macros, which is available from the -@c header. The macro -is of the form +@c header. The macros +are of the form @code BINDING_NAME("program name"); @@ -472,15 +472,14 @@ Go binding output (snippet): @code Input C++ (full program, 'random_numbers_main.cpp'): -// Program Name. -BINDING_PNAME("Random Numbers"); + // Program Name. + BINDING_PNAME("Random Numbers"); -// Short description. -BINDING_SHORT_DESC( - "An implementation of Random Numbers"); + // Short description. + BINDING_SHORT_DESC("An implementation of Random Numbers"); -// Long description. -BINDING_LONG_DESC( + // 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 " + @@ -495,8 +494,8 @@ BINDING_LONG_DESC( "randomly generated linear regression model can be saved with the " + PRINT_PARAM_STRING("output_model") + " output parameter."); -// Example. -BINDING_EXAMPLE( + // 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 " @@ -607,7 +606,7 @@ There exist several macros that can be used after a @c BINDING_LONG_DESC() and 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 +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 @@ -739,7 +738,7 @@ 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 BINDING_LONG_DESC() and @c BINDING_EXAMPLE() macro +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. @@ -822,7 +821,7 @@ could be created for the "random_numbers" program from earlier sections. @code #include -// BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC() , BINDING_EXAMPLE(), +// The BINDING_PNAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), BINDING_EXAMPLE(), // BINDING_SEE_ALSO() and PARAM_*() definitions should go here: // ... @@ -886,8 +885,8 @@ There are eight main components involved with mlpack bindings: - the BINDING_PNAME() 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 - - the BINDING_EXAMPLE() macro that defines the example - - the BINDING_SEE_ALSO() macro that defines the see also + - (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 @@ -915,7 +914,7 @@ 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 seealso. +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 diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 5db4129eab..627bf291d5 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -146,7 +146,7 @@ void PrintPYX(const string& mainFilename, cout << " " << pname.programName << endl; cout << endl; cout << " " << HyphenateString(longDesc.longDescription(), 2) << endl; - cout << endl; + cout << endl; for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) { util::Example& example = *IO::GetSingleton().examples[j]; diff --git a/src/mlpack/core/util/param.hpp b/src/mlpack/core/util/param.hpp index 14f2e04c22..938ed6de04 100644 --- a/src/mlpack/core/util/param.hpp +++ b/src/mlpack/core/util/param.hpp @@ -130,6 +130,7 @@ using DatasetInfo = DatasetMapper; mlpack::util::Example( \ []() { return(std::string(EXAMPLE)); }); #endif + /** * Document an executable. Mutiple instance of this macro can be * present in your program! Therefore, use it in the main.cpp @@ -164,6 +165,7 @@ using DatasetInfo = DatasetMapper; JOIN(JOIN(io_programsee_also_dummy_object_, __LINE__), opt) = \ mlpack::util::SeeAlso(DESCRIPTION, LINK); #endif + /** * Define a flag parameter. * diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 0ff5bf34a1..fbdfa7eeea 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -3,8 +3,8 @@ * @author Yashwant Singh Parihar * @author Ryan Curtin * - * Implementation of the mutiple classes. The classes 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 diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index a0bd2d8bbf..1cf953123f 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -41,6 +41,7 @@ class ProgramName * Construct an empty ProgramName object. (This is not meant to be used!) */ ProgramName(); + std::string programName; }; @@ -62,6 +63,7 @@ class ShortDescription * (This is not meant to be used!) */ ShortDescription(); + std::string shortDescription; }; @@ -82,6 +84,7 @@ class LongDescription * Construct an empty LongDescription object. (This is not meant to be used!) */ LongDescription(); + std::function longDescription; }; @@ -100,6 +103,7 @@ class Example * Construct an empty Example object. (This is not meant to be used!) */ Example(); + std::function example; }; @@ -119,9 +123,11 @@ class SeeAlso * Construct an empty SeeAlso object. (This is not meant to be used!) */ SeeAlso(); + std::string description; std::string link; }; + } // namespace util } // namespace mlpack From 6ecf8c058af07436709acee2afabf610fd9b193f Mon Sep 17 00:00:00 2001 From: Yashwant Date: Wed, 12 Aug 2020 09:25:43 +0530 Subject: [PATCH 13/25] Fake. --- src/mlpack/bindings/cli/print_help.cpp | 20 ++-- src/mlpack/bindings/go/generate_go.cpp.in | 2 +- src/mlpack/bindings/go/print_go.cpp | 20 ++-- src/mlpack/bindings/go/print_go.hpp | 3 +- src/mlpack/bindings/julia/generate_jl.cpp.in | 2 +- src/mlpack/bindings/julia/print_jl.cpp | 18 ++-- src/mlpack/bindings/julia/print_jl.hpp | 3 +- .../bindings/python/generate_pyx.cpp.in | 2 +- src/mlpack/bindings/python/print_pyx.cpp | 22 ++-- src/mlpack/bindings/python/print_pyx.hpp | 3 +- src/mlpack/core/util/CMakeLists.txt | 1 + src/mlpack/core/util/binding_details.hpp | 44 ++++++++ src/mlpack/core/util/io.cpp | 102 +----------------- src/mlpack/core/util/io.hpp | 88 ++------------- src/mlpack/core/util/program_doc.cpp | 23 ++-- src/mlpack/core/util/program_doc.hpp | 3 +- 16 files changed, 111 insertions(+), 245 deletions(-) create mode 100644 src/mlpack/core/util/binding_details.hpp diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index 2b2cf7bb58..6f2d4ae961 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -25,9 +25,7 @@ void PrintHelp(const std::string& param) std::string usedParam = param; std::map& parameters = IO::Parameters(); const std::map& aliases = IO::Aliases(); - util::ProgramName& pname = *IO::GetSingleton().pname; - util::LongDescription& longDesc = *IO::GetSingleton().longDesc; - + 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]); @@ -65,16 +63,16 @@ void PrintHelp(const std::string& param) } // Print out the descriptions. - if (pname.programName != "") + if (bindingDetails.programName->programName != "") { - std::cout << pname.programName << std::endl << std::endl; - std::cout << " " << util::HyphenateString(longDesc.longDescription(), - 2) << std::endl << std::endl; - for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + std::cout << bindingDetails.programName->programName + << std::endl << std::endl; + std::cout << " " << util::HyphenateString(bindingDetails.longDescription-> + longDescription(), 2) << std::endl << std::endl; + for (size_t j = 0; j < bindingDetails.example.size(); ++j) { - util::Example& example = *IO::GetSingleton().examples[j]; - std::cout << " " << util::HyphenateString(example.example(), 2) - << std::endl << std::endl; + std::cout << " " << util::HyphenateString(bindingDetails.example[j]-> + example(), 2) << std::endl << std::endl; } } else diff --git a/src/mlpack/bindings/go/generate_go.cpp.in b/src/mlpack/bindings/go/generate_go.cpp.in index 086783e3e2..0e75e9c4cd 100644 --- a/src/mlpack/bindings/go/generate_go.cpp.in +++ b/src/mlpack/bindings/go/generate_go.cpp.in @@ -45,5 +45,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintGo("${PROGRAM_NAME}"); + PrintGo(IO::GetSingleton().doc, "${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/go/print_go.cpp b/src/mlpack/bindings/go/print_go.cpp index d69e82e6fd..39796b8982 100644 --- a/src/mlpack/bindings/go/print_go.cpp +++ b/src/mlpack/bindings/go/print_go.cpp @@ -29,12 +29,11 @@ namespace go { * * @param functionName Name of the function (i.e. "pca"). */ -void PrintGo(const std::string& functionName) +void PrintGo(const util::BindingDetails& doc, + const std::string& functionName) { - util::ProgramName& pname = *IO::GetSingleton().pname; - util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(pname.programName); + IO::RestoreSettings(doc.programName->programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -124,13 +123,12 @@ void PrintGo(const std::string& functionName) // Print the comment describing the function and its parameters. cout << "/*" << endl; - cout << " " << HyphenateString(longDesc.longDescription(), 2) << endl; - cout << endl; - for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + cout << " " << HyphenateString(doc.longDescription->longDescription(), 2) + << endl << endl; + for (size_t j = 0; j < doc.example.size(); ++j) { - util::Example& example = *IO::GetSingleton().examples[j]; - cout << " " << util::HyphenateString(example.example(), 2) - << endl << endl; + cout << " " << util::HyphenateString(doc.example[j]->example(), 2) + << endl << endl; } cout << " Input parameters:" << endl; cout << endl; @@ -222,7 +220,7 @@ void PrintGo(const std::string& functionName) cout << " " << "disableVerbose()" << endl; // Restore the parameters. - cout << " " << "restoreSettings(\"" << pname.programName + cout << " " << "restoreSettings(\"" << doc.programName->programName << "\")" << endl; cout << endl; diff --git a/src/mlpack/bindings/go/print_go.hpp b/src/mlpack/bindings/go/print_go.hpp index 3a9da298c2..53a3280e8f 100644 --- a/src/mlpack/bindings/go/print_go.hpp +++ b/src/mlpack/bindings/go/print_go.hpp @@ -25,7 +25,8 @@ namespace go { * * @param functionName Name of the function (i.e. "pca"). */ -void PrintGo(const std::string& functionName); +void PrintGo(const util::BindingDetails& doc, + const std::string& functionName); } // namespace go diff --git a/src/mlpack/bindings/julia/generate_jl.cpp.in b/src/mlpack/bindings/julia/generate_jl.cpp.in index 4afceb02c5..8dbd38470c 100644 --- a/src/mlpack/bindings/julia/generate_jl.cpp.in +++ b/src/mlpack/bindings/julia/generate_jl.cpp.in @@ -35,5 +35,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintJL("${NAME}", "${MLPACK_JL_LIB_SUFFIX}"); + PrintJL(IO::GetSingleton().doc, "${NAME}", "${MLPACK_JL_LIB_SUFFIX}"); } diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index fd8c468d3c..c7ac7d985e 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -15,7 +15,7 @@ #include -using namespace mlpack; +using namespace mlpack::util; using namespace std; namespace mlpack { @@ -27,13 +27,12 @@ extern std::string programName; /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const string& functionName, +void PrintJL(const util::BindingDetails& doc, + const string& functionName, const std::string& mlpackJuliaLibSuffix) { - util::ProgramName& pname = *IO::GetSingleton().pname; - util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(pname.programName); + IO::RestoreSettings(doc.programName->programName); map& parameters = IO::Parameters(); typedef map::iterator ParamIter; @@ -169,12 +168,11 @@ void PrintJL(const string& functionName, cout << endl; // Next print the description. - cout << util::HyphenateString(longDesc.longDescription(), 0) << endl; - for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + cout << HyphenateString(doc.longDescription->longDescription(), 0) + << endl << endl; + for (size_t j = 0; j < doc.example.size(); ++j) { - util::Example& example = *IO::GetSingleton().examples[j]; - cout << util::HyphenateString(example.example(), 0) - << endl; + cout << util::HyphenateString(doc.example[j]->example(), 0) << endl << endl; } // Next, print information on the input options. cout << endl; diff --git a/src/mlpack/bindings/julia/print_jl.hpp b/src/mlpack/bindings/julia/print_jl.hpp index b8d813c559..5e73f590ff 100644 --- a/src/mlpack/bindings/julia/print_jl.hpp +++ b/src/mlpack/bindings/julia/print_jl.hpp @@ -21,7 +21,8 @@ namespace julia { /** * Print the code for a .jl binding for an mlpack program to stdout. */ -void PrintJL(const std::string& functionName, +void PrintJL(const util::BindingDetails& doc, + const std::string& functionName, const std::string& mlpackJuliaLibSuffix); } // namespace julia diff --git a/src/mlpack/bindings/python/generate_pyx.cpp.in b/src/mlpack/bindings/python/generate_pyx.cpp.in index 00ff566b9d..09905be574 100644 --- a/src/mlpack/bindings/python/generate_pyx.cpp.in +++ b/src/mlpack/bindings/python/generate_pyx.cpp.in @@ -45,5 +45,5 @@ int main(int /* argc */, char** /* argv */) // programName is defined in mlpack_main.hpp. IO::RestoreSettings(programName); - PrintPYX("${PROGRAM_MAIN_FILE}", "${PROGRAM_NAME}"); + PrintPYX(IO::GetSingleton().doc, "${PROGRAM_MAIN_FILE}", "${PROGRAM_NAME}"); } diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 5db4129eab..5b041611c9 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -31,13 +31,12 @@ namespace python { * "/path/to/pca_main.cpp"). * @param functionName Name of the function (i.e. "pca"). */ -void PrintPYX(const string& mainFilename, +void PrintPYX(const util::BindingDetails& doc, + const string& mainFilename, const string& functionName) { - util::ProgramName& pname = *IO::GetSingleton().pname; - util::LongDescription& longDesc = *IO::GetSingleton().longDesc; // Restore parameters. - IO::RestoreSettings(pname.programName); + IO::RestoreSettings(doc.programName->programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -143,15 +142,14 @@ void PrintPYX(const string& mainFilename, // Print the comment describing the function and its parameters. cout << " \"\"\"" << endl; - cout << " " << pname.programName << endl; + cout << " " << doc.programName->programName << endl; cout << endl; - cout << " " << HyphenateString(longDesc.longDescription(), 2) << endl; - cout << endl; - for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + cout << " " << HyphenateString(doc.longDescription->longDescription(), 2) + << endl << endl; + for (size_t j = 0; j < doc.example.size(); ++j) { - util::Example& example = *IO::GetSingleton().examples[j]; - cout << " " << util::HyphenateString(example.example(), 2) - << endl << endl; + cout << " " << util::HyphenateString(doc.example[j]->example(), 2) << endl + << endl; } cout << " Input parameters:" << endl; cout << endl; @@ -190,7 +188,7 @@ void PrintPYX(const string& mainFilename, cout << " DisableVerbose()" << endl; // Restore the parameters. - cout << " IO.RestoreSettings(\"" << pname.programName << "\")" + cout << " IO.RestoreSettings(\"" << doc.programName->programName << "\")" << endl; // Determine whether or not we need to copy parameters. diff --git a/src/mlpack/bindings/python/print_pyx.hpp b/src/mlpack/bindings/python/print_pyx.hpp index 789fba2446..a9ffa5da05 100644 --- a/src/mlpack/bindings/python/print_pyx.hpp +++ b/src/mlpack/bindings/python/print_pyx.hpp @@ -27,7 +27,8 @@ namespace python { * "/path/to/pca_main.cpp"). * @param functionName Name of the function (i.e. "pca"). */ -void PrintPYX(const std::string& mainFilename, +void PrintPYX(const util::BindingDetails& doc, + const std::string& mainFilename, const std::string& functionName); diff --git a/src/mlpack/core/util/CMakeLists.txt b/src/mlpack/core/util/CMakeLists.txt index 17a565ef87..19ddff3293 100644 --- a/src/mlpack/core/util/CMakeLists.txt +++ b/src/mlpack/core/util/CMakeLists.txt @@ -6,6 +6,7 @@ set(SOURCES arma_config_check.hpp backtrace.hpp backtrace.cpp + binding_details.hpp io.hpp io.cpp io_impl.hpp diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp new file mode 100644 index 0000000000..23ca2f2ce6 --- /dev/null +++ b/src/mlpack/core/util/binding_details.hpp @@ -0,0 +1,44 @@ +/** + * @file core/util/binding_detais.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 +#include "program_doc.hpp" + +namespace mlpack { +namespace util { + +/** + * This structure holds all of the information about bindings documentation. + */ +struct BindingDetails +{ + //! Name of the default module. + util::ProgramName* programName; + //! A short two-sentence description of the program, what it does, and what + //! it is useful for. + util::ShortDescription* shortDescription; + //! Long string containing documentation on what it is. No newline characters + //! are necessary; this is taken care of by IO later. + util::LongDescription* longDescription; + //! Documentation on how to use the program. + std::vector example; + //! A set of pairs of strings with useful "see also" information; each pair + //! is . + std::vector seeAlso; +}; + +} // namespace util +} // namespace mlpack + +#endif diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index 32e3d48b7a..331ec6a290 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -17,43 +17,17 @@ using namespace mlpack; using namespace mlpack::util; -// Fake ProgramName in case none is supplied. -static ProgramName emptyProgramName = ProgramName(""); - -// Fake ShortDescription in case none is supplied. -static ShortDescription emptyShortDescription = ShortDescription(""); - -// Fake LongDescription in case none is supplied. -static LongDescription emptyLongDescription = LongDescription( - []() { return ""; }); - -// Fake Example in case none is supplied. -static Example emptyExample = Example([]() { return ""; }); - -// Fake SeeAlso in case none is supplied. -static SeeAlso emptySeeAlso = SeeAlso("", ""); - /* Constructors, Destructors, Copy */ /* Make the constructor private, to preclude unauthorized instances */ IO::IO() : - didParse(false), - pname(&emptyProgramName), - shortDesc(&emptyShortDescription), - longDesc(&emptyLongDescription), - examples({}), - seeAlsos({}) + didParse(false) { return; } // Private copy constructor; don't want copies floating around. IO::IO(const IO& /* other */) : - didParse(false), - pname(&emptyProgramName), - shortDesc(&emptyShortDescription), - longDesc(&emptyLongDescription), - examples({}), - seeAlsos({}) + didParse(false) { return; } @@ -178,76 +152,6 @@ IO& IO::GetSingleton() return singleton; } -/** - * Registers a ProgramName object, which contains documentation about the - * program. - * - * @param pname Pointer to the ProgramName object. - */ -void IO::RegisterProgramName(util::ProgramName* pname) -{ - // Only register the pname 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 (pname != &emptyProgramName) - GetSingleton().pname = pname; -} - -/** - * Registers a ShortDescription object, which contains documentation about - * the program. - * - * @param shortDesc Pointer to the ShortDescription object. - */ -void IO::RegisterShortDescription(ShortDescription* shortDesc) -{ - // Only register the shortDesc 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 (shortDesc != &emptyShortDescription) - GetSingleton().shortDesc = shortDesc; -} - -/** - * Registers a LongDescription object, which contains documentation about - * the program. - * - * @param longDesc Pointer to the LongDescription object. - */ -void IO::RegisterLongDescription(LongDescription* longDesc) -{ - // Only register the longDesc 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 (longDesc != &emptyLongDescription) - GetSingleton().longDesc = longDesc; -} - -/** - * Registers a Example object, which contains documentation about the - * program. - * - * @param example Pointer to the Example object. - */ -void IO::RegisterExample(Example* example) -{ - // Only register the example 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 (example != &emptyExample) - GetSingleton().examples.push_back(example); -} - -/** - * Registers a SeeAlso object, which contains documentation about the - * program. - * - * @param seeAlso Pointer to the SeeAlso object. - */ -void IO::RegisterSeeAlso(SeeAlso* seeAlso) -{ - // 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 (seeAlso != &emptySeeAlso) - GetSingleton().seeAlsos.push_back(seeAlso); -} - // Get the parameters that the IO object knows about. std::map& IO::Parameters() { @@ -263,7 +167,7 @@ std::map& IO::Aliases() // Get the program name as set by BINDING_NAME(). std::string IO::ProgramName() { - return GetSingleton().pname->programName; + return GetSingleton().doc.programName->programName; } // Set a particular parameter as passed. diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index 844fb87a6e..21c48fe069 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -23,6 +23,7 @@ #include #include "timers.hpp" +#include "binding_details.hpp" #include "program_doc.hpp" #include "version.hpp" @@ -34,28 +35,10 @@ namespace mlpack { namespace util { -// Externally defined in option.hpp, this class holds information about the -// name of the program being run. -class ProgramName; - -// Externally defined in option.hpp, this class holds information about the -// short description of the program being run. -class ShortDescription; - -// Externally defined in option.hpp, this class holds information about the -// long description of the program being run. -class LongDescription; - -// Externally defined in option.hpp, this class holds information about the -// examples of the program being run. -class Example; - -// Externally defined in option.hpp, this class holds information about see -// also of the program being run. -class SeeAlso; - -} // namespace util +// This class holds information about the program being run. +struct BindingDetials; +} /** * @brief Parses the command line for parameters and holds user-specified * parameters. @@ -270,53 +253,6 @@ class IO */ static IO& GetSingleton(); - /** - * Registers a ProgramName object, which contains documentation about the - * program. If this method has been called before (that is, if two - * ProgramNames are instantiated in the program), a fatal error will occur. - * - * @param pname Pointer to the ProgramName object. - */ - static void RegisterProgramName(util::ProgramName* pname); - - /** - * Registers a ShortDescription object, which contains documentation about the - * program. If this method has been called before (that is, if two - * ShortDescriptions are instantiated in the program), a fatal error will - * occur. - * - * @param shortDesc Pointer to the ShortDescription object. - */ - static void RegisterShortDescription(util::ShortDescription* shortDesc); - - /** - * Registers a LongDescription object, which contains documentation about the - * program. If this method has been called before (that is, if two - * LongDescriptions are instantiated in the program), a fatal error will - * occur. - * - * @param longDesc Pointer to the LongDescription object. - */ - static void RegisterLongDescription(util::LongDescription* longDesc); - - /** - * Registers a Example object, which contains documentation about the - * program. If this method has been called before (that is, if two - * Examples are instantiated in the program), a fatal error will occur. - * - * @param examples Pointer to the Example object. - */ - static void RegisterExample(util::Example* examples); - - /** - * Registers a SeeAlso object, which contains documentation about the - * program. If this method has been called before (that is, if two - * SeeAlsos are instantiated in the program), a fatal error will occur. - * - * @param seeAlsos Pointer to the SeeAlso object. - */ - static void RegisterSeeAlso(util::SeeAlso* seeAlsos); - //! Return a modifiable list of parameters that IO knows about. static std::map& Parameters(); //! Return a modifiable list of aliases that IO knows about. @@ -390,20 +326,8 @@ class IO //! So that Timer::Start() and Timer::Stop() can access the timer variable. friend class Timer; - //! Pointer to the ProgramName object. - util::ProgramName* pname; - - //! Pointer to the ShortDescription object. - util::ShortDescription* shortDesc; - - //! Pointer to the LongDescription object. - util::LongDescription* longDesc; - - //! Pointer to the Example object. - std::vector examples; - - //! Pointer to the SeeAlso object. - std::vector seeAlsos; + //! Holds the bindingDetails objects. + util::BindingDetails doc; private: /** * Make the constructor private, to preclude unauthorized instances. diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 0ff5bf34a1..1c0ef6f5e8 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -31,7 +31,7 @@ ProgramName::ProgramName( programName(std::move(programName)) { // Register this with IO. - IO::RegisterProgramName(this); + IO::GetSingleton().doc.programName = this; } /** @@ -39,7 +39,7 @@ ProgramName::ProgramName( */ ProgramName::ProgramName() { - IO::RegisterProgramName(this); + IO::GetSingleton().doc.programName = this; } /** @@ -55,7 +55,7 @@ ShortDescription::ShortDescription( shortDescription(std::move(shortDescription)) { // Register this with IO. - IO::RegisterShortDescription(this); + IO::GetSingleton().doc.shortDescription = this; } /** @@ -63,7 +63,7 @@ ShortDescription::ShortDescription( */ ShortDescription::ShortDescription() { - IO::RegisterShortDescription(this); + IO::GetSingleton().doc.shortDescription = this; } /** @@ -79,7 +79,7 @@ LongDescription::LongDescription( longDescription(std::move(longDescription)) { // Register this with IO. - IO::RegisterLongDescription(this); + IO::GetSingleton().doc.longDescription = this; } /** @@ -87,7 +87,7 @@ LongDescription::LongDescription( */ LongDescription::LongDescription() { - IO::RegisterLongDescription(this); + IO::GetSingleton().doc.longDescription = this; } /** @@ -101,7 +101,7 @@ Example::Example( example(std::move(example)) { // Register this with IO. - IO::RegisterExample(this); + IO::GetSingleton().doc.example.push_back(this); } /** @@ -109,7 +109,7 @@ Example::Example( */ Example::Example() { - IO::RegisterExample(this); + IO::GetSingleton().doc.example.push_back(this); } /** @@ -121,11 +121,10 @@ Example::Example() */ SeeAlso::SeeAlso( const std::string& description, const std::string& link) : - description(std::move(description)), - link(std::move(link)) + seeAlso(std::move(make_pair(description, link))) { // Register this with IO. - IO::RegisterSeeAlso(this); + IO::GetSingleton().doc.seeAlso.push_back(this); } /** @@ -133,5 +132,5 @@ SeeAlso::SeeAlso( */ SeeAlso::SeeAlso() { - IO::RegisterSeeAlso(this); + IO::GetSingleton().doc.seeAlso.push_back(this); } diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index 90b8e8c38d..f9ae1be3d7 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -119,8 +119,7 @@ class SeeAlso * Construct an empty SeeAlso object. (This is not meant to be used!) */ SeeAlso(); - std::string description; - std::string link; + std::pair seeAlso; }; } // namespace util } // namespace mlpack From a60f75a42515d83992a46becc0fef7f62494ffbf Mon Sep 17 00:00:00 2001 From: Yashwant Date: Wed, 12 Aug 2020 13:26:40 +0530 Subject: [PATCH 14/25] Collect of macros into a single 'struct'. --- doc/guide/bindings.hpp | 4 +- src/mlpack/bindings/cli/print_help.cpp | 13 ++- src/mlpack/bindings/go/print_go.cpp | 9 +- src/mlpack/bindings/julia/print_jl.cpp | 6 +- src/mlpack/bindings/markdown/binding_info.cpp | 95 +------------------ src/mlpack/bindings/markdown/binding_info.hpp | 63 ++---------- src/mlpack/bindings/markdown/print_docs.cpp | 51 ++++------ .../bindings/markdown/program_doc_wrapper.hpp | 20 ++-- src/mlpack/bindings/python/print_pyx.cpp | 12 +-- src/mlpack/core/util/binding_details.hpp | 10 +- src/mlpack/core/util/io.cpp | 2 +- src/mlpack/core/util/program_doc.cpp | 67 ++----------- src/mlpack/core/util/program_doc.hpp | 37 -------- 13 files changed, 81 insertions(+), 308 deletions(-) diff --git a/doc/guide/bindings.hpp b/doc/guide/bindings.hpp index 6cd33bd9a8..2ef5db763b 100644 --- a/doc/guide/bindings.hpp +++ b/doc/guide/bindings.hpp @@ -472,8 +472,8 @@ Go binding output (snippet): @code Input C++ (full program, 'random_numbers_main.cpp'): -// Program Name. -BINDING_NAME("Random Numbers"); + // Program Name. + BINDING_NAME("Random Numbers"); // Short description. BINDING_SHORT_DESC("An implementation of Random Numbers"); diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index 6f2d4ae961..ee7eebec4a 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -63,16 +63,15 @@ void PrintHelp(const std::string& param) } // Print out the descriptions. - if (bindingDetails.programName->programName != "") + if (bindingDetails.programName != "") { - std::cout << bindingDetails.programName->programName - << std::endl << std::endl; - std::cout << " " << util::HyphenateString(bindingDetails.longDescription-> - longDescription(), 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]-> - example(), 2) << std::endl << std::endl; + std::cout << " " << util::HyphenateString(bindingDetails.example[j](), 2) + << std::endl << std::endl; } } else diff --git a/src/mlpack/bindings/go/print_go.cpp b/src/mlpack/bindings/go/print_go.cpp index 39796b8982..660e3d7aaa 100644 --- a/src/mlpack/bindings/go/print_go.cpp +++ b/src/mlpack/bindings/go/print_go.cpp @@ -33,7 +33,7 @@ void PrintGo(const util::BindingDetails& doc, const std::string& functionName) { // Restore parameters. - IO::RestoreSettings(doc.programName->programName); + IO::RestoreSettings(doc.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -123,11 +123,10 @@ void PrintGo(const util::BindingDetails& doc, // Print the comment describing the function and its parameters. cout << "/*" << endl; - cout << " " << HyphenateString(doc.longDescription->longDescription(), 2) - << endl << endl; + cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl; for (size_t j = 0; j < doc.example.size(); ++j) { - cout << " " << util::HyphenateString(doc.example[j]->example(), 2) + cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl; } cout << " Input parameters:" << endl; @@ -220,7 +219,7 @@ void PrintGo(const util::BindingDetails& doc, cout << " " << "disableVerbose()" << endl; // Restore the parameters. - cout << " " << "restoreSettings(\"" << doc.programName->programName + cout << " " << "restoreSettings(\"" << doc.programName << "\")" << endl; cout << endl; diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index c7ac7d985e..5637ed034a 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -32,7 +32,7 @@ void PrintJL(const util::BindingDetails& doc, const std::string& mlpackJuliaLibSuffix) { // Restore parameters. - IO::RestoreSettings(doc.programName->programName); + IO::RestoreSettings(doc.programName); map& parameters = IO::Parameters(); typedef map::iterator ParamIter; @@ -168,11 +168,11 @@ void PrintJL(const util::BindingDetails& doc, cout << endl; // Next print the description. - cout << HyphenateString(doc.longDescription->longDescription(), 0) + cout << HyphenateString(doc.longDescription(), 0) << endl << endl; for (size_t j = 0; j < doc.example.size(); ++j) { - cout << util::HyphenateString(doc.example[j]->example(), 0) << endl << endl; + cout << util::HyphenateString(doc.example[j](), 0) << endl << endl; } // Next, print information on the input options. cout << endl; diff --git a/src/mlpack/bindings/markdown/binding_info.cpp b/src/mlpack/bindings/markdown/binding_info.cpp index d23505f96e..eed8e2098a 100644 --- a/src/mlpack/bindings/markdown/binding_info.cpp +++ b/src/mlpack/bindings/markdown/binding_info.cpp @@ -17,101 +17,16 @@ namespace mlpack { namespace bindings { namespace markdown { -util::ProgramName& BindingInfo::GetProgramName(const std::string& bindingName) -{ - if (GetSingleton().mapProgramName.count(bindingName) == 0) - { - throw std::invalid_argument("No program name associated with'" + bindingName - + "'!"); - } - - return GetSingleton().mapProgramName.at(bindingName); -} - -util::ShortDescription& BindingInfo::GetShortDescription( +util::BindingDetails& BindingInfo::GetBindingDetails( const std::string& bindingName) { - if (GetSingleton().mapShortDescription.count(bindingName) == 0) + if (GetSingleton().map.count(bindingName) == 0) { - throw std::invalid_argument("No short description associated with'" - + bindingName + "'!"); + throw std::invalid_argument("Binding name '" + bindingName + + "' not known!"); } - return GetSingleton().mapShortDescription.at(bindingName); -} - -util::LongDescription& BindingInfo::GetLongDescription( - const std::string& bindingName) -{ - if (GetSingleton().mapLongDescription.count(bindingName) == 0) - { - throw std::invalid_argument("No long description associated with'" - + bindingName + "'!"); - } - - return GetSingleton().mapLongDescription.at(bindingName); -} - -std::vector& BindingInfo::GetExample(const std::string& - bindingName) -{ - // Some bindings may not have examples. - if (GetSingleton().mapExample.count(bindingName) == 0) - { - static std::vector empty; - return empty; - } - - return GetSingleton().mapExample.at(bindingName); -} - -std::vector& BindingInfo::GetSeeAlso(const std::string& - bindingName) -{ - if (GetSingleton().mapSeeAlso.count(bindingName) == 0) - { - throw std::invalid_argument("No see also associated with'" + bindingName - + "'!"); - } - - return GetSingleton().mapSeeAlso.at(bindingName); -} - -//! Register a ProgramName object with the given bindingName. -void BindingInfo::RegisterProgramName(const std::string& bindingName, - const util::ProgramName& programName) -{ - GetSingleton().mapProgramName[bindingName] = programName; -} - -//! Register a ShortDescription object with the given bindingName. -void BindingInfo::RegisterShortDescription(const std::string& bindingName, - const util::ShortDescription& - shortDescription) -{ - GetSingleton().mapShortDescription[bindingName] = shortDescription; -} - -//! Register a LongDescription object with the given bindingName. -void BindingInfo::RegisterLongDescription(const std::string& bindingName, - const util::LongDescription& - longDescription) -{ - GetSingleton().mapLongDescription[bindingName] = longDescription; -} - -//! Register a Example object with the given bindingName. -void BindingInfo::RegisterExample(const std::string& bindingName, - const util::Example& example) -{ - GetSingleton().mapExample[bindingName].push_back(example); -} - -//! Register a SeeAlso object with the given bindingName. -void BindingInfo::RegisterSeeAlso(const std::string& bindingName, - const util::SeeAlso& seeAlso) -{ - GetSingleton().mapSeeAlso[bindingName].push_back(seeAlso); + return GetSingleton().map.at(bindingName); } //! Get or modify the current language (don't set it to something invalid!). diff --git a/src/mlpack/bindings/markdown/binding_info.hpp b/src/mlpack/bindings/markdown/binding_info.hpp index b076d7d8bb..319bb0bcac 100644 --- a/src/mlpack/bindings/markdown/binding_info.hpp +++ b/src/mlpack/bindings/markdown/binding_info.hpp @@ -16,7 +16,7 @@ #define MLPACK_BINDINGS_MARKDOWN_BINDING_NAME_HPP #include -#include +#include namespace mlpack { namespace bindings { @@ -30,69 +30,22 @@ namespace markdown { class BindingInfo { public: - //! Return a ProgramName object for a given bindingName. - static util::ProgramName& GetProgramName(const std::string& bindingName); - - //! Return a ShortDescription object for a given bindingName. - static util::ShortDescription& GetShortDescription( + //! Return a BindingDetails object for a given bindingName. + static util::BindingDetails& GetBindingDetails( const std::string& bindingName); - //! Return a LongDescription object for a given bindingName. - static util::LongDescription& GetLongDescription( - const std::string& bindingName); - - //! Return a Example object for a given bindingName. - static std::vector& GetExample(const std::string& bindingName); - - //! Return a SeeAlso object for a given bindingName. - static std::vector& GetSeeAlso(const std::string& bindingName); - - //! Register a ProgramName object with the given bindingName. - static void RegisterProgramName(const std::string& bindingName, - const util::ProgramName& programName); - - //! Register a ShortDescription object with the given bindingName. - static void RegisterShortDescription(const std::string& bindingName, - const util::ShortDescription& - shortDescription); - - //! Register a LongDescription object with the given bindingName. - static void RegisterLongDescription(const std::string& bindingName, - const util::LongDescription& - longDescription); - - //! Register a Example object with the given bindingName. - static void RegisterExample(const std::string& bindingName, - const util::Example& example); - - //! Register a SeeAlso object with the given bindingName. - static void RegisterSeeAlso(const std::string& bindingName, - const util::SeeAlso& seeAlso); - //! 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 ProgramName name. - std::unordered_map mapProgramName; + //! Internally-held map for mapping a binding name to a BindingDetails. + std::unordered_map map; - //! Internally-held map for mapping a binding name to a ShortDescription name. - std::unordered_map mapShortDescription; - - //! Internally-held map for mapping a binding name to a LongDescription name. - std::unordered_map mapLongDescription; - - //! Internally-held map for mapping a binding name to a Example name. - std::unordered_map> mapExample; - - //! Internally-held map for mapping a binding name to a SeeAlso name. - std::unordered_map> mapSeeAlso; + 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 diff --git a/src/mlpack/bindings/markdown/print_docs.cpp b/src/mlpack/bindings/markdown/print_docs.cpp index 8762f41b7b..3083c0ec7f 100644 --- a/src/mlpack/bindings/markdown/print_docs.cpp +++ b/src/mlpack/bindings/markdown/print_docs.cpp @@ -12,7 +12,7 @@ #include "print_docs.hpp" #include -#include +#include #include "binding_info.hpp" #include "print_doc_functions.hpp" @@ -45,13 +45,7 @@ void PrintHeaders(const std::string& bindingName, void PrintDocs(const std::string& bindingName, const vector& languages) { - ProgramName& programName = BindingInfo::GetProgramName(bindingName); - ShortDescription& shortDescription = - BindingInfo::GetShortDescription(bindingName); - LongDescription& longDescription = - BindingInfo::GetLongDescription(bindingName); - std::vector& examples = BindingInfo::GetExample(bindingName); - std::vector& seeAlsos = BindingInfo::GetSeeAlso(bindingName); + BindingDetails& programDoc = BindingInfo::GetBindingDetails(bindingName); IO::RestoreSettings(bindingName); @@ -69,8 +63,8 @@ void PrintDocs(const std::string& bindingName, cout << endl; // Next, print the logical name of the binding (that's known by - // BINDING_NAME()). - cout << "#### " << programName.programName << endl; + // ProgramInfo). + cout << "#### " << programDoc.programName << endl; cout << endl; for (size_t i = 0; i < languages.size(); ++i) @@ -84,7 +78,7 @@ void PrintDocs(const std::string& bindingName, } cout << endl; - cout << shortDescription.shortDescription << " "; + cout << programDoc.shortDescription << " "; for (size_t i = 0; i < languages.size(); ++i) { cout << "[Detailed documentation](#" << languages[i] << "_" @@ -93,7 +87,7 @@ void PrintDocs(const std::string& bindingName, } cout << "." << endl; - // Next, print the documentation for each language. + // Next, print the PROGRAM_INFO() documentation for each language. for (size_t i = 0; i < languages.size(); ++i) { BindingInfo::Language() = languages[i]; @@ -219,44 +213,41 @@ void PrintDocs(const std::string& bindingName, cout << "{: #" << languages[i] << "_" << bindingName << "_detailed-documentation }" << endl; cout << endl; - string desc = boost::replace_all_copy(longDescription.longDescription(), - "|", "\\|"); - cout << desc << endl; - for (size_t j = 0; j < examples.size(); ++j) + string doc = boost::replace_all_copy(programDoc.longDescription(), "|", "\\|"); + cout << doc << endl; + cout << endl; + for (size_t j = 0; j < programDoc.example.size(); ++j) { - util::Example& example = examples[j]; - string eg = boost::replace_all_copy(example.example(), "|", "\\|"); + string eg = boost::replace_all_copy(programDoc.example[j](), + "|", "\\|"); cout << eg << endl; } - cout << endl; - cout << "### See also" << endl; cout << endl; - for (size_t j = 0; j < seeAlsos.size(); ++j) + for (size_t j = 0; j < programDoc.seeAlso.size(); ++j) { - util::SeeAlso& seeAlso = seeAlsos[j]; cout << " - " << "["; // We need special processing if the user has specified a binding name // starting with @ (i.e., '@kfn' or similar). - if (seeAlso.description[0] == '@') - cout << GetBindingName(seeAlso.description.substr(1)); + if (programDoc.seeAlso[j].first[0] == '@') + cout << GetBindingName(programDoc.seeAlso[j].first.substr(1)); else - cout << seeAlso.description; + cout << programDoc.seeAlso[j].first; cout << "]("; // We need special handling of Doxygen information. - if (seeAlso.link.substr(0, 8) == "@doxygen") + if (programDoc.seeAlso[j].second.substr(0, 8) == "@doxygen") { - cout << DOXYGEN_PREFIX << seeAlso.link.substr(9); + cout << DOXYGEN_PREFIX << programDoc.seeAlso[j].second.substr(9); } - else if (seeAlso.link[0] == '#') + else if (programDoc.seeAlso[j].second[0] == '#') { cout << "#" << languages[i] << "_" - << seeAlso.link.substr(1); + << programDoc.seeAlso[j].second.substr(1); } else { - cout << seeAlso.link; + cout << programDoc.seeAlso[j].second; } cout << ")" << endl; diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index 57637a4b12..4703136d89 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -32,8 +32,8 @@ class ProgramNameWrapper ProgramNameWrapper(const std::string& bindingName, const std::string& programName) { - util::ProgramName pd(programName); - BindingInfo::RegisterProgramName(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].programName = + std::move(programName); } }; @@ -47,8 +47,8 @@ class ShortDescriptionWrapper ShortDescriptionWrapper(const std::string& bindingName, const std::string& shortDescription) { - util::ShortDescription pd(shortDescription); - BindingInfo::RegisterShortDescription(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].shortDescription = + std::move(shortDescription); } }; @@ -62,8 +62,8 @@ class LongDescriptionWrapper LongDescriptionWrapper(const std::string& bindingName, const std::function& longDescription) { - util::LongDescription pd(longDescription); - BindingInfo::RegisterLongDescription(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].longDescription = + std::move(longDescription); } }; @@ -77,8 +77,8 @@ class ExampleWrapper ExampleWrapper(const std::string& bindingName, const std::function& example) { - util::Example pd(example); - BindingInfo::RegisterExample(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].example.push_back( + std::move(example)); } }; @@ -92,8 +92,8 @@ class SeeAlsoWrapper SeeAlsoWrapper(const std::string& bindingName, const std::string& description, const std::string& link) { - util::SeeAlso pd(description, link); - BindingInfo::RegisterSeeAlso(bindingName, pd); + BindingInfo::GetSingleton().map[bindingName].seeAlso.push_back( + std::move(std::make_pair(description, link))); } }; diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 62638925ff..ebe7ab1aa2 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -36,7 +36,7 @@ void PrintPYX(const util::BindingDetails& doc, const string& functionName) { // Restore parameters. - IO::RestoreSettings(doc.programName->programName); + IO::RestoreSettings(doc.programName); std::map& parameters = IO::Parameters(); typedef std::map::iterator ParamIter; @@ -142,13 +142,13 @@ void PrintPYX(const util::BindingDetails& doc, // Print the comment describing the function and its parameters. cout << " \"\"\"" << endl; - cout << " " << doc.programName->programName << endl; + cout << " " << doc.programName << endl; cout << endl; - cout << " " << HyphenateString(longDesc.longDescription(), 2) << endl; + cout << " " << HyphenateString(doc.longDescription(), 2) << endl; cout << endl; - for (size_t j = 0; j < IO::GetSingleton().examples.size(); ++j) + for (size_t j = 0; j < doc.example.size(); ++j) { - cout << " " << util::HyphenateString(doc.example[j]->example(), 2) << endl + cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl; } cout << " Input parameters:" << endl; @@ -188,7 +188,7 @@ void PrintPYX(const util::BindingDetails& doc, cout << " DisableVerbose()" << endl; // Restore the parameters. - cout << " IO.RestoreSettings(\"" << doc.programName->programName << "\")" + cout << " IO.RestoreSettings(\"" << doc.programName << "\")" << endl; // Determine whether or not we need to copy parameters. diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index 23ca2f2ce6..9d058bd477 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -24,18 +24,18 @@ namespace util { struct BindingDetails { //! Name of the default module. - util::ProgramName* programName; + std::string programName; //! A short two-sentence description of the program, what it does, and what //! it is useful for. - util::ShortDescription* shortDescription; + std::string shortDescription; //! Long string containing documentation on what it is. No newline characters //! are necessary; this is taken care of by IO later. - util::LongDescription* longDescription; + std::function longDescription; //! Documentation on how to use the program. - std::vector example; + std::vector> example; //! A set of pairs of strings with useful "see also" information; each pair //! is . - std::vector seeAlso; + std::vector> seeAlso; }; } // namespace util diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index 331ec6a290..3460270e1c 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -167,7 +167,7 @@ std::map& IO::Aliases() // Get the program name as set by BINDING_NAME(). std::string IO::ProgramName() { - return GetSingleton().doc.programName->programName; + return GetSingleton().doc.programName; } // Set a particular parameter as passed. diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 1697cef702..08601ab6b3 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -26,20 +26,10 @@ using namespace std; * * @param defaultModule Name of the default module. */ -ProgramName::ProgramName( - const std::string& programName) : - programName(std::move(programName)) +ProgramName::ProgramName(const std::string& programName) { // Register this with IO. - IO::GetSingleton().doc.programName = this; -} - -/** - * Construct an empty ProgramName object. - */ -ProgramName::ProgramName() -{ - IO::GetSingleton().doc.programName = this; + IO::GetSingleton().doc.programName = std::move(programName); } /** @@ -50,20 +40,10 @@ ProgramName::ProgramName() * @param shortDescription A short two-sentence description of the program, * what it does, and what it is useful for. */ -ShortDescription::ShortDescription( - const std::string& shortDescription) : - shortDescription(std::move(shortDescription)) +ShortDescription::ShortDescription(const std::string& shortDescription) { // Register this with IO. - IO::GetSingleton().doc.shortDescription = this; -} - -/** - * Construct an empty ShortDescription object. - */ -ShortDescription::ShortDescription() -{ - IO::GetSingleton().doc.shortDescription = this; + IO::GetSingleton().doc.shortDescription = std::move(shortDescription); } /** @@ -75,19 +55,10 @@ ShortDescription::ShortDescription() * taken care of by IO later. */ LongDescription::LongDescription( - const std::function& longDescription) : - longDescription(std::move(longDescription)) + const std::function& longDescription) { // Register this with IO. - IO::GetSingleton().doc.longDescription = this; -} - -/** - * Construct an empty LongDescription object. - */ -LongDescription::LongDescription() -{ - IO::GetSingleton().doc.longDescription = this; + IO::GetSingleton().doc.longDescription = std::move(longDescription); } /** @@ -97,19 +68,10 @@ LongDescription::LongDescription() * @param example Documentation on how to use the program. */ Example::Example( - const std::function& example) : - example(std::move(example)) + const std::function& example) { // Register this with IO. - IO::GetSingleton().doc.example.push_back(this); -} - -/** - * Construct an empty Example object. - */ -Example::Example() -{ - IO::GetSingleton().doc.example.push_back(this); + IO::GetSingleton().doc.example.push_back(std::move(example)); } /** @@ -120,17 +82,8 @@ Example::Example() * information; each pair is . */ SeeAlso::SeeAlso( - const std::string& description, const std::string& link) : - seeAlso(std::move(make_pair(description, link))) + const std::string& description, const std::string& link) { // Register this with IO. - IO::GetSingleton().doc.seeAlso.push_back(this); -} - -/** - * Construct an empty SeeAlso object. - */ -SeeAlso::SeeAlso() -{ - IO::GetSingleton().doc.seeAlso.push_back(this); + IO::GetSingleton().doc.seeAlso.push_back(std::move(make_pair(description, link))); } diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index 75dc5d6e7f..c30ad39a41 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -36,13 +36,6 @@ class ProgramName * @param programName Name of the default module. */ ProgramName(const std::string& programName); - - /** - * Construct an empty ProgramName object. (This is not meant to be used!) - */ - ProgramName(); - - std::string programName; }; class ShortDescription @@ -57,14 +50,6 @@ class ShortDescription * what it does, and what it is useful for. */ ShortDescription(const std::string& shortDescription); - - /** - * Construct an empty ShortDescription object. - * (This is not meant to be used!) - */ - ShortDescription(); - - std::string shortDescription; }; class LongDescription @@ -79,13 +64,6 @@ class LongDescription * taken care of by IO later. */ LongDescription(const std::function& longDescription); - - /** - * Construct an empty LongDescription object. (This is not meant to be used!) - */ - LongDescription(); - - std::function longDescription; }; class Example @@ -98,13 +76,6 @@ class Example * @param example Documentation on how to use the program. */ Example(const std::function& example); - - /** - * Construct an empty Example object. (This is not meant to be used!) - */ - Example(); - - std::function example; }; class SeeAlso @@ -118,14 +89,6 @@ class SeeAlso * @param link Link of SeeAlso. */ SeeAlso(const std::string& description, const std::string& link); - - /** - * Construct an empty SeeAlso object. (This is not meant to be used!) - */ - SeeAlso(); - - std::string description; - std::string link; }; } // namespace util From d8eeb1988b676b1e935bfb4ac62c3d4b32953d0d Mon Sep 17 00:00:00 2001 From: Yashwant Date: Wed, 12 Aug 2020 13:57:01 +0530 Subject: [PATCH 15/25] Resolve some comments. --- src/mlpack/bindings/go/print_go.cpp | 11 ++++-- src/mlpack/bindings/go/print_go.hpp | 2 +- src/mlpack/bindings/julia/print_jl.cpp | 7 ++-- src/mlpack/bindings/markdown/print_docs.cpp | 41 +++++++++++---------- src/mlpack/bindings/python/print_pyx.cpp | 14 ++++--- src/mlpack/bindings/python/print_pyx.hpp | 1 + src/mlpack/core/util/binding_details.hpp | 2 +- src/mlpack/core/util/io.hpp | 18 ++++----- src/mlpack/core/util/param.hpp | 24 ++++++------ 9 files changed, 64 insertions(+), 56 deletions(-) diff --git a/src/mlpack/bindings/go/print_go.cpp b/src/mlpack/bindings/go/print_go.cpp index 660e3d7aaa..e2c0c9ee27 100644 --- a/src/mlpack/bindings/go/print_go.cpp +++ b/src/mlpack/bindings/go/print_go.cpp @@ -27,6 +27,7 @@ namespace go { * Given a list of parameter definition and program documentation, print a * generated .go file to stdout. * + * @param doc Documentation for the program. * @param functionName Name of the function (i.e. "pca"). */ void PrintGo(const util::BindingDetails& doc, @@ -124,11 +125,14 @@ void PrintGo(const util::BindingDetails& doc, // Print the comment describing the function and its parameters. cout << "/*" << 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; + 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) @@ -219,8 +223,7 @@ void PrintGo(const util::BindingDetails& doc, cout << " " << "disableVerbose()" << endl; // Restore the parameters. - cout << " " << "restoreSettings(\"" << doc.programName - << "\")" << endl; + cout << " " << "restoreSettings(\"" << doc.programName << "\")" << endl; cout << endl; // Do any input processing. diff --git a/src/mlpack/bindings/go/print_go.hpp b/src/mlpack/bindings/go/print_go.hpp index 53a3280e8f..d2ce7161de 100644 --- a/src/mlpack/bindings/go/print_go.hpp +++ b/src/mlpack/bindings/go/print_go.hpp @@ -22,7 +22,7 @@ namespace go { /** * Given a list of parameter definition and program documentation, print a * generated .go file to stdout. - * + * @param doc Documentation for the program. * @param functionName Name of the function (i.e. "pca"). */ void PrintGo(const util::BindingDetails& doc, diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index 5637ed034a..ccaf3dc2e5 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -168,14 +168,15 @@ void PrintJL(const util::BindingDetails& doc, cout << endl; // Next print the description. - cout << HyphenateString(doc.longDescription(), 0) - << endl << 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; diff --git a/src/mlpack/bindings/markdown/print_docs.cpp b/src/mlpack/bindings/markdown/print_docs.cpp index 3083c0ec7f..5d8a55e140 100644 --- a/src/mlpack/bindings/markdown/print_docs.cpp +++ b/src/mlpack/bindings/markdown/print_docs.cpp @@ -45,7 +45,7 @@ void PrintHeaders(const std::string& bindingName, void PrintDocs(const std::string& bindingName, const vector& languages) { - BindingDetails& programDoc = BindingInfo::GetBindingDetails(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.shortDescription << " "; + cout << doc.shortDescription << " "; for (size_t i = 0; i < languages.size(); ++i) { cout << "[Detailed documentation](#" << languages[i] << "_" @@ -213,41 +213,44 @@ void PrintDocs(const std::string& bindingName, cout << "{: #" << languages[i] << "_" << bindingName << "_detailed-documentation }" << endl; cout << endl; - string doc = boost::replace_all_copy(programDoc.longDescription(), "|", "\\|"); - cout << doc << endl; - cout << endl; - for (size_t j = 0; j < programDoc.example.size(); ++j) - { - string eg = boost::replace_all_copy(programDoc.example[j](), + string desc = boost::replace_all_copy(doc.longDescription(), "|", "\\|"); - cout << eg << endl; + 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; diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index ebe7ab1aa2..2e07447f84 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -26,7 +26,7 @@ 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 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"). @@ -144,13 +144,17 @@ void PrintPYX(const util::BindingDetails& doc, cout << " \"\"\"" << endl; cout << " " << doc.programName << endl; cout << endl; - cout << " " << HyphenateString(doc.longDescription(), 2) << endl; - cout << 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; + 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) diff --git a/src/mlpack/bindings/python/print_pyx.hpp b/src/mlpack/bindings/python/print_pyx.hpp index a9ffa5da05..999fd3153b 100644 --- a/src/mlpack/bindings/python/print_pyx.hpp +++ b/src/mlpack/bindings/python/print_pyx.hpp @@ -23,6 +23,7 @@ namespace python { * Given a list of parameter definition and program documentation, print a * generated .pyx file to stdout. * + * @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"). diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index 9d058bd477..51c8586e99 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -1,5 +1,5 @@ /** - * @file core/util/binding_detais.hpp + * @file core/util/binding_details.hpp * @author Yashwant Singh Parihar * * This defines the structure that holds documentation details for bindings. diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index 21c48fe069..4cc05e1aa0 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -53,7 +53,7 @@ struct BindingDetials; * @section addparam Adding parameters to a program * * @code - * $ ./executable --bar=5 + * $ ./binding --bar=5 * @endcode * * @note The = is optional; a space can also be used. @@ -75,7 +75,7 @@ struct BindingDetials; * 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.", @@ -95,11 +95,7 @@ struct BindingDetials; * More documentation is available on the PARAM_*() macros in the documentation * for core/io/io.hpp. * - * @section bindingpname Documenting the programName. - * @section bindingshortdescription Documenting the shortDescription. - * @section bindinglongdescription Documenting the longDescription. - * @section bindingexample Documenting the example. - * @section bindingseealso Documenting the seeAlso. + * @section programinfo Documenting the program itself * * In addition to allowing documentation for each individual parameter and * module, the BINDING_NAME() macro provides support for documenting the @@ -165,10 +161,10 @@ struct BindingDetials; * * @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 diff --git a/src/mlpack/core/util/param.hpp b/src/mlpack/core/util/param.hpp index 7c39ca0cdd..ab679a2f00 100644 --- a/src/mlpack/core/util/param.hpp +++ b/src/mlpack/core/util/param.hpp @@ -42,9 +42,9 @@ using DatasetInfo = DatasetMapper; /** @endcond */ /** - * 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. + * 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(), @@ -59,9 +59,9 @@ using DatasetInfo = DatasetMapper; io_programname_dummy_object = mlpack::util::ProgramName(NAME); /** - * 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. + * 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(), @@ -79,9 +79,9 @@ using DatasetInfo = DatasetMapper; SHORT_DESC); /** - * Document an executable. Only one instance of this macro should be + * 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 executable) in your program. + * (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(), @@ -101,9 +101,9 @@ using DatasetInfo = DatasetMapper; []() { return std::string(LONG_DESC); }); /** - * Document an executable. Mutiple instance of this macro can be + * 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 executable) in your program. + * (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(), @@ -132,9 +132,9 @@ using DatasetInfo = DatasetMapper; #endif /** - * Document an executable. Mutiple instance of this macro can be + * 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 executable) in your program. + * (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(), From 8935de54ac01097bc137376828843fc3e89c238e Mon Sep 17 00:00:00 2001 From: Yashwant Date: Wed, 12 Aug 2020 14:05:40 +0530 Subject: [PATCH 16/25] Fix some manually checked style issue. --- src/mlpack/bindings/cli/print_help.cpp | 4 ++-- src/mlpack/bindings/julia/print_jl.cpp | 2 +- src/mlpack/bindings/markdown/program_doc_wrapper.hpp | 2 +- src/mlpack/bindings/python/print_pyx.cpp | 2 +- src/mlpack/core/util/binding_details.hpp | 4 ++-- src/mlpack/core/util/program_doc.cpp | 3 ++- 6 files changed, 9 insertions(+), 8 deletions(-) diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index ee7eebec4a..3178030613 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -66,8 +66,8 @@ void PrintHelp(const std::string& param) if (bindingDetails.programName != "") { std::cout << bindingDetails.programName << std::endl << std::endl; - std::cout << " " << util::HyphenateString(bindingDetails.longDescription(), 2) - << 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) diff --git a/src/mlpack/bindings/julia/print_jl.cpp b/src/mlpack/bindings/julia/print_jl.cpp index ccaf3dc2e5..5bf6eb26a9 100644 --- a/src/mlpack/bindings/julia/print_jl.cpp +++ b/src/mlpack/bindings/julia/print_jl.cpp @@ -168,7 +168,7 @@ void PrintJL(const util::BindingDetails& doc, cout << endl; // Next print the description. - cout << HyphenateString(doc.longDescription(), 0) << endl << endl; + cout << HyphenateString(doc.longDescription(), 0) << endl << endl; // Next print the examples. for (size_t j = 0; j < doc.example.size(); ++j) diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index 4703136d89..b8a6a012af 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -32,7 +32,7 @@ class ProgramNameWrapper ProgramNameWrapper(const std::string& bindingName, const std::string& programName) { - BindingInfo::GetSingleton().map[bindingName].programName = + BindingInfo::GetSingleton().map[bindingName].programName = std::move(programName); } }; diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index 2e07447f84..e7be1c837d 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -148,7 +148,7 @@ void PrintPYX(const util::BindingDetails& doc, // print the description. cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl; - // Next print the examples. + // Next print the examples. for (size_t j = 0; j < doc.example.size(); ++j) { cout << " " << util::HyphenateString(doc.example[j](), 2) << endl << endl; diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index 51c8586e99..151e70460e 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -25,7 +25,7 @@ struct BindingDetails { //! Name of the default module. std::string programName; - //! A short two-sentence description of the program, what it does, and what + //! A short two-sentence description of the program, what it does, and what //! it is useful for. std::string shortDescription; //! Long string containing documentation on what it is. No newline characters @@ -35,7 +35,7 @@ struct BindingDetails std::vector> example; //! A set of pairs of strings with useful "see also" information; each pair //! is . - std::vector> seeAlso; + std::vector> seeAlso; }; } // namespace util diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 08601ab6b3..99115a4121 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -85,5 +85,6 @@ 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))); + IO::GetSingleton().doc.seeAlso.push_back(std::move( + make_pair(description, link))); } From ab2d2a2f4ea6e68c8dc32aca9663486c54fa9b7b Mon Sep 17 00:00:00 2001 From: Yashwant Date: Wed, 12 Aug 2020 16:49:07 +0530 Subject: [PATCH 17/25] Fix some ignored documentation. --- .../bindings/markdown/program_doc_wrapper.hpp | 23 +++++++------------ src/mlpack/core/util/io.cpp | 6 ++--- src/mlpack/core/util/io.hpp | 4 ++-- 3 files changed, 12 insertions(+), 21 deletions(-) diff --git a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp index b8a6a012af..9cc333bdd6 100644 --- a/src/mlpack/bindings/markdown/program_doc_wrapper.hpp +++ b/src/mlpack/bindings/markdown/program_doc_wrapper.hpp @@ -2,11 +2,9 @@ * @file bindings/markdown/program_doc_wrapper.hpp * @author Ryan Curtin * - * A simple wrapper around ProgramName, ShortDescription, LongDescription, - * Example and SeeAlso that also respectively calls - * BindingInfo::RegisterProgramName(), BindingInfo::RegisterShortDescription(), - * BindingInfo::RegisterLongDescription(), BindingInfo::RegisterExample() and - * BindingInfo::RegisterSeeAlso() 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 @@ -26,8 +24,7 @@ class ProgramNameWrapper { public: /** - * Construct a ProgramName object and register it with - * BindingInfo::RegisterProgramName(). + * Register programName. */ ProgramNameWrapper(const std::string& bindingName, const std::string& programName) @@ -41,8 +38,7 @@ class ShortDescriptionWrapper { public: /** - * Construct a ShortDescription object and register it with - * BindingInfo::RegisterShortDescription(). + * Register shortDescription. */ ShortDescriptionWrapper(const std::string& bindingName, const std::string& shortDescription) @@ -56,8 +52,7 @@ class LongDescriptionWrapper { public: /** - * Construct a LongDescription object and register it with - * BindingInfo::RegisterLongDescription(). + * Register longDescription. */ LongDescriptionWrapper(const std::string& bindingName, const std::function& longDescription) @@ -71,8 +66,7 @@ class ExampleWrapper { public: /** - * Construct a Example object and register it with - * BindingInfo::RegisterExample(). + * Register example. */ ExampleWrapper(const std::string& bindingName, const std::function& example) @@ -86,8 +80,7 @@ class SeeAlsoWrapper { public: /** - * Construct a SeeAlso object and register it with - * BindingInfo::RegisterSeeAlso(). + * Register seeAlso. */ SeeAlsoWrapper(const std::string& bindingName, const std::string& description, const std::string& link) diff --git a/src/mlpack/core/util/io.cpp b/src/mlpack/core/util/io.cpp index 3460270e1c..12df2a50c6 100644 --- a/src/mlpack/core/util/io.cpp +++ b/src/mlpack/core/util/io.cpp @@ -19,15 +19,13 @@ using namespace mlpack::util; /* Constructors, Destructors, Copy */ /* Make the constructor private, to preclude unauthorized instances */ -IO::IO() : - didParse(false) +IO::IO() : didParse(false) { return; } // Private copy constructor; don't want copies floating around. -IO::IO(const IO& /* other */) : - didParse(false) +IO::IO(const IO& /* other */) : didParse(false) { return; } diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index 4cc05e1aa0..3cf3578ab6 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -38,7 +38,7 @@ namespace util { // This class holds information about the program being run. struct BindingDetials; -} +} // namespace util /** * @brief Parses the command line for parameters and holds user-specified * parameters. @@ -313,7 +313,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 ProgramName(). + //! name (argv[0]) not what is given in BindingDetails. std::string programName; //! Holds the timer objects. From e5c071fd9840917611a8a4ce11fc6f4162d537a0 Mon Sep 17 00:00:00 2001 From: himanshupathak21061998 Date: Thu, 13 Aug 2020 05:24:41 +0530 Subject: [PATCH 18/25] Removing variable --- src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index b2bdc10026..96c5615f75 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -102,9 +102,6 @@ RBM::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(input, spikeMean); SampleSpike(spikeMean, spikeSamples); SlabMean(input, spikeSamples, slabMean); @@ -116,9 +113,9 @@ RBM::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< From 6c31ebe45b446cdeb827283510484e9a13d3695d Mon Sep 17 00:00:00 2001 From: Himanshu Pathak Date: Thu, 13 Aug 2020 22:39:42 +0530 Subject: [PATCH 19/25] Update src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp Co-authored-by: Marcus Edel --- src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp index 96c5615f75..125c828310 100644 --- a/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp +++ b/src/mlpack/methods/ann/rbm/spike_slab_rbm_impl.hpp @@ -115,7 +115,7 @@ RBM::Phase( spikeBiasGrad = spikeMean; // Setting visiblePenaltyGrad. gradient.row(weightGrad.n_elem + spikeBiasGrad.n_elem) = -0.5 * arma::dot( - input, input) / std::pow(input.n_cols, 2); + input, input) / std::pow(input.n_cols, 2); } template< From e38c6b1dbf14dfb5a6a3e1ff85d546cd82b4539f Mon Sep 17 00:00:00 2001 From: Yashwant Singh Parihar Date: Fri, 14 Aug 2020 12:48:26 +0530 Subject: [PATCH 20/25] Apply suggestions from code review Co-authored-by: Ryan Curtin --- src/mlpack/core/util/binding_details.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index 151e70460e..2de4c8b1db 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -23,9 +23,9 @@ namespace util { */ struct BindingDetails { - //! Name of the default module. + //! Name of the binding. std::string programName; - //! A short two-sentence description of the program, what it does, and what + //! 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 From ffa4a7cfc16e3a081966547c7457a9bc12379b45 Mon Sep 17 00:00:00 2001 From: Yashwant Date: Fri, 14 Aug 2020 12:51:39 +0530 Subject: [PATCH 21/25] Resolve some final comments. --- src/mlpack/core/util/binding_details.hpp | 2 +- src/mlpack/core/util/io.hpp | 7 +------ 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index 2de4c8b1db..d4a3721665 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -31,7 +31,7 @@ struct BindingDetails //! Long string containing documentation on what it is. No newline characters //! are necessary; this is taken care of by IO later. std::function longDescription; - //! Documentation on how to use the program. + //! Documentation on how to use the binding. std::vector> example; //! A set of pairs of strings with useful "see also" information; each pair //! is . diff --git a/src/mlpack/core/util/io.hpp b/src/mlpack/core/util/io.hpp index 3cf3578ab6..427142c897 100644 --- a/src/mlpack/core/util/io.hpp +++ b/src/mlpack/core/util/io.hpp @@ -33,12 +33,7 @@ #include namespace mlpack { -namespace util { -// This class holds information about the program being run. -struct BindingDetials; - -} // namespace util /** * @brief Parses the command line for parameters and holds user-specified * parameters. @@ -53,7 +48,7 @@ struct BindingDetials; * @section addparam Adding parameters to a program * * @code - * $ ./binding --bar=5 + * $ ./executable --bar=5 * @endcode * * @note The = is optional; a space can also be used. From 0e15ae4f6b7761d013040709d039564003e5ec8e Mon Sep 17 00:00:00 2001 From: Yashwant Singh Parihar Date: Sun, 16 Aug 2020 10:10:27 +0530 Subject: [PATCH 22/25] Apply suggestions from code review Thanks @zoq for the suggestions. :) Co-authored-by: Marcus Edel --- src/mlpack/bindings/python/print_pyx.cpp | 2 +- src/mlpack/core/util/binding_details.hpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mlpack/bindings/python/print_pyx.cpp b/src/mlpack/bindings/python/print_pyx.cpp index e7be1c837d..87a412346b 100644 --- a/src/mlpack/bindings/python/print_pyx.cpp +++ b/src/mlpack/bindings/python/print_pyx.cpp @@ -145,7 +145,7 @@ void PrintPYX(const util::BindingDetails& doc, cout << " " << doc.programName << endl; cout << endl; - // print the description. + // Print the description. cout << " " << HyphenateString(doc.longDescription(), 2) << endl << endl; // Next print the examples. diff --git a/src/mlpack/core/util/binding_details.hpp b/src/mlpack/core/util/binding_details.hpp index d4a3721665..34fabe6627 100644 --- a/src/mlpack/core/util/binding_details.hpp +++ b/src/mlpack/core/util/binding_details.hpp @@ -33,7 +33,7 @@ struct BindingDetails std::function longDescription; //! Documentation on how to use the binding. std::vector> example; - //! A set of pairs of strings with useful "see also" information; each pair + //! A set of pairs of strings with useful "see also" information; each pair //! is . std::vector> seeAlso; }; From 346bbcf4ee272ad845c88127927317928dda5799 Mon Sep 17 00:00:00 2001 From: Yashwant Date: Sun, 16 Aug 2020 10:28:36 +0530 Subject: [PATCH 23/25] Ressolve some bad comments. --- src/mlpack/bindings/cli/print_help.cpp | 4 ++-- src/mlpack/core/util/program_doc.cpp | 14 +++++++------- src/mlpack/core/util/program_doc.hpp | 23 +++++++---------------- 3 files changed, 16 insertions(+), 25 deletions(-) diff --git a/src/mlpack/bindings/cli/print_help.cpp b/src/mlpack/bindings/cli/print_help.cpp index 3178030613..a1cf44089f 100644 --- a/src/mlpack/bindings/cli/print_help.cpp +++ b/src/mlpack/bindings/cli/print_help.cpp @@ -67,11 +67,11 @@ void PrintHelp(const std::string& param) { std::cout << bindingDetails.programName << std::endl << std::endl; std::cout << " " << util::HyphenateString(bindingDetails.longDescription(), - 2) << std::endl << std::endl; + 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; + << std::endl << std::endl; } } else diff --git a/src/mlpack/core/util/program_doc.cpp b/src/mlpack/core/util/program_doc.cpp index 99115a4121..44f3f8a42b 100644 --- a/src/mlpack/core/util/program_doc.cpp +++ b/src/mlpack/core/util/program_doc.cpp @@ -24,7 +24,7 @@ using namespace std; * 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 programName Name of the binding. */ ProgramName::ProgramName(const std::string& programName) { @@ -37,7 +37,7 @@ ProgramName::ProgramName(const std::string& programName) * itself with IO. A fatal error will be thrown if more than one is * constructed. * - * @param shortDescription A short two-sentence description of the program, + * @param shortDescription A short two-sentence description of the binding, * what it does, and what it is useful for. */ ShortDescription::ShortDescription(const std::string& shortDescription) @@ -63,9 +63,9 @@ LongDescription::LongDescription( /** * Construct a Example object. When constructed, it will register itself - * with IO. A fatal error will be thrown if more than one is constructed. + * with IO. * - * @param example Documentation on how to use the program. + * @param example Documentation on how to use the binding. */ Example::Example( const std::function& example) @@ -76,10 +76,10 @@ Example::Example( /** * Construct a SeeAlso object. When constructed, it will register itself - * with IO. A fatal error will be thrown if more than one is constructed. + * with IO. * - * @param seeAlso A set of pairs of strings with useful "see also" - * information; each pair is . + * @param description Description of SeeAlso. + * @param link Link of SeeAlso. */ SeeAlso::SeeAlso( const std::string& description, const std::string& link) diff --git a/src/mlpack/core/util/program_doc.hpp b/src/mlpack/core/util/program_doc.hpp index c30ad39a41..0d71d93fe5 100644 --- a/src/mlpack/core/util/program_doc.hpp +++ b/src/mlpack/core/util/program_doc.hpp @@ -3,8 +3,8 @@ * @author Yashwant Singh Parihar * @author Matthew Amidon * - * The structure used to store a program's name, documentation, example and - * see also. + * 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 @@ -17,15 +17,6 @@ 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 - * these BINDING_NAME(), BINDING_SHORT_DESC(), BINDING_LONG_DESC(), - * BINDING_EXAMPLE() and BINDING_SEE_ALSO() macros to declare these objects. - * Only correspond object should ever exist. - * - * @see core/util/io.hpp, mlpack::IO - */ class ProgramName { public: @@ -33,7 +24,7 @@ class ProgramName * 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 Name of the default module. + * @param programName Name of the binding. */ ProgramName(const std::string& programName); }; @@ -46,7 +37,7 @@ class ShortDescription * itself with IO. A fatal error will be thrown if more than one is * constructed. * - * @param shortDescription A short two-sentence description of the program, + * @param shortDescription A short two-sentence description of the binding, * what it does, and what it is useful for. */ ShortDescription(const std::string& shortDescription); @@ -71,9 +62,9 @@ class Example public: /** * Construct a Example object. When constructed, it will register itself - * with IO. A fatal error will be thrown if more than one is constructed. + * with IO. * - * @param example Documentation on how to use the program. + * @param example Documentation on how to use the binding. */ Example(const std::function& example); }; @@ -83,7 +74,7 @@ class SeeAlso public: /** * Construct a SeeAlso object. When constructed, it will register itself - * with IO. A fatal error will be thrown if more than one is constructed. + * with IO. * * @param description Description of SeeAlso. * @param link Link of SeeAlso. From 602cdd5df63bee68d9a58bf836c90662b804423a Mon Sep 17 00:00:00 2001 From: nishantkr18 Date: Mon, 17 Aug 2020 13:12:50 +0530 Subject: [PATCH 24/25] Added support for multiple actions in action space for sac --- .../environment/env_type.hpp | 8 ++++++- .../environment/pendulum.hpp | 7 +++++- .../reinforcement_learning/sac_impl.hpp | 23 ++++++++++--------- 3 files changed, 25 insertions(+), 13 deletions(-) diff --git a/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp b/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp index e15093120a..e8513e3bb9 100644 --- a/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp +++ b/src/mlpack/methods/reinforcement_learning/environment/env_type.hpp @@ -163,9 +163,15 @@ class ContinuousActionEnv class Action { public: - double action[1]; + std::vector action; // Storing degree of freedom. static size_t size; + + /** + * Construct an action instance. + */ + Action() : action(ContinuousActionEnv::Action::size) + { /* Nothing to do here */ } }; /** diff --git a/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp b/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp index 843cdf8557..cb810a33bc 100644 --- a/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp +++ b/src/mlpack/methods/reinforcement_learning/environment/pendulum.hpp @@ -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 action; // Storing degree of freedom. static const size_t size = 1; }; diff --git a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp index 5cad9ab285..a12dafb759 100644 --- a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp +++ b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp @@ -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::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(outputAction.n_rows) * 0.1; + arma::colvec noise = arma::randn(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>::from(outputAction); } template < From b6476e8a773a6db7a12edffca5cc8ec34e140b9f Mon Sep 17 00:00:00 2001 From: nishantkr18 Date: Tue, 18 Aug 2020 11:28:53 +0530 Subject: [PATCH 25/25] Added test for multi-action support for sac --- .../reinforcement_learning/sac_impl.hpp | 2 +- src/mlpack/tests/q_learning_test.cpp | 53 ++++++++++++++++++- 2 files changed, 52 insertions(+), 3 deletions(-) diff --git a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp index a12dafb759..7c77a8d0e2 100644 --- a/src/mlpack/methods/reinforcement_learning/sac_impl.hpp +++ b/src/mlpack/methods/reinforcement_learning/sac_impl.hpp @@ -294,7 +294,7 @@ void SAC< noise = arma::clamp(noise, -0.25, 0.25); outputAction = outputAction + noise; } - action.action = arma::conv_to>::from(outputAction); + action.action = arma::conv_to>::from(outputAction); } template < diff --git a/src/mlpack/tests/q_learning_test.cpp b/src/mlpack/tests/q_learning_test.cpp index 33ab7ea8a1..da7767ab3b 100644 --- a/src/mlpack/tests/q_learning_test.cpp +++ b/src/mlpack/tests/q_learning_test.cpp @@ -22,8 +22,9 @@ #include #include #include -#include #include +#include +#include #include #include #include @@ -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 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, 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, 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 replayMethod(32, 10000); + + TrainingConfig config; + config.StepSize() = 0.001; + config.TargetNetworkSyncInterval() = 1; + config.UpdateInterval() = 3; + + // Set up Soft actor-critic agent. + SAC + agent(config, qNetwork, policyNetwork, replayMethod); + + agent.State().Data() = arma::randu + (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();