| OpenMS 2.5.0

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Private Member Functions | Private Attributes | List of all members
TOPPBase Class Referenceabstract

Base class for TOPP applications. More...

`#include <OpenMS/APPLICATIONS/TOPPBase.h>`

Inheritance diagram for TOPPBase:

## Public Types

enum | ExitCodes { EXECUTION_OK, INPUT_FILE_NOT_FOUND, INPUT_FILE_NOT_READABLE, INPUT_FILE_CORRUPT, INPUT_FILE_EMPTY, CANNOT_WRITE_OUTPUT_FILE, ILLEGAL_PARAMETERS, MISSING_PARAMETERS, UNKNOWN_ERROR, EXTERNAL_PROGRAM_ERROR, PARSE_ERROR, INCOMPATIBLE_INPUT_DATA, INTERNAL_ERROR, UNEXPECTED_RESULT
}
| Exit codes. More...

## Public Member Functions

| TOPPBase (const String &name, const String &description, bool official=true, const std::vector< Citation > &citations={})
| Constructor. More...
virtual | ~TOPPBase ()
| Destructor. More...
ExitCodes | main (int argc, const char **argv)
| Main routine of all TOPP applications. More...

## Static Public Member Functions

static void | setMaxNumberOfThreads (int num_threads)
| Sets the maximal number of usable threads. More...

## Protected Member Functions

const String & | getIniLocation_ () const
| Returns the location of the ini file where parameters are taken from. E.g. if the command line was `TOPPTool -instance 17`, then this will be `"TOPPTool:17:"`. Note the ':' at the end. More...
const String & | toolName_ () const
| Returns the tool name. More...
void | printUsage_ ()
| Prints the tool-specific command line options and appends the common options. More...
virtual ExitCodes | main_ (int argc, const char **argv)=0
| The actual "main" method. main_() is invoked by main(). More...
bool | parseRange_ (const String &text, double &low, double &high) const
| Parses a range string ([a]:[b]) into two variables (doubles) More...
bool | parseRange_ (const String &text, Int &low, Int &high) const
| Parses a range string ([a]:[b]) into two variables (integers) More...
bool | writeCTD_ ()
| Write common tool description (CTD) file. More...
Parameter handling
Use the methods registerStringOption_, registerInputFile_, registerOutputFile_, registerDoubleOption_, registerIntOption_ and registerFlag_ in order to register parameters in registerOptionsAndFlags_. To access the values of registered parameters in the main_ method use methods getStringOption_ (also for input and output files), getDoubleOption_, getIntOption_,getStringList_(also for input and output file lists),getIntList_,getDoubleList_, and getFlag_.

The values of certain options can be restricted using: setMinInt_, setMaxInt_, setMinFloat_, setMaxFloat_, setValidStrings_ and setValidFormats_.

In order to format the help output, the method addEmptyLine_ can be used.

