GenericHistSFApplier< Object, Context >

Description

template<class Object, class... Context>
class DAS::GenericHistSFApplier< Object, Context >

A generic base class to simplify applying scale factors.

Template Parameters

Object	The object type to apply scale factors for.
Context	A set of object types that are needed to derive cuts and scale factors, but to which no corrections is applied.

GenericHistSFApplier can be used in situations where one wants to apply a cut to a collection of objects (e.g. photons) and correct the efficiency of this cut in MC with scale factors. This class must be subclassed before it can be used, and two methods need to be implemented in the subclass:

• passes() to check whether an object should pass the cut;
• binIndex() to retrieve the bin index in the histogram with the scale factors.

In addition, the constructor should load scale factors using loadNominal() and systematic uncertainties using loadBinWiseUnc() and loadGlobalUnc() (which differ in how the uncertainty will be correlated between bins of the scale factors).

Instances of classes derived from this one are used by calling the call operator on individual objects or whole object collections. Objects that do not pass the selection will be given a weight of zero. Objects passing the selection will be reweighted by the scale factor (if the correction is enabled) and new weights will be appended for systematics (again only if enabled).

Sometimes, additional inputs are needed to derive the cut and/or the scale factor. We call this contextual information. An arbitrary number of extra arguments can be passed to the call operator for context. The applier passes them directly to passes() and binIndex(), where they can be used to implement the selection or the correction. The types of context objects must be provided as class template arguments. The functions take constant references to these types.

Each uncertainty variation must be given a unique name. The names of all weights added by this class can be retrieved using the weightNames() method. This is useful to store them in the metainfo.

#include <GenericSFApplier.h>

Collaboration diagram for GenericHistSFApplier< Object, Context >:

Public Member Functions
	GenericHistSFApplier (const std::filesystem::path &filePath, bool correction, bool uncertainties)
virtual	~GenericHistSFApplier () noexcept=default
void	operator() (Object &object, const Context &... ctx) const
void	operator() (std::vector< Object > &objects, const Context &... ctx) const
std::vector< std::string >	weightNames () const

Protected Types
enum	Interpretation { UseBinContent, UseBinError }

Protected Member Functions
void	loadNominal (const std::string &histPath)
void	loadBinWiseUnc (const std::string &name, const std::string &histPath, Interpretation intp=UseBinContent)
void	loadGlobalUnc (const std::string &name, const std::string &histPath, Interpretation intp=UseBinContent)
virtual bool	passes (const Object &obj, const Context &... ctx) const =0
virtual int	binIndex (const Object &obj, const Context &... ctx, const std::unique_ptr< TH1 > &hist) const =0

Private Attributes
std::unique_ptr< TFile >	m_file
bool	m_correction
bool	m_uncertainties
std::unique_ptr< TH1 >	m_nominal
std::map< std::string, std::unique_ptr< TH1 > >	m_bin_wise_uncs
std::map< std::string, std::unique_ptr< TH1 > >	m_global_uncs

Member Enumeration Documentation

Interpretation

enum Interpretation

protected

How loaded histograms should be interpreted.

Enumerator
UseBinContent	The histogram contains the uncertainty in the scale factors.
UseBinError	The histogram errors contain the uncertainty in the scale factors.

                        {
        UseBinContent,
        UseBinError,
    };

Constructor & Destructor Documentation

GenericHistSFApplier()

GenericHistSFApplier	(	const std::filesystem::path &	filePath,
		bool	correction,
		bool	uncertainties
	)

Constructor.

Parameters

filePath	The path of a ROOT file to load scale factors from
correction	Whether to apply scale factors
uncertainties	Whether to store uncertainties

    : m_correction(correction)
    , m_uncertainties(uncertainties)
{
    namespace fs = std::filesystem;
 
    if (!correction)
        return;
 
    // Check that the file exists
    if (!fs::exists(filePath))
        BOOST_THROW_EXCEPTION(
            fs::filesystem_error("Not found",
                                 filePath,
                                 make_error_code(std::errc::no_such_file_or_directory)));
 
    m_file = std::make_unique<TFile>(filePath.c_str(), "READ");
}

~GenericHistSFApplier()

virtual ~GenericHistSFApplier ( )

virtualdefaultnoexcept

Member Function Documentation

binIndex()

virtual int binIndex ( const Object &  obj, const Context &...  ctx, const std::unique_ptr< TH1 > &  hist  ) const

protectedpure virtual

Called to retrieve the bin to use in the scale factor histograms.

The histogram passed as second parameter is always the nominal one, and it is assumed that the bin index is the same for uncertainty variations (that is, we assume that the binnings match).

loadBinWiseUnc()

