OpenMS  3.0.0
TOPPBase.h
Go to the documentation of this file.
1 // --------------------------------------------------------------------------
2 // OpenMS -- Open-Source Mass Spectrometry
3 // --------------------------------------------------------------------------
4 // Copyright The OpenMS Team -- Eberhard Karls University Tuebingen,
5 // ETH Zurich, and Freie Universitaet Berlin 2002-2022.
6 //
7 // This software is released under a three-clause BSD license:
8 // * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 // * Redistributions in binary form must reproduce the above copyright
11 // notice, this list of conditions and the following disclaimer in the
12 // documentation and/or other materials provided with the distribution.
13 // * Neither the name of any author or any participating institution
14 // may be used to endorse or promote products derived from this software
15 // without specific prior written permission.
16 // For a full list of authors, refer to the file AUTHORS.
17 // --------------------------------------------------------------------------
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 // ARE DISCLAIMED. IN NO EVENT SHALL ANY OF THE AUTHORS OR THE CONTRIBUTING
22 // INSTITUTIONS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
27 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
28 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 //
30 // --------------------------------------------------------------------------
31 // $Maintainer: Timo Sachsenberg $
32 // $Authors: Marc Sturm, Clemens Groepl $
33 // --------------------------------------------------------------------------
34 
35 #pragma once
36 
41 
44 
46 
48 
49 #include <fstream>
50 
51 #include <QString>
52 
53 class QStringList;
54 
55 namespace OpenMS
56 {
57  class FeatureMap;
58  class ConsensusMap;
59  struct ParameterInformation;
60 
73  struct Citation
74  {
75  std::string authors;
76  std::string title;
77  std::string when_where;
78  std::string doi;
79 
81  std::string toString() const
82  {
83  return authors + ". " + title + ". " + when_where + ". doi:" + doi + ".";
84  }
85  };
86 
87  namespace Exception
88  {
90  class OPENMS_DLLAPI UnregisteredParameter :
92  {
93 public:
94  UnregisteredParameter(const char* file, int line, const char* function, const String& parameter) :
95  BaseException(file, line, function, "UnregisteredParameter", parameter)
96  {
98  }
99 
100  };
102  class OPENMS_DLLAPI WrongParameterType :
104  {
105 public:
106  WrongParameterType(const char* file, int line, const char* function, const String& parameter) :
107  BaseException(file, line, function, "WrongParameterType", parameter)
108  {
110  }
111 
112  };
114  class OPENMS_DLLAPI RequiredParameterNotGiven :
116  {
117 public:
118  RequiredParameterNotGiven(const char* file, int line, const char* function, const String& parameter) :
119  BaseException(file, line, function, "RequiredParameterNotGiven", parameter)
120  {
122  }
123 
124  };
125  }
126 
147  class OPENMS_DLLAPI TOPPBase
148  {
149 public:
150 
153  {
167  UNEXPECTED_RESULT
168  };
169 
170 
171 
173  TOPPBase() = delete;
174 
176  TOPPBase(const TOPPBase&) = delete;
177 
188  TOPPBase(const String& name, const String& description, bool official = true, const std::vector<Citation>& citations = {}, bool toolhandler_test = true);
189 
191  virtual ~TOPPBase();
192 
194  ExitCodes main(int argc, const char** argv);
195 
203  static void setMaxNumberOfThreads(int num_threads);
204 
212  String getToolPrefix() const;
213 
214 private:
217 
220 
223 
226 
229 
232 
235 
238 
241 
244 
246  mutable std::ofstream log_;
247 
256  void enableLogging_() const;
257 
259  std::vector<ParameterInformation> parameters_;
260 
270  virtual Param getSubsectionDefaults_(const String& section) const;
271 
279  Param getSubsectionDefaults_() const;
280 
282  std::map<String, String> subsections_;
283 
285  std::map<String, String> subsections_TOPP_;
286 
287 
300  Param parseCommandLine_(const int argc, const char** argv, const String& misc = "misc", const String& unknown = "unknown");
301 
311  String getParamAsString_(const String& key, const String& default_value = "") const;
312 
318  Int getParamAsInt_(const String& key, Int default_value = 0) const;
319 
325  double getParamAsDouble_(const String& key, double default_value = 0) const;
326 
332  StringList getParamAsStringList_(const String& key, const StringList& default_value) const;
333 
339  IntList getParamAsIntList_(const String& key, const IntList& default_value) const;
340 
346  DoubleList getParamAsDoubleList_(const String& key, const DoubleList& default_value) const;
347 
357  bool getParamAsBool_(const String& key) const;
358 
370  const ParamValue& getParam_(const String& key) const;
371 
377  String getSubsection_(const String& name) const;
378 
380  String getDocumentationURL() const;
381 
383  Param getDefaultParameters_() const;
384 
386  Param getToolUserDefaults_(const String& tool_name) const;
388 
389 protected:
392 
395 
397  bool official_;
398 
400  std::vector<Citation> citations_;
401 
404 
412  const String& getIniLocation_() const
413  {
414  return ini_location_;
415  }
416 
418  const String& toolName_() const;
419 
440  virtual void registerOptionsAndFlags_() = 0;
441 
443  String getParamArgument_(const Param::ParamEntry& entry) const;
444 
446  std::vector<ParameterInformation> paramToParameterInformation_(const Param& param) const;
447 
457  ParameterInformation paramEntryToParameterInformation_(const Param::ParamEntry& entry, const String& argument = "", const String& full_name = "") const;
458 
459  void registerParamSubsectionsAsTOPPSubsections_(const Param& param);
460 
462  void registerFullParam_(const Param& param);
463 
474  void registerStringOption_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
475 
482  void setValidStrings_(const String& name, const std::vector<String>& strings);
483 
493  void setValidStrings_(const String& name, const std::string vstrings[], int count);
494 
512  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());
513 
527  void registerOutputFile_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
528 
549  void registerOutputPrefix_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
550 
563  void setValidFormats_(const String& name, const std::vector<String>& formats, const bool force_OpenMS_format = true);
564 
565 
576  void registerDoubleOption_(const String& name, const String& argument, double default_value, const String& description, bool required = true, bool advanced = false);
577 
583  void setMinInt_(const String& name, Int min);
589  void setMaxInt_(const String& name, Int max);
595  void setMinFloat_(const String& name, double min);
601  void setMaxFloat_(const String& name, double max);
602 
613  void registerIntOption_(const String& name, const String& argument,
614  Int default_value, const String& description,
615  bool required = true, bool advanced = false);
616 
628  void registerIntList_(const String& name, const String& argument, IntList default_value, const String& description, bool required = true, bool advanced = false);
629 
640  void registerDoubleList_(const String& name, const String& argument, DoubleList default_value, const String& description, bool required = true, bool advanced = false);
641 
652  void registerStringList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false);
653 
670  void registerInputFileList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false, const StringList& tags = StringList());
671 
685  void registerOutputFileList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false);
686 
688  void registerFlag_(const String& name, const String& description, bool advanced = false);
689 
697  void registerSubsection_(const String& name, const String& description);
698 
708  void registerTOPPSubsection_(const String& name, const String& description);
709 
710 
712  void addEmptyLine_();
713 
714 
723  String getStringOption_(const String& name) const;
724 
733  double getDoubleOption_(const String& name) const;
734 
743  Int getIntOption_(const String& name) const;
744 
753  StringList getStringList_(const String& name) const;
754 
763  IntList getIntList_(const String& name) const;
764 
773  DoubleList getDoubleList_(const String& name) const;
774 
776  bool getFlag_(const String& name) const;
777 
783  const ParameterInformation& findEntry_(const String& name) const;
784 
790  Param const& getParam_() const;
791 
805  void checkParam_(const Param& param, const String& filename, const String& location) const;
806 
817  void fileParamValidityCheck_(const StringList& param_value, const String& param_name, const ParameterInformation& p) const;
818 
834  void fileParamValidityCheck_(String& param_value, const String& param_name, const ParameterInformation& p) const;
835 
843  void checkIfIniParametersAreApplicable_(const Param& ini_params);
845 
847  void printUsage_();
848 
850  virtual ExitCodes main_(int argc, const char** argv) = 0;
851 
853 
854  void writeLog_(const String& text) const;
856 
858  void writeDebug_(const String& text, UInt min_level) const;
859 
861  void writeDebug_(const String& text, const Param& param, UInt min_level) const;
863 
865 
866  ExitCodes runExternalProcess_(const QString& executable, const QStringList& arguments, const QString& workdir = "") const;
868 
871  ExitCodes runExternalProcess_(const QString& executable, const QStringList& arguments, String& proc_stdout, String& proc_stderr, const QString& workdir = "") const;
873 
900  void inputFileReadable_(const String& filename, const String& param_name) const;
901 
912  void outputFileWritable_(const String& filename, const String& param_name) const;
914 
922  bool parseRange_(const String& text, double& low, double& high) const;
923 
931  bool parseRange_(const String& text, Int& low, Int& high) const;
932 
935 
937 
938 
940  void addDataProcessing_(ConsensusMap& map, const DataProcessing& dp) const;
941 
943  void addDataProcessing_(FeatureMap& map, const DataProcessing& dp) const;
944 
946  void addDataProcessing_(PeakMap& map, const DataProcessing& dp) const;
947 
949  DataProcessing getProcessingInfo_(DataProcessing::ProcessingAction action) const;
950 
952  DataProcessing getProcessingInfo_(const std::set<DataProcessing::ProcessingAction>& actions) const;
953 
955 
957  bool writeCTD_();
958 
971 
974 
976  static const Citation cite_openms_;
977 
980 private:
981 
987  void addText_(const String& text);
988 
996  ParameterInformation& getParameterByName_(const String& name);
997 
998  };
999 
1000 } // namespace OpenMS
1001 
LogStream.h
OpenMS::TOPPBase::debug_level_
Int debug_level_
Debug level set by -debug.
Definition: TOPPBase.h:979
OpenMS::TOPPBase::param_inifile_
Param param_inifile_
All parameters specified in the ini file.
Definition: TOPPBase.h:231
OpenMS::TOPPBase
Base class for TOPP applications.
Definition: TOPPBase.h:147
OpenMS::TOPPBase::subsections_TOPP_
std::map< String, String > subsections_TOPP_
Storage location and description for allowed subsections from TOPP tool's command-line parameters.
Definition: TOPPBase.h:285
OpenMS::TOPPBase::log_type_
ProgressLogger::LogType log_type_
Type of progress logging.
Definition: TOPPBase.h:934
OpenMS::TOPPBase::log_
std::ofstream log_
Log file stream. Use the writeLog_() and writeDebug_() methods to access it.
Definition: TOPPBase.h:246
OpenMS::TOPPBase::tool_name_
const String tool_name_
Tool name. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:216
OpenMS::TOPPBase::ILLEGAL_PARAMETERS
Definition: TOPPBase.h:160
OpenMS::Param::ParamEntry
Parameter entry used to store the actual information inside of a Param entry.
Definition: Param.h:74
OpenMS::Citation::when_where
std::string when_where
suggested format: journal. year; volume, issue: pages
Definition: TOPPBase.h:77
OpenMS::TOPPBase::citations_
std::vector< Citation > citations_
Papers, specific for this tool (will be shown in '–help')
Definition: TOPPBase.h:400
OpenMS::TOPPBase::test_mode_
bool test_mode_
Test mode.
Definition: TOPPBase.h:970
OpenMS::TOPPBase::param_common_tool_
Param param_common_tool_
Parameters from common section with tool name.
Definition: TOPPBase.h:240
OpenMS::Citation::toString
std::string toString() const
mangle members to string
Definition: TOPPBase.h:81
OpenMS::TOPPBase::verboseVersion_
String verboseVersion_
Version string including additional revision/date time information. Note: This differs from version_ ...
Definition: TOPPBase.h:394
OpenMS::TOPPBase::param_instance_
Param param_instance_
Parameters from instance section.
Definition: TOPPBase.h:237
OpenMS::String
A more convenient string class.
Definition: String.h:58
OpenMS::DoubleList
std::vector< double > DoubleList
Vector of double precision real types.
Definition: ListUtils.h:62
OpenMS::MSExperiment
In-Memory representation of a mass spectrometry run.
Definition: MSExperiment.h:70
OpenMS::TOPPBase::INPUT_FILE_NOT_READABLE
Definition: TOPPBase.h:156
OpenMS::Exception::GlobalExceptionHandler::getInstance
static GlobalExceptionHandler & getInstance()
The accessor for the singleton. It also serves as a replacement for the constructor.
Definition: GlobalExceptionHandler.h:88
OpenMS::TOPPBase::topp_ini_file_
static String topp_ini_file_
.TOPP.ini file for storing system default parameters
Definition: TOPPBase.h:973
OpenMS::TOPPBase::EXTERNAL_PROGRAM_ERROR
Definition: TOPPBase.h:163
OpenMS::ParamValue
Class to hold strings, numeric values, vectors of strings and vectors of numeric values using the stl...
Definition: ParamValue.h:54
OpenMS::IntList
std::vector< Int > IntList
Vector of signed integers.
Definition: ListUtils.h:55
OpenMS::TOPPBase::INPUT_FILE_NOT_FOUND
Definition: TOPPBase.h:155
OpenMS::Citation::title
std::string title
title of article
Definition: TOPPBase.h:76
OpenMS::TOPPBase::tool_description_
const String tool_description_
Tool description. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:219
OpenMS::Citation::authors
std::string authors
list of authors in AMA style, i.e. "surname initials", ...
Definition: TOPPBase.h:75
OpenMS::Citation::doi
std::string doi
plain DOI (no urls), e.g. 10.1021/pr100177k
Definition: TOPPBase.h:78
OpenMS::TOPPBase::INPUT_FILE_EMPTY
Definition: TOPPBase.h:158
OpenMS::Exception::WrongParameterType
A parameter was accessed with the wrong type.
Definition: TOPPBase.h:102
OpenMS::TOPPBase::getIniLocation_
const String & getIniLocation_() const
Returns the location of the ini file where parameters are taken from. E.g. if the command line was TO...
Definition: TOPPBase.h:412
OpenMS::Int
int Int
Signed integer type.
Definition: Types.h:102
OpenMS
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:47
OpenMS::DataProcessing::ProcessingAction
ProcessingAction
Definition: DataProcessing.h:58
OpenMS::Exception::GlobalExceptionHandler::setMessage
static void setMessage(const std::string &message)
DataProcessing.h
Exception.h
ProgressLogger.h
OpenMS::Exception::UnregisteredParameter
An unregistered parameter was accessed.
Definition: TOPPBase.h:90
OpenMS::TOPPBase::official_
bool official_
Flag indicating if this an official TOPP tool.
Definition: TOPPBase.h:397
Param.h
OpenMS::TOPPBase::EXECUTION_OK
Definition: TOPPBase.h:154
OpenMS::Exception::UnregisteredParameter::UnregisteredParameter
UnregisteredParameter(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:94
OpenMS::Exception::BaseException
Exception base class.
Definition: Exception.h:89
OpenMS::TOPPBase::PARSE_ERROR
Definition: TOPPBase.h:164
OpenMS::TOPPBase::INCOMPATIBLE_INPUT_DATA
Definition: TOPPBase.h:165
OpenMS::Citation
Stores Citations for individual TOPP tools.
Definition: TOPPBase.h:73
OpenMS::ConsensusMap
A container for consensus elements.
Definition: ConsensusMap.h:82
OpenMS::StringList
std::vector< String > StringList
Vector of String.
Definition: ListUtils.h:70
OpenMS::UInt
unsigned int UInt
Unsigned integer type.
Definition: Types.h:94
OpenMS::ProgressLogger::LogType
LogType
Possible log types.
Definition: ProgressLogger.h:68
OpenMS::TOPPBase::param_
Param param_
All parameters relevant to this invocation of the program.
Definition: TOPPBase.h:228
main
int main(int argc, const char **argv)
Definition: INIFileEditor.cpp:71
OpenMS::TOPPBase::INTERNAL_ERROR
Definition: TOPPBase.h:166
OpenMS::Exception::RequiredParameterNotGiven
A required parameter was not given.
Definition: TOPPBase.h:114
OpenMS::FeatureMap
A container for features.
Definition: FeatureMap.h:98
OpenMS::ParameterInformation
Struct that captures all information of a command line parameter.
Definition: ParameterInformation.h:47
OpenMS::TOPPBase::ini_location_
const String ini_location_
Location in the ini file where to look for parameters.
Definition: TOPPBase.h:225
OpenMS::TOPPBase::cite_openms_
static const Citation cite_openms_
The OpenMS citation.
Definition: TOPPBase.h:976
OpenMS::Exception::RequiredParameterNotGiven::RequiredParameterNotGiven
RequiredParameterNotGiven(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:118
OpenMS::TOPPBase::UNKNOWN_ERROR
Definition: TOPPBase.h:162
OpenMS::DataProcessing
Description of the applied preprocessing steps.
Definition: DataProcessing.h:51
tool_name
const char * tool_name
Definition: SwathWizard.cpp:145
OpenMS::TOPPBase::ExitCodes
ExitCodes
Exit codes.
Definition: TOPPBase.h:152
String.h
OpenMS::Param
Management and storage of parameters / INI files.
Definition: Param.h:69
OpenMS::TOPPBase::toolhandler_test_
bool toolhandler_test_
Enable the ToolHandler tests.
Definition: TOPPBase.h:403
OpenMS::TOPPBase::parameters_
std::vector< ParameterInformation > parameters_
Storage location for parameter information.
Definition: TOPPBase.h:259
OpenMS::TOPPBase::param_common_
Param param_common_
Parameters from common section without tool name.
Definition: TOPPBase.h:243
OpenMS::TOPPBase::version_
String version_
Version string (if empty, the OpenMS/TOPP version is printed)
Definition: TOPPBase.h:391
OpenMS::TOPPBase::MISSING_PARAMETERS
Definition: TOPPBase.h:161
OpenMS::TOPPBase::instance_number_
const Int instance_number_
Instance number.
Definition: TOPPBase.h:222
OpenMS::TOPPBase::subsections_
std::map< String, String > subsections_
Storage location and description for allowed subsections.
Definition: TOPPBase.h:282
OpenMS::TOPPBase::INPUT_FILE_CORRUPT
Definition: TOPPBase.h:157
StandardTypes.h
GlobalExceptionHandler.h
OpenMS::TOPPBase::CANNOT_WRITE_OUTPUT_FILE
Definition: TOPPBase.h:159
OpenMS::Exception::WrongParameterType::WrongParameterType
WrongParameterType(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:106
OpenMS::TOPPBase::param_cmdline_
Param param_cmdline_
Parameters from command line.
Definition: TOPPBase.h:234