CorrectionlibSFApplier< Object, Context >

Description

template<class Object, class... Context>
class DAS::CorrectionlibSFApplier< 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.

CorrectionlibSFApplier 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 3 or 4 methods need to be implemented in the subclass:

• inputs() to retrieve the correctionlib arguments for an object;
• passes() to check whether an object should pass the cut;
• varied() to extract up/down variations;
• Optionally, binIndex() to retrieve the bin index in the histogram with the scale factors (for bin-wise correlations).

In addition, the constructor should add systematic uncertainties using addBinWiseUnc() and addGlobalUnc() (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(), inputs(), 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.

Note

This class is reentrant but not thread-safe.

#include <GenericSFApplier.h>

Collaboration diagram for CorrectionlibSFApplier< Object, Context >:

Public Member Functions
	CorrectionlibSFApplier (const std::filesystem::path &filePath, const std::string &name, bool correction, bool uncertainties)
virtual	~CorrectionlibSFApplier () 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 Member Functions
void	addBinWiseUnc (const std::string &name, const correction::Variable::Type &input)
void	addGlobalUnc (const std::string &name, const correction::Variable::Type &input)
virtual bool	passes (const Object &obj, const Context &... ctx) const =0
virtual void	inputs (std::vector< correction::Variable::Type > &inputs, const Object &obj, const Context &... ctx) const =0
virtual std::pair< double, double >	varied (std::vector< correction::Variable::Type > &inputs, double sf, const correction::Variable::Type &uncname) const =0
virtual int	binIndex (const Object &obj, const Context &... ctx) const

Protected Attributes
correction::Correction::Ref	m_cref

Private Attributes
bool	m_correction
bool	m_uncertainties
std::map< std::string, correction::Variable::Type >	m_bin_wise_uncs
std::map< std::string, correction::Variable::Type >	m_global_uncs
std::vector< correction::Variable::Type >	m_cached_inputs

Constructor & Destructor Documentation

CorrectionlibSFApplier()

CorrectionlibSFApplier	(	const std::filesystem::path &	filePath,
		const std::string &	name,
		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)));
 
    auto cset = correction::CorrectionSet::from_file(filePath);
    m_cref = cset->at(name);
}

~CorrectionlibSFApplier()

virtual ~CorrectionlibSFApplier ( )

virtualdefaultnoexcept

Member Function Documentation

addBinWiseUnc()

void addBinWiseUnc ( const std::string &  name, const correction::Variable::Type &  input  )

protected

Loads a systematic with bin-by-bin correlations.

See also

addGlobalUnc()

The correction 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;
    m_bin_wise_uncs[name] = std::move(input);
}

addGlobalUnc()

void addGlobalUnc ( const std::string &  name, const correction::Variable::Type &  input  )

protected

Loads a fully correlated systematic.

See also

addBinWiseUnc()

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;
    m_global_uncs[name] = std::move(input);
}

binIndex()

virtual int binIndex ( const Object &  obj, const Context &...  ctx  ) const

inlineprotectedvirtual

Called to retrieve the bin index to use for bin-wise uncertainties.

This function can be ignored if all uncertainties are global.

    { return 0; }

inputs()

virtual void inputs ( std::vector< correction::Variable::Type > &  inputs, const Object &  obj, const Context &...  ctx  ) const

protectedpure virtual

Called to retrieve the inputs for correctionlib.

The vector passed as first argument should be filled with the inputs to fetch the nominal scale factor with correction::Correction::evaluate.

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 auto old = weights.front().v;
 
    // Apply the cut
    if (!passes(obj, ctx...)) {
        weights *= 0;
        return; // Skip applying weights
    }
 
    // Nominal correction
    if (!m_correction) return;
 
    m_cached_inputs.clear();
    inputs(m_cached_inputs, obj, ctx...);
    const auto sf = m_cref->evaluate(m_cached_inputs);
 
    weights *= sf;
 
    // Systematics
    if (!m_uncertainties) return;
 
    // The order of the next two blocks must match weightNames()
    if (!m_bin_wise_uncs.empty()) {
        const int bin = binIndex(obj, ctx...);
        for (const auto& [_, uncname] : m_bin_wise_uncs) {
            const auto& [up, down] = varied(m_cached_inputs, sf, uncname);
            weights.push_back({old * up, bin});
            weights.push_back({old * down, bin});
        }
    }
 
    for (const auto& [_, uncname] : m_global_uncs) {
        const auto& [up, down] = varied(m_cached_inputs, sf, uncname);
        weights.push_back({old * up, 0});
        weights.push_back({old * down, 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.

varied()

virtual std::pair<double, double> varied ( std::vector< correction::Variable::Type > &  inputs, double  sf, const correction::Variable::Type &  uncname  ) const

protectedpure virtual

Called to retrieve the up and down variations of a scale factor.

The value comes from addBinWiseUnc or addGlobalUnc.

Implemented in IDApplier.

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, correction::Variable::Type> m_bin_wise_uncs

private

Inputs for uncertainties correlated bin-by-bin.

m_cached_inputs

std::vector<correction::Variable::Type> m_cached_inputs

mutableprivate

Cached inputs to reduce allocations.

m_correction

bool m_correction

private

Apply the scale factors?

m_cref

correction::Correction::Ref m_cref

protected

Correction to be used.

m_global_uncs

std::map<std::string, correction::Variable::Type> m_global_uncs

private

Inputs for fully correlated uncertainties.

m_uncertainties

bool m_uncertainties

private

Calculate uncertainties?

---

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

• interface/GenericSFApplier.h