RooCategory.cxx

Go to the documentation of this file.

/*****************************************************************************
 * Project: RooFit                                                           *
 * Package: RooFitCore                                                       *
 * @(#)root/roofitcore:$Id$
 * Authors:                                                                  *
 *   WV, Wouter Verkerke, UC Santa Barbara, verkerke@slac.stanford.edu       *
 *   DK, David Kirkby,    UC Irvine,         dkirkby@uci.edu                 *
 *                                                                           *
 * Copyright (c) 2000-2005, Regents of the University of California          *
 *                          and Stanford University. All rights reserved.    *
 *                                                                           *
 * Redistribution and use in source and binary forms,                        *
 * with or without modification, are permitted according to the terms        *
 * listed in LICENSE (http://roofit.sourceforge.net/license.txt)             *
 *****************************************************************************/
 
/**
\class RooCategory
\ingroup Roofitcore
 
Object to represent discrete states.
States have names and index numbers, and the index numbers can be written into datasets and
used in calculations.
A category is "fundamental", i.e., its value doesn't depend on the value of other objects.
(Objects in datasets cannot depend on other objects' values, they need to be self-consistent.)
 
A category object can be used to *e.g.* conduct a simultaneous fit of
the same observable in multiple categories.
 
### Setting up a category
1. A category can be set up like this:
~~~{.cpp}
RooCategory myCat("myCat", "Lepton multiplicity category", {
                  {"0Lep", 0},
                  {"1Lep", 1},
                  {"2Lep", 2},
                  {"3Lep", 3}
});
~~~
2. Like this:
~~~{.cpp}
RooCategory myCat("myCat", "Asymmetry");
myCat["left"]  = -1;
myCat["right"] =  1;
~~~
3. Or like this:
~~~{.cpp}
RooCategory myCat("myCat", "Asymmetry");
myCat.defineType("left", -1);
myCat.defineType("right", 1);
~~~
Inspect the pairs of state names and state numbers like this:
~~~{.cpp}
for (const auto& nameIdx : myCat) {
  std::cout << nameIdx.first << " --> " << nameIdx.second << std::endl;
}
~~~
 
### Changing category states
Category states can be modified either by using the index state (faster) or state names.
For example:
~~~{.cpp}
myCat.setIndex(5);
myCat.setLabel("left");
for (const auto& otherNameIdx : otherCat) {
  myCat.setIndex(otherNameIdx);
}
~~~
 
Also refer to \ref tutorial_roofit, especially rf404_categories.C for an introduction, and to rf405_realtocatfuncs.C and rf406_cattocatfuncs.C
for advanced uses of categories.
**/
 
#include "RooCategory.h"
 
#include "RooArgSet.h"
#include "RooStreamParser.h"
#include "RooMsgService.h"
#include "RooTrace.h"
#include "RooHelpers.h"
#include "RooFitLegacy/RooCategorySharedProperties.h"
#include "RooFitLegacy/RooCatTypeLegacy.h"
 
#include "ROOT/StringUtils.hxx"
 
#include "TBuffer.h"
#include "TString.h"
#include "TList.h"
 
#include <cstdlib>
#include <iostream>
#include <memory>
 
using std::endl, std::istream, std::ostream;
 
 
std::map<RooSharedProperties::UUID, std::weak_ptr<RooCategory::RangeMap_t>> RooCategory::_uuidToSharedRangeIOHelper; // Helper for restoring shared properties
std::map<std::string, std::weak_ptr<RooCategory::RangeMap_t>> RooCategory::_sharedRangeIOHelper;
 
 
////////////////////////////////////////////////////////////////////////////////
 
