Namespace: Physicsobject

namespace physicsobject

This namespace contains functions to apply cuts on physics objects. The cut results are typically stored within a mask of the same length as the physics objects vector and is represented by a ROOT::RVec<int>.

In the mask
1 --> object passes a cut
0 --> object does not pass a cut

Multiple cuts can be combined by multiplying masks using physicsobject::CombineMasks.

Functions

ROOT::RDF::RNode PropagateToMET(ROOT::RDF::RNode df, const std::string &outputname, const std::string &p4_met, const std::string &pt_corrected, const std::string &eta_corrected, const std::string &phi_corrected, const std::string &mass_corrected, const std::string &pt, const std::string &eta, const std::string &phi, const std::string &mass, bool apply_propagation, float min_pt)

This function propagates object corrections to the MET based on vectors of physics objects. The objects can be e.g. a collection/vector of jets. If the energy of an object is corrected/changed (e.g. via some scale factor) or due to a shift, this change in energy has to be propagated to the MET vector, and the MET vector has to be adapted accordingly. The MET is recalculated via.

\[\begin{split} E_{T,miss,x}^{\text{corrected}} = E_{T,miss,x} + p_{x,\text{object}} - p_{x,\text{object}}^{\text{corrected}} \\ E_{T,miss,y}^{\text{corrected}} = E_{T,miss,y} + p_{y,\text{object}} - p_{y,\text{object}}^{\text{corrected}} \\ E_{T,miss}^{\text{corrected}} = \sqrt{E_{T,miss,x}^{\text{corrected}} * E_{T,miss,x}^{\text{corrected}} + E_{T,miss,y}^{\text{corrected}} * E_{T,miss,y}^{\text{corrected}}} \end{split}\]

The correction is done for all jets above a certain \(p_T\) threshold.

Parameters:

df – input dataframe
outputname – name of the new column containing the corrected MET Lorentz vector
p4_met – initial/uncorrected MET Lorentz vector
pt_corrected – name of the column containing \(p_T\) vector of the corrected objects
eta_corrected – name of the column containing \(\eta\) vector of the corrected objects
phi_corrected – name of the column containing \(\phi\) vector of the corrected objects
mass_corrected – name of the column containing mass vector of the corrected objects
pt – name of the column containing \(p_T\) vector of the uncorrected objects
eta – name of the column containing \(\eta\) vector of the uncorrected objects
phi – name of the column containing \(\phi\) vector of the uncorrected objects
mass – name of the column containing mass vector of the uncorrected objects
apply_propagation – boolean indicating whether the propagation should be applied or just the original MET vector should be returned
min_pt – minimal \(p_T\), the corrected object has to have in order for the MET propagation to be applied

Returns:

a dataframe with the new column containing the corrected MET Lorentz vector

ROOT::RDF::RNode CutQuantityBarrelEndcap(ROOT::RDF::RNode df, const std::string &outputname, const std::string &eta, const std::string &quantity, const float &barrel_endcap_boundary, const float &lower_threshold_barrel, const float &upper_threshold_barrel, const float &lower_threshold_endcap, const float &upper_threshold_endcap)

This function defines a mask in the dataframe that selects objects based on eta-dependent upper and lower thresholds for a given object quantity. The selection criteria differ between the barrel and endcap regions of the detector.

Parameters:

df – input dataframe
outputname – name of the output mask column
eta – name of the eta column of a physics object in the dataframe
quantity – name of the quantity column to apply the selection on
barrel_endcap_boundary – absolute eta boundary separating the barrel and endcap regions
lower_threshold_barrel – lower threshold for selection in the barrel region
upper_threshold_barrel – upper threshold for selection in the barrel region
lower_threshold_endcap – lower threshold for selection in the endcap region
upper_threshold_endcap – upper threshold for selection in the endcap region

Returns:

a dataframe containing the new mask as a column

ROOT::RDF::RNode VetoSingleObject(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask, const int index)

This function updates the mask by setting the value at the specified index to zero, effectively vetoing the object at that position.

Parameters:

df – input dataframe
outputname – name of the output mask column after vetoing the object
object_mask – name of the mask column that contains object selection flags
index – index of an object that specifies which object to veto

Returns:

a dataframe containing the new mask as a column

ROOT::RDF::RNode VetoSingleObject(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask, const std::string &index_vector, const int position)

This function updates the mask by setting the value at the specified index to zero, effectively vetoing the object at that position.

Parameters:

df – input dataframe
outputname – name of the output mask column after vetoing the object
object_mask – name of the mask column that contains object selection flags
index_vector – name of the column containing indices of objects
position – position in the index vector that specifies which object to veto

Returns:

a dataframe containing the new mask as a column

ROOT::RDF::RNode Count(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask)

This function counts the number of selected objects in the provided object mask and stores the number.

Parameters:

df – input dataframe
outputname – name of the output column storing the object count
object_mask – name of the mask column indicating selected objects

Returns:

a dataframe with a new column

ROOT::RDF::RNode CountFlag(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask, const int &number)

This function checks how many objects are selected based on the provided mask and returns true if the count matches the specified number.

Parameters:

df – input dataframe
outputname – name of the output flag column
object_mask – name of the mask column indicating selected objects
number – expected number of selected objects

Returns:

a dataframe with a new flag column

ROOT::RDF::RNode Veto(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask)

This function checks if there is at least one selected object in the provided object mask. If at least one object is selected, the output flag is set to true, otherwise, it is set to false. This flag can be used to veto events that include a specific object.

Parameters:

df – input dataframe
outputname – name of the output column storing the veto flag
object_mask – name of the mask column indicating selected objects

Returns:

a dataframe with a new flag column

ROOT::RDF::RNode OverlapVeto(ROOT::RDF::RNode df, const std::string &outputname, const std::string &target_p4, const std::string &object_pt, const std::string &object_eta, const std::string &object_phi, const std::string &object_mass, const std::string &object_mask, const float min_delta_r)

This function checks if any object in a given collection (object_mask) overlaps with a specified target object defined by its four-momentum within a user-defined delta_r_cut distance. If an object is found within this threshold, the function returns true, indicating an overlap with the target object. The result can be used to veto events that have overlapping objects.

Parameters:

df – input dataframe
outputname – name of the output column storing the overlap veto flag
target_p4 – name of the column containing the target four-momentum as a ROOT::Math::PtEtaPhiMVector
object_pt – name of the column containing object transverse momenta
object_eta – name of the column containing object pseudorapidities
object_phi – name of the column containing object azimuthal angles
object_mass – name of the column containing object masses
object_mask – name of the column containing the mask of selected objects to compare with
min_delta_r – minimal deltaR distance allowed between objects and target to count as not overlapping

Returns:

a dataframe with a new flag column

ROOT::RDF::RNode LeptonPairVeto(ROOT::RDF::RNode df, const std::string &outputname, const std::string &lepton_pt, const std::string &lepton_eta, const std::string &lepton_phi, const std::string &lepton_mass, const std::string &lepton_charge, const std::string &lepton_mask, const float max_delta_r)

This function checks for the presence of same-flavor opposite-sign lepton pairs with a given deltaR separation (delta_r_cut). If such a pair is found, a veto flag is set and can be later used to remove event with such lepton pairs.

Parameters:

df – input dataframe
outputname – name of the output flag column
lepton_pt – name of the column containing lepton transverse momenta
lepton_eta – name of the column containing lepton pseudorapidities
lepton_phi – name of the column containing lepton azimuthal angles
lepton_mass – name of the column containing lepton masses
lepton_charge – name of the column containing lepton charges
lepton_mask – name of the column containing the mask of selected lepton objects
max_delta_r – maximal deltaR distance allowed between lepton objects to not being vetoed

Returns:

a dataframe with a new flag column

ROOT::RDF::RNode GetIndices(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_mask)

This function extracts the indices of objects that are marked as selected in the given object mask.

Parameters:

df – input dataframe
outputname – name of the output column storing the object indices
object_mask – name of the mask column indicating selected objects

Returns:

a dataframe with a new column

ROOT::RDF::RNode OrderByPt(ROOT::RDF::RNode df, const std::string &outputname, const std::string &object_pt, const std::string &object_mask)

This function orders objects by their transverse momentum ( \(p_T\)) in descending order. Only selected objects based on a provided mask are taken and then sorted according to their \(p_T\).

Parameters:

df – input dataframe
outputname – name of the output column storing sorted object indices
object_pt – name of the column containing object transverse momenta
object_mask – name of the column containing the object selection mask (with 1 for selected objects, 0 otherwise)

Returns:

a dataframe containing the ordered object indices

ROOT::RDF::RNode MassCorrectionWithPt(ROOT::RDF::RNode df, const std::string &outputname, const std::string &raw_mass, const std::string &raw_pt, const std::string &corrected_pt)

This function modifies the mass of objects in an event using the formula.

\[ M_{\text{corrected},i} = M_{\text{raw},i} \times \frac{p_{T,\text{corrected},i}}{p_{T,\text{raw},i}} \]

for each object of an object collection in the event. The correction is applied element-wise to the mass vector and is needed as part of for example energy scale corrections that were before to the transverse momenta.

Parameters:

df – input dataframe
outputname – name of the output column storing the corrected masses
raw_mass – name of the column containing raw object masses
raw_pt – name of the column containing raw object transverse momenta
corrected_pt – name of the column containing corrected transverse momenta

Returns:

a dataframe with a new column

template<typename ...Args> inline ROOT::RDF::RNode CombineMasks(ROOT::RDF::RNode df, const std::string &outputname, const Args... args)

This function takes multiple masks and applies a logical operation ("any_of", "all_of", or "none_of") elemet-wise to generate a combined mask. The function ensures that elements are correctly merged based on the given mode:

"any_of": The resulting mask contains true values if any element of the input masks is true (element-wise)
"all_of": The resulting mask contains true values if all elements of the input masks are true (element-wise)
"none_of": The resulting mask contains true values if no element of the input masks is true (element-wise)

Note

The masks must have the same size, as element-wise operations are performed.

Template Parameters:

Args – variadic template parameter pack representing mask columns plus mode

Parameters:

