Namespace: Genparticles

namespace genparticles

Functions

ROOT::RDF::RNode GetBoson(ROOT::RDF::RNode df, const std::string outputname, const std::string &genparticles_pt, const std::string &genparticles_eta, const std::string &genparticles_phi, const std::string &genparticles_mass, const std::string &genparticles_pdg_id, const std::string &genparticles_status, const std::string &genparticles_status_flags, bool is_data)

This function reconstructs the Lorentz vector of a generator-level boson (e.g., W, Z, H). The reconstruction is performed by looping over all genparticles in an event and selecting final-state leptons that originate from the hard process.

The particle selection criteria are:

The particle is a lepton (PDG ID 11-16) with status=1 (stable) and the ‘fromHardProcessFinalState’ (bit 8) status flag OR
The particle has the isDirectHardProcessTauDecayProduct (bit 10) status flag

For real data (when is_data is true), a default Lorentz vector is returned, as no generator-level information is available.

The meaning of the genparticle status flag codes is listed in the table below.

Meaning	Value	Bit (value used in the config)
isPrompt	1	0
isDecayedLeptonHadron	2	1
isTauDecayProduct	4	2
isPromptTauDecayProduct	8	3
isDirectTauDecayProduct	16	4
isDirectPromptTauDecayProduct	32	5
isDirectHadronDecayProduct	64	6
isHardProcess	128	7
fromHardProcess	256	8
isHardProcessTauDecayProduct	512	9
isDirectHardProcessTauDecayProduct	1024	10
fromHardProcessBeforeFSR	2048	11
isFirstCopy	4096	12
isLastCopy	8192	13
isLastCopyBeforeFSR	16384	14

Parameters:

df – input dataframe
outputname – name of the new column containing the reconstructed gen. boson
genparticles_pt – name of the column containing the \(p_T\) of the genparticles
genparticles_eta – name of the column containing the \(\eta\) of the genparticles
genparticles_phi – name of the column containing the \(\phi\) of the genparticles
genparticles_mass – name of the column containing the mass of the genparticles
genparticles_pdg_id – name of the column containing the PDG IDs of the genparticles
genparticles_status – name of the column containing the status of the genparticles
genparticles_status_flags – name of the column containing the status flags of the genparticles, e.g. isPrompt, isHardProcess, isLastCopy, …
is_data – boolean flag to indicate if real data (true) or simulation (false) is processed

Returns:

a new dataframe containing the gen. boson Lorentz vector

ROOT::RDF::RNode GetVisibleBoson(ROOT::RDF::RNode df, const std::string outputname, const std::string &genparticles_pt, const std::string &genparticles_eta, const std::string &genparticles_phi, const std::string &genparticles_mass, const std::string &genparticles_pdg_id, const std::string &genparticles_status, const std::string &genparticles_status_flags, bool is_data)

This function reconstructs the Lorentz vector of a generator-level boson (e.g., W, Z, H), explicitly excluding neutrinos to represent only the visible energy and momentum. The reconstruction is performed by looping over all genparticles in an event and selecting final-state leptons (except neutrinos) that originate from the hard process.

The particle selection criteria are:

The particle is a lepton (PDG ID 11-16) with status=1 (stable) and the ‘fromHardProcessFinalState’ (bit 8) status flag OR
The particle has the isDirectHardProcessTauDecayProduct (bit 10) status flag

Further, particles identified as neutrinos (PDG IDs 12, 14, 16) that pass these initial checks are then excluded from the final four-vector sum.

For real data (when is_data is true), a default Lorentz vector is returned, as no generator-level information is available.

Parameters:

df – input dataframe
outputname – name of the new column containing the reconstructed gen. boson
genparticles_pt – name of the column containing the \(p_T\) of the genparticles
genparticles_eta – name of the column containing the \(\eta\) of the genparticles
genparticles_phi – name of the column containing the \(\phi\) of the genparticles
genparticles_mass – name of the column containing the mass of the genparticles
genparticles_pdg_id – name of the column containing the PDG IDs of the genparticles
genparticles_status – name of the column containing the status of the genparticles
genparticles_status_flags – name of the column containing the status flags of the genparticles, e.g. isPrompt, isHardProcess, isLastCopy, …
is_data – boolean flag to indicate if real data (true) or simulation (false) is processed

