Parses the command line for parameters and holds user-specified parameters. More...

Static Public Member Functions
static void	AddBindingName (const std::string &bindingName, const std::string &name)
	Add a user-friendly name for a binding. More...

static void	AddExample (const std::string &bindingName, const std::function< std::string()> &example)
	Add an example for a binding. More...

static void	AddFunction (const std::string &type, const std::string &name, void(func)(util::ParamData &, const void , void *))
	Add a function to the function map. More...

static void	AddLongDescription (const std::string &bindingName, const std::function< std::string()> &longDescription)
	Add a long description for a binding. More...

static void	AddParameter (const std::string &bindingName, util::ParamData &&d)
	Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More...

static void	AddSeeAlso (const std::string &bindingName, const std::string &description, const std::string &link)
	Add a SeeAlso for a binding. More...

static void	AddShortDescription (const std::string &bindingName, const std::string &shortDescription)
	Add a short description for a binding. More...

static IO &	GetSingleton ()
	Retrieve the singleton. More...

static util::Timers &	GetTimers ()
	Retrieve the global Timers object. More...

static util::Params	Parameters (const std::string &bindingName)
	Return a new Params object initialized with all the parameters of the binding `bindingName`. More...

Detailed Description

Parses the command line for parameters and holds user-specified parameters.

The IO class is a subsystem by which parameters for machine learning methods can be specified and accessed. In conjunction with the macros PARAM_DOUBLE, PARAM_INT, PARAM_STRING, PARAM_FLAG, and others, this class aims to make user configurability of mlpack methods very easy. There are only three methods in IO that a user should need: IO::ParseCommandLine(), IO::GetParam(), and IO::HasParam() (in addition to the PARAM_*() macros).

Adding parameters to a program

$ ./executable --bar=5

Note: The = is optional; a space can also be used.

A parameter is specified by using one of the following macros (this is not a complete list; see core/io/io.hpp):

PARAM_FLAG(ID, DESC, ALIAS)
PARAM_DOUBLE(ID, DESC, ALIAS, DEF)
PARAM_INT(ID, DESC, ALIAS, DEF)
PARAM_STRING(ID, DESC, ALIAS, DEF)

Parameters

ID	Name of the parameter.
DESC	Short description of the parameter (one/two sentences).
ALIAS	An alias for the parameter.
DEF	Default value of the parameter.

The flag (boolean) type automatically defaults to false; it is specified 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 binding (methods/neighbor_search/knn_main.cpp):

PARAM_STRING_REQ("reference_file", "File containing the reference dataset.",
    "r");
PARAM_STRING_REQ("distances_file", "File to output distances into.", "d");
PARAM_STRING_REQ("neighbors_file", "File to output neighbors into.", "n");
PARAM_INT_REQ("k", "Number of furthest neighbors to find.", "k");
PARAM_STRING("query_file", "File containing query points (optional).", "q",
    "");
PARAM_INT("leaf_size", "Leaf size for tree building.", "l", 20);
PARAM_FLAG("naive", "If true, O(n^2) naive mode is used for computation.",
    "N");
PARAM_FLAG("single_mode", "If true, single-tree search is used (as opposed "
    "to dual-tree search.", "s");

More documentation is available on the PARAM_*() macros in the documentation for core/io/io.hpp.

Documenting the program itself

In addition to allowing documentation for each individual parameter and module, the BINDING_NAME() macro provides support for documenting the programName, BINDING_SHORT_DESC() macro provides support for documenting the shortDescription, BINDING_LONG_DESC() macro provides support for documenting the longDescription, the BINDING_EXAMPLE() macro provides support for documenting the example and the BINDING_SEE_ALSO() macro provides support for documenting the seeAlso. There should only be one instance of the BINDING_NAME(), BINDING_SHORT_DESC() and BINDING_LONG_DESC() macros and there can be multiple instance of BINDING_EXAMPLE() and BINDING_SEE_ALSO() macro. Below is an example:

BINDING_NAME("Maximum Variance Unfolding");
BINDING_SHORT_DESC("An implementation of Maximum Variance Unfolding");
BINDING_LONG_DESC( "This program performs maximum "
   "variance unfolding on the given dataset, writing a lower-dimensional "
   "unfolded dataset to the given output file.");
BINDING_EXAMPLE("mvu", "input", "dataset", "new_dim", 5, "output", "output");
BINDING_SEE_ALSO("Perceptron", "#perceptron");

This description should be verbose, and explain to a non-expert user what the program does and how to use it. If relevant, paper citations should be included.

Parsing the command line with IO