RooCategory::RooCategory()
{
  TRACE_CREATE;
}
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// Constructor. Types must be defined using defineType() before variable can be used
RooCategory::RooCategory(const char *name, const char *title) :
  RooAbsCategoryLValue(name,title),
  _ranges{std::make_unique<RangeMap_t>()}
{
  setValueDirty() ;
  setShapeDirty() ;
  TRACE_CREATE;
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Create a new category and define allowed states.
/// \param[in] name Name used to refer to this object.
/// \param[in] title Title for e.g. plotting.
/// \param[in] allowedStates Map of allowed states. Pass e.g. `{ {"0Lep", 0}, {"1Lep:, 1} }`
RooCategory::RooCategory(const char* name, const char* title, const std::map<std::string, int>& allowedStates) :
  RooAbsCategoryLValue(name,title),
  _ranges{std::make_unique<RangeMap_t>()}
{
  defineTypes(allowedStates);
}
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// Copy constructor
 
RooCategory::RooCategory(const RooCategory& other, const char* name) :
  RooAbsCategoryLValue(other, name),
  _ranges(other._ranges)
{
  TRACE_CREATE;
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Destructor
 
RooCategory::~RooCategory()
{
  TRACE_DESTROY;
}
 
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// Set value by specifying the index code of the desired state.
/// If printError is set, a message will be printed if
/// the specified index does not represent a valid state.
/// \return bool signalling if an error occurred.
bool RooCategory::setIndex(Int_t index, bool printError)
{
  if (!hasIndex(index)) {
    if (printError) {
      coutE(InputArguments) << "RooCategory: Trying to set invalid state " << index << " for category " << GetName() << std::endl;
    }
    return true;
  }
 
  _currentIndex = index;
  setValueDirty();
 
  return false;
}
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// Set value by specifying the name of the desired state.
/// If printError is set, a message will be printed if
/// the specified label does not represent a valid state.
/// \return false on success.
bool RooCategory::setLabel(const char* label, bool printError)
{
  const auto item = stateNames().find(label);
  if (item != stateNames().end()) {
    _currentIndex = item->second;
    setValueDirty();
    return false;
  }
 
  if (printError) {
    coutE(InputArguments) << "Trying to set invalid state label '" << label << "' for category " << GetName() << std::endl;
  }
 
  return true;
}
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// Define a state with given name.
/// The lowest available positive integer is assigned as index. Category
/// state labels may not contain semicolons.
/// \return True in case of an error.
bool RooCategory::defineType(const std::string& label)
{
  if (label.find(';') != std::string::npos) {
    coutE(InputArguments) << "RooCategory::defineType(" << GetName()
        << "): semicolons not allowed in label name" << std::endl ;
    return true;
  }
 
  return RooAbsCategory::defineState(label) == invalidCategory();
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Define a state with given name and index. Category
/// state labels may not contain semicolons.
/// \return True in case of error.
bool RooCategory::defineType(const std::string& label, Int_t index)
{
  if (label.find(';') != std::string::npos) {
    coutE(InputArguments) << "RooCategory::defineType(" << GetName()
         << "): semicolons not allowed in label name" << std::endl ;
    return true;
  }
 
  return RooAbsCategory::defineState(label, index) == invalidCategory();
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Define multiple states in a single call. Use like:
/// ```
/// myCat.defineTypes({ {"0Lep", 0}, {"1Lep", 1}, {"2Lep", 2}, {"3Lep", 3} });
/// ```
/// Note: When labels or indices are defined multiple times, an error message is printed,
/// and the corresponding state is ignored.
void RooCategory::defineTypes(const std::map<std::string, int>& allowedStates) {
  for (const auto& nameAndIdx : allowedStates) {
    defineType(nameAndIdx.first, nameAndIdx.second);
  }
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Access a named state. If a state with this name doesn't exist yet, the state is
/// assigned the next available positive integer.
/// \param[in] stateName Name of the state to be accessed.
/// \return Reference to the category index. If no state exists, it will be created on the fly.
RooAbsCategory::value_type& RooCategory::operator[](const std::string& stateName) {
  setShapeDirty();
  if (stateNames().count(stateName) == 0) {
    _insertionOrder.push_back(stateName);
    return stateNames()[stateName] = nextAvailableStateIndex();
 
  }
 
  return stateNames()[stateName];
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Return a reference to the map of state names to index states.
/// This can be used to manipulate the category.
/// \note Calling this function will **always** trigger recomputations of
/// of **everything** that depends on this category, since in case the map gets
/// manipulated, names or indices might change. Also, the order that states have
/// been inserted in gets lost. This changes what is returned by getOrdinal().
std::map<std::string, RooAbsCategory::value_type>& RooCategory::states() {
  auto& theStates = stateNames();
  setValueDirty();
  setShapeDirty();
  _insertionOrder.clear();
  return theStates;
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Read object contents from given stream. If token is a decimal digit, try to
/// find a corresponding state for it. If that succeeds, the state denoted by this
/// index is used. Otherwise, interpret it as a label.
bool RooCategory::readFromStream(istream& is, bool /*compact*/, bool verbose)
{
  // Read single token
  RooStreamParser parser(is) ;
  TString token = parser.readToken() ;
 
  if (token.IsDec() && hasIndex(std::stoi(token.Data()))) {
    return setIndex(std::stoi(token.Data()), verbose);
  } else {
    return setLabel(token,verbose) ;
  }
}
 
 
 
////////////////////////////////////////////////////////////////////////////////
/// compact only at the moment
 
void RooCategory::writeToStream(ostream& os, bool compact) const
{
  if (compact) {
    os << getCurrentIndex() ;
  } else {
    os << getCurrentLabel() ;
  }
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Clear the named range.
/// \note This affects **all** copies of this category, because they are sharing
/// range definitions. This ensures that categories inside a dataset and their
/// counterparts on the outside will both see a modification of the range.
void RooCategory::clearRange(const char* name, bool silent)
{
  std::map<std::string, std::vector<value_type>>::iterator item = _ranges->find(name);
  if (item == _ranges->end()) {
    if (!silent)
      coutE(InputArguments) << "RooCategory::clearRange(" << GetName() << ") ERROR: must specify valid range name" << std::endl ;
    return;
  }
 
  _ranges->erase(item);
}
 
 
////////////////////////////////////////////////////////////////////////////////
 
void RooCategory::setRange(const char* name, const char* stateNameList)
{
  clearRange(name,true) ;
  addToRange(name,stateNameList) ;
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Add the given state to the given range.
/// \note This creates or accesses a **shared** map with allowed ranges. All copies of this
/// category will share this range such that a category inside a dataset and its
/// counterpart on the outside will both see a modification of the range.
void RooCategory::addToRange(const char* name, RooAbsCategory::value_type stateIndex) {
  auto item = _ranges->find(name);
  if (item == _ranges->end()) {
    if (!name) {
      coutE(Contents) << "RooCategory::addToRange(" << GetName()
          << "): Need valid range name." << std::endl;
      return;
    }
 
    item = _ranges->emplace(name, std::vector<value_type>()).first;
    coutI(Contents) << "RooCategory::setRange(" << GetName()
        << ") new range named '" << name << "' created for state " << stateIndex << std::endl ;
  }
 
  item->second.push_back(stateIndex);
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Add the list of state names to the given range. State names can be separated
/// with ','.
/// \note This creates or accesses a **shared** map with allowed ranges. All copies of this
/// category will share this range such that a category inside a dataset and its
/// counterpart on the outside will both see a modification of the range.
void RooCategory::addToRange(const char* name, const char* stateNameList)
{
  if (!stateNameList) {
    coutE(InputArguments) << "RooCategory::setRange(" << GetName() << ") ERROR: must specify valid name and state name list" << std::endl ;
    return;
  }
 
  // Parse list of state names, verify that each is valid and add them to the list
  for (const auto& token : ROOT::Split(stateNameList, ",")) {
    const value_type idx = lookupIndex(token);
    if (idx != invalidCategory().second) {
      addToRange(name, idx);
    } else {
      coutW(InputArguments) << "RooCategory::setRange(" << GetName() << ") WARNING: Ignoring invalid state name '"
             << token << "' in state name list" << std::endl ;
    }
  }
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Check if the state is in the given range.
/// If no range is specified either as argument or if no range has been defined for this category
/// (*i.e.*, the default range is meant), all category states count as being in range.
bool RooCategory::isStateInRange(const char* rangeName, RooAbsCategory::value_type stateIndex) const {
  if (rangeName == nullptr || _ranges->empty())
    return true;
 
  const auto item = _ranges->find(rangeName);
  if (item == _ranges->end())
    return false;
 
  const std::vector<value_type>& vec = item->second;
  return std::find(vec.begin(), vec.end(), stateIndex) != vec.end();
}
 
 
////////////////////////////////////////////////////////////////////////////////
/// Check if the state is in the given range.
/// If no range is specified (*i.e.*, the default range), all category states count as being in range.
/// This overload requires a name lookup. Recommend to use the category index with
/// RooCategory::isStateInRange(const char*, RooAbsCategory::value_type) const.
bool RooCategory::isStateInRange(const char* rangeName, const char* stateName) const
{
  // Check that both input arguments are not null pointers
  if (!rangeName) {
    return true;
  }
 
  if (!stateName) {
    coutE(InputArguments) << "RooCategory::isStateInRange(" << GetName() << ") ERROR: must specify valid state name" << std::endl ;
    return false;
  }
 
  return isStateInRange(rangeName, lookupIndex(stateName));
}
 
 
////////////////////////////////////////////////////////////////////////////////
 
void RooCategory::Streamer(TBuffer &R__b)
{
  UInt_t R__s;
  UInt_t R__c;
  if (R__b.IsReading()) {
 
    Version_t R__v = R__b.ReadVersion(&R__s, &R__c);
 
    if (R__v==1) {
      RooAbsCategoryLValue::Streamer(R__b);
 
      // In v1, properties were a direct pointer:
      RooCategorySharedProperties* props = nullptr;
      R__b >> props;
      installLegacySharedProp(props);
      // props was allocated by I/O system, we cannot delete here in case it gets reused
 
    } else if (R__v == 2) {
      RooAbsCategoryLValue::Streamer(R__b);
 
      // In v2, properties were written directly into the class buffer
      auto props = std::make_unique<RooCategorySharedProperties>();
      props->Streamer(R__b);
      installLegacySharedProp(props.get());
 
    } else {
      // Starting at v3, ranges are shared using a shared pointer, which cannot be read by ROOT's I/O.
      // Instead, ranges are written as a normal pointer, and here we restore the sharing.
      R__b.ReadClassBuffer(RooCategory::Class(), this, R__v, R__s, R__c);
      installSharedRange(std::unique_ptr<RangeMap_t>(_rangesPointerForIO));
      _rangesPointerForIO = nullptr;
    }
 
    R__b.CheckByteCount(R__s, R__c, RooCategory::IsA());
 
  } else {
    // Since we cannot write shared pointers yet, assign the shared ranges to a normal pointer,
    // write, and restore.
    if (_ranges)
      _rangesPointerForIO = _ranges.get();
 
    R__b.WriteClassBuffer(RooCategory::Class(), this);
    _rangesPointerForIO = nullptr;
  }
}
 
 
/// When reading old versions of the class, we get instances of shared properties.
/// Since these only contain ranges with numbers, just convert to vectors of numbers.
void RooCategory::installLegacySharedProp(const RooCategorySharedProperties* props) {
  if (props == nullptr || (*props == RooCategorySharedProperties("00000000-0000-0000-0000-000000000000")))
    return;
 
  auto& weakPtr = _uuidToSharedRangeIOHelper[props->uuid()];
  if (auto existingObject = weakPtr.lock()) {
    // We know this range, start sharing
    _ranges = std::move(existingObject);
  } else {
    // This range is unknown, make a new object
    _ranges = std::make_unique<std::map<std::string, std::vector<value_type>>>();
    auto& rangesMap = *_ranges;
 
    // Copy the data:
    for (auto * olist : static_range_cast<TList*>(props->_altRanges)) {
      std::vector<value_type>& vec = rangesMap[olist->GetName()];
 
 
      for(auto * ctype : static_range_cast<RooCatType*>(*olist)) {
        vec.push_back(ctype->getVal());
      }
    }
 
    // Register the shared_ptr for future sharing
    weakPtr = _ranges;
  }
}
 
 
/// In current versions of the class, a map with ranges can be shared between instances.
/// If an instance with the same name already uses the same map, the instances will start sharing.
/// Otherwise, this instance will be registered, and future copies being read will share with this
/// one.
void RooCategory::installSharedRange(std::unique_ptr<RangeMap_t>&& rangeMap) {
  if (rangeMap == nullptr)
    return;
 
  auto checkRangeMapsEqual = [](const RooCategory::RangeMap_t& a, const RooCategory::RangeMap_t& b) {
    if (&a == &b)
      return true;
 
    if (a.size() != b.size())
      return false;
 
    for (const auto& itemA : a) {
      const auto itemB = b.find(itemA.first);
      if (itemB == b.end())
        return false;
 
      if (itemA.second != itemB->second)
        return false;
    }
 
    return true;
  };
 
 
  auto& weakPtr = _sharedRangeIOHelper[GetName()];
  auto existingMap = weakPtr.lock();
  if (existingMap && checkRangeMapsEqual(*rangeMap, *existingMap)) {
    // We know this map, use the shared one.
    _ranges = std::move(existingMap);
    if (rangeMap.get() == _ranges.get()) {
      // This happens when ROOT's IO has written the same pointer twice. We cannot delete now.
      (void) rangeMap.release(); // NOLINT: clang-tidy is normally right that this leaks. Here, we need to leave the result unused, though.
    }
  } else {
    // We don't know this map. Register for sharing.
    _ranges = std::move(rangeMap);
    weakPtr = _ranges;
  }
}