virtual void | registerOptionsAndFlags_ ()=0
| Sets the valid command line options (with argument) and flags (without argument). More...
String | getParamArgument_ (const Param::ParamEntry &entry) const
| Utility function that determines a suitable argument value for the given Param::ParamEntry. More...
std::vector< ParameterInformation > | paramToParameterInformation_ (const Param &param) const
| Translates the given parameter object into a vector of ParameterInformation, that can be utilized for cl parsing. More...
ParameterInformation | paramEntryToParameterInformation_ (const Param::ParamEntry &entry, const String &argument="", const String &full_name="") const
| Transforms a ParamEntry object to command line parameter (ParameterInformation). More...
void | registerParamSubsectionsAsTOPPSubsections_ (const Param &param)
void | registerFullParam_ (const Param &param)
| Register command line parameters for all entries in a Param object. More...
void | registerStringOption_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
| Registers a string option. More...
void | setValidStrings_ (const String &name, const std::vector< String > &strings)
| Sets the valid strings for a string option or a whole string list. More...
void | setValidStrings_ (const String &name, const std::string vstrings[], int count)
| Sets the valid strings for a string option or a whole string list. More...
void | registerInputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false, const StringList &tags=StringList())
| Registers an input file option. More...
void | registerOutputFile_ (const String &name, const String &argument, const String &default_value, const String &description, bool required=true, bool advanced=false)
| Registers an output file option. More...
void | setValidFormats_ (const String &name, const std::vector< String > &formats, const bool force_OpenMS_format=true)
| Sets the formats for a input/output file option or for all members of an input/output file lists. More...
void | registerDoubleOption_ (const String &name, const String &argument, double default_value, const String &description, bool required=true, bool advanced=false)
| Registers a double option. More...
void | setMinInt_ (const String &name, Int min)
| Sets the minimum value for the integer parameter(can be a list of integers,too) `name`. More...
void | setMaxInt_ (const String &name, Int max)
| Sets the maximum value for the integer parameter(can be a list of integers,too) `name`. More...
void | setMinFloat_ (const String &name, double min)
| Sets the minimum value for the floating point parameter(can be a list of floating points,too) `name`. More...
void | setMaxFloat_ (const String &name, double max)
| Sets the maximum value for the floating point parameter(can be a list of floating points,too) `name`. More...
void | registerIntOption_ (const String &name, const String &argument, Int default_value, const String &description, bool required=true, bool advanced=false)
| Registers an integer option. More...
void | registerIntList_ (const String &name, const String &argument, IntList default_value, const String &description, bool required=true, bool advanced=false)
| Registers a list of integers option. More...
void | registerDoubleList_ (const String &name, const String &argument, DoubleList default_value, const String &description, bool required=true, bool advanced=false)
| Registers a list of doubles option. More...
void | registerStringList_ (const String &name, const String &argument, StringList default_value, const String &description, bool required=true, bool advanced=false)
| Registers a list of strings option. More...
void | registerInputFileList_ (const String &name, const String &argument, StringList default_value, const String &description, bool required=true, bool advanced=false, const StringList &tags=StringList())
| Registers a list of input files option. More...
void | registerOutputFileList_ (const String &name, const String &argument, StringList default_value, const String &description, bool required=true, bool advanced=false)
| Registers a list of output files option. More...
void | registerFlag_ (const String &name, const String &description, bool advanced=false)
| Registers a flag. More...
void | registerSubsection_ (const String &name, const String &description)
| Registers an allowed subsection in the INI file (usually from OpenMS algorithms). More...
void | registerTOPPSubsection_ (const String &name, const String &description)
| Registers an allowed subsection in the INI file originating from the TOPP tool itself. More...
void | addEmptyLine_ ()
| Adds an empty line between registered variables in the documentation. More...
String | getStringOption_ (const String &name) const
| Returns the value of a previously registered string option. More...
double | getDoubleOption_ (const String &name) const
| Returns the value of a previously registered double option. More...
Int | getIntOption_ (const String &name) const
| Returns the value of a previously registered integer option. More...
StringList | getStringList_ (const String &name) const
| Returns the value of a previously registered StringList. More...
IntList | getIntList_ (const String &name) const
| Returns the value of a previously registered IntList. More...
DoubleList | getDoubleList_ (const String &name) const
| Returns the value of a previously registered DoubleList. More...
bool | getFlag_ (const String &name) const
| Returns the value of a previously registered flag. More...
const ParameterInformation & | findEntry_ (const String &name) const
| Finds the entry in the parameters_ array that has the name `name`. More...
Param const & | getParam_ () const
| Return all parameters relevant to this TOPP tool. More...
void | checkParam_ (const Param &param, const String &filename, const String &location) const
| Checks top-level entries of `param` according to the information during registration. More...
void | fileParamValidityCheck_ (String &filename, const String &param_name, const ParameterInformation &p) const
| checks if an input file exists (respecting the flags) More...
void | checkIfIniParametersAreApplicable_ (const Param &ini_params)
| Checks if the parameters of the provided ini file are applicable to this tool. More...
Debug and Log output
void | writeLog_ (const String &text) const
| Writes a string to the log file and to std::cout. More...
void | writeDebug_ (const String &text, UInt min_level) const
| Writes a `text` to the log file and to std::cout if the debug level is at least `min_level`. More...
void | writeDebug_ (const String &text, const Param &param, UInt min_level) const
| Writes a String followed by a Param to the log file and to std::cout if the debug level is at least `min_level`. More...
Temporary directories
String | makeTempDirectory_ () const
| Creates a unique temporary directory and returns its name (you have to clean it up yourself) More...
String | makeAutoRemoveTempDirectory_ (Int keep_debug=2)
| Creates a unique temporary directory and returns its name (will be cleaned up automatically if debug level is high enough) More...
void | removeTempDirectory_ (const String &dirname, Int keep_debug=2) const
| Removes a (temporary) directory. More...
External processes (TODO consider creating another AdapterBase class)
ExitCodes | runExternalProcess_ (const QString &executable, const QStringList &arguments, const QString &workdir="") const
| Runs an external process via QProcess and reports its status in the logs. More...
File IO checking methods
Methods used to check the validity of input and output files in main_. Checking input and output files is only necessary, if you did register the file as string option, e.g. when only a file prefix is given which is completed in the program. The exceptions thrown in these methods are caught in the main method of this class. They do not have to be handled in the tool itself!
void | inputFileReadable_ (const String &filename, const String &param_name) const
| Checks if an input file exists, is readable and is not empty. More...
void | outputFileWritable_ (const String &filename, const String &param_name) const
| Checks if an output file is writable. More...
Data processing auxiliary functions
void | addDataProcessing_ (ConsensusMap &map, const DataProcessing &dp) const
| Data processing setter for consensus maps. More...
void | addDataProcessing_ (FeatureMap &map, const DataProcessing &dp) const
| Data processing setter for feature maps. More...
void | addDataProcessing_ (PeakMap &map, const DataProcessing &dp) const
| Data processing setter for peak maps. More...
DataProcessing | getProcessingInfo_ (DataProcessing::ProcessingAction action) const
| Returns the data processing information. More...
DataProcessing | getProcessingInfo_ (const std::set< DataProcessing::ProcessingAction > &actions) const
| Returns the data processing information. More...

## Protected Attributes

String | version_
| Version string (if empty, the OpenMS/TOPP version is printed) More...
String | verboseVersion_
| Version string including additional revision/date time information. Note: This differs from version_ only if not provided by the user. More...
bool | official_
| Flag indicating if this an official TOPP tool. More...
std::vector< Citation > | citations_
| Papers, specific for this tool (will be shown in '–help') More...
ProgressLogger::LogType | log_type_
| Type of progress logging. More...
bool | test_mode_
| Test mode. More...
Int | debug_level_
| Debug level set by -debug. More...

## Static Protected Attributes