To have IO parse the command line at the beginning of code execution, only a call to ParseCommandLine() is necessary:

int main(int argc, char** argv)
{
  IO::ParseCommandLine(argc, argv);
  ...
}

IO provides –help and –info options which give nicely formatted documentation of each option; the documentation is generated from the DESC arguments in the PARAM_*() macros.

Getting parameters with IO

When the parameters have been defined, the next important thing is how to access them. For this, the HasParam() and GetParam() methods are used. For instance, to see if the user passed the flag (boolean) "naive":

if (IO::HasParam("naive"))
{
  Log::Info << "Naive has been passed!" << std::endl;
}

To get the value of a parameter, such as a string, use GetParam:

const std::string filename = IO::GetParam<std::string>("filename");

Note: Options should only be defined in files which define main() (that is, main 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 identifier for options declared using the PARAM_*() macros. However, not all compilers have this support–most notably, gcc < 4.3. In that case, the LINE macro is used as an attempt to get a unique global identifier, but collisions are still possible, and they produce bizarre error messages. See https://github.com/mlpack/mlpack/issues/100 for more information.

Definition at line 176 of file io.hpp.

Member Function Documentation

◆ AddBindingName()

static void AddBindingName	(	const std::string &	bindingName,
		const std::string &	name
	)

static

Add a user-friendly name for a binding.

Parameters

bindingName	Name of the binding to add the user-friendly name for.
name	User-friendly name.

◆ AddExample()

static void AddExample	(	const std::string &	bindingName,
		const std::function< std::string()> &	example
	)

static

Add an example for a binding.

Parameters

bindingName	Name of the binding to add the example for.
example	Function that returns the example.

◆ AddFunction()

static void AddFunction	(	const std::string &	type,
		const std::string &	name,
		void()(util::ParamData &, const void , void *)	func
	)

static

Add a function to the function map.

Parameters

type	Type that this function should be called for.
name	Name of the function.
func	Function to call.

Referenced by CLIOption< N >::CLIOption(), GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), and ROption< T >::ROption().

◆ AddLongDescription()

static void AddLongDescription	(	const std::string &	bindingName,
		const std::function< std::string()> &	longDescription
	)

static

Add a long description for a binding.

Parameters

bindingName	Name of the binding to add the description for.
longDescription	Function that returns the long description.

◆ AddParameter()

static void AddParameter	(	const std::string &	bindingName,
		util::ParamData &&	d
	)

static

Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e.

PARAM_INT()).

Parameters

bindingName	Name of the binding that this parameter is associated with.
d	Utility structure holding parameter data.

Referenced by CLIOption< N >::CLIOption(), GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), ROption< T >::ROption(), and TestOption< N >::TestOption().

◆ AddSeeAlso()

static void AddSeeAlso	(	const std::string &	bindingName,
		const std::string &	description,
		const std::string &	link
	)

static

Add a SeeAlso for a binding.

Parameters

bindingName	Name of the binding to add the example for.
description	Description of the SeeAlso.
link	Link of the SeeAlso.

◆ AddShortDescription()

static void AddShortDescription	(	const std::string &	bindingName,
		const std::string &	shortDescription
	)

static

Add a short description for a binding.

Parameters

bindingName	Name of the binding to add the description for.
shortDescription	Description to use.

◆ GetSingleton()

static IO& GetSingleton ( )

static

Retrieve the singleton.

As an end user, if you are just using the IO object, you should not need to use this function—the other static functions should be sufficient.

In this case, the singleton is used to store data for the static methods, as there is no point in defining static methods only to have users call private instance methods.

Returns: The singleton instance for use in the static methods.

◆ GetTimers()

static util::Timers& GetTimers ( )

static

Retrieve the global Timers object.

◆ Parameters()

static util::Params Parameters ( const std::string & bindingName )

static

Return a new Params object initialized with all the parameters of the binding bindingName.

This is intended to be called at the beginning of the run of a binding.

Referenced by MDOption< T >::MDOption(), and mlpack::bindings::cli::ParseCommandLine().

The documentation for this class was generated from the following file:

/home/ryan/src/mlpack.org/_src/mlpack-git/src/mlpack/core/util/io.hpp

Static Public Member Functions

Detailed Description

Adding parameters to a program

Documenting the program itself

Parsing the command line with IO

Getting parameters with IO

Member Function Documentation

◆ AddBindingName()

◆ AddExample()

◆ AddFunction()

◆ AddLongDescription()

◆ AddParameter()

◆ AddSeeAlso()

◆ AddShortDescription()

◆ GetSingleton()

◆ GetTimers()

◆ Parameters()