include/Rivet/AnalysisInfo.hh

0001 // -*- C++ -*-
0002 #ifndef RIVET_AnalysisInfo_HH
0003 #define RIVET_AnalysisInfo_HH
0004
0005 #include "Rivet/Config/RivetCommon.hh"
0006 #include <ostream>
0007
0008 namespace Rivet {
0009
0010
0011   /// @brief Holder of analysis metadata
0012   class AnalysisInfo {
0013   public:
0014
0015     /// Static factory method: returns null pointer if no metadata found
0016     static unique_ptr<AnalysisInfo> make(const std::string& name);
0017
0018     /// Default constructor
0019     AnalysisInfo() { clear(); }
0020
0021     ~AnalysisInfo() { }
0022
0023     void parseInfoFile();
0024
0025
0026     /// @defgroup anainfo_metadata Metadata
0027     ///
0028     /// Metadata is used for querying from the command line and also for
0029     /// building web pages and the analysis pages in the Rivet manual.
0030     /// @{
0031
0032     /// Get the name of the analysis. By default this is computed using the
0033     /// experiment, year and Inspire/Spires ID metadata methods.
0034     std::string name() const {
0035       if (!_name.empty()) return _name;
0036       if (!experiment().empty() && !year().empty()) {
0037         if (!inspireID().empty()) {
0038           return experiment() + "_" + year() + "_I" + inspireID();
0039         } else if (!spiresID().empty()) {
0040           return experiment() + "_" + year() + "_S" + spiresID();
0041         }
0042       }
0043       return "";
0044     }
0045     /// Set the name of the analysis.
0046     void setName(const std::string& name) { _name = name; }
0047
0048     /// Get the reference data name of the analysis (if different from plugin name).
0049     std::string getRefDataName() const {
0050       if (!_refDataName.empty())  return _refDataName;
0051       return name();
0052     }
0053     /// Set the reference data name of the analysis (if different from plugin name).
0054     void setRefDataName(const std::string& name) { _refDataName = name; }
0055
0056     /// Get the Inspire (SPIRES replacement) ID code for this analysis.
0057     const std::string& inspireID() const { return _inspireID; }
0058
0059     /// Set the Inspire (SPIRES replacement) ID code for this analysis.
0060     void setInspireID(const std::string& inspireID) { _inspireID = inspireID; }
0061
0062     /// Get the SPIRES ID code for this analysis.
0063     const std::string& spiresID() const { return _spiresID; }
0064
0065     /// Set the SPIRES ID code for this analysis.
0066     void setSpiresID(const std::string& spiresID) { _spiresID = spiresID; }
0067
0068     /// @brief Names & emails of paper/analysis authors.
0069     ///
0070     /// Names and email of authors in 'NAME \<EMAIL\>' format. The first
0071     /// name in the list should be the primary contact person.
0072     const std::vector<std::string>& authors() const { return _authors; }
0073     /// Set the author list.
0074     void setAuthors(const std::vector<std::string>& authors) { _authors = authors; }
0075
0076     /// @brief Get a short description of the analysis.
0077     ///
0078     /// Short (one sentence) description used as an index entry.
0079     /// Use @a description() to provide full descriptive paragraphs
0080     /// of analysis details.
0081     const std::string& summary() const { return _summary; }
0082     /// Set the short description for this analysis.
0083     void setSummary(const std::string& summary) { _summary = summary; }
0084
0085     /// @brief Get a full description of the analysis.
0086     ///
0087     /// Full textual description of this analysis, what it is useful for,
0088     /// what experimental techniques are applied, etc. Should be treated
0089     /// as a chunk of restructuredText (http://docutils.sourceforge.net/rst.html),
0090     /// with equations to be rendered as LaTeX with amsmath operators.
0091     const std::string& description() const { return _description; }
0092     /// Set the full description for this analysis.
0093     void setDescription(const std::string& description) { _description = description; }
0094
0095     /// @brief Information about the events needed as input for this analysis.
0096     ///
0097     /// Event types, energies, kinematic cuts, particles to be considered
0098     /// stable, etc. etc. Should be treated as a restructuredText bullet list
0099     /// (http://docutils.sourceforge.net/rst.html)
0100     const std::string& runInfo() const { return _runInfo; }
0101     /// Set the full description for this analysis.
0102     void setRunInfo(const std::string& runInfo) { _runInfo = runInfo; }
0103
0104     /// Beam particle types
0105     const std::vector<PdgIdPair>& beamIDs() const { return _beams; }
0106
0107     /// Set beam particle types
0108     void setBeamIDs(const std::vector<PdgIdPair>& beamids) { _beams = beamids; }
0109
0110     /// Sets of valid beam energies
0111     const std::vector<std::pair<double,double> >& energies() const { return _energies; }
0112     /// Set the valid beam energies
0113     void setEnergies(const std::vector<std::pair<double, double> >& energies) { _energies = energies; }
0114
0115     /// Experiment which performed and published this analysis.
0116     const std::string& experiment() const { return _experiment; }
0117     /// Set the experiment which performed and published this analysis.
0118     void setExperiment(const std::string& experiment) { _experiment = experiment; }
0119
0120     /// Collider on which the experiment ran.
0121     const std::string& collider() const { return _collider; }
0122     /// Set the collider on which the experiment ran.
0123     void setCollider(const std::string& collider) { _collider = collider; }
0124
0125     /// @brief When the original experimental analysis was published.
0126     ///
0127     /// When the refereed paper on which this is based was published, according to Inspire-HEP.
0128     const std::string& year() const { return _year; }
0129
0130     /// Set the year in which the original experimental analysis was published.
0131     void setYear(const std::string& year) { _year = year; }
0132
0133     /// The integrated data luminosity of the data set in 1/fb
0134     double luminosityfb() const { return _luminosityfb; }
0135     /// The integrated data luminosity of the data set in 1/pb
0136     double luminosity() const { return 1000*_luminosityfb; }
0137
0138     /// Set the integrated data luminosity of the data set
0139     void setLuminosityfb(const double luminosityfb) { _luminosityfb = luminosityfb; }
0140
0141     /// Journal and preprint references.
0142     const std::vector<std::string>& references() const { return _references; }
0143     /// Set the journal and preprint reference list.
0144     void setReferences(const std::vector<std::string>& references) { _references = references; }
0145
0146     /// Analysis keywords, for grouping etc.
0147     const std::vector<std::string>& keywords() const { return _keywords; }
0148     void setKeywords(const std::vector<std::string>& keywords) { _keywords = keywords; }
0149
0150     /// Any warning message
0151     const std::string& warning() const { return _warning; }
0152     void setWarning(const std::string warning) { _warning = warning; }
0153
0154     /// Positive filtering regex for ref-data HepData sync
0155     const std::string& refMatch() const { return _refmatch; }
0156     void setRefMatch(const std::string refmatch) { _refmatch = refmatch; }
0157
0158     /// Negative filtering regex for ref-data HepData sync
0159     const std::string& refUnmatch() const { return _refunmatch; }
0160     void setRefUnmatch(const std::string refunmatch) { _refunmatch = refunmatch; }
0161
0162     /// Positive filtering regex for setting double precision in Writer
0163     const std::string& writerDoublePrecision() const { return _writerdoubleprecision; }
0164     void setWriterDoublePrecision(const std::string dp) { _writerdoubleprecision = dp; }
0165
0166     /// BibTeX citation key for this article.
0167     const std::string& bibKey() const { return _bibKey; }
0168     /// Set the BibTeX citation key for this article.
0169     void setBibKey(const std::string& bibKey) { _bibKey = bibKey; }
0170
0171     /// BibTeX citation entry for this article.
0172     const std::string& bibTeX() const { return _bibTeX; }
0173     /// Set the BibTeX citation entry for this article.
0174     void setBibTeX(const std::string& bibTeX) { _bibTeX = bibTeX; }
0175
0176     /// Any work to be done on this analysis.
0177     const std::vector<std::string>& todos() const { return _todos; }
0178     /// Set the to-do list.
0179     void setTodos(const std::vector<std::string>& todos) { _todos = todos; }
0180
0181     /// @}
0182
0183
0184     /// @defgroup anainfo_options Analysis-options support
0185     /// @{
0186
0187     /// Get the option list.
0188     const std::vector<std::string>& options() const { return _options; }
0189
0190     /// Check if the given option is valid.
0191     bool validOption(std::string key, std::string val) const;
0192
0193     /// Set the option list.
0194     void setOptions(const std::vector<std::string>& opts) {
0195       _options = opts;
0196       buildOptionMap();
0197     }
0198
0199     /// Build a map of options to facilitate checking.
0200     void buildOptionMap();
0201
0202     /// @}
0203
0204
0205     /// @defgroup anainfo_status Status info and categories
0206     /// @{
0207
0208     /// Whether this analysis is trusted (in any way!)
0209     const std::string& status() const { return _status; }
0210     /// Set the analysis code status.
0211     void setStatus(const std::string& status) { _status = status; }
0212
0213     /// Return true if finalize() can be run multiple times for this analysis.
0214     bool reentrant() const { return _reentrant; }
0215     /// Set re-entrant status
0216     void setReentrant(bool ree=true) { _reentrant = ree; }
0217
0218     /// Return true if validated
0219     bool validated() const {
0220       return statuscheck("VALIDATED");
0221     }
0222
0223     /// Return true if preliminary
0224     bool preliminary() const {
0225       return statuscheck("PRELIMINARY");
0226     }
0227
0228     /// Return true if obsolete
0229     bool obsolete() const {
0230       return statuscheck("OBSOLETE");
0231     }
0232
0233     /// Return true if unvalidated
0234     bool unvalidated() const {
0235       return statuscheck("UNVALIDATED");
0236     }
0237
0238     /// Return true if includes random variations
0239     bool random() const {
0240       return statuscheck("RANDOM");
0241     }
0242
0243     /// Return true if the analysis uses generator-dependent information.
0244     bool unphysical() const {
0245       return statuscheck("UNPHYSICAL");
0246     }
0247
0248     /// Check if refdata comes automatically from Hepdata.
0249     bool hepdata() const {
0250       return !statuscheck("NOHEPDATA");
0251     }
0252
0253     /// Check if this analysis can handle multiple weights.
0254     bool multiweight() const {
0255       return !statuscheck("SINGLEWEIGHT");
0256     }
0257
0258     /// Helper function for checking status-string contents
0259     bool statuscheck(const string& word) const {
0260       auto pos =_status.find(word);
0261       if ( pos == string::npos ) return false;
0262       if ( pos > 0 && isalnum(_status[pos - 1]) ) return false;
0263       if ( pos + word.length() < _status.length() &&
0264            isalnum(_status[pos + word.length()]) ) return false;
0265       return true;
0266     }
0267
0268     /// @}
0269
0270
0271     /// Find the path to the reference-data file for this analysis
0272     std::string refFile() const;
0273
0274     /// List a series of command lines to be used for valdation
0275     const std::vector<std::string> & validation() const {
0276       return _validation;
0277     }
0278
0279
0280   private:
0281
0282     // std::map<string,string> _yamldict;
0283
0284     static std::string _infoFilePath;
0285
0286     std::string _name;
0287     std::string _refDataName;
0288     std::string _spiresID, _inspireID;
0289     std::vector<std::string> _authors;
0290     std::string _summary;
0291     std::string _description;
0292     std::string _runInfo;
0293     std::string _experiment;
0294     std::string _collider;
0295     std::vector<std::pair<PdgId, PdgId> > _beams;
0296     std::vector<std::pair<double, double> > _energies;
0297     std::string _year;
0298     double _luminosityfb;
0299     std::vector<std::string> _references;
0300     std::vector<std::string> _keywords;
0301     std::string _bibKey;
0302     std::string _bibTeX;
0303     //std::string _bibTeXBody; ///< Was thinking of avoiding duplication of BibKey...
0304     std::string _status;
0305     std::string _warning;
0306     std::string _refmatch;
0307     std::string _refunmatch;
0308     std::string _writerdoubleprecision;
0309     std::vector<std::string> _todos;
0310     bool _needsCrossSection;
0311     bool _isInitialised;
0312
0313     std::vector<std::string> _options;
0314     std::map< std::string, std::set<std::string> > _optionmap;
0315
0316     std::vector<std::string> _validation;
0317
0318     bool _reentrant;
0319
0320     void clear() {
0321       //_yamldict.clear();
0322       _name = "";
0323       _refDataName = "";
0324       _spiresID = "";
0325       _inspireID = "";
0326       _authors.clear();
0327       _summary = "";
0328       _description = "";
0329       _runInfo = "";
0330       _experiment = "";
0331       _collider = "";
0332       _beams.clear();
0333       _energies.clear();
0334       _year = "";
0335       _luminosityfb = -1;
0336       _references.clear();
0337       _keywords.clear();
0338       _bibKey = "";
0339       _bibTeX = "";
0340       //_bibTeXBody = "";
0341       _status = "";
0342       _warning = "";
0343       _refmatch = "";
0344       _refunmatch = "";
0345       _writerdoubleprecision = "";
0346       _todos.clear();
0347       _needsCrossSection = false;
0348       _options.clear();
0349       _optionmap.clear();
0350       _validation.clear();
0351       _reentrant = false;
0352       _isInitialised = false;
0353     }
0354
0355   };
0356
0357
0358   /// String representation
0359   std::string toString(const AnalysisInfo& ai);
0360
0361   /// Stream an AnalysisInfo as a text description
0362   inline std::ostream& operator<<(std::ostream& os, const AnalysisInfo& ai) {
0363     os << toString(ai);
0364     return os;
0365   }
0366
0367
0368 }
0369
0370 #endif