mlpack  3.0.2
mlpack::util Namespace Reference

Classes

struct  IsStdVector
 Metaprogramming structure for vector detection. More...

 
struct  IsStdVector< std::vector< T, A > >
 Metaprogramming structure for vector detection. More...

 
class  NullOutStream
 Used for Log::Debug when not compiled with debugging symbols. More...

 
struct  ParamData
 This structure holds all of the information about a single parameter, including its value (which is set when ParseCommandLine() is called). More...

 
class  PrefixedOutStream
 Allows us to output to an ostream with a prefix at the beginning of each line, in the same way we would output to cout or cerr. More...

 
class  ProgramDoc
 A static object whose constructor registers program documentation with the CLI class. More...

 

Functions

void DisableBacktrace ()
 Disable backtraces. More...

 
void DisableVerbose ()
 Turn verbose output off. More...

 
void EnableTimers ()
 Enable timing. More...

 
void EnableVerbose ()
 Turn verbose output on. More...

 
template
<
typename
T
>
T * GetParamPtr (const std::string &paramName)
 Return a pointer. More...

 
template
<
typename
T
>
T & GetParamWithInfo (const std::string &paramName)
 Return the matrix part of a matrix + dataset info parameter. More...

 
std::string GetVersion ()
 This will return either "mlpack x.y.z" or "mlpack master-XXXXXXX" depending on whether or not this is a stable version of mlpack or a git repository. More...

 
std::string HyphenateString (const std::string &str, int padding)
  * Hyphenate a string or split it onto multiple 80-character lines, with some  * amount of padding on each line. More...

 
void ReportIgnoredParam (const std::vector< std::pair< std::string, bool >> &constraints, const std::string &paramName)
 Report that a parameter is ignored, if each of the constraints given are satisfied. More...

 
void ReportIgnoredParam (const std::string &paramName, const std::string &reason)
 If the given parameter is passed, report that it is ignored, supplying a custom reason. More...

 
void RequireAtLeastOnePassed (const std::vector< std::string > &constraints, const bool fatal=true, const std::string &customErrorMessage="")
 Require that at least one of the given parameters in the constraints set was passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message. More...

 
void RequireNoneOrAllPassed (const std::vector< std::string > &constraints, const bool fatal=true, const std::string &customErrorMessage="")
 Require that either none or all of the given parameters in the constraints set were passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message. More...

 
void RequireOnlyOnePassed (const std::vector< std::string > &constraints, const bool fatal=true, const std::string &customErrorMessage="")
 Require that only one of the given parameters in the constraints set was passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message. More...

 
template
<
typename
T
>
void RequireParamInSet (const std::string &paramName, const std::vector< T > &set, const bool fatal, const std::string &errorMessage)
 Require that a given parameter is in a set of allowable parameters. More...

 
template
<
typename
T
>
void RequireParamValue (const std::string &paramName, const std::function< bool(T)> &conditional, const bool fatal, const std::string &errorMessage)
 Require that a given parameter satisfies the given conditional function. More...

 
void ResetTimers ()
 Reset the status of all timers. More...

 
template
<
typename
T
>
void SetInputParam (const std::string &name, T &&value)
 Utility function that is used in binding tests for setting a parameter and marking it as passed; it uses copy semantics for lvalues and move semantics for rvalues. More...

 
template
<
typename
T
>
void SetParam (const std::string &identifier, T &value)
 Set the parameter to the given value. More...

 
template
<
typename
T
>
void SetParamPtr (const std::string &identifier, T *value, const bool copy)
 Set the parameter to the given value, given that the type is a pointer. More...

 
template
<
typename
T
>
void SetParamWithInfo (const std::string &identifier, T &matrix, const bool *dims)
 Set the parameter (which is a matrix/DatasetInfo tuple) to the given value. More...

 

Function Documentation

◆ DisableBacktrace()

void mlpack::util::DisableBacktrace ( )
inline

Disable backtraces.

Definition at line 144 of file cli_util.hpp.

References PrefixedOutStream::backtrace, and Log::Fatal.

◆ DisableVerbose()

void mlpack::util::DisableVerbose ( )
inline

Turn verbose output off.

Definition at line 136 of file cli_util.hpp.

References PrefixedOutStream::ignoreInput, and Log::Info.

◆ EnableTimers()

void mlpack::util::EnableTimers ( )
inline

Enable timing.

Definition at line 161 of file cli_util.hpp.

References Timer::EnableTiming().

◆ EnableVerbose()

