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

#include <io.hpp>

Collaboration diagram for mlpack::IO:

Public Types
typedef std::map< std::string, std::map< std::string, void()(util::ParamData &, const void , void *)> >	FunctionMapType
	Map for functions and types. More...

Static Public Member Functions
static void	Add (util::ParamData &&d)
	Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More...

static bool	HasParam (const std::string &identifier)
	See if the specified flag was found while parsing. More...

template<typename T >
static T &	GetParam (const std::string &identifier)
	Get the value of type T found while parsing. More...

template<typename T >
static std::string	GetPrintableParam (const std::string &identifier)
	Cast the given parameter of the given type to a short, printable std::string, for use in status messages. More...

template<typename T >
static T &	GetRawParam (const std::string &identifier)
	Get the raw value of the parameter before any processing that GetParam() might normally do. More...

template<typename T >
static void	CheckInputMatrix (const T &matrix, const std::string &identifier)
	Utility function for CheckInputMatrices(). More...

static void	MakeInPlaceCopy (const std::string &outputParamName, const std::string &inputParamName)
	Given two (matrix) parameters, ensure that the first is an in-place copy of the second. More...

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

static std::map< std::string, util::ParamData > &	Parameters ()
	Return a modifiable list of parameters that IO knows about.

static std::map< char, std::string > &	Aliases ()
	Return a modifiable list of aliases that IO knows about.

static std::string	ProgramName ()
	Get the program name as set by the BINDING_NAME() macro.

static void	SetPassed (const std::string &name)
	Mark a particular parameter as passed. More...

static void	StoreSettings (const std::string &name)
	Take all parameters and function mappings and store them, under the given name. More...

static void	RestoreSettings (const std::string &name, const bool fatal=true)
	Restore all of the parameters and function mappings of the given name, if they exist. More...

static void	ClearSettings ()
	Clear all of the settings, removing all parameters and function mappings.

static void	CheckInputMatrices ()
	Checks all input matrices for NaN and inf values, exits if found any.

Public Attributes
FunctionMapType	functionMap

bool	didParse
	True, if IO was used to parse command line options.

std::string	programName
	Holds the name of the program for –version. More...

Timers	timer
	Holds the timer objects.

util::BindingDetails	doc
	Holds the bindingDetails objects.

Friends
class	Timer
	So that Timer::Start() and Timer::Stop() can access the timer variable.

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.

Member Typedef Documentation

◆ FunctionMapType

typedef std::map<std::string, std::map<std::string, void (*)(util::ParamData&, const void*, void*)> > mlpack::IO::FunctionMapType

Map for functions and types.

Use as functionMap["typename"]["functionName"].

Member Function Documentation

◆ Add()

void IO::Add ( util::ParamData && d )

static

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

PARAM_INT()).

Parameters

d	Utility structure holding parameter data.

◆ CheckInputMatrix()

template<typename T >

void mlpack::IO::CheckInputMatrix	(	const T &	matrix,
		const std::string &	identifier
	)

static

Utility function for CheckInputMatrices().

Parameters

matrix	Matrix to check.
identifier	Name of the parameter in question.

◆ GetParam()

template<typename T >

T & mlpack::IO::GetParam ( const std::string & identifier )

static

Get the value of type T found while parsing.

Returns the value of the specified parameter.

You can set the value using this reference safely.

Parameters

identifier The name of the parameter in question.

If the parameter is unspecified, an undefined but more or less valid value is returned.

Template Parameters

T	The type of the parameter.

Parameters

identifier The full name of the parameter.

Returns: The value of the parameter. Use IO::CheckValue to determine if it's valid.

◆ GetPrintableParam()

template<typename T >

std::string mlpack::IO::GetPrintableParam ( const std::string & identifier )

static

Cast the given parameter of the given type to a short, printable std::string, for use in status messages.

Ideally the message returned here should be only a handful of characters, and certainly no longer than one line.

Parameters

identifier The name of the parameter in question.

◆ GetRawParam()

template<typename T >

T & mlpack::IO::GetRawParam ( const std::string & identifier )

static

Get the raw value of the parameter before any processing that GetParam() might normally do.

So, e.g., for command-line programs, this does not perform any data loading or manipulation like GetParam() does. So if you want to access a matrix or model (or similar) parameter before it is loaded, this is the method to use.

Parameters

identifier The name of the parameter in question.

◆ GetSingleton()

IO & 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.

◆ HasParam()

bool IO::HasParam ( const std::string & key )

static

See if the specified flag was found while parsing.

Parameters

identifier The name of the parameter in question.

◆ MakeInPlaceCopy()

void IO::MakeInPlaceCopy	(	const std::string &	outputParamName,
		const std::string &	inputParamName
	)

static

Given two (matrix) parameters, ensure that the first is an in-place copy of the second.

This will generally do nothing (as the bindings already do this automatically), except for command-line bindings, where we need to ensure that the output filename is the same as the input filename.

Parameters

outputParamName	Name of output (matrix) parameter.
inputParamName	Name of input (matrix) parameter.

◆ RestoreSettings()

void IO::RestoreSettings	(	const std::string &	name,
		const bool	fatal = `true`
	)

static

Restore all of the parameters and function mappings of the given name, if they exist.

A std::invalid_argument exception will be thrown if fatal is true and no settings with the given name have been stored (with StoreSettings()).

Parameters

name	Name of settings to restore.
fatal	Whether to throw an exception on an unknown name.

◆ SetPassed()

void IO::SetPassed ( const std::string & name )

static

Mark a particular parameter as passed.

Parameters

name	Name of the parameter.

◆ StoreSettings()

void IO::StoreSettings ( const std::string & name )

static

Take all parameters and function mappings and store them, under the given name.

This can later be restored with RestoreSettings(). If settings have already been saved under the given name, they will be overwritten. This also clears the current parameters and function map.

Parameters

name	Name of settings to save.

Member Data Documentation

◆ programName

std::string mlpack::IO::programName

Holds the name of the program for –version.

This is the true program name (argv[0]) not what is given in BindingDetails.

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

src/mlpack/core/util/io.hpp
src/mlpack/core/util/io.cpp
src/mlpack/core/util/io_impl.hpp

Public Types

Static Public Member Functions

Public Attributes

Friends

Detailed Description

Adding parameters to a program

Documenting the program itself

Parsing the command line with IO

Getting parameters with IO

Member Typedef Documentation

◆ FunctionMapType

Member Function Documentation

◆ Add()

◆ CheckInputMatrix()

◆ GetParam()

◆ GetPrintableParam()

◆ GetRawParam()

◆ GetSingleton()

◆ HasParam()

◆ MakeInPlaceCopy()

◆ RestoreSettings()

◆ SetPassed()

◆ StoreSettings()

Member Data Documentation

◆ programName