Returns:

a new dataframe containing the visible gen. boson Lorentz vector

namespace drell_yan

Functions

ROOT::RDF::RNode DecayFlavor(ROOT::RDF::RNode df, const std::string &outputname, const std::string &lhe_pdg_id, const std::string &lhe_status)

Extract the flavor of a leptonic Drell-Yan process from the LHE information. This function checks if exactly two final-state LHE leptons (electron, muon, tau) of the same flavor are present in the event. If so, the PDG ID of the lepton that the Z boson or the photon decays into is returned. If no such pair is found, the function returns -1.

Possible values of the returned PDG ID are:

11 for a decay into an electron pair,
13 for a decay into a muon pair,
15 for a decay into a tau pair.

Parameters:

df – input dataframe
outputname – name of the new column containing the PDG ID of the decay particles
lhe_pdg_id – name of the column containing the PDG ID values of the LHE particles
lhe_status – name of the column containing the status of the LHE particles

Returns:

a new dataframe with the decay flavor column added.

namespace tau

Functions

ROOT::RDF::RNode HadronicGenTaus(ROOT::RDF::RNode df, const std::string &outputname, const std::string &genparticles_pdg_id, const std::string &genparticles_status_flags, const std::string &genparticles_mother_index)

This function finds all hadronic generator-level taus needed for the matching to the reconstructed hadronic taus, based on the implementation from https://github.com/KIT-CMS/Artus/blob/dictchanges/KappaAnalysis/src/Utility/GeneratorInfo.cc.

The procedure is go trough all genparticles and check, if a genparticle, that is prompt, without any leptonic daughters can be found. If this genparticle has a neutrino as daughter, this genparticle is indentified as a hadronic generator-level tau (GenTau).

Parameters:

df – input dataframe
outputname – name of the output column containing the hadronic tau indices vector
genparticles_pdg_id – name of the column containing the PDG IDs of the genparticles
genparticles_status_flags – name of the column containing the status flags of the genparticles, e.g. isPrompt, isHardProcess, isLastCopy, …
genparticles_mother_index – name of the column containing the mother particle indices of the genparticles

Returns:

a new dataframe with the new column

ROOT::RDF::RNode GenMatching(ROOT::RDF::RNode df, const std::string &outputname, const std::string &hadronic_gen_taus, const std::string &genparticles_pdg_id, const std::string &genparticles_status_flags, const std::string &genparticles_pt, const std::string &genparticles_eta, const std::string &genparticles_phi, const std::string &genparticles_mass, const std::string &reco_had_tau)

This function determines the true origin of a reconstructed hadronic tau by matching it to generator-level particles. The implementation is based on https://github.com/KIT-CMS/Artus/blob/dictchanges/KappaAnalysis/src/Utility/GeneratorInfo.cc.

The matching is represented by integer flags:

Decaytype	Value
IS_ELE_PROMPT	1
IS_MUON_PROMPT	2
IS_ELE_FROM_TAU	3
IS_MUON_FROM_TAU	4
IS_TAU_HAD_DECAY	5
IS_FAKE (not matched)	6

The matching logic is as follows:

For each reconstructed tau, first, the closest “prompt” or “from tau

decay” generator-level electron or muon with
\(p_T\) > 8 GeV is found. The distance ( \(\Delta R\)) to this lepton is saved.
Next, an iteration is done through pre-identified generator-level hadronic taus. If a gen. tau with \(p_T\) > 15 GeV is found within a cone of \(\Delta R\) < 0.2 of the reco. tau, and it is closer than the closest electron/muon found in step 1, the match is classified as IS_TAU_HAD_DECAY (value: 5).
If no such hadronic tau is found, it re-evaluates the closest electron/muon from step 1. If this lepton is within \(\Delta R\) < 0.2 of the reco. tau, the match is classified based on the lepton’s identity and origin:
- Prompt electron (other): IS_ELE_PROMPT (value: 1)
- Prompt muon (other): IS_MUON_PROMPT (value: 2)
- Electron from a tau decay: IS_ELE_FROM_TAU (value: 3)
- Muon from a tau decay: IS_MUON_FROM_TAU (value: 4)
If nothing of the above is matched, the reco. tau is classified as a IS_FAKE (value: 6).