static String | topp_ini_file_
| .TOPP.ini file for storing system default parameters More...
static const Citation | cite_openms_
| The OpenMS citation. More...

## Private Member Functions

| TOPPBase ()
| No default constructor. It is "declared away". More...
| TOPPBase (const TOPPBase &)
| No default copy constructor. It is "declared away". More...
void | enableLogging_ () const
| Ensures that at least some default logging destination is opened for writing in append mode. More...
virtual Param | getSubsectionDefaults_ (const String &section) const
| This method should return the default parameters for subsections. More...
Param | getSubsectionDefaults_ () const
| Returns a single Param object containing all subsection parameters. More...
Param | parseCommandLine_ (const int argc, const char **argv, const String &misc="misc", const String &unknown="unknown")
| Parses command line arguments using parameter definitions from TOPPBase. More...
void | addText_ (const String &text)
ParameterInformation & | getParameterByName_ (const String &name)
| Returns the parameter identified by the given name. More...
Internal parameter handling
String | getParamAsString_ (const String &key, const String &default_value="") const
| Return the value of parameter `key` as a string or `default_value` if this value is not set. More...
Int | getParamAsInt_ (const String &key, Int default_value=0) const
| Return the value of parameter `key` as an integer or `default_value` if this value is not set. More...
double | getParamAsDouble_ (const String &key, double default_value=0) const
| Return the value of parameter `key` as a double or `default_value` if this value is not set. More...
StringList | getParamAsStringList_ (const String &key, const StringList &default_value) const
| Return the value of parameter `key` as a StringList or `default_value` if this value is not set. More...
IntList | getParamAsIntList_ (const String &key, const IntList &default_value) const
| Return the value of parameter `key` as a IntList or `default_value` if this value is not set. More...
DoubleList | getParamAsDoubleList_ (const String &key, const DoubleList &default_value) const
| Return the value of parameter `key` as a DoubleList or `default_value` if this value is not set. More...
bool | getParamAsBool_ (const String &key) const
| Return the value of flag parameter `key` as bool. More...
const DataValue & | getParam_ (const String &key) const
| Return the value `key` of parameters as DataValue. DataValue::EMPTY indicates that a parameter was not found. More...
String | getSubsection_ (const String &name) const
| Get the part of a parameter name that makes up the subsection. More...
String | getDocumentationURL () const
Param | getDefaultParameters_ () const
| Returns the default parameters. More...
Param | getToolUserDefaults_ (const String &tool_name) const
| Returns the user defaults for the given tool, if any default parameters are stored in the users home. More...

## Private Attributes

String const | tool_name_
| Tool name. This is assigned once and for all in the constructor. More...
String const | tool_description_
| Tool description. This is assigned once and for all in the constructor. More...
Int const | instance_number_
| Instance number. More...
String const | ini_location_
| Location in the ini file where to look for parameters. More...
String | working_dir_
| An optional temporary working directory. More...
Int | working_dir_keep_debug_lvl_
| Debug level at which to keep working dir. More...
Param | param_
| All parameters relevant to this invocation of the program. More...
Param | param_inifile_
| All parameters specified in the ini file. More...
Param | param_cmdline_
| Parameters from command line. More...
Param | param_instance_
| Parameters from instance section. More...
Param | param_common_tool_
| Parameters from common section with tool name. More...
Param | param_common_
| Parameters from common section without tool name. More...
std::ofstream | log_
| Log file stream. Use the writeLog_() and writeDebug_() methods to access it. More...
std::vector< ParameterInformation > | parameters_
| Storage location for parameter information. More...
std::map< String, String > | subsections_
| Storage location and description for allowed subsections. More...
std::map< String, String > | subsections_TOPP_
| Storage location and description for allowed subsections from TOPP tool's command-line parameters. More...

## Detailed Description

Base class for TOPP applications.

This base class implements functionality used in most TOPP tools:

- parameter handling
- file handling
- progress logging

If you want to create a new TOPP tool, please take care of the following:

- derive a new class from this class
- implement the registerOptionsAndFlags_ and main_ methods
- add a Doxygen page for the tool and add the page to TOPP.doxygen
- hide the derived class in the OpenMS documentation by using Doxygen condition macros.

Todo:
  : replace writeLog_, writeDebug_ with a logger concept we'd need something like -VLevels [LOGGERS] to specify which loggers shall print something the '-log' flag should clone all output to the log-file (maybe with custom [LOGGERS]), which can either be specified directly or is equal to '-out' (if present) with a ".log" suffix maybe a new LOGGER type (TOPP), which is only usable on TOPP level?

## Member Enumeration Documentation

## ◆ ExitCodes

enum ExitCodes

Exit codes.

Enumerator
EXECUTION_OK |
INPUT_FILE_NOT_FOUND |
INPUT_FILE_NOT_READABLE |
INPUT_FILE_CORRUPT |
INPUT_FILE_EMPTY |
CANNOT_WRITE_OUTPUT_FILE |
ILLEGAL_PARAMETERS |
MISSING_PARAMETERS |
UNKNOWN_ERROR |
EXTERNAL_PROGRAM_ERROR |
PARSE_ERROR |
INCOMPATIBLE_INPUT_DATA |
INTERNAL_ERROR |
UNEXPECTED_RESULT |

## Constructor & Destructor Documentation

## ◆ TOPPBase() [1/3]

TOPPBase | ( | const String & | name,
|  | const String & | description,
|  | bool | official = `true`,
|  | const std::vector< Citation > & | citations = `{}`
| ) |  |

