Configuration files
Here a more detailed description of the configuration files is given. We focus on those options that have been recently implemented or that might be confusing to Analyzer users.
Let's understand first the structure of our output files. After you run the Analyzer, you can explore what is in the output file by running:
root -l <outputFilename>.root
This file will have the following structure:
These trees are copies of the original trees stored in the samples analyzed and contain a subset of the branches in them. Only one event is stored in each of these branches. They are kept for cross-checking purposes and future developments (for example, use the framework with CRAB).
These folders are made when reading PartDet/Cuts.in and represent the cutflow of our analysis. In each folder a copy of all histograms we chose to print in PartDet/Hist_entries.in is stored after applying the cut referred in the name of the folder. This is helpful to study how the distributions changed after one or a set of cuts are applied.
By default, the last significant cut (range is not [0, -1]) will be printed into a folder. To add folders, edit your PartDet/Cuts.in file adding *** before the cut/folder you want to print without any intermediate spaces. For example, to print the NDiTauCombinations folder:
NRecoMuon1 0 -1
NRecoTau1 2 2
***NDiTauCombinations 1 2
NSusyCombinations 1 -1
NDiJetCombinations 0 -1
More details about Cuts.in and Hist_entries.in is given below.
New trees can be stored by filling them in the main Analyzer code or when using the Special analyzer.
Currently, the relevant configuration files in the analyzer are:
| General | Particle definitions | DiParticle combinations | Histograms | Systematics |
|---|---|---|---|---|
Cuts.in |
Electron_info.in |
DiParticle_info.in |
Hist_entries.in |
Systematics_info.in |
Run_info.in |
Muon_info.in |
ElectronJet_info.in |
Hist_syst_entries.in |
|
Gen_info.in |
Tau_info.in |
ElectronTau_info.in |
||
Jet_info.in |
MuonElectron_info.in |
|||
FatJet_info.in |
MuonTau_info.in |
|||
Photon_info.in |
MuonTau_info.in |
The files ControlRegions.in and VBFCuts_info.in are kept for historical reasons but are not part of the latest version of the Analyzer. The descriptions below highlight the main changes to several of these files.
This file includes several options that apply globally to all events. Everything is under the block called Run.
Here we have information related to pileup, event weights, gen-level selections, triggers, MET and more advanced options like mu->nu emulation.
After studying the modification of the official recipe to derive JER corrections for jets in 2017, some remaining effects from the EE noise and mis-calibration are present in data, specifically for jets with 50 < pT < 80 GeV and 2.65 < |eta| < 3.14. This problem shows up only in data eras 2017E and 2017F. Therefore a new event veto was developed and implemented to reject events with one or more jets with these problematic (pT, eta) regions only for the affected eras. It was implemented as a new flag in the Run_info.in configuration file:
ApplyEEnoiseVeto2017EF true
There is NO need to run separately data taking eras 2017E and 2017F, since this functionality checks internally the era and applies the veto only to those that are affected. This flag should be turned on for data and off for running over simulation. More details about the event veto can be found here (slides 23-29)
In Run II, a modulation of the MET in phi has been observed for data and MC. Therefore, additional corrections to handle this asymmetry have been derived per year for data and simulation. These corrections are applied to the type-I corrected MET. More details about the asymmetry, corrections and implementations can be found in this presentation (slides 31-36). These corrections are available for each year and can be applied by using the following flag:
ApplyMETxyShiftCorrections true
It is recommended to include these corrections in your studies, specially if any of your key kinematic variables for your signal or control region studies rely on the phi coordinate of MET. The validation for 2016 has been performed already and found in the presentation linked above.
Given the disagreement of data/MC in the MET distribution for a standard candle Z(->mumu)+jets control region, several studies were performed to understand the source of the disagreement. All of them point to a correlation of the mismodeling of pileup activity in simulation. Therefore, a new set of event weights was derived in this CR, correcting the shape of the number of primary vertices (NPV) distribution in simulation to match the observed one in data. These weights work as an additional pileup correction and had an impact on improving the data/MC agreement in the MET distribution in this particular region. In order to include these corrections a new flag has been added (ApplyNPVweights):
UsePileUpWeight true
ApplyNPVweights true
At the moment these weights are available 2016-2018 (update: June 3, 2021). Information about the derivation and validation of these weights can be found here (slides 37-43).
In 2016 & 2017, the gradual timing shift of ECAL was not properly propagated, leading to a significant fraction of high eta L1 trigger primitives (TP) being mistakenly associated to the previous bunch crossing. The result is that events can self veto if a significant amount of ECAL energy is found in the region of 2.<|eta|<3. This effect is not described by the simulations, and therefore weights have been added to correct for this. These weights should only be applied to 2016 & 2017 samples. More information can be found here and here.
To (de)activate these weights, you need to turn the following flag to (false) true:
ApplyL1PrefiringWeight true
These weights have been validated in a W+jets and Z+jets regions, showing their effect on two different sets of selections: those for central objects and those proper of VBF topologies. The latest updates to this functionality and validations are described in the following links for years 2016 and 2017.
A number of different Z Boost scale factor options have been derived to correct for mismodeling in MC when running over Z+Jets and W+Jets control regions. These weights, which are topology dependent, include:
ApplyISRZBoostSF false
ApplySUSYZBoostSF false
ApplyVBFSusyZBoostSF false
- ApplyISRZBoostSF corrects for ISR type topologies (as derived from SUS-19-002),
- ApplySUSYZBoostSF are the official weights derived by the SUSY PAG (SUS-17-002): these weights are Z-mass and Z-pT dependent, where the mass and pT are taken from the gen-level information,
- ApplyVBFSusyZBoostSF are weights derived by the VBF SUSY team (slide 3) for Run II to correct VBF topologies: these weights were derived for on-mass shell Z bosons (reconstructed dilepton mass between 60 and 120 GeV) and Z-pT dependent, where the Z-pT corresponds to the reconstructed dilepton (dimuon) pT.
Only one set of Z-boost scale factors should be applied at a time, and only to MC. These weights apply to 2016, 2017, & 2018.
Note (Sep 28, 2020): The VBFSusyZBoostSFs are currently being applied to W/Z bosons with any gen-level mass (no requirements) and taking the gen-level pT. This method is not at all completely correct, since there can be differences between the gen- and reco-level Z-pT. The VBF SUSY team is currently working on improve this implementation. Use this set of weights keeping the above in mind.
There is a filter for the data in this framework that reads the information from the golden JSON file for each data-taking period. This is because good run and luminosity sections are not selected already in the nanoAOD datasets. In the latest version of the Analyzer, the year corresponding to the data/MC being analyzed is an input argument that will automatically take care of reading the right golden JSON file (which keeps track of the good parts of the data). In the Analyzer, this is done by the new Analyzer::checkGoodRunsAndLumis function called in Analyzer::preprocess. Please read the notes to follow:
- In
Analyzer/Pileup, there is a file calledjson2016.txt. This file has the good run and luminosity section bounds for 2016 data.- This file is in a format that is usable for the filter. That is, it is a series of numbers separated by commas.
- The first number in the line is the run number.
- The subsequent numbers in each line define the luminosity bounds that are good. That is, consider the following:
- Example: 112500,17,20,41,57: Run 112500 has good luminosity sections from 17 to 20, inclusive, and 41 to 57, inclusive.
When you are running over data samples, you most likely need to filter them by good run and lumi sections (like SingleMuon), then set the following option to true
FilterDataByGoldenJSON true
Some special cases may not need filtering, so you can turn this filter off.
- The current good Pileup files for the various runs have been added to Analyzer/Pileup. Thanks to Brandon for gathering these:
| Year | Data (nom) | MC | Data (syst. down) | Data (syst. up) |
|---|---|---|---|---|
| 2016 | PileUpReweighting2016.root | mc2016_pileup_Dec2018reReco.root | PileUpReweighting2016Do.root | PileUpReweighting2016Up.root |
| 2017 | PileUpReweighting2017.root | mc2017_pileup_Dec2018reReco.root | PileUpReweighting2017Do.root | PileUpReweighting2017Up.root |
| 2018 | PileUpReweighting2018.root | mc2018_pileup_Dec2018reReco.root | PileUpReweighting2018Do.root | PileUpReweighting2018Up.root |
Note: After the update on June 16, 2020, the files PileUpReweighting201X.root contain the three pileup distributions: nominal (pileup), shift up (pileupUp) and shift down (pileupDo). However, nothing changes in the way we work with this option in the config file.
Due to a bug in MC production, some MC samples have pileup distributions that are different to that in mc2017_pileup_Dec2018reReco.root. A new functionality has been added to the Analyzer to deal with this issue. The Special MC PU calculation was implemented to derive specific pileup weights for each 2017 NanoAODv6 MC sample. If you want to use this functionality, you need. to set the first option to true and the second will read the name of the root file (located in the Pileup directory) that containes the nTruePU distributions for each MC sample.
SpecialMCPUCalculation true
SpecialMCPUHistos new_mc2017_pileupReweighting_NanoAODv6.root
The available files follow the name convention new_mc2017_pileupReweighting_NanoAODv6XX.root:
| File name | MC samples included (only 2017) |
|---|---|
new_mc2017_pileupReweighting_NanoAODv6.root |
Most MC samples used in our analyses excluding DY+Jets and W+Jets inclusive samples. |
new_mc2017_pileupReweighting_NanoAODv6_wanddylo_incl.root |
DY+Jets and W+Jets inclusive samples at LO (MadgraphMLM). |
new_mc2017_pileupReweighting_NanoAODv6_dynlo_incl.root |
DY+Jets inclusive sample at NLO (aMCatNLO). |
Note: when running over the DY+Jets and W+Jets inclusive samples, since you will be applying the HT filter, make sure to change the pileup file name for the special PU weight calculation accordingly.
Two things to take into account:
-
The list of samples included in the ROOT files for the special PU calculation can be found here. If you are using samples that are not included, then you need to set the
SpecialMCPUCalculationflag tofalseand use the normal PU weight calculation for your specific samples. -
If you want to run using this function interactively, you need to name your output file in a way that the name of the MC sample is included, because the histogram that is read is based on the output file name, for example:
./Analyzer -in root://cmsxrootd.fnal.gov///store/mc/RunIIFall17NanoAODv6/TTToSemiLeptonic_TuneCP5_PSweights_13TeV-powheg-pythia8/NANOAODSIM/PU2017_12Apr2018_Nano25Oct2019_102X_mc2017_realistic_v7-v1/110000/0BD5AC15-90E4-AC47-BFBE-023E726B75CE.root -out TTToSemiLeptonic.root -t
This will be improved in future versions of the analyzer. However, it is not necessary to worry about this when submitting jobs to the LPC cluster, since output files are by default named based on the input sample name.
Tau ID and anti-light lepton discriminator scale factors were recently implemented in the framework, based on the official tool released by the Tau POG (*). To activate/deactivate these, we have these options:
ApplyTauIDSF true # Tau ID scale factors that are pT-dependent (default).
TauIdSFsByDM false # Tau ID scale factors that are decay mode (DM) - dependent.
TauSFforEmbeddedSamples false
ApplyTauAntiEleSF true
ApplyTauAntiMuSF true
More details about the available SFs, please refer to the documentation here. To know more about the current recommendations for Run II analyses check https://twiki.cern.ch/twiki/bin/viewauth/CMS/TauIDRecommendationForRun2
If you want to apply a cut on HT, for example, for the inclusive DY+Jets and W+Jets samples to obtain the low HT bin, the relevant block is:
DiscrByGenHT false
LowerGenHtCut 0.0
UpperGenHtCut 100.0
Also, a new function has been added to exclusively filter DY+Jets MC samples by dilepton mass at gen-level. To turn on/off this functionality, you need the following options:
DiscrByGenDileptonMass false
GenDilepMassRange 80.0 100.0
The function will only apply the filter to DY+Jets samples. In case you have this flag on and you run over non-DY+Jets samples, the filter will not be applied.
In an old implementation of the code, some cuts to the gen-level dilepton mass could be applied at gen-level with the function Analyzer::initializeMCSelection. This has been made optional with the option
InitializeMCSelection false
since a new functionality has been added to perform the same task, we recommend to have this flag always set to false.
The options you need to apply trigger requirements for that are the following:
Trigger1FirstRequirement HLT_IsoMu24
Trigger1SecondRequirement HLT_IsoMu24
UseTriggerWildcard true
You can use Trigger1SecondRequirement to set a different trigger name in the case you are performing trigger efficiency studies. Otherwise, keep both requirements set to the same name.
Also, if you want to get select all events that fire a trigger that starts with HLT_IsoMu2 (HLT_IsoMu21, HLT_IsoMu22, HLT_IsoMu24, etc), you need to set the new flag ``UseTriggerWildcard``` to true. Otherwise, the code will only loop over the triggers that match exactly the names provided. The full list of triggers loaded for the trigger requirements will be printed each time you run the analyzer before looping over all events.
Example 1:
- Config file:
Trigger1FirstRequirement HLT_IsoMu24
Trigger1SecondRequirement HLT_IsoMu27
UseTriggerWildcard false <------ wildcard off!
- Triggers to be probed (printout):
Full list of triggers to be probed:
HLT_IsoMu24
HLT_IsoMu27
Example 2:
- Config file:
Trigger1FirstRequirement HLT_IsoMu24
Trigger1SecondRequirement HLT_IsoMu27
UseTriggerWildcard true <------ wildcard on!
- Triggers to be probed (printout):
Full list of triggers to be probed:
HLT_IsoMu24
HLT_IsoMu24_eta2p1
HLT_IsoMu24_eta2p1_MediumChargedIsoPFTau35_Trk1_TightID_eta2p1_Reg_CrossL1
HLT_IsoMu24_eta2p1_MediumChargedIsoPFTau35_Trk1_eta2p1_Reg_CrossL1
HLT_IsoMu24_eta2p1_MediumChargedIsoPFTau50_Trk30_eta2p1_1pr
HLT_IsoMu24_eta2p1_MediumChargedIsoPFTauHPS35_Trk1_eta2p1_Reg_CrossL1
HLT_IsoMu24_eta2p1_TightChargedIsoPFTau35_Trk1_TightID_eta2p1_Reg_CrossL1
HLT_IsoMu24_eta2p1_TightChargedIsoPFTau35_Trk1_eta2p1_Reg_CrossL1
HLT_IsoMu27
HLT_IsoMu27_LooseChargedIsoPFTau20_Trk1_eta2p1_SingleL1
HLT_IsoMu27_MET90
HLT_IsoMu27_MediumChargedIsoPFTau20_Trk1_eta2p1_SingleL1
HLT_IsoMu27_TightChargedIsoPFTau20_Trk1_eta2p1_SingleL1
Now you can apply MET filters turning on the following option
ApplyMetFilters true
In 2018, data-taking was affected by the HEM 15/16 failure (*). Therefore, a new function was added to veto events that contain jets in the HEM regions affected both in data and MC.
To (de)activate it, you need to turn the following flag to (false) true:
ApplyHEMVeto2018 true
Given that now selections can be applied to photons, there are two additional flags in Cuts.in which take care of applying photon multiplicity cuts:
NRecoPhoton1 0 -1
NRecoPhoton2 0 -1
This file gives all of the multiplicity cuts that are made in the code. The order of the cuts can be changed. The first variable is the name that corresponds to the CUTS enum value that holds the number of "good" particles that correspond to the name. These are defined in the map called "cut_num" in src/Analyzer.cc. The next two numbers are the minimum and maximum number of particles allowed. -1 corresponds to infinity, i.e.,
NParticleA 2 -1
means the particle "ParticleA" must have at least 2 particles. The cuts are applied cumulatively, so after a cut, only events that passed that cut will be considered in the next cut. If you want to see the histograms after a specific multiplicity cut, you can make that cut into a folder by putting *** before the cut name. The folder will hold histograms that were filled AFTER the cut is applied, i.e.
***NParticleB 0 0
means a folder with histograms filled after the cut of have exactly 0 of "ParticleB". In order to apply a cut on the MET, the option METCut should be set up as follows:
METCut 1 -1
The details related to this cut are stored in Run_info.in.
Kinematic and mother particle ID requirements can now be applied to gen-level electrons and muons separately:
DiscrElecByPtAndEta false
ElecPtCut -10.0 100000.0
ElecEtaCut 10.0
DiscrElecByMotherID 0
ElecMotherIDs 15. 15.
DiscrMuonByPtAndEta false
MuonPtCut -10.0 100000.0
MuonEtaCut 10.0
DiscrMuonByMotherID 0
MuonMotherIDs 15. 15.
In the case of the MotherIDs requirement, it can be done as a pair-valued cut (explained below) or as a list of values for different IDs, for example:
MuonMotherIDs 5 15 23 24
This can be done for electrons, muons, taus (before decays) and hadronic taus at gen-level. For cases in which the mother particle ID is the same as the one for the lepton, a loop was implemented to look for the first mother particle ID with ID different to that of the gen-particle studied. This accounts for possible momentum corrections that some leptons receive in the hadronization process.
In addition, a new flag that is independent from the mother PID requirement, has been implement to remove leptons coming from pileup particles. The way it is defined is as follows: the index of the mother particles is traced back until it is == -1. Only the initial state particles will have this mother particle index in the GenPart collection. The initial quarks/gluons that initiated the hard-scatter process usually are listed with indices 0 and 1. Therefore if the mother particle index is -1 and the particle index is different from 0 or 1, it most likely will come from a pileup particle (not from the hard scatter process (see below an example taken from a VBF SUSY signal sample):
index = 0, pdg_id: 1 p_T: 0 phi: 0 status: 21 mother particle index = -1
index = 1, pdg_id: 2 p_T: 0 phi: 0 status: 21 mother particle index = -1
index = 2, pdg_id: 1000015 p_T: 253.5 phi: -1.34375 status: 22 mother particle index = 0
index = 3, pdg_id: 1000015 p_T: 311 phi: 1.9375 status: 22 mother particle index = 0
index = 4, pdg_id: 2 p_T: 52.875 phi: 0.233887 status: 23 mother particle index = 0
index = 5, pdg_id: 1 p_T: 55.625 phi: -1.50781 status: 23 mother particle index = 0
index = 6, pdg_id: 1000015 p_T: 263 phi: -1.33594 status: 44 mother particle index = 2
index = 7, pdg_id: 1000015 p_T: 308 phi: 1.9375 status: 44 mother particle index = 3
index = 8, pdg_id: 1000015 p_T: 264 phi: -1.33984 status: 44 mother particle index = 6
index = 9, pdg_id: 1000015 p_T: 307 phi: 1.94141 status: 44 mother particle index = 7
index = 10, pdg_id: 1000015 p_T: 264 phi: -1.33984 status: 44 mother particle index = 8
index = 11, pdg_id: 1000015 p_T: 307 phi: 1.94141 status: 44 mother particle index = 9
index = 12, pdg_id: 1000015 p_T: 263 phi: -1.33984 status: 62 mother particle index = 10
index = 13, pdg_id: 1000015 p_T: 307 phi: 1.94141 status: 62 mother particle index = 11
index = 14, pdg_id: 1000022 p_T: 232.5 phi: -1.40234 status: 1 mother particle index = 12
index = 15, pdg_id: 15 p_T: 34.5 phi: -0.90625 status: 2 mother particle index = 12
index = 16, pdg_id: 1000022 p_T: 290 phi: 1.98047 status: 1 mother particle index = 13
index = 17, pdg_id: 15 p_T: 21.0625 phi: 1.35547 status: 2 mother particle index = 13
index = 18, pdg_id: 421 p_T: 0.336914 phi: 0.25293 status: 2 mother particle index = -1
index = 19, pdg_id: 423 p_T: 0.475586 phi: -2.23438 status: 2 mother particle index = -1
index = 20, pdg_id: 2 p_T: 21.1875 phi: 0.478516 status: 71 mother particle index = 4
index = 21, pdg_id: 421 p_T: 3.01562 phi: -0.106445 status: 2 mother particle index = -1
index = 22, pdg_id: 411 p_T: 4.5625 phi: -1.17969 status: 2 mother particle index = -1
index = 23, pdg_id: 1 p_T: 38.625 phi: -1.42188 status: 71 mother particle index = 5
index = 24, pdg_id: 21 p_T: 39.25 phi: -1.42578 status: 71 mother particle index = 5
index = 25, pdg_id: 423 p_T: 7.23438 phi: -1.14453 status: 2 mother particle index = 5
index = 26, pdg_id: 2 p_T: 20 phi: -0.231934 status: 71 mother particle index = 4
index = 27, pdg_id: 21 p_T: 22.625 phi: 2.07812 status: 71 mother particle index = -1
index = 28, pdg_id: 421 p_T: 1.70312 phi: 1.01953 status: 2 mother particle index = 5
index = 29, pdg_id: 421 p_T: 1.28125 phi: 1.56641 status: 2 mother particle index = -1
index = 30, pdg_id: 4132 p_T: 0.871094 phi: -2.35938 status: 2 mother particle index = -1
index = 31, pdg_id: 16 p_T: 16.6875 phi: -0.892578 status: 1 mother particle index = 15
index = 32, pdg_id: 13 p_T: 7.21875 phi: -0.984375 status: 1 mother particle index = 15
index = 33, pdg_id: 14 p_T: 10.6875 phi: -0.873047 status: 1 mother particle index = 15
index = 34, pdg_id: 16 p_T: 10.25 phi: 1.30859 status: 1 mother particle index = 17
index = 35, pdg_id: 111 p_T: 5.73437 phi: 1.42578 status: 2 mother particle index = 17
index = 36, pdg_id: 211 p_T: 5.10938 phi: 1.375 status: 1 mother particle index = 17
index = 37, pdg_id: 421 p_T: 0.482422 phi: -2.20312 status: 2 mother particle index = 19
index = 38, pdg_id: 13 p_T: 0.317383 phi: -1.98438 status: 1 mother particle index = 21
index = 39, pdg_id: 14 p_T: 0.28125 phi: 0.505859 status: 1 mother particle index = 21
index = 40, pdg_id: 421 p_T: 6.5625 phi: -1.14844 status: 2 mother particle index = 25
index = 41, pdg_id: 22 p_T: 3.66406 phi: 1.41797 status: 1 mother particle index = 35
index = 42, pdg_id: 22 p_T: 2.07031 phi: 1.4375 status: 1 mother particle index = 35
An example of a lepton NOT coming from pileup, in this case a muon with id = 13, is for particle with index = 32, which is a final state muon (status = 1). This muon has mother particle index = 15, which is a tau lepton. The mother particle indices starting with the tau (tracing back are): 12 (pdg_id = 1000015), 10 (pdg_id = 1000015), 8 (pdg_id = 1000015), 6 (pdg_id = 1000015), 2 (pdg_id = 1000015), 0 (pdg_id = 1) and -1. So, the first particle in this chain was the initial up quark with index = 0. Therefore, this is a muon from the hard scatter process.
Now, let's take the muon with index = 38. This is also a final state muon, with mother particle index = 21, which is a D0 meson (pdg_id = 421; for reference, see MC particle numbering scheme from the PDG here). The mother particle index for the D0 meson is -1, therefore is not a meson coming from the hard-scatter and the final state muon coming from its decay can be classified as a muon from pileup.
The flags that check this characteristic for each lepton are:
DiscrElecByNotFromPileup true
DiscrMuonByNotFromPileup true
DiscrTauByNotFromPileup true
and can be added as appropriate for your studies.
New options have been added to apply gen-level cuts to hadronic tau candidates (GenVisTau collection, described here):
DiscrHadTauByPtAndEta true
HadTauPtCut 18.0 9999.9
HadTauEtaCut 2.4
DiscrByTauDecayMode false
TauDecayModes 0 15
For the decay modes, all numbers between 0 and 15 are considered (this is a pair-valued cut). See GenVisTau_status to know the corresponding number codes to select taus according to decay modes at gen-level. If you want a specific code, just set both values of the pair to the same code (for example, TauDecayModes 1 1).
The latest changes to the Particle configuration files are described below:
Two new flags have been added to apply either of these ID requirements to muons: DoDiscrByLooseID and DoDiscrByMediumID.
DoDiscrBySoftID 0
DoDiscrByLooseID 0 # (0 or 1)
DoDiscrByMediumID 0 # (0 or 1)
DoDiscrByTightID 1
Before this update, the Photon_info.in config file used to be empty. Now, it is possible to apply selections on photons and they have been updated in this file. The structure is similar to Electron_info.in, including some selections which are relevant to photons.
In order to improve the data to MC agreement, jet energy resolution scale factors can be applied to MC for the nominal 4-momenta of jets (not only when studying systematics). The recommendation for analysis is that we include these effects and propagate them to MET. This is done with the newly integrated Analyzer::applyJetEnergyCorrections function. Make sure that in your Jet_info.in file, you would have to set the option SmearTheJet to true, under the Smear block (at the moment, this is only done for AK4 jets):
The recommended value for dR between the reconstructed jet and gen-level jet is R_{cone AK4-jet} / 2 = 0.4 / 2 = 0.2. Therefore, the parameter GenMatchingDeltaR should be set to 0.2.
In the latest version of the Analyzer (March 15, 2021), some flags were removed, leaving the Smear block as follows:
########################################
Smear
#######################################
SmearTheJet 1
GenMatchingDeltaR 0.2
ResolutionMatching 1
MuonMatchingDeltaR 0.4
ModifiedPUsmearing 0
ModifiedForwardSmearing 0
CombinedModifiedSmearing 0
Here is a description of the last three flags:
-
ResolutionMatching: this option adds an additional condition based on the absolute difference between the pTs of the reconstructed level jet and that that is matched at generator level. This is the official method to do gen-level matching for jet energy smearing at CMS. -
MuonMatchingDeltaR: in order to know if the energy of a jet will be smeared or not, one needs to check if the jet overlaps with a genuine muon. The parameter given to this flag will establish the minimum separation in R between the jet and any close muons. We're setting it to be R_(cone, AK4 jet). -
ModifiedPUsmearing: The VBF SUSY team proposed a slightly modified approach to smear the jet energies, by considering an extra requirement on jets to be smeared. Specifically, each jet that is not matched to a gen-level jet, must pass the tight pileup jet ID in order to be smeared; otherwise this jet's energy won't be smeared. More details about the implementation and results can be found in the presentation here. If you would like to stick to the official recipe to smear jet energies, please set this option to 0. Otherwise, you can test this by setting the option to 1.
In the update from June 3, 2021, two more flags were implemented for different recipes to derive the JER corrections (see full presentation here):
-
ModifiedForwardSmearing: This a second modification (independent of the previous one) that the VBF SUSY team proposed to smear the jet energies. Jets with pT < 50 GeV and |eta| > 2.5 are not smeared. -
CombinedModifiedSmearing: This a third proposal from the VBF SUSY team, in whichModifiedPUsmearingandModifiedForwardSmearingare combined as described here (slide 9).
If all three flags (ModifiedPUsmearing, ModifiedForwardSmearing and CombinedModifiedSmearing) are set to 0, then the official recipe is applied. Otherwise, only one of the three flags can be set to 1 in order to apply a specific modified recipe.
Between 2016 and 2017-2018 the jet ID requirements changed. In 2016, the recommendation is to use Loose jet ID whereas for 2017 and 2018 the Tight jet ID is recommended. Recently we also implemented the TightLepVeto ID, available for all years. The available options under any of the blocks in Jet_info.in are:
ApplyLooseID 1
ApplyTightID 0
ApplyTightLepVetoID 0
Only one of these can be set to 1 (true).
In addition, we have recently incorporated the option to apply pileup jet ID to jets with pT ≤ 50 GeV. The appropriate flags are described below:
ApplyPileupJetID 1
PUJetIDCut 0
FailPUJetID 0
Pileup jet ID can be used in combination with the usual PF jet ID described above. The code will automatically check for the jet pT to discriminate which jets will have PF ID applied and which ones not. There are three different working points of PU jet ID: tight (PUJetIDCut 0), medium (PUJetIDCut 1) and loose (PUJetIDCut 2). Jets passing tight PU jet ID are more likely to NOT be pileup jets. The looser the cut on ID (medium and loose), the more likely the jet is going to be a PU jet. If a jet fails PU jet ID (FailPUJetID 1), then this jet is much more like a pileup jet.
Most part of the changes are related to b-jets. Since new algorithms besides CSVv2 are now available, the user can choose in this configuration file the desired one for their studies. The relevant options are:
ApplyJetBTaggingCSVv2 0
ApplyJetBTaggingDeepCSV 1
ApplyJetBTaggingDeepFlav 0
These substitute the old ApplyJetBTagging option. Also, two new options are added:
JetBTaggingWP medium
JetBTaggingCut 0.6321
MatchBToGen 0
UseBtagSF 1
RemoveBJetsFromJets 0
JetBTaggingWP accepts the name of the working point you are using to correctly set up the b-tagging scale factor readers in the analyzer by retrieving the right file according to the working point in this option and algorithm selected. JetBTaggingWP is independent of JetBTaggingCut, which you still have to setup manually according to the working point definitions given by the BTag POG. Information about the different cuts, working points and algorithms available for Run II can be found here.
Also a new option to remove overlap between AK8 jets with b-jets were added:
RemoveOverlapWithJs 1
JMatchingDeltaR 0.8
A new option that drops jets in the problematic region in 2017 has been added under each block of the Jet_info.in file. When analyzing 2017 data, make sure to set this flag to True for both data and MC:
Apply2017EEnoiseVeto true
IMPORTANT NOTE (June 3, 2021): this veto removes noisy jets from the jet vector in each event. It is different to the EE noise event veto implemented in the updated code from June 3, 2021 and both of them must be applied at the same time in data (the event veto in Run_info.in does not apply to MC).
In the Electron_info.in and Muon_info.in, the isolation requirement is applied using the option
DoDiscrByIsolation 1
IsoSumPtCutValue 0.0 0.15
where IsoSumPtCutValue is a pair-valued cut, with the first element being the minimum isolation cone radius and the second element the maximum isolation cone radius.
In Tau_info.in this cut is applied in a slightly different way:
DoDiscrByIsolation true
DiscrByMinIsolation 16
DiscrByMaxIsolation 2
FlipIsolationRequirement false
For taus, we use the tau ID isolation working points (discriminator against jets), where tighter isolation equals a reduced isolation cone radius and looser isolation means a wider cone:
In the example above, 16 = Medium and 2 = VVLoose. When you perform studies that require this cut, make sure that you use the minimum and maximum isolation in the right order, to avoid confusions. This explanation applies to versions of the Analyzer released after April 2020.
IMPORTANT NOTE: Before May 2020, the minimum isolation represented the looser isolation working point and the maximum isolation corresponded to the tighter isolation working point:
If you have performed or are performing any studies with versions of the Analyzer prior to this date, this is the convention you were/should be using (min. iso. = looser WPs, max. iso. = tighter WPs). Version of the Analyzer after May 2020, use the convention explained in the diagram above. Please, make sure you are using the correct one. Read the reminder of the information taking that into consideration.
Also, there is an additional option that allows to flip the isolation requirement (FlipIsolationRequirement).
Let's say you only need to apply a single isolation cut (for example, for tau ID efficiency studies). Then the only cut you should modify is DiscrByMinIsolation, since DiscrByMaxIsolation will be ignored as long as the FlipIsolation is set to false.
Now, if you want to do data-driven background estimations (for example, QCD), where you want to calculate tight-to-loose ratio. This requires to flip the tau isolation requirement. Then you need to:
- Set the
FlipIsolationflag totrue. - Keep the nominal tau isolation cut in
DiscrByMinIsolation, like in the case you only care about a single isolation cut. Usually here you will put the tighter requirement. In this example, we want min. iso. to beTight. - Change the
DiscrByMaxIsolationrequirement to the WP that you want to "flip" to. In our example, we want max. iso. to beLoose.
When the FlipIsolation flag is true, all tau candidates that fail the min. iso. requirement and pass the max. iso. requirement will be kept, which is exactly what we need.
Just to make sure, some examples:
Example 1: Require taus that pass tight ID isolation. In DeepTau, tight = 32 (for more information, see here).
DoDiscrByIsolation true # The tau ID requirement will be applied.
DiscrByMinIsolation 32 # The working point selected is 32, in DeepTau this means Tight.
FlipIsolationRequirement false # Since the flag is set to false, taus that *pass* the MinIsolation requirement will be kept.
DiscrByMaxIsolation 2 # This option is ignored because FlipIsolationRequirement is set to false.
Example 2: Require taus that fail tight ID isolation and pass loose ID. In DeepTau, loose = 8 (for more information, see here).
DoDiscrByIsolation true # The tau ID requirement will be applied.
DiscrByMinIsolation 32 # The working point selected is tight. This is the working point we want our taus to *fail*.
FlipIsolationRequirement true # Since the flag is set to true, taus that *fail* the MinIsolation AND *pass* the MaxIsolation will be kept.
DiscrByMaxIsolation 8 # In this option, we set the working point that taus will need to *pass*. In our case, this corresponds to the loose WP.
The current recommended identification algorithm is DeepTauIDv2p1. Up to April 2020, only the MVA-based ID was implemented in the framework. For versions on or after May 2020, the DeepTauID is available. For this, a new block was created in the Tau_info.in file:
//////////////////////////////
TauID
////////////////////////////
TauIDAlgorithm Tau_idDeepTau2017v2p1
The available options are: Tau_idDeepTau2017v2p1 to use DeepTau or Tau_idMVAoldDM2017v2 to use the latest MVA-based ID. If you don't have this block in your config file, the MVA-based ID will be set up by default.
You can apply tau energy scale corrections to hadronic taus with the following option:
SmearTheParticle 1
The current recommendation from the Tau POG is to include these corrections for analysis. Have a look at the Tau POG recommendations here. It is also possible to apply a e->tau fake energy scale correction to the tau 4-momentum (only available for DeepTau). This can be done by setting the following flag to 1:
ApplyETauFakeRateESSF 1
A new flag has been implemented to check the MC truth for a reconstructed tau based on the available information in NanoAOD samples. The branch Tau_genPartFlav provides the information of the "flavor" of genParticle for MC matching to status==2 (before decays): 1 = prompt electron, 2 = prompt muon, 3 = tau->e decay, 4 = tau->mu decay, 5 = hadronic decay, 0 = unknown or unmatched. The flag below is intended to select reconstructed hadronic taus with "status" within certain range (pair-like range):
DiscrByGenMatchingStatus true
GenMatchingStatusRange 3 5
In the example above, the taus selected can have a genParticle flavor equal to 3, 4 or 5 and represent genuine tau decays to leptons and hadrons. This could be useful for cases where the fake-rate from electrons and muons is studied (by selecting reconstructed hadronic taus with GenMatchingStatusRange 3 4) or to only get genuine hadronic taus (GenMatchingStatusRange 5 5).