void mlpack::util::EnableVerbose ( )
inline

Turn verbose output on.

Definition at line 128 of file cli_util.hpp.

References PrefixedOutStream::ignoreInput, and Log::Info.

◆ GetParamPtr()

T* mlpack::util::GetParamPtr ( const std::string &  paramName)

Return a pointer.

This function exists to work around Cython's seeming lack of support for template pointer types.

Definition at line 109 of file cli_util.hpp.

◆ GetParamWithInfo()

T& mlpack::util::GetParamWithInfo ( const std::string &  paramName)

Return the matrix part of a matrix + dataset info parameter.

Definition at line 118 of file cli_util.hpp.

◆ GetVersion()

std::string mlpack::util::GetVersion ( )

This will return either "mlpack x.y.z" or "mlpack master-XXXXXXX" depending on whether or not this is a stable version of mlpack or a git repository.

Referenced by mlpack::bindings::cli::ParseCommandLine().

◆ HyphenateString()

std::string mlpack::util::HyphenateString ( const std::string &  str,
int  padding 
)
inline

 * Hyphenate a string or split it onto multiple 80-character lines, with some  * amount of padding on each line.

  This is used for option output.  *  *

Parameters
strString to hyphenate (splits are on ' ').  *
paddingAmount of padding on the left for each new line.  

Definition at line 25 of file hyphenate_string.hpp.

Referenced by mlpack::bindings::python::PrintDoc().

◆ ReportIgnoredParam() [1/2]

void mlpack::util::ReportIgnoredParam ( const std::vector< std::pair< std::string, bool >> &  constraints,
const std::string &  paramName 
)

Report that a parameter is ignored, if each of the constraints given are satisfied.

The constraints should be a set of string/bool pairs. If all of the constraints are true, and the given parameter in 'paramName' is passed, then a warning will be issued noting that the parameter is ignored. The warning will go to Log::Warn.

Parameters
constraintsSet of constraints.
paramNameName of parameter to check.

◆ ReportIgnoredParam() [2/2]

void mlpack::util::ReportIgnoredParam ( const std::string &  paramName,
const std::string &  reason 
)

If the given parameter is passed, report that it is ignored, supplying a custom reason.

The reason should specify, in short and clear terms, why the parameter is ignored. So, for example, the output may be similar to:

--iterations (-i) ignored because <reason>.

and in this case a good reason might be "SGD is not being used as an optimizer". Be sure that when you write the reason, the full message makes sense.

Parameters
paramNameName of parameter to check.
reasonReason that parameter is ignored, if it is passed.

◆ RequireAtLeastOnePassed()

void mlpack::util::RequireAtLeastOnePassed ( const std::vector< std::string > &  constraints,
const bool  fatal = true,
const std::string &  customErrorMessage = "" 
)

Require that at least one of the given parameters in the constraints set was passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message.

This uses the correct binding type name for each parameter (i.e. '–parameter' for CLI bindings, 'parameter' for Python bindings).

This can be used with a set of only one constraint and the output is still sensible.

If you use a custom error message, be aware that the given output will be similar to, for example:

Should pass one of '--codes_file (-c)', '--dictionary_file (-d)', or
'--output_model_file (-M)'; <custom error message>!

so when you write your custom error message, be sure that the sentence makes sense. The custom error message should not have a capitalized first character and no ending punctuation (a '!' will be added by this function).

Parameters
constraintsSet of parameters from which only one should be passed.
fatalIf true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessageError message to append.

◆ RequireNoneOrAllPassed()

void mlpack::util::RequireNoneOrAllPassed ( const std::vector< std::string > &  constraints,
const bool  fatal = true,
const std::string &  customErrorMessage = "" 
)

Require that either none or all of the given parameters in the constraints set were passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message.

This uses the correct binding type name for each parameter (i.e. '–parameter' for CLI bindings, 'parameter' for Python bindings).

If you use a custom error message, be aware that the given output will be similar to, for example:

Must pass none or all of '--codes_file (-c)', '--dictionary_file (-d)', and
'--output_model_file (-M)'; <custom error message>!

so when you write your custom error message, be sure that the sentence makes sense. The custom error message should not have a capitalized first character and no ending punctuation (a '!' will be added by this function).

Parameters
constraintsSet of parameters of which none or all should be passed.
fatalIf true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessageError message to append.

◆ RequireOnlyOnePassed()

