| OpenMS 2.5.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-2020.
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
37 #include <OpenMS/CONCEPT/Exception.h>
38 #include <OpenMS/CONCEPT/GlobalExceptionHandler.h>
39 #include <OpenMS/CONCEPT/ProgressLogger.h>
40
41 #include <OpenMS/DATASTRUCTURES/Param.h>
42 #include <OpenMS/DATASTRUCTURES/String.h>
43
44 #include <OpenMS/METADATA/DataProcessing.h>
45
46 #include <OpenMS/KERNEL/StandardTypes.h>
47
48 #include <fstream>
49
50 class QStringList;
51
52 namespace OpenMS
53 {
54 class FeatureMap;
55 class ConsensusMap;
56 struct ParameterInformation;
57
70 struct Citation
71 {
72 std::string authors;
73 std::string title;
74 std::string when_where;
75 std::string doi;
76
78 std::string toString() const
79 {
80 return authors + ". " + title + ". " + when_where + ". doi:" + doi + ".";
81 }
82 };
83
84 namespace Exception
85 {
87 class OPENMS_DLLAPI UnregisteredParameter :
88 public Exception::BaseException
89 {
90 public:
91 UnregisteredParameter(const char* file, int line, const char* function, const String& parameter) :
92 BaseException(file, line, function, "UnregisteredParameter", parameter)
93 {
94 GlobalExceptionHandler::getInstance().setMessage(what_);
95 }
96
97 };
99 class OPENMS_DLLAPI WrongParameterType :
100 public Exception::BaseException
101 {
102 public:
103 WrongParameterType(const char* file, int line, const char* function, const String& parameter) :
104 BaseException(file, line, function, "WrongParameterType", parameter)
105 {
106 GlobalExceptionHandler::getInstance().setMessage(what_);
107 }
108
109 };
111 class OPENMS_DLLAPI RequiredParameterNotGiven :
112 public Exception::BaseException
113 {
114 public:
115 RequiredParameterNotGiven(const char* file, int line, const char* function, const String& parameter) :
116 BaseException(file, line, function, "RequiredParameterNotGiven", parameter)
117 {
118 GlobalExceptionHandler::getInstance().setMessage(what_);
119 }
120
121 };
122 }
123
144 class OPENMS_DLLAPI TOPPBase
145 {
146 public:
147
149 enum ExitCodes
150 {
151 EXECUTION_OK,
152 INPUT_FILE_NOT_FOUND,
153 INPUT_FILE_NOT_READABLE,
154 INPUT_FILE_CORRUPT,
155 INPUT_FILE_EMPTY,
156 CANNOT_WRITE_OUTPUT_FILE,
157 ILLEGAL_PARAMETERS,
158 MISSING_PARAMETERS,
159 UNKNOWN_ERROR,
160 EXTERNAL_PROGRAM_ERROR,
161 PARSE_ERROR,
162 INCOMPATIBLE_INPUT_DATA,
163 INTERNAL_ERROR,
164 UNEXPECTED_RESULT
165 };
166
177 TOPPBase(const String& name, const String& description, bool official = true, const std::vector<Citation>& citations = {});
178
180 virtual ~TOPPBase();
181
183 ExitCodes main(int argc, const char** argv);
184
192 static void setMaxNumberOfThreads(int num_threads);
193
194 private:
196 String const tool_name_;
197
199 String const tool_description_;
200
202 Int const instance_number_;
203
205 String const ini_location_;
206
208 String working_dir_;
209
211 Int working_dir_keep_debug_lvl_;
212
214 TOPPBase();
215
217 TOPPBase(const TOPPBase&);
218
220 Param param_;
221
223 Param param_inifile_;
224
226 Param param_cmdline_;
227
229 Param param_instance_;
230
232 Param param_common_tool_;
233
235 Param param_common_;
236
238 mutable std::ofstream log_;
239
248 void enableLogging_() const;
249
251 std::vector<ParameterInformation> parameters_;
252
262 virtual Param getSubsectionDefaults_(const String& section) const;
263
271 Param getSubsectionDefaults_() const;
272
274 std::map<String, String> subsections_;
275
277 std::map<String, String> subsections_TOPP_;
278
279
292 Param parseCommandLine_(const int argc, const char** argv, const String& misc = "misc", const String& unknown = "unknown");
293
303 String getParamAsString_(const String& key, const String& default_value = "") const;
304
310 Int getParamAsInt_(const String& key, Int default_value = 0) const;
311
317 double getParamAsDouble_(const String& key, double default_value = 0) const;
318
324 StringList getParamAsStringList_(const String& key, const StringList& default_value) const;
325
331 IntList getParamAsIntList_(const String& key, const IntList& default_value) const;
332
338 DoubleList getParamAsDoubleList_(const String& key, const DoubleList& default_value) const;
339
349 bool getParamAsBool_(const String& key) const;
350
362 const DataValue& getParam_(const String& key) const;
363
369 String getSubsection_(const String& name) const;
370
371 String getDocumentationURL() const;
372
374 Param getDefaultParameters_() const;
375
377 Param getToolUserDefaults_(const String& tool_name) const;
379
380 protected:
382 String version_;
383
385 String verboseVersion_;
386
388 bool official_;
389
391 std::vector<Citation> citations_;
392
400 const String& getIniLocation_() const
401 {
402 return ini_location_;
403 }
404
406 const String& toolName_() const;
407
428 virtual void registerOptionsAndFlags_() = 0;
429
431 String getParamArgument_(const Param::ParamEntry& entry) const;
432
434 std::vector<ParameterInformation> paramToParameterInformation_(const Param& param) const;
435
445 ParameterInformation paramEntryToParameterInformation_(const Param::ParamEntry& entry, const String& argument = "", const String& full_name = "") const;
446
447 void registerParamSubsectionsAsTOPPSubsections_(const Param& param);
448
450 void registerFullParam_(const Param& param);
451
462 void registerStringOption_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
463
470 void setValidStrings_(const String& name, const std::vector<String>& strings);
471
481 void setValidStrings_(const String& name, const std::string vstrings[], int count);
482
500 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());
501
515 void registerOutputFile_(const String& name, const String& argument, const String& default_value, const String& description, bool required = true, bool advanced = false);
516
527 void setValidFormats_(const String& name, const std::vector<String>& formats, const bool force_OpenMS_format = true);
528
529
540 void registerDoubleOption_(const String& name, const String& argument, double default_value, const String& description, bool required = true, bool advanced = false);
541
547 void setMinInt_(const String& name, Int min);
553 void setMaxInt_(const String& name, Int max);
559 void setMinFloat_(const String& name, double min);
565 void setMaxFloat_(const String& name, double max);
566
577 void registerIntOption_(const String& name, const String& argument,
578 Int default_value, const String& description,
579 bool required = true, bool advanced = false);
580
592 void registerIntList_(const String& name, const String& argument, IntList default_value, const String& description, bool required = true, bool advanced = false);
593
604 void registerDoubleList_(const String& name, const String& argument, DoubleList default_value, const String& description, bool required = true, bool advanced = false);
605
616 void registerStringList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false);
617
634 void registerInputFileList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false, const StringList& tags = StringList());
635
649 void registerOutputFileList_(const String& name, const String& argument, StringList default_value, const String& description, bool required = true, bool advanced = false);
650
652 void registerFlag_(const String& name, const String& description, bool advanced = false);
653
661 void registerSubsection_(const String& name, const String& description);
662
672 void registerTOPPSubsection_(const String& name, const String& description);
673
674
676 void addEmptyLine_();
677
678
687 String getStringOption_(const String& name) const;
688
697 double getDoubleOption_(const String& name) const;
698
707 Int getIntOption_(const String& name) const;
708
717 StringList getStringList_(const String& name) const;
718
727 IntList getIntList_(const String& name) const;
728
737 DoubleList getDoubleList_(const String& name) const;
738
740 bool getFlag_(const String& name) const;
741
747 const ParameterInformation& findEntry_(const String& name) const;
748
754 Param const& getParam_() const;
755
769 void checkParam_(const Param& param, const String& filename, const String& location) const;
770
786 void fileParamValidityCheck_(String& filename, const String& param_name, const ParameterInformation& p) const;
787
795 void checkIfIniParametersAreApplicable_(const Param& ini_params);
797
799 void printUsage_();
800
802 virtual ExitCodes main_(int argc, const char** argv) = 0;
803
805
806 void writeLog_(const String& text) const;
808
810 void writeDebug_(const String& text, UInt min_level) const;
811
813 void writeDebug_(const String& text, const Param& param, UInt min_level) const;
815
817
818 String makeTempDirectory_() const;
820
822 String makeAutoRemoveTempDirectory_(Int keep_debug = 2);
823
829 void removeTempDirectory_(const String& dirname, Int keep_debug = 2) const;
831
833
834 ExitCodes runExternalProcess_(const QString& executable, const QStringList& arguments, const QString& workdir = "") const;
837
864 void inputFileReadable_(const String& filename, const String& param_name) const;
865
876 void outputFileWritable_(const String& filename, const String& param_name) const;
878
886 bool parseRange_(const String& text, double& low, double& high) const;
887
895 bool parseRange_(const String& text, Int& low, Int& high) const;
896
898 ProgressLogger::LogType log_type_;
899
901
902
904 void addDataProcessing_(ConsensusMap& map, const DataProcessing& dp) const;
905
907 void addDataProcessing_(FeatureMap& map, const DataProcessing& dp) const;
908
910 void addDataProcessing_(PeakMap& map, const DataProcessing& dp) const;
911
913 DataProcessing getProcessingInfo_(DataProcessing::ProcessingAction action) const;
914
916 DataProcessing getProcessingInfo_(const std::set<DataProcessing::ProcessingAction>& actions) const;
917
919
921 bool writeCTD_();
922
934 bool test_mode_;
935
937 static String topp_ini_file_;
938
940 static const Citation cite_openms_;
941
943 Int debug_level_;
944 private:
945
951 void addText_(const String& text);
952
960 ParameterInformation& getParameterByName_(const String& name);
961
962 };
963
964 } // namespace OpenMS
965
OpenMS::TOPPBase::cite_openms_
static const Citation cite_openms_
The OpenMS citation.
Definition: TOPPBase.h:940
OpenMS::Exception::GlobalExceptionHandler::setMessage
static void setMessage(const std::string &message)
OpenMS::Citation::toString
std::string toString() const
mangle members to string
Definition: TOPPBase.h:78
OpenMS::Exception::BaseException
Exception base class.
Definition: Exception.h:89
OpenMS::String
A more convenient string class.
Definition: String.h:58
OpenMS::TOPPBase::debug_level_
Int debug_level_
Debug level set by -debug.
Definition: TOPPBase.h:943
OpenMS::DataValue
Class to hold strings, numeric values, lists of strings and lists of numeric values.
Definition: DataValue.h:56
OpenMS::TOPPBase::verboseVersion_
String verboseVersion_
Version string including additional revision/date time information. Note: This differs from version_ ...
Definition: TOPPBase.h:385
OpenMS::TOPPBase::MISSING_PARAMETERS
Definition: TOPPBase.h:158
OpenMS::TOPPBase::PARSE_ERROR
Definition: TOPPBase.h:161
OpenMS::DataProcessing
Description of the applied preprocessing steps.
Definition: DataProcessing.h:51
OpenMS::IntList
std::vector< Int > IntList
Vector of signed integers.
Definition: ListUtils.h:55
OpenMS::TOPPBase::INTERNAL_ERROR
Definition: TOPPBase.h:163
OpenMS::TOPPBase::instance_number_
Int const instance_number_
Instance number.
Definition: TOPPBase.h:202
OpenMS::TOPPBase::test_mode_
bool test_mode_
Test mode.
Definition: TOPPBase.h:934
OpenMS::TOPPBase::ExitCodes
ExitCodes
Exit codes.
Definition: TOPPBase.h:149
OpenMS::MSExperiment
In-Memory representation of a mass spectrometry experiment.
Definition: MSExperiment.h:77
main
int main(int argc, const char **argv)
Definition: INIFileEditor.cpp:73
OpenMS::Exception::RequiredParameterNotGiven::RequiredParameterNotGiven
RequiredParameterNotGiven(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:115
GlobalExceptionHandler.h
tool_name
const char * tool_name
Definition: TOPPAS.cpp:94
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
Exception.h
OpenMS::FeatureMap
A container for features.
Definition: FeatureMap.h:95
OpenMS::TOPPBase::INPUT_FILE_NOT_FOUND
Definition: TOPPBase.h:152
StandardTypes.h
OpenMS::Citation::authors
std::string authors
list of authors in AMA style, i.e. `<surname>` `<initials>`, ...
Definition: TOPPBase.h:72
OpenMS::TOPPBase::param_cmdline_
Param param_cmdline_
Parameters from command line.
Definition: TOPPBase.h:226
OpenMS::ParameterInformation
Struct that captures all information of a command line parameter.
Definition: ParameterInformation.h:47
OpenMS::TOPPBase::EXECUTION_OK
Definition: TOPPBase.h:151
OpenMS::TOPPBase::EXTERNAL_PROGRAM_ERROR
Definition: TOPPBase.h:160
OpenMS::TOPPBase
Base class for TOPP applications.
Definition: TOPPBase.h:144
DataProcessing.h
OpenMS::Citation::title
std::string title
title of article
Definition: TOPPBase.h:73
OpenMS::TOPPBase::working_dir_keep_debug_lvl_
Int working_dir_keep_debug_lvl_
Debug level at which to keep working dir.
Definition: TOPPBase.h:211
OpenMS::TOPPBase::INPUT_FILE_NOT_READABLE
Definition: TOPPBase.h:153
OpenMS::TOPPBase::log_
std::ofstream log_
Log file stream. Use the writeLog_() and writeDebug_() methods to access it.
Definition: TOPPBase.h:238
OpenMS::Citation::when_where
std::string when_where
suggested format: journal. year; volume, issue: pages
Definition: TOPPBase.h:74
OpenMS::TOPPBase::ini_location_
String const ini_location_
Location in the ini file where to look for parameters.
Definition: TOPPBase.h:205
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:400
OpenMS::TOPPBase::log_type_
ProgressLogger::LogType log_type_
Type of progress logging.
Definition: TOPPBase.h:898
OpenMS::TOPPBase::param_inifile_
Param param_inifile_
All parameters specified in the ini file.
Definition: TOPPBase.h:223
String.h
ProgressLogger.h
OpenMS::DoubleList
std::vector< double > DoubleList
Vector of double precision real types.
Definition: ListUtils.h:62
OpenMS
Main OpenMS namespace.
Definition: FeatureDeconvolution.h:46
OpenMS::TOPPBase::version_
String version_
Version string (if empty, the OpenMS/TOPP version is printed)
Definition: TOPPBase.h:382
OpenMS::Citation
Stores Citations for individual TOPP tools.
Definition: TOPPBase.h:70
OpenMS::TOPPBase::subsections_
std::map< String, String > subsections_
Storage location and description for allowed subsections.
Definition: TOPPBase.h:274
OpenMS::TOPPBase::param_
Param param_
All parameters relevant to this invocation of the program.
Definition: TOPPBase.h:220
OpenMS::TOPPBase::tool_description_
String const tool_description_
Tool description. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:199
Param.h
OpenMS::TOPPBase::working_dir_
String working_dir_
An optional temporary working directory.
Definition: TOPPBase.h:208
OpenMS::ProgressLogger::LogType
LogType
Possible log types.
Definition: ProgressLogger.h:70
OpenMS::TOPPBase::tool_name_
String const tool_name_
Tool name. This is assigned once and for all in the constructor.
Definition: TOPPBase.h:196
OpenMS::UInt
unsigned int UInt
Unsigned integer type.
Definition: Types.h:94
OpenMS::TOPPBase::subsections_TOPP_
std::map< String, String > subsections_TOPP_
Storage location and description for allowed subsections from TOPP tool&#39;s command-line parameters...
Definition: TOPPBase.h:277
OpenMS::TOPPBase::param_instance_
Param param_instance_
Parameters from instance section.
Definition: TOPPBase.h:229
OpenMS::TOPPBase::CANNOT_WRITE_OUTPUT_FILE
Definition: TOPPBase.h:156
OpenMS::TOPPBase::topp_ini_file_
static String topp_ini_file_
.TOPP.ini file for storing system default parameters
Definition: TOPPBase.h:937
OpenMS::Exception::WrongParameterType
A parameter was accessed with the wrong type.
Definition: TOPPBase.h:99
OpenMS::TOPPBase::INCOMPATIBLE_INPUT_DATA
Definition: TOPPBase.h:162
OpenMS::Param
Management and storage of parameters / INI files.
Definition: Param.h:73
OpenMS::StringList
std::vector< String > StringList
Vector of String.
Definition: ListUtils.h:70
OpenMS::TOPPBase::UNKNOWN_ERROR
Definition: TOPPBase.h:159
int
OpenMS::TOPPBase::citations_
std::vector< Citation > citations_
Papers, specific for this tool (will be shown in &#39;–help&#39;)
Definition: TOPPBase.h:391
OpenMS::ConsensusMap
A container for consensus elements.
Definition: ConsensusMap.h:79
OpenMS::TOPPBase::param_common_
Param param_common_
Parameters from common section without tool name.
Definition: TOPPBase.h:235
OpenMS::Citation::doi
std::string doi
plain DOI (no urls), e.g. 10.1021/pr100177k
Definition: TOPPBase.h:75
OpenMS::DataProcessing::ProcessingAction
ProcessingAction
Definition: DataProcessing.h:58
OpenMS::Exception::UnregisteredParameter
An unregistered parameter was accessed.
Definition: TOPPBase.h:87
OpenMS::TOPPBase::official_
bool official_
Flag indicating if this an official TOPP tool.
Definition: TOPPBase.h:388
OpenMS::Exception::WrongParameterType::WrongParameterType
WrongParameterType(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:103
OpenMS::Exception::RequiredParameterNotGiven
A required parameter was not given.
Definition: TOPPBase.h:111
OpenMS::TOPPBase::INPUT_FILE_EMPTY
Definition: TOPPBase.h:155
OpenMS::Param::ParamEntry
Parameter entry used to store the actual information inside of a Param entry.
Definition: Param.h:78
OpenMS::Exception::UnregisteredParameter::UnregisteredParameter
UnregisteredParameter(const char *file, int line, const char *function, const String &parameter)
Definition: TOPPBase.h:91
OpenMS::TOPPBase::INPUT_FILE_CORRUPT
Definition: TOPPBase.h:154
OpenMS::TOPPBase::ILLEGAL_PARAMETERS
Definition: TOPPBase.h:157
OpenMS::TOPPBase::param_common_tool_
Param param_common_tool_
Parameters from common section with tool name.
Definition: TOPPBase.h:232
OpenMS::TOPPBase::parameters_
std::vector< ParameterInformation > parameters_
Storage location for parameter information.
Definition: TOPPBase.h:251