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