void loadBinWiseUnc ( const std::string &  name, const std::string &  histPath, Interpretation  intp = UseBinContent  )

protected

Loads a systematic with bin-by-bin correlations.

See also

loadGlobalUnc()

The histogram is expected to contain the (symmetric) uncertainty in the scale factor. This function has no effect when not applying the correction or when uncertainties are disabled.

{
    if (!m_correction || !m_uncertainties) return;
    auto hist = getHistSafe(m_file, histPath);
    if (intp == UseBinError) // We always store variations in the bin contents
        for (int i = 0; i <= hist->GetNcells(); ++i)
            hist->SetBinContent(i, hist->GetBinError(i));
    m_bin_wise_uncs[name] = std::move(hist);
}

loadGlobalUnc()

void loadGlobalUnc ( const std::string &  name, const std::string &  histPath, Interpretation  intp = UseBinContent  )

protected

Loads a fully correlated systematic.

See also

loadGlobalUnc()

The histogram is expected to contain the (symmetric) uncertainty in the scale factor. This function has no effect when not applying the correction or when uncertainties are disabled.

{
    if (!m_correction || !m_uncertainties) return;
    auto hist = getHistSafe(m_file, histPath);
    if (intp == UseBinError) // We always store variations in the bin contents
        for (int i = 0; i <= hist->GetNcells(); ++i)
            hist->SetBinContent(i, hist->GetBinError(i));
    m_global_uncs[name] = std::move(hist);
}

loadNominal()

void loadNominal ( const std::string &  histPath )

protected

Loads the histogram with the nominal scale factor. Has no effect when not applying the correction.

{
    if (!m_correction) return;
    m_nominal = getHistSafe(m_file, histPath);
}

operator()() [1/2]

void operator()	(	Object &	object,
		const Context &...	ctx
	)		const

Applies the selection and scale factors to a single object.

{
    auto& weights = obj.weights;
 
    // For safety
    if (weights.empty()) weights.emplace_back(DAS::Weight{1, 0});
 
    const float old = weights.front().v;
 
    // Apply the cut
    if (!passes(obj, ctx...)) {
        weights *= 0;
        return; // Skip applying weights
    }
 
    // Nominal correction
    if (!m_correction) return;
 
    const int bin = binIndex(obj, ctx..., m_nominal);
    const float sf = m_nominal->GetBinContent(bin);
    weights *= sf;
 
    // Systematics
    if (!m_uncertainties) return;
 
    // The order of the next two blocks must match weightNames()
    for (const auto& [_, hist] : m_bin_wise_uncs) {
        const float variation = hist->GetBinContent(bin);
        weights.push_back({old * (sf + variation), bin});
        weights.push_back({old * (sf - variation), bin});
    }
 
    for (const auto& [_, hist] : m_global_uncs) {
        const float variation = hist->GetBinContent(bin);
        weights.push_back({old * (sf + variation), 0});
        weights.push_back({old * (sf - variation), 0});
    }
}

operator()() [2/2]

void operator()	(	std::vector< Object > &	objects,
		const Context &...	ctx
	)		const

Applies the selection and scale factors to objects in a vector.

{
    for (auto& obj: objects) {
        (*this)(obj, ctx...);
    }
}

passes()

virtual bool passes ( const Object &  obj, const Context &...  ctx  ) const

protectedpure virtual

Called to check whether an object passes the selection.

Note

As an optimization, this is only called when the object weight is not already zero.

weightNames()

std::vector< std::string > weightNames

Retrieves the name of weights added by this applier. Returns an empty vector when uncertainties are disabled.

{
    std::vector<std::string> names;
    // The order of the next two blocks must match the call operator
    for (const auto& [name, _] : m_bin_wise_uncs) {
        names.push_back(name + SysUp);
        names.push_back(name + SysDown);
    }
    for (const auto& [name, _] : m_global_uncs) {
        names.push_back(name + SysUp);
        names.push_back(name + SysDown);
    }
    return names;
}

Member Data Documentation

m_bin_wise_uncs

std::map<std::string, std::unique_ptr<TH1> > m_bin_wise_uncs

private

Histograms with uncertainties correlated bin-by-bin.

m_correction

bool m_correction

private

Apply the scale factors?

m_file

std::unique_ptr<TFile> m_file

private

SFs are loaded from this file.

m_global_uncs

std::map<std::string, std::unique_ptr<TH1> > m_global_uncs

private

Histograms with uncertainties correlated.

m_nominal

std::unique_ptr<TH1> m_nominal

private

Histogram with the nominal SFs.

m_uncertainties

bool m_uncertainties

private

Calculate uncertainties?

---

The documentation for this class was generated from the following file:

• interface/GenericSFApplier.h