Constructor.

Parameters

  name | Tool name.
  description | Short description of the tool (one line).
  official | If this is an official TOPP tool contained in the OpenMS/TOPP release. If true the tool name is checked against the list of TOPP tools and a warning printed if missing.
  citations | Add one or more citations if they are associated specifically to this TOPP tool; they will be printed during –help

## ◆ ~TOPPBase()

virtual ~TOPPBase | ( |  | ) |

virtual

Destructor.

## ◆ TOPPBase() [2/3]

TOPPBase | ( |  | ) |

private

No default constructor. It is "declared away".

## ◆ TOPPBase() [3/3]

TOPPBase | ( | const TOPPBase & |  | ) |

private

No default copy constructor. It is "declared away".

## Member Function Documentation

## ◆ addDataProcessing_() [1/3]

void addDataProcessing_ | ( | ConsensusMap & | map,
|  | const DataProcessing & | dp
| ) |  | const

protected

Data processing setter for consensus maps.

## ◆ addDataProcessing_() [2/3]

void addDataProcessing_ | ( | FeatureMap & | map,
|  | const DataProcessing & | dp
| ) |  | const

protected

Data processing setter for feature maps.

## ◆ addDataProcessing_() [3/3]

void addDataProcessing_ | ( | PeakMap & | map,
|  | const DataProcessing & | dp
| ) |  | const

protected

Data processing setter for peak maps.

## ◆ addEmptyLine_()

void addEmptyLine_ | ( |  | ) |

protected

Adds an empty line between registered variables in the documentation.

## ◆ addText_()

void addText_ | ( | const String & | text | ) |

private

Adds a left aligned text between registered variables in the documentation e.g. for subdividing the documentation. This should not be usable for derived classes, since this formatting is not carried over to INI files and thus INI files might lack important information. Instead, subdivision of parameters should be achieved using TOPPSubsections with appropriate description Currently only used for "Common TOPP options" within TOPPBase.cpp

## ◆ checkIfIniParametersAreApplicable_()

void checkIfIniParametersAreApplicable_ | ( | const Param & | ini_params | ) |

protected

Checks if the parameters of the provided ini file are applicable to this tool.

This method does not abort execution of the tool, but will warn the user through stderr! It is called automatically whenever a ini file is loaded.

## ◆ checkParam_()

void checkParam_ | ( | const Param & | param,
|  | const String & | filename,
|  | const String & | location
| ) |  | const

protected

Checks top-level entries of `param` according to the information during registration.

Only top-level entries and allowed subsections are checked. Checking the content of the subsection is the duty of the algorithm it is passed to.

This method does not abort execution of the tool, but will warn the user through stderr! It is called automatically in the main method.

Parameters

  param | Parameters to check
  filename | The source file name
  location | Exact location inside the source file

## ◆ enableLogging_()

void enableLogging_ | ( |  | ) | const

private

Ensures that at least some default logging destination is opened for writing in append mode.

Note
  This might be invoked at various places early in the startup process of the TOPP tool. Thus we cannot consider the ini file here. The final logging destination is determined in main().

## ◆ fileParamValidityCheck_()

void fileParamValidityCheck_ | ( | String & | filename,
|  | const String & | param_name,
|  | const ParameterInformation & | p
| ) |  | const

protected

checks if an input file exists (respecting the flags)

Checks if String/Format restrictions are met (or throws InvalidParameter() otherwise).

For InputFile(s), it checks if the file is readable/findable. If 'is_executable' is specified as a tag, the filename is searched on PATH and upon success, the full absolute path is returned.

For OutputFile(s), it checks if the file is writeable.

Parameters

  filename | ...as given via commandline/ini/default
  param_name | Name of the parameter (key)
  p | All meta information for this param

## ◆ findEntry_()

const ParameterInformation& findEntry_ | ( | const String & | name | ) | const

protected

Finds the entry in the parameters_ array that has the name `name`.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered

## ◆ getDefaultParameters_()

Param getDefaultParameters_ | ( |  | ) | const

private

Returns the default parameters.

## ◆ getDocumentationURL()

String getDocumentationURL | ( |  | ) | const

private

## ◆ getDoubleList_()

DoubleList getDoubleList_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered DoubleList.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getDoubleOption_()

double getDoubleOption_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered double option.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getFlag_()

bool getFlag_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered flag.

## ◆ getIniLocation_()

const String& getIniLocation_ | ( |  | ) | const

inline protected

Returns the location of the ini file where parameters are taken from. E.g. if the command line was `TOPPTool -instance 17`, then this will be `"TOPPTool:17:"`. Note the ':' at the end.

This is assigned during tool startup, depending on the command line but (of course) not depending on ini files.

## ◆ getIntList_()

IntList getIntList_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered IntList.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getIntOption_()

Int getIntOption_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered integer option.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getParam_() [1/2]

const DataValue& getParam_ | ( | const String & | key | ) | const

private

Return the value `key` of parameters as DataValue. DataValue::EMPTY indicates that a parameter was not found.

Parameters are searched in this order:

1. command line
2. instance section, e.g. "TOPPTool:1:some_key", see getIniLocation_().
3. common section with tool name, e.g. "common:ToolName:some_key"
4. common section without tool name, e.g. "common:some_key"

where "some_key" == key in the examples.

## ◆ getParam_() [2/2]

