include/root/RooAbsCategory.h

0001 /*****************************************************************************
0002  * Project: RooFit                                                           *
0003  * Package: RooFitCore                                                       *
0004  *    File: $Id: RooAbsCategory.h,v 1.38 2007/05/11 09:11:30 verkerke Exp $
0005  * Authors:                                                                  *
0006  *   WV, Wouter Verkerke, UC Santa Barbara, verkerke@slac.stanford.edu       *
0007  *   DK, David Kirkby,    UC Irvine,         dkirkby@uci.edu                 *
0008  *                                                                           *
0009  * Copyright (c) 2000-2005, Regents of the University of California          *
0010  *                          and Stanford University. All rights reserved.    *
0011  *                                                                           *
0012  * Redistribution and use in source and binary forms,                        *
0013  * with or without modification, are permitted according to the terms        *
0014  * listed in LICENSE (http://roofit.sourceforge.net/license.txt)             *
0015  *****************************************************************************/
0016 #ifndef ROO_ABS_CATEGORY
0017 #define ROO_ABS_CATEGORY
0018
0019 #include "RooAbsArg.h"
0020
0021 #include <functional>
0022 #include <limits>
0023 #include <map>
0024 #include <string>
0025 #include <vector>
0026
0027 class RooCatType;
0028 class TTree;
0029 class RooVectorDataStore;
0030 class Roo1DTable;
0031 class TIterator;
0032 struct TreeReadBuffer; /// A space to attach TBranches
0033
0034 class RooAbsCategory : public RooAbsArg {
0035 public:
0036   /// The type used to denote a specific category state.
0037   using value_type = int;
0038
0039   // Constructors, assignment etc.
0040   RooAbsCategory();
0041   RooAbsCategory(const char *name, const char *title);
0042   RooAbsCategory(const RooAbsCategory& other, const char* name=nullptr) ;
0043   ~RooAbsCategory() override;
0044
0045   // Value accessors
0046   virtual value_type getCurrentIndex() const ;
0047   virtual const char* getCurrentLabel() const ;
0048
0049   const std::map<std::string, value_type>::value_type& getOrdinal(unsigned int n) const;
0050   unsigned int getCurrentOrdinalNumber() const;
0051
0052   bool operator==(value_type index) const ;
0053   bool operator!=(value_type index) {  return !operator==(index);}
0054   bool operator==(const char* label) const ;
0055   bool operator!=(const char* label) { return !operator==(label);}
0056   bool operator==(const RooAbsArg& other) const override ;
0057   bool         operator!=(const RooAbsArg& other) { return !operator==(other);}
0058   bool isIdentical(const RooAbsArg& other, bool assumeSameType=false) const override;
0059
0060   /// Check if a state with name `label` exists.
0061   bool hasLabel(const std::string& label) const {
0062     return stateNames().find(label) != stateNames().end();
0063   }
0064   /// Check if a state with index `index` exists.
0065   bool hasIndex(value_type index) const;
0066
0067   /// Get the name corresponding to the given index.
0068   /// \return Name or empty string if index is invalid.
0069   const std::string& lookupName(value_type index) const;
0070   value_type lookupIndex(const std::string& stateName) const;
0071
0072
0073   bool isSignType(bool mustHaveZero=false) const ;
0074
0075   Roo1DTable *createTable(const char *label) const ;
0076
0077   // I/O streaming interface
0078   bool readFromStream(std::istream& is, bool compact, bool verbose=false) override ;
0079   void writeToStream(std::ostream& os, bool compact) const override ;
0080
0081   void printValue(std::ostream& os) const override ;
0082   void printMultiline(std::ostream& os, Int_t contents, bool verbose=false, TString indent="") const override ;
0083
0084   virtual bool isIntegrationSafeLValue(const RooArgSet* /*set*/) const {
0085     // Is this l-value object safe for use as integration observable
0086     return true ;
0087   }
0088
0089   RooFit::OwningPtr<RooAbsArg> createFundamental(const char* newname=nullptr) const override;
0090
0091   /// Iterator for category state names. Points to pairs of index and name.
0092   std::map<std::string, value_type>::const_iterator begin() const {
0093     return stateNames().cbegin();
0094   }
0095   /// Iterator for category state names. Points to pairs of index and name.
0096   std::map<std::string, value_type>::const_iterator end() const {
0097     return stateNames().cend();
0098   }
0099   /// Number of states defined.
0100   std::size_t size() const {
0101     return stateNames().size();
0102   }
0103   /// If there are no states defined
0104   bool empty() const {
0105     return stateNames().empty();
0106   }
0107
0108   bool isCategory() const override { return true; }
0109
0110   /// \name Legacy interface
0111   /// Previous versions of RooAbsCategory were based on RooCatType, a class containing a state and a label.
0112   /// It has been replaced by integers, which use less space and allow for faster access. The following part of the interface
0113   /// should not be used if possible.
0114   /// Since RooCatType in essence is only an index and a state name, equivalent functionality can be achieved using begin()
0115   /// and end() to iterate through pairs of <index, stateName> and by using using lookupName() and lookupIndex().
0116   /// @{
0117   const RooCatType*
0118   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use lookupName()")
0119   lookupType(value_type index, bool printError=false) const;
0120   const RooCatType*
0121   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use lookupIndex()")
0122   lookupType(const char* label, bool printError=false) const;
0123   const RooCatType*
0124   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use lookupName() / lookupIndex()")
0125   lookupType(const RooCatType& type, bool printError=false) const;
0126   TIterator*
0127   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use begin(), end() or range-based for loops.")
0128   typeIterator() const;
0129   /// Return number of types defined (in range named rangeName if rangeName!=nullptr)
0130   Int_t numTypes(const char* /*rangeName*/=nullptr) const {
0131     return stateNames().size();
0132   }
0133   /// Retrieve the current index. Use getCurrentIndex() for more clarity.
0134   Int_t getIndex() const { return getCurrentIndex(); }
0135   /// Retrieve current label. Use getCurrentLabel() for more clarity.
0136   const char* getLabel() const { return getCurrentLabel(); }
0137 protected:
0138   virtual bool
0139   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use hasIndex() or hasLabel().")
0140   isValid(const RooCatType& value) const ;
0141   /// \deprecated Use defineState(const std::string& label)
0142   const RooCatType*
0143   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use defineState().")
0144   defineType(const char* label);
0145   /// \deprecated Use defineState(const std::string& label, value_type index)
0146   const RooCatType*
0147   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use defineState().")
0148   defineType(const char* label, int index);
0149   /// \deprecated Use defineStateUnchecked(const std::string& label, value_type index)
0150   const RooCatType*
0151   R__SUGGEST_ALTERNATIVE("This interface is inefficient. Use defineTypeUnchecked().")
0152   defineTypeUnchecked(const char* label, value_type index);
0153   /// @}
0154
0155
0156 protected:
0157   /// Access the map of state names to index numbers. Triggers a recomputation
0158   /// if the shape is dirty.
0159   const std::map<std::string, value_type>& stateNames() const {
0160     if (isShapeDirty()) {
0161       _legacyStates.clear();
0162       const_cast<RooAbsCategory*>(this)->recomputeShape();
0163       clearShapeDirty();
0164     }
0165
0166     return _stateNames;
0167   }
0168   /// \copydoc stateNames() const
0169   std::map<std::string, value_type>& stateNames() {
0170     if (isShapeDirty()) {
0171       _legacyStates.clear();
0172       recomputeShape();
0173       clearShapeDirty();
0174     }
0175
0176     //Somebody might modify the states
0177     setShapeDirty();
0178
0179     return _stateNames;
0180   }
0181
0182   /// Evaluate the category state and return.
0183   /// The returned state index should correspond to a state name that has been defined via e.g. defineType().
0184   virtual value_type evaluate() const = 0;
0185
0186   // Type definition management
0187   virtual const std::map<std::string, RooAbsCategory::value_type>::value_type& defineState(const std::string& label);
0188   virtual const std::map<std::string, RooAbsCategory::value_type>::value_type& defineState(const std::string& label, value_type index);
0189
0190   void defineStateUnchecked(const std::string& label, value_type index);
0191   void clearTypes() ;
0192
0193   bool isValid() const override {
0194     return hasIndex(_currentIndex);
0195   }
0196
0197   /// If a category depends on the shape of others, i.e.\ its state numbers or names depend
0198   /// on the states of other categories, this function has to be implemented to recompute
0199   /// _stateNames and _insertionOrder.
0200   /// If one of these two changes, setShapeDirty() has to be called to propagate this information
0201   /// to possible users of this category.
0202   virtual void recomputeShape() = 0;
0203
0204   friend class RooVectorDataStore ;
0205   void syncCache(const RooArgSet* set=nullptr) override ;
0206   void copyCache(const RooAbsArg* source, bool valueOnly=false, bool setValueDirty=true) override ;
0207   void setCachedValue(double value, bool notifyClients = true) final;
0208   void attachToTree(TTree& t, Int_t bufSize=32000) override ;
0209   void attachToVStore(RooVectorDataStore& vstore) override ;
0210   void setTreeBranchStatus(TTree& t, bool active) override ;
0211   void fillTreeBranch(TTree& t) override ;
0212
0213   RooCatType* retrieveLegacyState(value_type index) const;
0214   value_type nextAvailableStateIndex() const;
0215
0216
0217   mutable value_type _currentIndex{std::numeric_limits<int>::min()}; ///< Current category state
0218   std::map<std::string, value_type> _stateNames;                     ///< Map state names to index numbers. Make sure state names are updated in recomputeShape().
0219   std::vector<std::string> _insertionOrder;                          ///< Keeps track in which order state numbers have been inserted. Make sure this is updated in recomputeShape().
0220   mutable std::map<value_type, std::unique_ptr<RooCatType, std::function<void(RooCatType*)>> > _legacyStates; ///<! Map holding pointers to RooCatType instances. Only for legacy interface. Don't use if possible.
0221
0222   static const decltype(_stateNames)::value_type& invalidCategory();
0223
0224 private:
0225   TreeReadBuffer *_treeReadBuffer = nullptr; //! A buffer for reading values from trees
0226
0227   ClassDefOverride(RooAbsCategory, 4) // Abstract discrete variable
0228 };
0229
0230 #endif