#include <mlpack/prereqs.hpp>
#include "param_checks_impl.hpp"

Include dependency graph for param_checks.hpp:

This graph shows which files directly or indirectly include this file:

Namespaces
	mlpack
	Linear algebra utility functions, generally performed on matrices or vectors.

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

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 IO object; otherwise, issue a warning or fatal error, optionally with the given custom error message. More...

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 IO object; otherwise, issue a warning or fatal error, optionally with the given custom error message. More...

template<typename T >
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. More...

template<typename T >
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. More...

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. More...

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. More...

Detailed Description

Author: Ryan Curtin

A set of utility functions to check parameter values for mlpack programs. These are meant to be used as the first part of an mlpackMain() function, to validate parameters.

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.

Function Documentation

◆ ReportIgnoredParam() [1/2]

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

inline

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

constraints	Set of constraints.
paramName	Name of parameter to check.

◆ ReportIgnoredParam() [2/2]

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

inline

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

paramName	Name of parameter to check.
reason	Reason 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 = `""`
	)

inline

Require that at least one of the given parameters in the constraints set was passed to the IO 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

constraints	Set of parameters from which only one should be passed.
fatal	If true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessage	Error message to append.

◆ RequireNoneOrAllPassed()

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

inline

Require that either none or all of the given parameters in the constraints set were passed to the IO 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

constraints	Set of parameters of which none or all should be passed.
fatal	If true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessage	Error message to append.

◆ RequireOnlyOnePassed()

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

inline

Require that only one of the given parameters in the constraints set was passed to the IO 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

constraints	Set of parameters from which only one should be passed.
fatal	If true, output goes to Log::Fatal instead of Log::Warn and an exception is thrown.
customErrorMessage	Error message to append.
allowNone	If true, then no error message will be thrown if none of the parameters in the constraints were passed.

◆ RequireParamInSet()

template<typename T >

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

T	Type of parameter.

Parameters

paramName	Name of parameter to check.
set	Set of valid values for parameter.
fatal	If true, an exception is thrown and output goes to Log::Fatal.
errorMessage	Error message to output.

◆ RequireParamValue()

template<typename T >

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

T	Type of parameter to check.

Parameters

paramName	Name of parameter to check.
conditional	Function to use to check parameter value; should return 'true' if the parameter value is okay.
fatal	If true, an exception is thrown and output goes to Log::Fatal.
errorMessage	Error message to output.

Namespaces

Functions

Detailed Description

Function Documentation

◆ ReportIgnoredParam() [1/2]

◆ ReportIgnoredParam() [2/2]

◆ RequireAtLeastOnePassed()

◆ RequireNoneOrAllPassed()

◆ RequireOnlyOnePassed()

◆ RequireParamInSet()

◆ RequireParamValue()