Param const& getParam_ | ( |  | ) | const

protected

Return all parameters relevant to this TOPP tool.

Returns a Param that contains everything you can get by the getParamAs...() methods.

Referenced by TOPPOpenSwathBase::performCalibration().

## ◆ getParamArgument_()

String getParamArgument_ | ( | const Param::ParamEntry & | entry | ) | const

protected

Utility function that determines a suitable argument value for the given Param::ParamEntry.

## ◆ getParamAsBool_()

bool getParamAsBool_ | ( | const String & | key | ) | const

private

Return the value of flag parameter `key` as bool.

Only the string values 'true' and 'false' are interpreted.

Exceptions

  Exception::InvalidParameter | is thrown for non-string parameters and string parameters with values other than 'true' and 'false'.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsDouble_()

double getParamAsDouble_ | ( | const String & | key,
|  | double | default_value = `0`
| ) |  | const

private

Return the value of parameter `key` as a double or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsDoubleList_()

DoubleList getParamAsDoubleList_ | ( | const String & | key,
|  | const DoubleList & | default_value
| ) |  | const

private

Return the value of parameter `key` as a DoubleList or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsInt_()

Int getParamAsInt_ | ( | const String & | key,
|  | Int | default_value = `0`
| ) |  | const

private

Return the value of parameter `key` as an integer or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsIntList_()

IntList getParamAsIntList_ | ( | const String & | key,
|  | const IntList & | default_value
| ) |  | const

private

Return the value of parameter `key` as a IntList or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsString_()

String getParamAsString_ | ( | const String & | key,
|  | const String & | default_value = `""`
| ) |  | const

private

Return the value of parameter `key` as a string or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParamAsStringList_()

StringList getParamAsStringList_ | ( | const String & | key,
|  | const StringList & | default_value
| ) |  | const

private

Return the value of parameter `key` as a StringList or `default_value` if this value is not set.

Note
  See getParam_(const String&) const for the order in which parameters are searched.

## ◆ getParameterByName_()

ParameterInformation& getParameterByName_ | ( | const String & | name | ) |

private

Returns the parameter identified by the given name.

Parameters

  name | The name of the parameter to search.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered

Returns
  A reference to the parameter with the given name.

## ◆ getProcessingInfo_() [1/2]

DataProcessing getProcessingInfo_ | ( | DataProcessing::ProcessingAction | action | ) | const

protected

Returns the data processing information.

Referenced by TOPPOpenSwathBase::prepareChromOutput().

## ◆ getProcessingInfo_() [2/2]

DataProcessing getProcessingInfo_ | ( | const std::set< DataProcessing::ProcessingAction > & | actions | ) | const

protected

Returns the data processing information.

## ◆ getStringList_()

StringList getStringList_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered StringList.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getStringOption_()

String getStringOption_ | ( | const String & | name | ) | const

protected

Returns the value of a previously registered string option.

Exceptions

  Exception::UnregisteredParameter | is thrown if the parameter was not registered
  Exception::RequiredParameterNotGiven | is if a required parameter is not present
  Exception::WrongParameterType | is thrown if the parameter has the wrong type
  Exception::InvalidParameter | is thrown if the parameter restrictions are not met

## ◆ getSubsection_()

String getSubsection_ | ( | const String & | name | ) | const

private

Get the part of a parameter name that makes up the subsection.

The subsection extends until the last colon (":"). If there is no subsection, the empty string is returned.

## ◆ getSubsectionDefaults_() [1/2]

virtual Param getSubsectionDefaults_ | ( | const String & | section | ) | const

private virtual

This method should return the default parameters for subsections.

It is called once for each registered subsection, when writing the example ini file.

Reimplement this method to set the defaults written in the 'write_ini' method.

Note
  Make sure to set the 'advanced' flag of the parameters right in order to hide certain parameters from inexperienced users.

Reimplemented in Epifany.

## ◆ getSubsectionDefaults_() [2/2]

Param getSubsectionDefaults_ | ( |  | ) | const

private

Returns a single Param object containing all subsection parameters.

Returns
  A single Param object containing all parameters for all registered subsections.

See also
  getSubsectionDefaults_(String)

## ◆ getToolUserDefaults_()

Param getToolUserDefaults_ | ( | const String & | tool_name | ) | const

private

Returns the user defaults for the given tool, if any default parameters are stored in the users home.

## ◆ inputFileReadable_()

void inputFileReadable_ | ( | const String & | filename,
|  | const String & | param_name
| ) |  | const

protected

Checks if an input file exists, is readable and is not empty.

The filename is a URI to the file to be read and param_name gives the name of the parameter , e.g. "in" which specified the filename (this is useful for error messages when the file cannot be read, so the user can immediately see which parameter to change). If no parameter is responsible for the name of the input file, then leave param_name empty.

Parameters

  filename | An absolute or relative path+filename
  param_name | Name of the parameter the filename value was provided by

Exceptions

  Exception::FileNotFound | is thrown if the file is not found
  Exception::FileNotReadable | is thrown if the file is not readable
  Exception::FileEmpty | is thrown if the file is empty

## ◆ main()

ExitCodes main | ( | int | argc,
|  | const char ** | argv
| ) |  |

Main routine of all TOPP applications.

Referenced by main().

## ◆ main_()

virtual ExitCodes main_ | ( | int | argc,
|  | const char ** | argv
| ) |  |