df – input dataframe
outputname – name of the output column containing the combined mask
args – parameter pack of column names that contain the considered masks of type ROOT::RVec<int>, with the last argument being the mode ("any_of", "all_of", or "none_of")

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutMin(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy a minimum threshold requirement. The mask is created by comparing the values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – minimum threshold value of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutAbsMin(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy a minimum threshold requirement. The mask is created by comparing the absolute values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – minimum threshold value of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutMax(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy a maximum threshold requirement. The mask is created by comparing the values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – maximum threshold value of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutAbsMax(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy a maximum threshold requirement. The mask is created by comparing the absolute values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – maximum threshold value of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutEqual(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy an exact threshold requirement. The mask is created by comparing the values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – exact threshold value of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutAbsEqual(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const T &threshold)

This function defines a mask for objects that satisfy an exact threshold requirement. The mask is created by comparing the absolute values in the specified column with the given threshold, marking elements as 1 if they pass the cut and 0 otherwise.

Template Parameters:

T – type of the threshold and input quantity (e.g. float, int)

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the object column in the NanoAOD for which the cut should be applied, expected to be of type ROOT::RVec<T>
threshold – exact threshold value of type T

Returns:

a dataframe containing the new mask as a column

inline ROOT::RDF::RNode CutBitmask(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const int &threshold)

This function checks whether a specified bit (given by threshold) is set in each element of the input column and creates a new mask column with values of 1 if the bit is set, and 0 otherwise. If threshold is 0 or negative, all values in the mask are set to 1.

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the input column containing the bitmasks of type ROOT::RVec<UChar_t>
threshold – bit position to check in each bitmask

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode CutQuantity(ROOT::RDF::RNode df, const std::string &outputname, const std::string &quantity, const std::vector<T> &selection)

This function compares each element in the input column against a provided selection list and returns a mask column where each entry is 1 if the value is in the selection list and 0 otherwise.

Template Parameters:

T – type of values in the input column and the selection list

Parameters:

df – input dataframe
outputname – name of the new column containing the selected object mask
quantity – name of the input column containing values to be checked of type ROOT::RVec<T>
selection – a vector containing the selection of values of type T

Returns:

a dataframe containing the new mask as a column

template<typename T> inline ROOT::RDF::RNode Size(ROOT::RDF::RNode df, const std::string &outputname, const std::string &vector_quantity)

This function returns the length of the vector containers in columns that contain ROOT::VecOps::RVec<T> objects. The function is templated with T, which must be set to the underlying type of the vector object.

Parameters:

df – input dataframe
outputname – name of the output column storing the object count
vector_quantity – name of the quantity stored in vector structures

Returns:

a dataframe with a new column

namespace electron

Functions

ROOT::RDF::RNode PtCorrectionMC(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &seed_gain, const std::string &es_resolution_up, const std::string &es_resolution_down, const std::string &es_file, const std::string &es_name, const std::string &era, const std::string &variation)

This function calculates uncertainties for the electron energy scale and resolution corrections that are already applied in nanoAOD (Run2 UL). The resolution uncertainty is taken for dedicated variation branches in the nanoAODs. The same cannot be done for the scale uncertainty due to a bug in the nanoAOD (Run2 UL) production. Therefore, a patch is used based on a correctionlib json file. This procedure is recommended by EGM POG and described in.

https://cms-talk.web.cern.ch/t/electron-scale-smear-variables-in-nanoaod/20210

and https://twiki.cern.ch/twiki/bin/view/CMS/EgammaSFJSON

Note

This function is intended for analyses working with Run 2 NanoAODv9 samples. For the corresponding function that can be used with Run 3, look at the overloaded version of this function.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction scale uncertainty patch file
outputname – name of the output column for corrected \(p_T\) values
pt – name of the column containing electron \(p_T\) values
eta – name of the column containing electron pseudorapidities
seed_gain – name of the column containing electron gain values
es_resolution_up – name of the column containing the one sigma upward energy smearing uncertainties
es_resolution_down – name of the column containing the one sigma downward energy smearing uncertainties
es_file – path to the correction file for the energy scale uncertainties
es_name – name of the correction in the es_file
era – data-taking period of Run2, possible options are “2018”, “2017”, “2016postVFP”, “2016preVFP”
variation – name of the energy correction variation that should be calculated (e.g., “resolutionUp”, “resolutionDown”, “scaleUp”, “scaleDown”), for “nominal” nothing is done because energy correction is already applied

Returns:

a dataframe containing the varied electron transverse momenta

ROOT::RDF::RNode PtCorrectionMC(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &delta_eta_sc, const std::string &r9, const std::string &event_seed, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function applies energy scale and resolution corrections to MC. The corrections are obtained from a dedicated correctionlib file.

For Run 3 samples, the electron energy scale correction has to be evaluated using a centrally provided correctionlib file. The documentation of the file content can be found here:

An implementation recipe is provided here: egmScaleAndSmearingExample.py.

Note

This function is intended for analyses working with Run 3 NanoAODv12 or higher. In the Run 2 samples, the scale correction in data is already applied in the NanoAOD files. Look at the overloaded version of this function for Run 2 analyses.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction scale uncertainty patch file
outputname – name of the output column for corrected \(p_T\) values
pt – name of the column containing electron \(p_T\) values
eta – name of the column containing electron pseudorapidities
delta_eta_sc – name of the column containing the distance in pseudorapidity between supercluster and electron
r9 – name of the column containing the R9 value of the electron’s supercluster
event_seed – name of the column containing the event seed for the smearing
sf_file – path to the correction file for the energy scale corrections and variations
sf_name – path to the correction and the uncertainty shifts to be accessed.
variation – name of the energy correction variation that should be calculated (e.g., “resolutionUp”, “resolutionDown”, “scaleUp”, “scaleDown”), for “nominal” nothing is done because energy correction is already applied

Returns:

a dataframe containing the varied electron transverse momenta

ROOT::RDF::RNode PtCorrectionData(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &delta_eta_sc, const std::string &seed_gain, const std::string &r9, const std::string &run, const std::string &sf_file, const std::string &sf_name)

This function applies energy scale corrections to data. The corrections are obtained from a dedicated correctionlib file.

For Run 3 samples, the electron scale correction is not available in the NanoAOD files and the corrections have to be evaluated using a centrally provided correctionlib file. This function should only be used The documentation of the file content can be found here:

An implementation recipe is provided here: egmScaleAndSmearingExample.py.

Note

This function is intended for analyses working with Run 3.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction scale uncertainty patch file
outputname – name of the output column for corrected \(p_T\) values
pt – name of the column containing electron \(p_T\) values
eta – name of the column containing electron pseudorapidities
delta_eta_sc – name of the column containing the distance in pseudorapidity between supercluster and electron
seed_gain – name of the column containing electron gain values
r9 – name of the column containing the R9 value of the electron’s supercluster
run – name of the column containing the run number
sf_file – path to the correction file for the energy scale corrections
sf_name – name of the correction to be accessed. calculated (e.g., “resolutionUp”, “resolutionDown”, “scaleUp”, “scaleDown”), for “nominal” nothing is done because energy correction is already applied

Returns:

a dataframe containing the varied electron transverse momenta

ROOT::RDF::RNode VetoECALGap(ROOT::RDF::RNode df, const std::string &outputname, const std::string &eta, const std::string &delta_eta_sc, const float &end_ecal_barrel, const float &start_ecal_endcap)

This function defines a boolean mask that identifies electrons falling within the ECAL barrel-endcap transition gap. The mask is true for electrons outside the gap and false for those inside.

Parameters:

df – input dataframe
outputname – name of the output column containing the veto mask
eta – name of the column containing electron pseudorapidities
delta_eta_sc – name of the column containing the distance in pseudorapidity between supercluster and electron
end_ecal_barrel – end of the ECAL barrel region (in pseudorapidity)
start_ecal_endcap – begin of the ECAL endcap region (in pseudorapidity)

Returns:

a dataframe containing the new mask as a column

ROOT::RDF::RNode CutInteractionPoint(ROOT::RDF::RNode df, const std::string &outputname, const std::string &eta, const std::string &delta_eta_sc, const std::string &dxy, const std::string &dz, const float &ecal_barrel_endcap_boundary, const float &max_dxy_barrel, const float &max_dz_barrel, const float &max_dxy_endcap, const float &max_dz_endcap)

This function creates a selection mask based on the transverse impact parameter dxy and longitudinal impact parameter dz of electrons. The selection criteria differ between the barrel and endcap regions of the detector.

Parameters:

df – input dataframe
outputname – name of the output column containing the selection mask
eta – name of the column containing electron pseudorapidities
delta_eta_sc – name of the column containing the distance in pseudorapidity between supercluster and electron
dxy – name of the column containing transverse impact parameter
dz – name of the column containing longitudinal impact parameter
ecal_barrel_endcap_boundary – absolute eta boundary separating the barrel and endcap regions
max_dxy_barrel – maximal dxy in the ECAL barrel region
max_dz_barrel – maximal dz in the ECAL barrel region
max_dxy_endcap – maximal dxy in the ECAL endcap region
max_dz_endcap – maximal dz in the ECAL endcap region

Returns:

a dataframe containing the new mask as a column

namespace scalefactor

Functions

ROOT::RDF::RNode Id(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &phi, const std::string &era, const std::string &wp, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates electron ID scale factors (SFs) for a single electron dependening on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

Recommendations by EgammaPOG:

Run2
Run3

Note

This function needs the dependence on phi only in case of 2023 data because for whatever reason EGM POG introduced it only in that era.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the electron scale factor file
outputname – name of the output column containing the ID scale factor
pt – name of the column containing the transverse momentum of an electron
eta – name of the column containing the pseudorapidity of an electron
phi – name of the column containing the azimuthal angle of an electron
era – string with the era name of a data taking period, e.g. “2016preVFP”
wp – working point of the electron id that should be used, e.g. “Medium”, “wp90noiso”, …
sf_file – path to the file with the electron scale factors
sf_name – name of the electron scale factor for the ID correction, e.g. “UL-Electron-ID-SF”
variation – name the scale factor variation, “sf” for the nominal scale factor and “sfup”/”sfdown” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Trigger(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &trigger_flag, const std::string &era, const std::string &path_id_name, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates single electron trigger scale factors (SFs) for a single electron dependening on its pseudorapidity ( \(\eta\)), its transverse momentum ( \(p_T\)), and the electron identification working point. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. This function only uses the scale factor from the correctionlib evaluation if the corresponding trigger flag is set to true. Otherwise, it returns a scale factor of 1.0.

Recommendations by EgammaPOG:

The documentation of the corresponding jsonPOG files can be found here:

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the electron scale factor file
outputname – name of the output column containing the ID scale factor
pt – name of the column containing the transverse momentum of an electron
eta – name of the column containing the pseudorapidity of an electron
trigger_flag – name of the column containing the trigger flag
era – string with the era name of a data taking period, e.g. “2016preVFP”
path_id_name – string that serves as an identifier for the used combination of trigger path and electron ID, e.g. “HLT_SF_Ele30_TightID”, “HLT_SF_Ele30_MVAiso90ID”, …
sf_file – path to the file with the electron scale factors
sf_name – name of the electron scale factor for the ID correction, e.g. “UL-Electron-ID-SF”
variation – name the scale factor variation, “sf” for the nominal scale factor and “sfup”/”sfdown” for the up/down variation

Returns:

a new dataframe containing the new column

namespace fatjet

namespace quantity

Functions

ROOT::RDF::RNode ParticleNet_XvsQCD(ROOT::RDF::RNode df, const std::string &outputname, const std::string &pNet_X_decay, const std::string &pNet_QCD, const std::string &fatjet_collection, const int &position)

This function calculates a discriminator score from two ParticleNet tagger outputs (a signal X and the QCD background). The signal can e.g. be \(X\rightarrow bb\) or \(X\rightarrow cc\) etc.

The score is computed using the formula:

\[ Score = \frac{P(X)}{P(X) + P(QCD)} \]

Note

This function is mainly needed when working with nanoAODv9, in newer versions this ratio is already included as a branch.

Parameters:

df – input dataframe
outputname – name of the new column containing the XvsQCD score
pNet_X_decay – name of the column containing the ParticleNet score for the signal process ( \(X\rightarrow ...\))
pNet_QCD – name of the column containing the ParticleNet score for the QCD background
fatjet_collection – name of the column containing a collection (vector) of good fatjet indices
position – position of the fatjet in the collection (vector) that should be used for the score calculation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode NsubjettinessRatio(ROOT::RDF::RNode df, const std::string &outputname, const std::string &tau_N, const std::string &tau_Nm1, const std::string &fatjet_collection, const int &position)

This function calculates the ratio of two N-subjettiness variables of one fatjet, typically used for discriminating jet substructure:

\[ \tau_{ratio} = \frac{\tau_N}{\tau_{N-1}} \]

For example, \(\tau_{21} = \tau_2 / \tau_1\) for 2-prong vs. 1-prong decay identification. The resulting ratio is always between 0 and 1. If it is close to 0, the jet is more likely to be a N-prong jet, while a value close to 1 indicates a (N-1)-prong jet.

Parameters:

df – input dataframe
outputname – name of the new column containing the N-subjettiness ratio
tau_N – name of the column containing the N-subjettiness variable for the numerator with number N
tau_Nm1 – name of the column containing the N-subjettiness variable for the denominator with number N-1
fatjet_collection – name of the column containing a collection (vector) of good fatjet indices
position – position of the fatjet in the collection (vector) that should be used for the ratio calculation

Returns:

a new dataframe containing the new column

namespace jet

Functions

ROOT::RDF::RNode RawPt(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_pt, const std::string &jet_raw_factor)

This function calculates back to the raw jet transverse momenta based on the raw factor stored in nanoAOD. This is needed to reapply the newest jet energy corrections, since the already applied corrections in the nanoAOD files are often outdated.

Parameters:

df – input dataframe
outputname – name of the new column containing the raw jet \(p_T\)’s
jet_pt – name of the column containing the default jet \(p_T\)’s
jet_raw_factor – name of the column containing the raw factor for each jet to get back to the raw jet \(p_T\)’s

Returns:

a dataframe with a new column of raw jet \(p_T\)’s

ROOT::RDF::RNode PtCorrectionL1(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname_L1, const std::string &outputname_L1_T1MET, const std::string &jet_raw_pt, const std::string &jet_eta, const std::string &jet_phi, const std::string &jet_area, const std::string &jet_raw_muonfactor, const std::string &lowpt_jet_raw_pt, const std::string &lowpt_jet_eta, const std::string &lowpt_jet_phi, const std::string &lowpt_jet_area, const std::string &lowpt_jet_raw_muonfactor, const std::string &rho, const std::string &jec_file, const std::string &jec_algo, const std::string &jes_tag)

This function applies L1 energy corrections to raw jet momenta based on the recommendations of JetMET POG. More details: https://cms-jerc.web.cern.ch/JES/. It calculates corrected jet momenta for both standard and low-pt jets, and stores the results in the specified output columns.

The function needs both standard jets (> 15 GeV) and low-pt jets, and it calculates L1 corrected versions for the standard jets only and the combination of both which is need for the recalculation of MET (met::Type1Correction).

Note

This function can be used for both Run 2 and Run 3 as well as for data and MC.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet energy correction file
outputname_L1 – name of the output column for L1 corrected jet \(p_T\)’s
outputname_L1_T1MET – name of the output column for L1 corrected jet \(p_T\)’s including low-pt jets, this is needed for the Type-1 MET correction
jet_raw_pt – name of the column containing raw jet momenta
jet_eta – name of the column containing jet pseudorapidity
jet_phi – name of the column containing jet azimuthal angle
jet_area – name of the column containing jet area
jet_raw_muonfactor – name of the column containing raw muon subtraction factors
lowpt_jet_raw_pt – name of the column containing raw momenta for low-pt jets
lowpt_jet_eta – name of the column containing pseudorapidity for low-pt jets
lowpt_jet_phi – name of the column containing azimuthal angle for low-pt jets
lowpt_jet_area – name of the column containing area for low-pt jets
lowpt_jet_raw_muonfactor – name of the column containing raw muon subtraction factors for low-pt jets
rho – name of the column containing the event energy density
jec_file – path to the JEC file containing the corrections
jec_algo – name of the JEC algorithm use for jet reconstruction (e.g., “AK4PFchs”, “AK4PUPPI”)
jes_tag – tag for the JES correction campaign (e.g., “Summer19UL18_V5_MC”, “Summer24Prompt24_V2_DATA”)

Returns:

a newdataframe with a two new column of L1 corrected jet \(p_T\)’s

ROOT::RDF::RNode PtCorrectionL2L3(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname_L2L3, const std::string &outputname_L2L3_T1MET, const std::string &jet_L1_pt, const std::string &jet_eta, const std::string &jet_phi, const std::string &jet_area, const std::string &jet_id, const std::string &jet_L1_T1MET_pt, const std::string &lowpt_jet_eta, const std::string &lowpt_jet_phi, const std::string &lowpt_jet_area, const std::string &gen_jet_pt, const std::string &gen_jet_eta, const std::string &gen_jet_phi, const std::string &rho, const std::string &jer_seed, const std::string &run, const std::string &jec_file, const std::string &jec_algo, const std::string &jes_tag, const std::vector<std::string> &jes_shift_sources, const std::string &jer_tag, const int &jes_shift, const std::string &jer_shift, const std::string &era)

This function applies the L2, and L2L3 energy corrections to already L1 corrected jet momenta based on the recommendations of JME POG. More details: https://cms-jerc.web.cern.ch/JES/. It calculates corrected jet momenta for both standard and low-pt jets, and stores the results in the specified output column.

The function needs both standard jets (> 15 GeV) and low-pt jets, and it calculates fully corrected versions for the standard jets only and the combination of both which is need for the recalculation of MET (met::Type1Correction).

Further, this function applies the jet energy resolution smearing to simulated events, based on the JER correction factors provided by JME POG.

This function is able to process the JEC uncertainties, which includes the induvidual jes uncertainties as well as the merged uncertainty scheme. Additionally, the HEM issue (2018) can be included as an uncertainty based on https://hypernews.cern.ch/HyperNews/CMS/get/JetMET/2000.html.

Note

This function can be used for both Run 2 and Run 3 as well as for data and MC.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet energy correction file
outputname_L2L3 – name of the output column for L2L3 corrected jet momenta
outputname_L2L3_T1MET – name of the output column for L2L3 corrected jet momenta for Type-1 MET correction (including low-pt jets)
jet_L1_pt – name of the column containing L1 corrected jet momenta
jet_eta – name of the column containing jet pseudorapidities
jet_phi – name of the column containing jet azimuthal angles
jet_area – name of the column containing jet area
jet_id – name of the column containing jet IDs
jet_L1_T1MET_pt – name of the column containing L1 corrected jet momenta specifically for Type-1 MET correction, which includes low-pt jets
lowpt_jet_eta – name of the column containing low-pt jet pseudorapidities
lowpt_jet_phi – name of the column containing low-pt jet azimuthal angles
lowpt_jet_area – name of the column containing low-pt jet area
gen_jet_pt – name of the column containing generator-level jet momenta
gen_jet_eta – name of the column containing generator-level jet pseudorapidities
gen_jet_phi – name of the column containing generator-level jet azimuthal angles
rho – name of the column containing the event energy density
jer_seed – seed value for the random number generator that is used for the jet energy resolution smearing in MC simulated events
run – name of the column containing the run number (relevant for data)
jec_file – path to the JEC correction file
jec_algo – name of the JEC algorithm use for jet reconstruction (e.g., “AK4PFchs”, “AK4PUPPI”)
jes_tag – tag for the JES correction campaign (e.g., “Summer19UL18_V5_MC”, “Summer24Prompt24_V2_DATA”)
jes_shift_sources – list of JES shift sources for systematic uncertainties
jer_tag – tag of the JER correction campaign (e.g., “Summer19UL18_JRV2_MC”)
jes_shift – JES shift variation (0 = nominal, +/-1 = up/down)
jer_shift – JER shift variation (“nom”, “up”, or “down”)
era – string defining the currently processed era, needed due to different kind of recommendations from JME POG for different eras (e.g., “2018”, “2022preEE”)

Returns:

a new dataframe with two columns for with fully corrected jet momenta

ROOT::RDF::RNode PtCorrectionMC(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &jet_pt, const std::string &jet_eta, const std::string &jet_phi, const std::string &jet_area, const std::string &jet_raw_factor, const std::string &jet_id, const std::string &gen_jet_pt, const std::string &gen_jet_eta, const std::string &gen_jet_phi, const std::string &rho, const std::string &jer_seed, const std::string &jec_file, const std::string &jec_algo, const std::string &jes_tag, const std::vector<std::string> &jes_shift_sources, const std::string &jer_tag, bool reapply_jes, const int &jes_shift, const std::string &jer_shift, const std::string &era, const bool &no_jer_for_unmatched_forward_jets = false)

This function applies jet energy scale corrections (JES) and jet energy resolution (JER) smearing to simulated jets using correction factors. In nanoAOD the JES corrections are already applied to jets, however, if new corrections are measured it is possible to reapply them using the newest correction files by setting reapply_jes to true.

The second part of the jet energy corrections (JEC) is the resolution correction. For that this function follows CMS recommendations on how to apply the jet energy smearing using the hybrid method. (Ref. https://twiki.cern.ch/twiki/bin/viewauth/CMS/JetResolution)

This function is able to process the JEC uncertainties, which includes the induvidual jes uncertainties as well as the merged uncertainty scheme. Additionally, the HEM issue (2018) can be included as an uncertainty based on https://hypernews.cern.ch/HyperNews/CMS/get/JetMET/2000.html

Note

If jets with \(p_T\) > 15 GeV are corrected, this change should be propagated to the missing transverse momentum. (see physicsobject::PropagateToMET)

Note

The option no_jer_for_unmatched_forward_jets is introduced to mitigate jet horns appearing in the eta distribution of jets at \(|\eta| \sim 2-3\) in Run 3 analyses. If the option is set to true, no jet energy resolution smearing is applied to jets without a matching generator-level jet for \(|\eta| > 2.5\). Only use this option set to true if the recipe to mitigate jet horns is implemented in the analysis.

Warning

This function is deprecated. It is recommended to use physicsobject::jet::PtCorrectionL1 and physicsobject::jet::PtCorrectionL2L3 instead for both Run 2 and Run 3 as well as for data and MC.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet energy correction file
outputname – name of the output column for corrected jet \(p_T\)’s
jet_pt – name of the column containing the jet transverse momenta
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
jet_area – name of the column containing the jet catchment area
jet_raw_factor – name of the column containing the jet factors to calculate back to the raw jet \(p_T\)’s
jet_id – name of the column containing the jet IDs
gen_jet_pt – name of the column containing the generator-level jet \(p_T\)’s
gen_jet_eta – name of the column containing generator-level jet etas
gen_jet_phi – name of the column containing generator-level jet phis
rho – name of the column containing the event energy density
jer_seed – seed value for the random number generator that is used for the jet energy resolution smearing
jec_file – path to the JEC correction file
jec_algo – name of the jet reconstruction algorithm (e.g., “AK4PFchs” or “AK8PFPuppi”)
jes_tag – tag of the JES correction campaign (e.g., “Summer19UL18_V5_MC”)
jes_shift_sources – list of JES shift sources for systematic uncertainties
jer_tag – tag of the JER correction campaign (e.g., “Summer19UL18_JRV2_MC”)
reapply_jes – boolean flag to indicate whether to the JES correction should be reapplied
jes_shift – JES shift variation (0 = nominal, +/-1 = up/down)
jer_shift – JER shift variation (“nom”, “up”, or “down”)
era – string defining the currently processed era, needed due to different kind of recommendations from JME POG for different eras
no_jer_for_unmatched_forward_jets – if true, no jet energy resolution smearing is applied to unmatched jets in the forward region ( \(|\eta| > 2.5\)).

Returns:

a dataframe with a new column of corrected jet \(p_T\)’s

ROOT::RDF::RNode PtCorrectionData(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &jet_pt, const std::string &jet_eta, const std::string &jet_phi, const std::string &jet_area, const std::string &jet_raw_factor, const std::string &rho, const std::string &run, const std::string &jec_file, const std::string &jec_algo, const std::string &jes_tag, const std::string &era)

This function applies jet energy corrections (JEC) to jets in real data using correction factors. In nanoAOD the JEC corrections are already applied to jets, however, if new corrections are measured it is possible to reapply them using the newest correction files. The JEC is reapplied to data if a jes_tag is specified.

Unlike in Monte Carlo (MC), no smearing is applied, as resolution corrections are not necessary for data.

Note

If jets with \(p_T\) > 15 GeV are corrected, this change should be propagated to the missing transverse momentum. (see physicsobject::PropagateToMET)

Warning

This function is deprecated. It is recommended to use physicsobject::jet::PtCorrectionL1 and physicsobject::jet::PtCorrectionL2L3 instead for both Run 2 and Run 3 as well as for data and MC.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet energy correction file
outputname – name of the output column for corrected jet \(p_T\)’s
jet_pt – name of the column containing the jet transverse momenta
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
jet_area – name of the column containing the jet catchment area
jet_raw_factor – name of the column containing the jet factors to calculate back to the raw jet \(p_T\)’s
rho – name of the column containing the event energy density
run – name of the column containing the run number
jec_file – path to the JEC correction file
jec_algo – name of the jet reconstruction algorithm (e.g., “AK4PFchs” or “AK8PFPuppi”)
jes_tag – tag of the JES correction campaign which is run dependent (e.g., “Summer19UL18_RunA_V5_DATA”)
era – string defining the currently processed era, needed due to different kind of recommendations from JME POG for different eras

Returns:

a dataframe with a new column of corrected jet \(p_T\)’s

ROOT::RDF::RNode PtCorrectionBJets(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_pt, const std::string &scale_factor, const std::string &bjet_mask)

This function applies a b-jet energy regression. The \(p_T\) correction is applied to all b-jets identified with a b-tagging algorithm, e.g. DeepJet. The goal of the regression is to better estimate the energy of b-jets because compared to other jet flavors, b-jets have a significantly higher rate of leptons and therefore also neutrinos in the decay, which leads to a lower reconstructed energy. The correction is determined with a neural network that was trained to simultaneously estimate the b-jet energy and resolution. The application can be done on top of the general jet energy scale corrections. Ref. http://cds.cern.ch/record/2690804.

Note

This function should only be used for Run2 since the regression was not further developed for Run3 and is also not present in the nanoAODs anymore.

Parameters:

df – input dataframe
outputname – name of the output column for corrected b-jet \(p_T\)’s
jet_pt – name of the column containing the jet \(p_T\)’s
scale_factor – name of the column containing the scale factors for the b-jet \(p_T\)
bjet_mask – name of the column containing the jet mask with identified b-jets

Returns:

a dataframe with a new column

ROOT::RDF::RNode CutPileupID(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_pu_id, const std::string &jet_pt, const int &pu_id_cut, const float &pt_cut)

This function applies a jet pileup ID cut to jets. The pileup ID is recommended to be applied in addition to the usual jet ID and only for jets with \(p_T\) < 50 GeV. (Run2 ref. https://twiki.cern.ch/twiki/bin/view/CMS/PileupJetIDUL)

The jet pileup ID has four possible values:

0: Fail
4: Pass loose
6: Pass loose and medium
7: Pass loose, medium, and tight

Parameters:

df – input dataframe
outputname – name of the output column storing the selection mask
jet_pu_id – name of the column containing jet pileup ID values
jet_pt – name of the column containing jet transverse momenta
pu_id_cut – minimum pileup ID value required for a jet to pass
pt_cut – minimum \(p_T\) threshold for a jet to bypass the pileup ID cut

Returns:

a dataframe containing the new mask as a column

ROOT::RDF::RNode VetoMap(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &jet_eta, const std::string &jet_phi, const std::string &vetomap_file, const std::string &vetomap_name, const std::string &vetomap_type)

This function applies a veto map to jets based on their pseudorapidity and azimuthal angle. This function checks if jets fall within vetoed regions defined in an external correction file from JetMET POG and marks them accordingly in the output mask.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet veto map file
outputname – name of the output column storing the veto mask
jet_eta – name of the column containing jet pseudorapidities
jet_phi – name of the column containing jet azimuthal angles
vetomap_file – path to the veto map file
vetomap_name – name of the veto map correction within the file
vetomap_type – type of veto map to apply, recommented is “jetvetomap”

Returns:

a new dataframe containing the veto mask

ROOT::RDF::RNode VetoMap(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &jet_pt, const std::string &jet_eta, const std::string &jet_phi, const std::string &jet_id, const std::string &jet_ch_em_ef, const std::string &jet_ne_em_ef, const std::string &jet_vetomap_file, const std::string &jet_vetomap_name, const std::string &jet_vetomap_type, const float &min_pt, const int &id_wp, const float &max_em_frac)

Create a veto flag for events with jets in regions, which are known to produce wrong measurements. The function checks for jets which pass the base selection criteria if they are in a eta-phi region with “hot” and/or “cold” towers. Events with any jet in such a region are vetoed in data and simulation. If the event is vetoed, a value of true is stored in the new column, otherwise false. The locations are provided by a correctionlib file and depend on the data-taking era. This procedure follows the official JME POG recommendations.

Note

The veto map selection is mandatory for Run 3 analyses and can also be applied to Run 2 analyses.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet veto map file
outputname – name of the output column storing the veto event mask
jet_pt – name of the column containing the jet transverse momenta
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
jet_id – name of the column containing the jet IDs
jet_ch_em_ef – name of the column containing the jet charged electromagnetic energy fraction
jet_ne_em_ef – name of the column containing the jet neutral electromagnetic energy fraction
jet_vetomap_file – file path to the correctionlib jet veto map
jet_vetomap_name – name of the correction to access jet veto map
jet_vetomap_type – jet veto map type; for analyses, this name should be "jetvetomap".
min_pt – minimum transverse momentum for selected jets
id_wp – working point for the jet identification
max_em_frac – maximum charged and neutral electromagnetic energy fraction for selected jets

Returns:

a new data frame with the veto event mask column

ROOT::RDF::RNode VetoOverlappingJets(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_eta, const std::string &jet_phi, const std::string &target_p4_1, const std::string &target_p4_2, const float &min_delta_r)

This function checks the separation (deltaR) between each jet and the given four-momentum vectors which can be for example a selected lepton pair. If the deltaR is below min_delta_r, the jet is vetoed.

Parameters:

df – input dataframe
outputname – name of the output column storing the veto mask
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
target_p4_1 – first four-momentum vector of a target object pair (e.g., a selected lepton pair)
target_p4_2 – second four-momentum vector of the target object pair (e.g., a selected lepton pair)
min_delta_r – minimal deltaR distance allowed between jets and targets to count as not overlapping

Returns:

a new dataframe containing the veto mask

ROOT::RDF::RNode VetoOverlappingJets(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_eta, const std::string &jet_phi, const std::string &target_p4, const float &min_delta_r)

This function checks the separation (deltaR) between each jet and the given four-momentum vector which can be for example a selected lepton. If the deltaR is smaller than min_delta_r, the jet is vetoed.

Parameters:

df – input dataframe
outputname – name of the output column storing the veto mask
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
target_p4 – four-momentum vector of the target object (e.g., a selected lepton)
min_delta_r – minimal deltaR distance allowed between jets and target to count as not overlapping

Returns:

a new dataframe containing the veto mask

ROOT::RDF::RNode VetoOverlappingJetsWithIsoLepton(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_eta, const std::string &jet_phi, const std::string &lepton_p4, const std::string &lepton_iso, const float &min_delta_r)

This function vetos jets that overlap with an isolated lepton with a given deltaR. A jet is only vetoed if the lepton is flagged as isolated (lepton_iso of +1) and deltaR is smaller than min_delta_r.

Parameters:

df – input dataframe
outputname – name of the output column storing the veto mask
jet_eta – name of the column containing the jet pseudorapidities
jet_phi – name of the column containing the jet azimuthal angles
lepton_p4 – four-momentum vector of the target lepton
lepton_iso – name of the column name containing the lepton isolation flag with values of +1, -1 or 0
min_delta_r – minimal deltaR distance allowed between jets and target to count as not overlapping

Returns:

a new dataframe containing the veto mask

ROOT::RDF::RNode VetoMap(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_eta, const std::string &jet_phi, const std::string &vetomap_file, const std::string &vetomap_name, const std::string &vetomap_type)

namespace quantity

Functions

ROOT::RDF::RNode PatchedIDNanoV12(ROOT::RDF::RNode df, const std::string &outputname, const std::string &jet_pt, const std::string &jet_eta, const std::string &jet_id, const std::string &jet_ne_h_ef, const std::string &jet_ne_em_ef, const std::string &jet_mu_ef, const std::string &jet_ch_em_ef)

Patch for wrong Jet ID values in Run3 NanoAOD v12 samples.

The implementation follows the recipe by the JME POG.

Parameters:

df – input dataframe
outputname – name of the produced column
jet_pt – name of the column with jet pt values
jet_eta – name of the column with jet eta values
jet_id – name of the column with (broken) jet ID values
jet_ne_h_ef – name of the column with neutral hadron energy fraction
jet_ne_em_ef – name of the column with neutral EM energy fraction
jet_mu_ef – name of the column with muon energy fraction
jet_ch_em_ef – name of the column with charged EM energy fraction

Returns:

a dataframe with the new column

ROOT::RDF::RNode ID(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &jet_eta, const std::string &jet_ch_h_ef, const std::string &jet_ne_h_ef, const std::string &jet_ch_em_ef, const std::string &jet_ne_em_ef, const std::string &jet_mu_ef, const std::string &jet_ch_mult, const std::string &jet_ne_mult, const std::string &jet_id_file, const std::string &jet_name)

Applies jet identification criteria based on JSON-defined jet ID corrections.

This function loads jet ID definitions from correctionlib JSON files for the specified jet collection and evaluates two sets of criteria:

Tight ID
Tight Lepton Veto ID

It uses these evaluations to assign a jet ID code to each jet in the input dataframe:

6 : passes Tight and Tight Lepton Veto IDs
2 : passes Tight ID but fails Tight Lepton Veto ID
0 : fails Tight ID (Ref. https://twiki.cern.ch/twiki/bin/view/CMS/JetID13p6TeV#Recommendations_for_the_13_6_AN1)

The jet ID is returned as a vector of int, compatible with NanoAOD v9 conventions.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the jet ID patch file
outputname – name of the new column to hold the computed jet ID flags
jet_eta – name of the branch for jet pseudorapidity
jet_ch_h_ef – name of the branch for charged hadron energy fraction
jet_ne_h_ef – name of the branch for neutral hadron energy fraction
jet_ch_em_ef – name of the branch for charged electromagnetic energy fraction
jet_ne_em_ef – name of the branch for neutral electromagnetic energy fraction
jet_mu_ef – name of the branch for muon energy fraction
jet_ch_mult – name of the branch for number of charged particles in a jet
jet_ne_mult – name of the branch for number of neutral particles in a jet
jet_id_file – path to the jet ID JSON file containing correction definitions
jet_name – prefix of the jet collection used to select the appropriate corrections

Returns:

a new dataframe with the new jet ID column appended

namespace scalefactor

Functions

ROOT::RDF::RNode BtaggingShape(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &btag_value, const std::string &flavor, const std::string &jet_mask, const std::string &bjet_mask, const std::string &jet_veto_mask, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates the b-tagging scale factor. The scale factor corrects inconsistencies in the b-tagging efficiency between data and simulation. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

This producer is optimized for evaluating b-tagging scale factors for a full shape correction of the b-tagging discriminant (DeepJet). Working point based scale factors have different dependencies.

More information from BTV POG can be found here https://btv-wiki.docs.cern.ch/ScaleFactors/

and about the correctionlib files:

Note

TODO: Add Run3 support and additional producers for working point based scale factors.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column containing the b-tagging scale factor
pt – name of the column containing the transverse momenta of jets
eta – name of the column containing the pseudorapidity of jets
btag_value – name of the column containing the btag values of jets based on a b-jet tagger (e.g. DeepJet)
flavor – name of the column containing the flavors of jets, usually used flavors are: 5=b-jet, 4=c-jet, 0=light jet (g, u, d, s)
jet_mask – name of the column containing the mask for good/selected jets
bjet_mask – name of the column containing themask for good/selected b-jets
jet_veto_mask – name of the column containing the veto mask for overlapping jets (e.g. with selected lepton pairs)
sf_file – path to the file with the b-tagging scale factors
sf_name – name of the b-tagging scale factor correction e.g. “deepJet_shape”
variation – name the scale factor variation, available values: central, down_*, up_* (* name of specific variation)

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode BtaggingWP(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &btag_value, const std::string &flavor, const std::string &jet_mask, const std::string &bjet_mask, const std::string &jet_veto_mask, const std::string &sf_file, const std::string &sf_bc_name, const std::string &sf_lf_name, const std::string &sf_wp_name, const std::string &eff_file, const std::string &eff_name, const std::string &sample_type, const std::string &variation, const std::string &btag_wp_name)

This function calculates the event b jet tagging scale factor for a setup with a single working point. The scale factor corrects inconsistencies in the b-tagging efficiency between data and simulation. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. In addition, tagging efficiencies of the jets are loaded from a separate correctionlib file to be able to apply the appropriate scale factor.

The procedure follows the recommendations of the BTV group: https://btv-wiki.docs.cern.ch/PerformanceCalibration/fixedWPSFRecommendations/#scale-factor-recommendations-for-event-reweighting

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column containing the b-tagging scale factor
pt – name of the column containing the transverse momenta of jets
eta – name of the column containing the pseudorapidity of jets
btag_value – name of the column containing the btag scores of jets
flavor – name of the column containing the flavors of jets, usually used flavors are: 5=b-jet, 4=c-jet, 0=light jet (g, u, d, s)
jet_mask – name of the column containing the mask for good/selected jets
bjet_mask – name of the column containing the mask for good/selected b-jets
jet_veto_mask – name of the column containing the veto mask for overlapping jets (e.g. with selected lepton pairs)
sf_file – path to the file with the b-tagging scale factors
sf_name – name of the b-tagging scale factor correction
sf_wp_name – name of the correction set containing the b tagging score cuts for the different working points
eff_file – path to the file with the b jet tagging efficiencies
eff_name – name of the b jet tagging efficiency correction set
variation – name the scale factor variation, available values: central, down_*, up_* (* name of specific variation)
btag_wp_name – string that specifies the b-tagging working point used in an analysis e.g. “L”, “M”, “T”, …

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode BtaggingMultipleWP(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &btag_value, const std::string &flavor, const std::string &jet_mask, const std::string &bjet_mask, const std::string &jet_veto_mask, const std::string &sf_file, const std::string &sf_bc_name, const std::string &sf_lf_name, const std::string &sf_wp_name, const std::string &eff_file, const std::string &eff_name, const std::string &sample_type, const std::string &variation)

This function calculates the event b jet tagging scale factor for a setup with multiple working points. The scale factor corrects inconsistencies in the b-tagging efficiency between data and simulation. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. In addition, tagging efficiencies of the jets are loaded from a separate correctionlib file to be able to apply the appropriate scale factor.

The procedure follows the recommendations of the BTV group: https://btv-wiki.docs.cern.ch/PerformanceCalibration/fixedWPSFRecommendations/#scale-factor-recommendations-for-event-reweighting

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column containing the b-tagging scale factor
pt – name of the column containing the transverse momenta of jets
eta – name of the column containing the pseudorapidity of jets
btag_value – name of the column containing the btag scores of jets
flavor – name of the column containing the flavors of jets, usually used flavors are: 5=b-jet, 4=c-jet, 0=light jet (g, u, d, s)
jet_mask – name of the column containing the mask for good/selected jets
bjet_mask – name of the column containing the mask for good/selected b-jets
jet_veto_mask – name of the column containing the veto mask for overlapping jets (e.g. with selected lepton pairs)
sf_file – path to the file with the b-tagging scale factors
sf_name – name of the b-tagging scale factor correction
sf_wp_name – name of the correction set containing the b tagging score cuts for the different working points
eff_file – path to the file with the b jet tagging efficiencies
eff_name – name of the b jet tagging efficiency correction set
variation – name the scale factor variation, available values: central, down_*, up_* (* name of specific variation)

Returns:

a new dataframe containing the new column

namespace muon

Functions

ROOT::RDF::RNode PtCorrectionMC(ROOT::RDF::RNode df, const std::string &outputname, const std::string &charge, const std::string &pt, const std::string &eta, const std::string &phi, const std::string &gen_pt, const std::string &n_tracker_layers, const std::string &rndm_vector, const std::string &index_vector, const int &position, const std::string &filename, const int error_set, const int error_member)

This function defines a new column in the dataframe that contains the corrected transverse momentum ( \(p_T\)) of a muon, calculated using the Rochester correction for Monte Carlo (MC) simulation.

The correction is taken from https://gitlab.cern.ch/akhukhun/roccor (Run2) and is evaluated using the RoccoR correction function which is also taken from this repository.

The correction is applied depending on whether the muon could be matched to a generator level muon or not. If the muon is matched, the correction is done using kSpreadMC, otherwise kSmearMC is used.

Note

TODO: Corrections for Run3 are not yet implemented

Parameters:

df – input dataframe
outputname – name of the new column containing the corrected \(p_T\) values
charge – name of the column containing the muon charges
pt – name of the column containing the muon transverse momenta
eta – name of the column containing the muon eta values
phi – name of the column containing the muon phi values
gen_pt – name of the column containing the generator level transverse momentum of the matched muon, if no muon can be match a negative default value has to be provide
n_tracker_layers – name of the column containing the number of tracker layers
rndm_vector – name of the column containing random values for the smearing
index_vector – name of the column containing index values
position – position within the index vector used to retrieve the index of the wanted muon
filename – file path to the Rochester correction
error_set – error set number that should be used
error_member – error member number that should be used

Returns:

a dataframe with the new column

ROOT::RDF::RNode PtCorrectionData(ROOT::RDF::RNode df, const std::string &outputname, const std::string &charge, const std::string &pt, const std::string &eta, const std::string &phi, const std::string &index_vector, const int &position, const std::string &filename, int error_set, int error_member)

This function defines a new column in the dataframe that contains the corrected transverse momentum ( \(p_T\)) of a muon, calculated using the Rochester correction for data.

The correction is taken from https://gitlab.cern.ch/akhukhun/roccor (Run2) and is evaluated using the RoccoR correction function which is also taken from this repository.

Note

TODO: Corrections for Run3 are not yet implemented

Parameters:

df – input dataframe
outputname – name of the new column containing the corrected \(p_T\) values
charge – name of the column containing the muon charges
pt – name of the column containing the muon transverse momenta
eta – name of the column containing the muon eta values
phi – name of the column containing the muon phi values
index_vector – name of the column containing index values
position – position within the index vector used to retrieve the index of the wanted muon
filename – file path to the Rochester correction
error_set – error set number that should be used
error_member – error member number that should be used

Returns:

a dataframe with the new column

namespace scalefactor

Functions

ROOT::RDF::RNode Reco(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates muon reco scale factors (SFs) for a single muon dependening on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

Recommendations by MuonPOG:

Run2
Run3

Note

The \(p_T\) dependence of the reco scale factor is only for consistency with the other scale factors. It was only derived in one \(p_T\) bin and should be applied for all muons \(p_T\)’s (recommendation: [10-200] GeV).

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the muon scale factor file
outputname – name of the output column containing the reco scale factor
pt – name of the column containing the transverse momentum of a muon
eta – name of the column containing the pseudorapidity of a muon
sf_file – path to the file with the muon scale factors
sf_name – name of the muon scale factor for the reco correction, e.g. “NUM_TrackerMuons_DEN_genTracks”
variation – name the scale factor variation, “nominal” for the nominal scale factor and “systup”/”systdown” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Id(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates muon ID scale factors (SFs) for a single muon dependening on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

Recommendations by MuonPOG:

Run2
Run3

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the muon scale factor file
outputname – name of the output column containing the ID scale factor
pt – name of the column containing the transverse momentum of a muon
eta – name of the column containing the pseudorapidity of a muon
sf_file – path to the file with the muon scale factors
sf_name – name of the muon scale factor for the ID correction, e.g. “NUM_MediumID_DEN_TrackerMuons”
variation – name the scale factor variation, “nominal” for the nominal scale factor and “systup”/”systdown” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Iso(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates muon iso scale factors (SFs) for a single muon dependening on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

Recommendations by MuonPOG:

Run2
Run3

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the muon scale factor file
outputname – name of the output column containing the iso scale factor
pt – name of the column containing the transverse momentum of a muon
eta – name of the column containing the pseudorapidity of a muon
sf_file – path to the file with the muon scale factors
sf_name – name of the muon scale factor for the iso correction, e.g. “NUM_TightRelIso_DEN_MediumID”
variation – name the scale factor variation, “nominal” for the nominal scale factor and “systup”/”systdown” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Trigger(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates muon trigger scale factors (SFs) for a single muon dependening on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation.

Recommendations by MuonPOG:

Run2
Run3

Warning

This function is deprecated. Use the overloaded function with the additional parameter trigger_flag instead.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the muon scale factor file
outputname – name of the output column containing the trigger scale factor
pt – name of the column containing the transverse momentum of a muon
eta – name of the column containing the pseudorapidity of a muon
sf_file – path to the file with the muon scale factors
sf_name – name of the muon scale factor for the trigger correction, e.g. “NUM_IsoMu24_DEN_CutBasedIdTight_and_PFIsoTight”
variation – name the scale factor variation, “nominal” for the nominal scale factor and “systup”/”systdown” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Trigger(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &trigger_flag, const std::string &sf_file, const std::string &sf_name, const std::string &variation)

This function calculates muon trigger scale factors (SFs) for a single muon depending on its pseudorapidity ( \(\eta\)) and transverse momentum ( \(p_T\)). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. This function only uses the scale factor from the correctionlib evaluation if the corresponding trigger flag is set to true. Otherwise, it returns a scale factor of 1.0.

Recommendations by MuonPOG:

Run2
Run3

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the muon scale factor file
outputname – name of the output column containing the trigger scale factor
pt – name of the column containing the transverse momentum of a muon
eta – name of the column containing the pseudorapidity of a muon
trigger_flag – name of the column containing the trigger flag
sf_file – path to the file with the muon scale factors
sf_name – name of the muon scale factor for the trigger correction, e.g. “NUM_IsoMu24_DEN_CutBasedIdTight_and_PFIsoTight”
variation – name the scale factor variation, “nominal” for the nominal scale factor and “systup”/”systdown” for the up/down variation

Returns:

a new dataframe containing the new column

namespace photon

namespace tau

Functions

std::string get_tes_variation(const float &abs_eta, const int &decay_mode, const int &gen_match, const std::string &variation_efake_dm0_barrel, const std::string &variation_efake_dm1_barrel, const std::string &variation_efake_dm0_endcap, const std::string &variation_efake_dm1_endcap, const std::string &variation_mufake, const std::string &variation_gentau_dm0, const std::string &variation_gentau_dm1, const std::string &variation_gentau_dm10, const std::string &variation_gentau_dm11)

Helper to get the variation of the tau pt scale correction to use in the correctionlib evaluator, depending on the absolute pseudorapidity, decay mode, and gen match of the tau. If no criterion for any of the variations is matched, the nominal shift “nom” is returned.

Parameters:

abs_eta – absolute pseudorapidity of the tau
decay_mode – decay mode of the tau
gen_match – gen match of the tau
variation_efake_dm0_barrel – variation for electron faking a tau with decay mode 0 in the barrel region
variation_efake_dm1_barrel – variation for electron faking a tau with decay mode 1 in the barrel region
variation_efake_dm0_endcap – variation for electron faking a tau with decay mode 0 in the endcap region
variation_efake_dm1_endcap – variation for electron faking a tau with decay mode 1 in the endcap region
variation_mufake – variation for muon faking a tau
variation_gentau_dm0 – variation for genuine tau with decay mode 0
variation_gentau_dm1 – variation for genuine tau with decay mode 1
variation_gentau_dm10 – variation for genuine tau with decay mode 10
variation_gentau_dm11 – variation for genuine tau with decay mode 11

Returns:

the variation to use in the correctionlib evaluator

ROOT::RDF::RNode PtCorrectionMC(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &variation_efake_dm0_barrel, const std::string &variation_efake_dm1_barrel, const std::string &variation_efake_dm0_endcap, const std::string &variation_efake_dm1_endcap, const std::string &variation_mufake, const std::string &variation_gentau_dm0, const std::string &variation_gentau_dm1, const std::string &variation_gentau_dm10, const std::string &variation_gentau_dm11, const std::string &id_vs_jet_wp = "", const std::string &id_vs_ele_wp = "")

This function applies a transverse momentum ( \(p_T\)) correction to hadronic taus in MC simulations.

The correction depends on the physical origin of the tau (electron fake, muon fake, or genuine tau), the decay mode, the \(p_T\), and the pseudorapidity.

For Run 3 analyses, the corrections are calculated for different working points of the DeepTau algorithm, regarding the identification against jets and against electrons. This is not the case for Run 2 analyses. This function can be used for both Run 2 and Run 3 analyses. For Run 2 analyses, the values of id_vs_jet_wp and id_vs_ele_wp can be set to "" to obtain the corrections.

The uncertainty scheme is split into nine different uncertainty sources:

For electrons faking taus, four uncertainty sources are considered, split by the decay modes 0 and 1, and by whether the tau is found in the barrel or the endcap region.
For muons faking taus, one inclusive uncertainty source is considered.
For genuine taus, four uncertainty sources are considered, split by the decay modes 0, 1, 10, and 11. For each source, the variation can be set individually. The variations can take the values nom, up, or down.

The correction procedure is taken from the officially recommendation of the TauPOG:

The implementation of this function is based on the TAU POG recommendations for Run 2 and recommendations for Run 3.

The specification of the correctionlib files used to evaluate the corrections can be found here:

Note

This function is intended to be used for Run 3 analyses. In Run 3, the tau energy scale corrections also depend on the DeepTau working points for ID vs. electrons and vs. jets. An overloaded version of this function exists for this purpose.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
id_vs_jet_wp – working point for the identification against jets; set to "" if the corrections do not depend on this parameter
id_vs_ele_wp – working point for the identification against electrons; set to "" if the corrections do not depend on this parameter
variation_efake_dm0_barrel – variation for electron faking a tau for decay mode 0 in the barrel region, options are “nom”, “up”, “down”
variation_efake_dm1_barrel – variation for electron faking a tau for decay mode 1 in the barrel region, options are “nom”, “up”, “down”
variation_efake_dm0_endcap – variation for electron faking a tau for decay mode 0 in the endcap regionefake_, options are “nom”, “up”, “down”
variation_efake_dm1_endcap – variation for electron faking a tau for decay mode 1 in the endcap region, options are “nom”, “up”, “down”
variation_mufake – variation for muon faking a tau, options are “nom”, “up”, “down”
variation_gentau_dm0 – variation for genuine tau for decay mode 0, options are “nom”, “up”, “down”
variation_gentau_dm1 – variation for genuine tau for decay mode 1, options are “nom”, “up”, “down”
variation_gentau_dm10 – variation for genuine tau for decay mode 10, options are “nom”, “up”, “down”
variation_gentau_dm11 – variation for genuine tau for decay mode 11, options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_eleFake(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &variation_dm0_barrel, const std::string &variation_dm1_barrel, const std::string &variation_dm0_endcap, const std::string &variation_dm1_endcap)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of hadronic taus that originate from electrons that are misidentified. The energy scale correction for these objects is measured for two tau decay modes (dm0 and dm1) and depends on the barrel and endcap region of the detector. This configuration corresponds to the officially provided scale factors in Run 2.

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Run3: https://twiki.cern.ch/twiki/bin/view/CMS/TauIDRecommendationForRun3 (not added yet)

Note

This correction is only applied to misidentified hadronic taus originating from prompt electrons (gen_match=1) and electrons that decayed from a tau lepton (gem_match=3).

Note

This function is intended to be used for Run 2 analyses. In Run 3, the tau energy scale corrections also depend on the DeepTau working points for ID vs. electrons and vs. jets. Use physicsobject::tau::TauCorrectionMC instead.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
variation_dm0_barrel – variation for decay mode 0 in the barrel region, options are “nom”, “up”, “down”
variation_dm1_barrel – variation for decay mode 1 in the barrel region, options are “nom”, “up”, “down”
variation_dm0_endcap – variation for decay mode 0 in the endcap region, options are “nom”, “up”, “down”
variation_dm1_endcap – variation for decay mode 1 in the endcap region, options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_muFake(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &variation)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of hadronic taus that originate from muons that are misidentified. The energy scale correction is always set to 1 and for the uncertainty varied by 1%.

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Run3: https://twiki.cern.ch/twiki/bin/view/CMS/TauIDRecommendationForRun3 (not added yet)

Note

This correction is only applied to misidentified hadronic taus originating from prompt muons (gen_match=2) and muons that decayed from a tau lepton (gen_match=4).

Note

This function is intended to be used for Run 2 analyses. In Run 3, the tau energy scale corrections also depend on the DeepTau working points for ID vs. electrons and vs. jets. Use physicsobject::tau::TauCorrectionMC instead.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
variation – variation of the correction, options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_genuineTau(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &variation_dm0, const std::string &variation_dm1, const std::string &variation_dm10, const std::string &variation_dm11)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of genuine hadronic taus. The energy scale correction for these objects is measured for four tau decay modes (dm0, dm1, dm10 and dm11) of the hadronic tau. This correction is only applied to genuine hadronic taus (gen_match=5).

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Note

This function is intended to be used for Run 2 analyses working with NanoAOD versions below v15 because it is not using the tau ID vsJet and vsEle working points as input.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
variation_dm0 – variation for decay mode 0, options are “nom”, “up”, “down”
variation_dm1 – variation for decay mode 1, options are “nom”, “up”, “down”
variation_dm10 – variation for decay mode 10, options are “nom”, “up”, “down”
variation_dm11 – variation for decay mode 11, options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_genuineTau(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &variation_dm0_pt20to40, const std::string &variation_dm0_pt40toInf, const std::string &variation_dm1_pt20to40, const std::string &variation_dm1_pt40toInf, const std::string &variation_dm10_pt20to40, const std::string &variation_dm10_pt40toInf, const std::string &variation_dm11_pt20to40, const std::string &variation_dm11_pt40toInf)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of genuine hadronic taus. The energy scale correction for these objects is measured for four tau decay modes (dm0, dm1, dm10 and dm11) and in two ( \(p_T\)) bins of the hadronic tau. This correction is only applied to genuine hadronic taus (gen_match=5).

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Note

This function is intended to be used for Run 2 analyses working with NanoAOD versions below v15 because it is not using the tau ID vsJet and vsEle working points as input.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
variation_dm0_pt20to40 – variation for decay mode 0 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm0_pt40toInf – variation for decay mode 0 and \(40 \leq p_{T,\tau} <\infty\) GeV, options are “nom”, “up”, “down”
variation_dm1_pt20to40 – variation for decay mode 1 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm1_pt40toInf – variation for decay mode 1 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm10_pt20to40 – variation for decay mode 10 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm10_pt40toInf – variation for decay mode 10 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm11_pt20to40 – variation for decay mode 11 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm11_pt40toInf – variation for decay mode 11 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_genuineTau(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &wp, const std::string &vsele_wp, const std::string &variation_dm0, const std::string &variation_dm1, const std::string &variation_dm10, const std::string &variation_dm11)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of genuine hadronic taus. The energy scale correction for these objects is measured for four tau decay modes (dm0, dm1, dm10 and dm11) of the hadronic tau. This correction is only applied to genuine hadronic taus (gen_match=5).

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Run3: https://twiki.cern.ch/twiki/bin/view/CMS/TauIDRecommendationForRun3

Note

This function is intended to be used for Run 3 analyses or Run 2 analyses working with NanoAODv15. The reason is the newly introduced dependence of the tau ID vsJet and vsEle working points.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
wp – working point of the vsJet ID
vsele_wp – working point of the vsEle ID
variation_dm0 – variation for decay mode 0, options are “nom”, “up”, “down”
variation_dm1 – variation for decay mode 1, options are “nom”, “up”, “down”
variation_dm10 – variation for decay mode 10, options are “nom”, “up”, “down”
variation_dm11 – variation for decay mode 11, options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

ROOT::RDF::RNode PtCorrectionMC_genuineTau(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &es_file, const std::string &correction_name, const std::string &id_algorithm, const std::string &wp, const std::string &vsele_wp, const std::string &variation_dm0_pt20to40, const std::string &variation_dm0_pt40toInf, const std::string &variation_dm1_pt20to40, const std::string &variation_dm1_pt40toInf, const std::string &variation_dm10_pt20to40, const std::string &variation_dm10_pt40toInf, const std::string &variation_dm11_pt20to40, const std::string &variation_dm11_pt40toInf)

This function corrects the transverse momentum ( \(p_T\)) in MC simulations of genuine hadronic taus. The energy scale correction for these objects is measured for four tau decay modes (dm0, dm1, dm10 and dm11) and in two ( \(p_T\)) bins of the hadronic tau. This correction is only applied to genuine hadronic taus (gen_match=5).

The correction procedure is taken from the officially recommendation of the TauPOG:

Run2 (UL): https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2

Run3: https://twiki.cern.ch/twiki/bin/view/CMS/TauIDRecommendationForRun3

Note

This function is intended to be used for Run 3 analyses or Run 2 analyses working with NanoAODv15. The reason is the newly introduced dependence of the tau ID vsJet and vsEle working points.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the correction file
outputname – name of the output column storing the corrected hadronic tau \(p_T\) values
pt – name of the input column containing hadronic tau \(p_T\) values
eta – name of the column containing hadronic tau eta values
decay_mode – name of the column containing hadronic tau decay modes
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
es_file – path to the correction file for the energy scale correction
correction_name – name of the correction in es_file
id_algorithm – identification algorithm used for hadronic tau ID
wp – working point of the vsJet ID
vsele_wp – working point of the vsEle ID
variation_dm0_pt20to40 – variation for decay mode 0 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm0_pt40toInf – variation for decay mode 0 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm1_pt20to40 – variation for decay mode 1 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm1_pt40toInf – variation for decay mode 1 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm10_pt20to40 – variation for decay mode 10 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm10_pt40toInf – variation for decay mode 10 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm11_pt20to40 – variation for decay mode 11 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm11_pt40toInf – variation for decay mode 11 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”

Returns:

a dataframe containing the corrected transverse momenta

namespace quantity

Functions

ROOT::RDF::RNode IDFlag_v9(ROOT::RDF::RNode df, const std::string &outputname, const std::string &ID, const std::string &index_vector, const int &position, const int &wp)

This function writes out a flag that is true if a tau passes a specific tau ID working point (wp). The working point is defined by the bit value. The bit values can be found e.g. in the description of the tau ID scale factors.

Note

This function should be used only for nanoAODv9. Starting with nanoAODv12 physicsobject::tau::quantity::IDFlag_v12 should be used instead because the content of the tau ID branches was changed.

Parameters:

df – input dataframe
outputname – name of the output column containing the flag
ID – name of the column containing the tau ID values
index_vector – name of the column containing the vector with the relevant tau pair indices
position – position in the index vector of the relevant tau in the pair
wp – bit value of the WP that has to be passed

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode IDFlag_v12(ROOT::RDF::RNode df, const std::string &outputname, const std::string &ID, const std::string &index_vector, const int &position, const int &wp)

This function writes out a flag that is true if a tau passes a specific tau ID working point (wp). The content of the tau ID branch changed in nanoAODv12. The working points are defied in integer steps (still saved as UChar_t).

For vsJet and vsEle: 1 = VVVLoose, 2 = VVLoose, 3 = VLoose, 4 = Loose, 5 = Medium, 6 = Tight, 7 = VTight, 8 = VVTight

For vsMu: 1 = VLoose, 2 = Loose, 3 = Medium, 4 = Tight

Parameters:

df – input dataframe
outputname – name of the output column containing the flag
ID – name of the column containing the tau ID values
index_vector – name of the column containing the vector with the relevant tau pair indices
position – position in the index vector of the relevant tau in the pair
wp – bit value of the WP that has to be passed

Returns:

a new dataframe containing the new column

namespace scalefactor

Functions

ROOT::RDF::RNode Id_vsJet_lt(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &decay_mode, const std::string &gen_match, const std::string &sf_file, const std::string &sf_name, const std::vector<int> &selected_dms, const std::string &wp, const std::string &vsele_wp, const std::string &sf_dependence, const std::string &variation_pt30to35, const std::string &variation_pt35to40, const std::string &variation_pt40to500, const std::string &variation_pt500to1000, const std::string &variation_pt1000toInf)

This function calculates scale factors (SFs) for tau identification (ID) against jets (vsJet). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The variation and the scale factor itself is binned in transverse momenta ( \(p_T\)) of hadronic taus for this function.

Description of the bit map used to define the tau ID against jets working points of the DeepTau v2.1 tagger. vsJets | Value | Bit (value used in the config) ————————————|—-—|—-— no ID selection (takes every tau) | 0 | - VVVLoose | 1 | 1 VVLoose | 2 | 2 VLoose | 4 | 3 Loose | 8 | 4 Medium | 16 | 5 Tight | 32 | 6 VTight | 64 | 7 VVTight | 128 | 8

Warning

This function uses an outdated \(p_T\) splitting for the uncertainty variations from legacy H(tautau).

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the vsJets ID scale factor
pt – name of the column containing the transverse momentum of a tau
decay_mode – name of the column containing the decay mode of the tau
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the vsJet ID correction
selected_dms – list of allowed decay modes for which a scale factor should be calculated
wp – working point of the vsJet ID
vsele_wp – working point of the vsEle ID
sf_dependence – variable dependence of the scale factor, options are “pt” or “dm”
variation_pt30to35 – name of the scale factor variation for \(30 \leq p_T <35\) GeV, “nom” for nominal and “up”/”down” the up/down variation
variation_pt35to40 – name of the scale factor variation for \(35 \leq p_T <40\) GeV, “nom” for nominal and “up”/”down” the up/down variation
variation_pt40to500 – name of the scale factor variation for \(40 \leq p_T <500\) GeV, “nom” for nominal and “up”/”down” the up/down variation
variation_pt500to1000 – name of the scale factor variation for \(500 \leq p_T <1000\) GeV, “nom” for nominal and “up”/”down” the up/down variation
variation_pt1000toInf – name of the scale factor variation for \(1000 \leq p_T < \infty \) GeV, “nom” for nominal and “up”/”down” the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Id_vsJet(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &decay_mode, const std::string &gen_match, const std::string &sf_file, const std::string &sf_name, const std::string &wp, const std::string &vsele_wp, const std::string &sf_dependence, const std::string &variation_dm0, const std::string &variation_dm1, const std::string &variation_dm10, const std::string &variation_dm11)

This function calculates scale factors (SFs) for tau identification (ID) against jets (vsJet). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The variation and the scale factor itself is binned in decay modes of hadronic taus for this function.

Description of the bit map used to define the tau ID against jets working points of the DeepTau v2.1 or v2.5 tagger. vsJets | Value | Bit (value used in the config) ————————————|—-—|—-— no ID selection (takes every tau) | 0 | - VVVLoose | 1 | 1 VVLoose | 2 | 2 VLoose | 4 | 3 Loose | 8 | 4 Medium | 16 | 5 Tight | 32 | 6 VTight | 64 | 7 VVTight | 128 | 8

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the vsJets ID scale factor
pt – name of the column containing the transverse momentum of a tau
decay_mode – name of the column containing the decay mode of the tau
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the vsJet ID correction
wp – working point of the vsJet ID
vsele_wp – working point of the vsEle ID
sf_dependence – variable dependence of the scale factor, options are “pt” (which is dm+pt) or “dm” (which is dm only)
variation_dm0 – name of the scale factor variation for decay mode 0, “nom” for nominal and “up”/”down” the up/down variation
variation_dm1 – name of the scale factor variation for decay mode 1, “nom” for nominal and “up”/”down” the up/down variation
variation_dm10 – name of the scale factor variation for decay mode 10, “nom” for nominal and “up”/”down” the up/down variation
variation_dm11 – name of the scale factor variation for decay mode 11, “nom” for nominal and “up”/”down” the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Id_vsJet(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &decay_mode, const std::string &gen_match, const std::string &sf_file, const std::string &sf_name, const std::string &wp, const std::string &vsele_wp, const std::string &sf_dependence, const std::string &variation_dm0_pt20to40, const std::string &variation_dm0_pt40toInf, const std::string &variation_dm1_pt20to40, const std::string &variation_dm1_pt40toInf, const std::string &variation_dm10_pt20to40, const std::string &variation_dm10_pt40toInf, const std::string &variation_dm11_pt20to40, const std::string &variation_dm11_pt40toInf)

This function calculates scale factors (SFs) for tau identification (ID) against jets (vsJet). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The variation and the scale factor itself is binned in decay modes and transverse momentum of hadronic taus for this function.

Description of the bit map used to define the tau ID against jets working points of the DeepTau v2.1 and v2.5 tagger. vsJets | Value | Bit (value used in the config) ————————————|—-—|—-— no ID selection (takes every tau) | 0 | - VVVLoose | 1 | 1 VVLoose | 2 | 2 VLoose | 4 | 3 Loose | 8 | 4 Medium | 16 | 5 Tight | 32 | 6 VTight | 64 | 7 VVTight | 128 | 8

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the vsJets ID scale factor
pt – name of the column containing the transverse momentum of a tau
decay_mode – name of the column containing the decay mode of the tau
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the vsJet ID correction
wp – working point of the vsJet ID
vsele_wp – working point of the vsEle ID
sf_dependence – variable dependence of the scale factor, options are “pt” (which is dm+pt) or “dm” (which is dm only)
variation_dm0_pt20to40 – variation for decay mode 0 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm0_pt40toInf – variation for decay mode 0 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm1_pt20to40 – variation for decay mode 1 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm1_pt40toInf – variation for decay mode 1 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm10_pt20to40 – variation for decay mode 10 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm10_pt40toInf – variation for decay mode 10 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”
variation_dm11_pt20to40 – variation for decay mode 11 and \(20 \leq p_T <40\) GeV, options are “nom”, “up”, “down”
variation_dm11_pt40toInf – variation for decay mode 11 and 40 GeV \(\leq p_{T,\tau}\), options are “nom”, “up”, “down”

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Id_vsEle(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &eta, const std::string &decay_mode, const std::string &gen_match, const std::string &sf_file, const std::string &sf_name, const std::string &wp, const std::string &era, const std::string &variation_barrel, const std::string &variation_endcap)

This function calculates scale factors (SFs) for tau identification (ID) against electrons (vsEle). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The variation and the scale factor itself is binned in pseudorapidities of hadronic taus for this function.

Description of the bit map used to define the tau ID against electrons working points of the DeepTau v2.1 tagger. vsElectrons | Value | Bit (value used in the config) ————————————|—-—|—-— no ID selection (takes every tau) | 0 | - VVVLoose | 1 | 1 VVLoose | 2 | 2 VLoose | 4 | 3 Loose | 8 | 4 Medium | 16 | 5 Tight | 32 | 6 VTight | 64 | 7 VVTight | 128 | 8

Note

This function is intended to be used with Run 2 analyses. The scale factor additionally depends on the decay mode of the tau in Run 3. For Run 3 analyses, use the overloaded version of this function.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the vsEle ID scale factor
eta – name of the column containing the pseudorapidity of a tau
decay_mode – name of the column containing the decay mode of the tau
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
era – data-taking era, e.g. “2017” or “2018”, needed to set the eta boundaries for the endcap region
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the vsEle ID correction
wp – working point of the vsEle ID
variation_barrel – name of the scale factor variation for the barrel region ( \(|\eta| <1.46\)), “nom” for nominal and “up”/”down” the up/down variation
variation_endcap – name of the scale factor variation for the endcap region ( \(1.558 \leq |\eta| <2.3\)), “nom” for nominal and “up”/”down” the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Id_vsMu(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &eta, const std::string &gen_match, const std::string &sf_file, const std::string &sf_name, const std::string &wp, const std::string &wp_ele, const std::string &wp_jet, const std::string &era, const std::string &variation_wheel1, const std::string &variation_wheel2, const std::string &variation_wheel3, const std::string &variation_wheel4, const std::string &variation_wheel5)

This function calculates scale factors (SFs) for tau identification (ID) against muons (vsMu). The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The variation and the scale factor itself is binned in pseudorapidities of hadronic taus for this function.

Description of the bit map used to define the tau ID against muons working points of the DeepTau v2.1 tagger. vsMuons | Value | Bit (value used in the config) ————————————|—-—|—-— no ID selection (takes every tau) | 0 | - VLoose | 1 | 1 Loose | 2 | 2 Medium | 4 | 3 Tight | 8 | 4

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the vsMu ID scale factor
eta – name of the column containing the pseudorapidity of a tau
gen_match – name of the column with the matching information of the hadronic tau to generator-level particles (matches are: 1=prompt e, 2=prompt mu, 3=tau->e, 4=tau->mu, 5=had. tau, 0=unmatched)
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the vsMu ID correction
wp – working point of the vsMu ID
wp_ele – working point of the vsEle ID
wp_jet – working point of the vsJet ID
era – string defining the currently processed era, needed due to different kind of scale factor dependencies introduced by TAU POG for different eras
variation_wheel1 – name of the scale factor variation for the muon wheel ( \(|\eta| <0.4\)), “nom” for nominal and “up”/”down” the up/down variation
variation_wheel2 – name of the scale factor variation for the muon wheel ( \(0.4 \leq |\eta| <0.8\)), “nom” for nominal and “up”/”down” the up/down variation
variation_wheel3 – name of the scale factor variation for the muon wheel ( \(0.8 \leq |\eta| <1.2\)), “nom” for nominal and “up”/”down” the up/down variation
variation_wheel4 – name of the scale factor variation for the muon wheel ( \(1.2 \leq |\eta| <1.7\)), “nom” for nominal and “up”/”down” the up/down variation
variation_wheel5 – name of the scale factor variation for the muon wheel ( \(1.7 \leq |\eta| <2.3\)), “nom” for nominal and “up”/”down” the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Trigger(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &decay_mode, const std::string &sf_file, const std::string &sf_name, const std::string &trigger_name, const std::string &wp, const std::string &corr_type, const std::string &variation)

This function calculates scale factors (SFs) for tau triggers. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The scale factor is binned in \(p_T\) and decay modes of hadronic taus for this function.

Warning

This function is deprecated. Use the overloaded function with the additional parameter trigger_flag instead.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the trigger scale factor
pt – name of the column containing the transverse momentum of a tau
decay_mode – name of the column containing the decay mode of the tau
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the trigger correction
trigger_name – name of the trigger, e.g. “ditau”, “etau”, “mutau”
wp – working point of the vsJet ID
corr_type – type of the value to be read out, options are “sf” (for scale factors), “eff_data”, “eff_mc”
variation – name the scale factor variation, “nom” for the nominal scale factor and “up”/”down” for the up/down variation

Returns:

a new dataframe containing the new column

ROOT::RDF::RNode Trigger(ROOT::RDF::RNode df, correctionManager::CorrectionManager &correction_manager, const std::string &outputname, const std::string &pt, const std::string &decay_mode, const std::string &trigger_flag, const std::string &sf_file, const std::string &sf_name, const std::string &trigger_name, const std::string &wp, const std::string &corr_type, const std::string &variation)

This function calculates scale factors (SFs) for tau triggers. The scale factors are loaded from a correctionlib file using a specified scale factor name and variation. The scale factor is binned in \(p_T\) and decay modes of hadronic taus for this function. This function only uses the scale factor from the correctionlib evaluation if the corresponding trigger flag is set to true. Otherwise, it returns a scale factor of 1.0.

Parameters:

df – input dataframe
correction_manager – correction manager responsible for loading the tau scale factor file
outputname – name of the output column containing the trigger scale factor
pt – name of the column containing the transverse momentum of a tau
decay_mode – name of the column containing the decay mode of the tau
trigger_flag – name of the column containing the trigger flag
sf_file – path to the file with the tau scale factors
sf_name – name of the tau scale factor for the trigger correction
trigger_name – name of the trigger, e.g. “ditau”, “etau”, “mutau”
wp – working point of the vsJet ID
corr_type – type of the value to be read out, options are “sf” (for scale factors), “eff_data”, “eff_mc”
variation – name the scale factor variation, “nom” for the nominal scale factor and “up”/”down” for the up/down variation

Returns:

a new dataframe containing the new column