void mlpack::util::RequireOnlyOnePassed ( const std::vector< std::string > &  constraints,
const bool  fatal = true,
const std::string &  customErrorMessage = "" 
)

Require that only one of the given parameters in the constraints set was passed to the CLI object; otherwise, issue a warning or fatal error, optionally with the given custom error message.

This uses the correct binding type name for each parameter (i.e. '–parameter' for CLI bindings, 'parameter' for Python bindings).

If you use a custom error message, be aware that the given output will be similar to, for example:

Must specify one of '--reference_file (-r)' or '--input_model_file (-m)';
<custom error message here>!

so when you write your custom error message, be sure that the sentence makes sense. The custom error message should not have a capitalized first character and no ending punctuation (a '!' will be added by this function).

Parameters
constraintsSet of parameters from which only one should be passed.
fatalIf true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessageError message to append.

◆ RequireParamInSet()

void mlpack::util::RequireParamInSet ( const std::string &  paramName,
const std::vector< T > &  set,
const bool  fatal,
const std::string &  errorMessage 
)

Require that a given parameter is in a set of allowable parameters.

This is probably most useful with T = std::string. If fatal is true, then an exception is thrown. An error message is not optional and must be specified. The error message does not need to specify the values in the set; this function will already output them. So, for example, the output may be similar to:

Invalid value of '--weak_learner (-w)' specified ('something'); <error
message>; must be one of 'decision_stump', or 'perceptron'!

so when you write the error message, make sure that the message makes sense. For example, in the message above, a good error message might be "unknown weak learner type".

Template Parameters
TType of parameter.
Parameters
paramNameName of parameter to check.
setSet of valid values for parameter.
fatalIf true, an exception is thrown and output goes to Log::Fatal.
errorMessageError message to output.

◆ RequireParamValue()

void mlpack::util::RequireParamValue ( const std::string &  paramName,
const std::function< bool(T)> &  conditional,
const bool  fatal,
const std::string &  errorMessage 
)

Require that a given parameter satisfies the given conditional function.

This is useful for, e.g., checking that a given parameter is greater than 0. If fatal is true, then an exception is thrown. An error message is not optional and must be specified. The error message should specify, in clear terms, what the value of the parameter should be. So, for example, the output may be similar to:

Invalid value of '--iterations (-i)' specified (-1); <error message>!

and in this case a good error message might be "number of iterations must be positive". Be sure that when you write the error message, the message makes sense.

Template Parameters
TType of parameter to check.
Parameters
paramNameName of parameter to check.
conditionalFunction to use to check parameter value; should return 'true' if the parameter value is okay.
fatalIf true, an exception is thrown and output goes to Log::Fatal.
errorMessageError message to output.

◆ ResetTimers()

void mlpack::util::ResetTimers ( )
inline

Reset the status of all timers.

Definition at line 152 of file cli_util.hpp.

References CLI::GetSingleton(), Timers::Reset(), and CLI::timer.

◆ SetInputParam()

void mlpack::util::SetInputParam ( const std::string &  name,
T &&  value 
)

Utility function that is used in binding tests for setting a parameter and marking it as passed; it uses copy semantics for lvalues and move semantics for rvalues.

Parameters
nameName of parameter to set.
valueValue to set parameter to.

Definition at line 29 of file test_helper.hpp.

References CLI::SetPassed().

◆ SetParam()

void mlpack::util::SetParam ( const std::string &  identifier,
T &  value 
)
inline

Set the parameter to the given value.

This function exists to work around Cython's lack of support for lvalue references.

Parameters
identifierName of parameter.
valueValue to set parameter to.

Definition at line 32 of file cli_util.hpp.

◆ SetParamPtr()

void mlpack::util::SetParamPtr ( const std::string &  identifier,
T *  value,
const bool  copy 
)
inline

Set the parameter to the given value, given that the type is a pointer.

This function exists to work around both Cython's lack of support for lvalue references and also its seeming lack of support for template pointer types.

Parameters
identifierName of parameter.
valueValue to set parameter to.
copyWhether or not the object should be copied.

Definition at line 48 of file cli_util.hpp.

◆ SetParamWithInfo()

void mlpack::util::SetParamWithInfo ( const std::string &  identifier,
T &  matrix,
const bool *  dims 
)
inline

Set the parameter (which is a matrix/DatasetInfo tuple) to the given value.

Definition at line 59 of file cli_util.hpp.

References mlpack::data::categorical, DatasetMapper< PolicyType, InputType >::MapString(), and DatasetMapper< PolicyType, InputType >::Type().