protected pure virtual

The actual "main" method. main_() is invoked by main().

Implemented in UTILProteomicsLFQ, NucleicAcidSearchEngine, Epifany, and TOPPGNPSExport.

## ◆ makeAutoRemoveTempDirectory_()

String makeAutoRemoveTempDirectory_ | ( | Int | keep_debug = `2` | ) |

protected

Creates a unique temporary directory and returns its name (will be cleaned up automatically if debug level is high enough)

## ◆ makeTempDirectory_()

String makeTempDirectory_ | ( |  | ) | const

protected

Creates a unique temporary directory and returns its name (you have to clean it up yourself)

## ◆ outputFileWritable_()

void outputFileWritable_ | ( | const String & | filename,
|  | const String & | param_name
| ) |  | const

protected

Checks if an output file is writable.

The filename is a URI to the file to be written and param_name gives the name of the parameter , e.g. "out" which specified the filename (this is useful for error messages when the file cannot be written, so the user can immediately see which parameter to change). If no parameter is responsible for the name of the output file, then leave param_name empty.

Exceptions

  Exception::UnableToCreateFile | is thrown if the file cannot be created

## ◆ paramEntryToParameterInformation_()

ParameterInformation paramEntryToParameterInformation_ | ( | const Param::ParamEntry & | entry,
|  | const String & | argument = `""`,
|  | const String & | full_name = `""`
| ) |  | const

protected

Transforms a ParamEntry object to command line parameter (ParameterInformation).

A ParamEntry of type String is turned into a flag if its default value is "false" and its valid strings are "true" and "false".

Parameters

  entry | The ParamEntry that defines name, default value, description, restrictions, and required-/advancedness (via tags) of the parameter.
  argument | Argument description text for the help output.
  full_name | Full name of the parameter, if different from the name in the ParamEntry (ParamEntry names cannot contain sections)

## ◆ paramToParameterInformation_()

std::vector<ParameterInformation> paramToParameterInformation_ | ( | const Param & | param | ) | const

protected

Translates the given parameter object into a vector of ParameterInformation, that can be utilized for cl parsing.

## ◆ parseCommandLine_()

Param parseCommandLine_ | ( | const int | argc,
|  | const char ** | argv,
|  | const String & | misc = `"misc"`,
|  | const String & | unknown = `"unknown"`
| ) |  |

private

Parses command line arguments using parameter definitions from TOPPBase.

Parses command line arguments according to the current parameter definitions and returns the result as a Param object.

Parameters

  argc | `argc` variable from command line
  argv | `argv` variable from command line
  misc | Key to store a StringList of all non-option arguments
  unknown | Key to store a StringList of all unknown options

Returns
  A Param object representing the parameters set on the command line.

## ◆ parseRange_() [1/2]

bool parseRange_ | ( | const String & | text,
|  | double & | low,
|  | double & | high
| ) |  | const

protected

Parses a range string ([a]:[b]) into two variables (doubles)

The variables are only overwritten if a value is set for the respective boundary.

Returns
  True if a value was set for either of the two boundaries

## ◆ parseRange_() [2/2]

bool parseRange_ | ( | const String & | text,
|  | Int & | low,
|  | Int & | high
| ) |  | const

protected

Parses a range string ([a]:[b]) into two variables (integers)

The variables are only overwritten if a value is set for the respective boundary.

Returns
  True if a value was set for either of the two boundaries

## ◆ printUsage_()

void printUsage_ | ( |  | ) |

protected

Prints the tool-specific command line options and appends the common options.

## ◆ registerDoubleList_()