Parameters:

df – input dataframe
outputname – name of the output column containing the gen. matching value
hadronic_gen_taus – name of the column containing the hadronic gen. tau indices found with genparticles::tau::HadronicGenTaus
genparticles_pdg_id – name of the column containing the PDG IDs of the genparticles
genparticles_status_flags – name of the column containing the status flags of the genparticles, e.g. isPrompt, isHardProcess, isLastCopy, …
genparticles_pt – name of the column containing the \(p_T\) of the genparticles
genparticles_eta – name of the column containing the \(\eta\) of the genparticles
genparticles_phi – name of the column containing the \(\phi\) of the genparticles
genparticles_mass – name of the column containing the mass of the genparticles
reco_had_tau – name of the column containing the Lorentz vector of the reconstructed hadronic tau lepton

Returns:

a new dataframe with the new column

ROOT::RDF::RNode GenMatching(ROOT::RDF::RNode df, const std::string &outputname, const std::string &hadronic_gen_taus, const std::string &genparticles_pdg_id, const std::string &genparticles_status_flags, const std::string &genparticles_mother_index, const std::string &genparticles_pt, const std::string &genparticles_eta, const std::string &genparticles_phi, const std::string &genparticles_mass, const std::string &reco_had_tau)

This function determines the true origin of a reconstructed hadronic tau by matching it to generator-level particles. The implementation is based on https://github.com/KIT-CMS/Artus/blob/dictchanges/KappaAnalysis/src/Utility/GeneratorInfo.cc.

The matching is represented by integer flags:

Decaytype	Value
IS_ELE_PROMPT	1
IS_MUON_PROMPT	2
IS_ELE_FROM_TAU	3
IS_MUON_FROM_TAU	4
IS_TAU_HAD_DECAY	5
IS_FAKE (not matched)	6
IS_ELE_PROMPT_FROM_W	7
IS_MUON_PROMPT_FROM_W	8

The matching logic is as follows:

For each reconstructed tau, first, the closest “prompt” or “from tau

decay” generator-level electron or muon with
\(p_T\) > 8 GeV is found. The distance ( \(\Delta R\)) to this lepton is saved.
Next, an iteration is done through pre-identified generator-level hadronic taus. If a gen. tau with \(p_T\) > 15 GeV is found within a cone of \(\Delta R\) < 0.2 of the reco. tau, and it is closer than the closest electron/muon found in step 1, the match is classified as IS_TAU_HAD_DECAY (value: 5).
If no such hadronic tau is found, it re-evaluates the closest electron/muon from step 1. If this lepton is within \(\Delta R\) < 0.2 of the reco. tau, the match is classified based on the lepton’s identity and origin:
- Prompt electron (from W boson): IS_ELE_PROMPT_FROM_W (value: 7)
- Prompt electron (other): IS_ELE_PROMPT (value: 1)
- Prompt muon (from W boson): IS_MUON_PROMPT_FROM_W (value: 8)
- Prompt muon (other): IS_MUON_PROMPT (value: 2)
- Electron from a tau decay: IS_ELE_FROM_TAU (value: 3)
- Muon from a tau decay: IS_MUON_FROM_TAU (value: 4)
If nothing of the above is matched, the reco. tau is classified as a IS_FAKE (value: 6).

Note

This function additionally matches if the prompt electron/muon decayed from a W boson.

Parameters:

df – input dataframe
outputname – name of the output column containing the gen. matching value
hadronic_gen_taus – name of the column containing the hadronic gen. tau indices found with genparticles::tau::HadronicGenTaus
genparticles_pdg_id – name of the column containing the PDG IDs of the genparticles
genparticles_status_flags – name of the column containing the status flags of the genparticles, e.g. isPrompt, isHardProcess, isLastCopy, …
genparticles_mother_index – name of the column containing the mother particle indices of the genparticles
genparticles_pt – name of the column containing the \(p_T\) of the genparticles
genparticles_eta – name of the column containing the \(\eta\) of the genparticles
genparticles_phi – name of the column containing the \(\phi\) of the genparticles
genparticles_mass – name of the column containing the mass of the genparticles
reco_had_tau – name of the column containing the Lorentz vector of the reconstructed hadronic tau lepton

Returns:

a new dataframe with the new column