void registerDoubleList_ | ( | const String & | name,
|  | const String & | argument,
|  | DoubleList | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a list of doubles option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerDoubleOption_()

void registerDoubleOption_ | ( | const String & | name,
|  | const String & | argument,
|  | double | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a double option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerFlag_()

void registerFlag_ | ( | const String & | name,
|  | const String & | description,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a flag.

## ◆ registerFullParam_()

void registerFullParam_ | ( | const Param & | param | ) |

protected

Register command line parameters for all entries in a Param object.

## ◆ registerInputFile_()

void registerInputFile_ | ( | const String & | name,
|  | const String & | argument,
|  | const String & | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`,
|  | const StringList & | tags = `StringList()`
| ) |  |

protected

Registers an input file option.

Input files behave like string options, but are automatically checked with inputFileReadable_() when the option is accessed in the TOPP tool. This may also enable lookup on the PATH or skipping of the existance-check (see `tags`).

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (verified in getStringOption())
  advanced | If true, this parameter is advanced and by default hidden in the GUI.
  tags | A list of tags, extending/omitting automated checks on the input file (e.g. when its an executable) Valid tags: 'skipexists' - will prevent checking if the given file really exists (useful for partial paths, e.g. in OpenMS/share/... which will be resolved by the TOPP tool internally) 'is_executable' - checks existance of the file first using its actual value, and upon failure also using the PATH environment (and common exe file endings on Windows, e.g. .exe and .bat).

## ◆ registerInputFileList_()

void registerInputFileList_ | ( | const String & | name,
|  | const String & | argument,
|  | StringList | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`,
|  | const StringList & | tags = `StringList()`
| ) |  |

protected

Registers a list of input files option.

A list of input files behaves like a StringList, but are automatically checked with inputFileWritable_() when the option is accessed in the TOPP tool.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.
  tags | A list of tags, extending/omitting automated checks on the input file (e.g. when its an executable) Valid tags: 'skipexists' - will prevent checking if the given file really exists (useful for partial paths, e.g. in OpenMS/share/... which will be resolved by the TOPP tool internally) 'is_executable' - checks existance of the file using the PATH environment (and common exe file endings on Windows, e.g. .exe and .bat).

## ◆ registerIntList_()

void registerIntList_ | ( | const String & | name,
|  | const String & | argument,
|  | IntList | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a list of integers option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerIntOption_()

void registerIntOption_ | ( | const String & | name,
|  | const String & | argument,
|  | Int | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers an integer option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerOptionsAndFlags_()

virtual void registerOptionsAndFlags_ | ( |  | ) |

protected pure virtual

Sets the valid command line options (with argument) and flags (without argument).

The options '-ini' '-log' '-instance' '-debug' and the flag '–help' are automatically registered.

Implemented in NucleicAcidSearchEngine, UTILProteomicsLFQ, Epifany, and TOPPGNPSExport.

## ◆ registerOutputFile_()

void registerOutputFile_ | ( | const String & | name,
|  | const String & | argument,
|  | const String & | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers an output file option.

Output files behave like string options, but are automatically checked with outputFileWritable_() when the option is accessed in the TOPP tool.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerOutputFileList_()

void registerOutputFileList_ | ( | const String & | name,
|  | const String & | argument,
|  | StringList | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a list of output files option.

A list of output files behaves like a StringList, but are automatically checked with outputFileWritable_() when the option is accessed in the TOPP tool.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerParamSubsectionsAsTOPPSubsections_()

void registerParamSubsectionsAsTOPPSubsections_ | ( | const Param & | param | ) |

protected

## ◆ registerStringList_()

void registerStringList_ | ( | const String & | name,
|  | const String & | argument,
|  | StringList | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a list of strings option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerStringOption_()

void registerStringOption_ | ( | const String & | name,
|  | const String & | argument,
|  | const String & | default_value,
|  | const String & | description,
|  | bool | required = `true`,
|  | bool | advanced = `false`
| ) |  |

protected

Registers a string option.

Parameters

  name | Name of the option in the command line and the INI file
  argument | Argument description text for the help output
  default_value | Default argument
  description | Description of the parameter. Indentation of newline is done automatically.
  required | If the user has to provide a value i.e. if the value has to differ from the default (checked in get-method)
  advanced | If true, this parameter is advanced and by default hidden in the GUI.

## ◆ registerSubsection_()

void registerSubsection_ | ( | const String & | name,
|  | const String & | description
| ) |  |

protected

Registers an allowed subsection in the INI file (usually from OpenMS algorithms).

Use this method to register subsections that are passed to algorithms.

See also
  checkParam_

## ◆ registerTOPPSubsection_()

void registerTOPPSubsection_ | ( | const String & | name,
|  | const String & | description
| ) |  |

protected

Registers an allowed subsection in the INI file originating from the TOPP tool itself.

Use this method to register subsections which is created by a commandline param (registered by e.g. registerDoubleOption_() ) and contains a ':' in its name. This is done to distinguish these parameters from normal subsections, which are filled by calling 'getSubsectionDefaults_()'. This is not necessary for here.

See also
  checkParam_

## ◆ removeTempDirectory_()

void removeTempDirectory_ | ( | const String & | dirname,
|  | Int | keep_debug = `2`
| ) |  | const

protected

Removes a (temporary) directory.

If `keep_debug` is set to a positive value (> 0), the directory is kept if the current debug level (`debug_level_`) is at least at that value.

## ◆ runExternalProcess_()

ExitCodes runExternalProcess_ | ( | const QString & | executable,
|  | const QStringList & | arguments,
|  | const QString & | workdir = `""`
| ) |  | const

protected

Runs an external process via QProcess and reports its status in the logs.

## ◆ setMaxFloat_()

void setMaxFloat_ | ( | const String & | name,
|  | double | max
| ) |  |

protected

Sets the maximum value for the floating point parameter(can be a list of floating points,too) `name`.

Exceptions

  Exception::ElementNotFound | is thrown if `name` is not found or if the parameter type is wrong

## ◆ setMaxInt_()

void setMaxInt_ | ( | const String & | name,
|  | Int | max
| ) |  |

protected

Sets the maximum value for the integer parameter(can be a list of integers,too) `name`.

Exceptions

  Exception::ElementNotFound | is thrown if `name` is not found or if the parameter type is wrong

## ◆ setMaxNumberOfThreads()

static void setMaxNumberOfThreads | ( | int | num_threads | ) |

static

Sets the maximal number of usable threads.

Parameters

  num_threads | The number of threads that should be usable.

Note
  This method only works if OpenMS is compiled with OpenMP support.

## ◆ setMinFloat_()

void setMinFloat_ | ( | const String & | name,
|  | double | min
| ) |  |

protected

Sets the minimum value for the floating point parameter(can be a list of floating points,too) `name`.

Exceptions

  Exception::ElementNotFound | is thrown if `name` is not found or if the parameter type is wrong

## ◆ setMinInt_()

void setMinInt_ | ( | const String & | name,
|  | Int | min
| ) |  |

protected

Sets the minimum value for the integer parameter(can be a list of integers,too) `name`.

Exceptions

  Exception::ElementNotFound | is thrown if `name` is not found or if the parameter type is wrong

## ◆ setValidFormats_()

void setValidFormats_ | ( | const String & | name,
|  | const std::vector< String > & | formats,
|  | const bool | force_OpenMS_format = `true`
| ) |  |

protected

Sets the formats for a input/output file option or for all members of an input/output file lists.

Setting the formats causes a check for the right file format (input file) or the right file extension (output file). This check is performed only, when the option is accessed in the TOPP tool. When `force_OpenMS_format` is set, only formats known to OpenMS internally are allowed (default).

Exceptions

  Exception::ElementNotFound | is thrown if the parameter is unset or not a file parameter
  Exception::InvalidParameter | is thrown if an unknown format name is used (

See also
  FileHandler::Type)

## ◆ setValidStrings_() [1/2]

void setValidStrings_ | ( | const String & | name,
|  | const std::vector< String > & | strings
| ) |  |

protected

Sets the valid strings for a string option or a whole string list.

Exceptions

  Exception::ElementNotFound | is thrown if the parameter is unset or not a string parameter
  Exception::InvalidParameter | is thrown if the valid strings contain comma characters

## ◆ setValidStrings_() [2/2]

void setValidStrings_ | ( | const String & | name,
|  | const std::string | vstrings[],
|  | int | count
| ) |  |

protected

Sets the valid strings for a string option or a whole string list.

This overload should be used for options which are 1:1 with Enums + their static string representations. E.g. MSNumpressCoder::NamesOfNumpressCompression[]

Exceptions

  Exception::ElementNotFound | is thrown if the parameter is unset or not a string parameter
  Exception::InvalidParameter | is thrown if the valid strings contain comma characters

## ◆ toolName_()

const String& toolName_ | ( |  | ) | const

protected

Returns the tool name.

## ◆ writeCTD_()

bool writeCTD_ | ( |  | ) |

protected

Write common tool description (CTD) file.

## ◆ writeDebug_() [1/2]

void writeDebug_ | ( | const String & | text,
|  | UInt | min_level
| ) |  | const

protected

Writes a `text` to the log file and to std::cout if the debug level is at least `min_level`.

## ◆ writeDebug_() [2/2]

void writeDebug_ | ( | const String & | text,
|  | const Param & | param,
|  | UInt | min_level
| ) |  | const

protected

Writes a String followed by a Param to the log file and to std::cout if the debug level is at least `min_level`.

## ◆ writeLog_()

void writeLog_ | ( | const String & | text | ) | const

protected

Writes a string to the log file and to std::cout.

## Member Data Documentation

## ◆ citations_

std::vector<Citation> citations_

protected

Papers, specific for this tool (will be shown in '–help')

## ◆ cite_openms_

const Citation cite_openms_

static protected

The OpenMS citation.

## ◆ debug_level_

Int debug_level_

protected

Debug level set by -debug.

## ◆ ini_location_

String const ini_location_

private

Location in the ini file where to look for parameters.

## ◆ instance_number_

Int const instance_number_

private

Instance number.

## ◆ log_

std::ofstream log_

mutable private

Log file stream. Use the writeLog_() and writeDebug_() methods to access it.

## ◆ log_type_

ProgressLogger::LogType log_type_

protected

Type of progress logging.

Referenced by TOPPOpenSwathBase::loadSwathFiles_(), TOPPOpenSwathBase::loadTransitionList(), and TOPPOpenSwathBase::performCalibration().

## ◆ official_

bool official_

protected

Flag indicating if this an official TOPP tool.

## ◆ param_

Param param_

private

All parameters relevant to this invocation of the program.

## ◆ param_cmdline_

Param param_cmdline_

private

Parameters from command line.

## ◆ param_common_

Param param_common_

private

Parameters from common section without tool name.

## ◆ param_common_tool_

Param param_common_tool_

private

Parameters from common section with tool name.

## ◆ param_inifile_

Param param_inifile_

private

All parameters specified in the ini file.

## ◆ param_instance_

Param param_instance_

private

Parameters from instance section.

## ◆ parameters_

std::vector<ParameterInformation> parameters_

private

Storage location for parameter information.

## ◆ subsections_

std::map<String, String> subsections_

private

Storage location and description for allowed subsections.

## ◆ subsections_TOPP_

std::map<String, String> subsections_TOPP_

private

Storage location and description for allowed subsections from TOPP tool's command-line parameters.

## ◆ test_mode_

bool test_mode_

protected

Test mode.

Test mode is enabled using the command line parameter -test .

It disables writing of data, which would corrupt tests:

- absolute paths (e.g. in consensus maps)
- processing parameters (input/output files contain absolute paths as well)
- current date
- current OpenMS version

## ◆ tool_description_

String const tool_description_

private

Tool description. This is assigned once and for all in the constructor.

## ◆ tool_name_

String const tool_name_

private

Tool name. This is assigned once and for all in the constructor.

## ◆ topp_ini_file_

String topp_ini_file_

static protected

.TOPP.ini file for storing system default parameters

## ◆ verboseVersion_

String verboseVersion_

protected

Version string including additional revision/date time information. Note: This differs from version_ only if not provided by the user.

## ◆ version_

String version_

protected

Version string (if empty, the OpenMS/TOPP version is printed)

## ◆ working_dir_

String working_dir_

private

An optional temporary working directory.

## ◆ working_dir_keep_debug_lvl_

Int working_dir_keep_debug_lvl_

private

Debug level at which to keep working dir.