Jet Energy Corrections: Official Software Tools for applying JEC Corrections and Uncertainties.

Contents

Introduction

The basic idea behind the JEC corrections at CMS is described in https://twiki.cern.ch/twiki/bin/view/CMS/IntroToJEC. You can find more information related to Jet Energy Corrections here.

The latest recommended corrections and global tags for data and MC simulation can be found at the link https://twiki.cern.ch/twiki/bin/view/CMS/JECDataMC

Instructions

How to connect to a global tag

process.load('Configuration.StandardSequences.Services_cff')
process.load('Configuration.StandardSequences.FrontierConditions_GlobalTag_cff')
process.GlobalTag.globaltag = 'GR_R_52_V9::All'

How to connect to a local SQLite file

The recommended way of accessing JEC is via a global tag, as described above. However, it is also possible to read them from an SQLite file, which is mainly exercised during the initial testing phase in preparation of a global tag.

In order to read conditions from an SQLite file, one should use module PoolDBESSource as follows:

from CondCore.DBCommon.CondDBSetup_cfi import CondDBSetup
process.jec = cms.ESSource('PoolDBESSource',
    CondDBSetup,
    connect = cms.string('sqlite:Fall15_V2_DATA.db'),
    toGet = cms.VPSet(
        cms.PSet(
            record = cms.string('JetCorrectionsRecord'),
            tag    = cms.string('JetCorrectorParametersCollection_Fall15_V2_DATA_AK4PFchs'),
            label  = cms.untracked.string('AK4PFchs')
        ),
        cms.PSet(
            record = cms.string('JetCorrectionsRecord'),
            tag    = cms.string('JetCorrectorParametersCollection_Fall15_V2_DATA_AK8PFPuppi'),
            label  = cms.untracked.string('AK8PFPuppi')
        ),
        # ...and so on for all jet types you need
    )
)

# Add an ESPrefer to override JEC that might be available from the global tag
process.es_prefer_jec = cms.ESPrefer('PoolDBESSource', 'jec')

You will need to adapt the above snippet to your specific case, providing the path to the SQLite file and listing all required jet types with appropriate tags. In order to resolve the location of the file with the FileInPath functionality, use prefix sqlite_fip:. The tags are specific to a particular SQLite file. Their list can be printed with the command conddb --db <dbfile.db> listTags. Although it is technically possible to provide an arbitrary string for the label attribute, it is recommended to stick to the jet type labels used in global tags:

  • AK4PF
  • AK4PFchs
  • AK4PFPuppi
  • AK8PF
  • AK8PFchs
  • AK8PFPuppi

How to get the JEC txt files from the database

For those who need to produce the corresponding JEC txt files (for standalone use for example), one can download these from the wiki JECDataMC. This is a preferred method. One can also reproduce the original txt files using the JetCorrectorDBReader module. Below is a complete cfg file. However, this method is error-prone: for GTs which are interleaved by IOVs, it produces text files corresponding to the first IOV encountered, which may not be what the user needs.

  import FWCore.ParameterSet.Config as cms
  process = cms.Process("jectxt")
  process.load('Configuration.StandardSequences.Services_cff')
  process.load('Configuration.StandardSequences.FrontierConditions_GlobalTag_condDBv2_cff')
  # define your favorite global tag
  process.GlobalTag.globaltag = cms.string('74X_mcRun2_asymptotic_v4')
  process.maxEvents = cms.untracked.PSet(input = cms.untracked.int32(1))
  process.source = cms.Source("EmptySource")
  process.readAK4PFchs    = cms.EDAnalyzer('JetCorrectorDBReader',  
        # below is the communication to the database 
        payloadName    = cms.untracked.string('AK4PFchs'),
        # this is used ONLY for the name of the printed txt files. You can use any name that you like, 
        # but it is recommended to use the GT name that you retrieved the files from.
        globalTag      = cms.untracked.string('74X_mcRun2_asymptotic_v4'),  
        printScreen    = cms.untracked.bool(False),
        createTextFile = cms.untracked.bool(True)
  )
  process.readAK8PFchs = process.readAK4PFchs.clone(payloadName = 'AK8PFchs')
  process.readAK4PF = process.readAK4PFchs.clone(payloadName = 'AK4PF')
  process.p = cms.Path(process.readAK4PFchs * process.readAK8PFchs * process.readAK4PF)

If the config file above is run, a number of txt files will be created in your local area. These can be used as inputs to your standalone code. The names of the txt files will have the format 74X_mcRun2_asymptotic_v4_XXXX_YYYY.txt, where XXXX is the correction level (e.g. L2Relative), and where YYYY is the payload name (jet algo).

Note: JEC uncertainty sources are not accessible from data base, but are provided as txt files at https://twiki.cern.ch/twiki/bin/view/CMS/JECUncertaintySources.

Applying the Jet Energy Corrections

UPDATED: Since CMSSW 7.6.X, the consumes interface is now mandatory. The jet corrector framework was not modular enough to enforce this, so a new one was developed. The old interface is deprecated (using JetCorrector::getJetCorrector and friends) and won't work anymore on CMSSW 7.6.X and above.

Sections below have been updated to reflect these changes, but you can find a more in-depth migration tutorial on this twiki page: https://twiki.cern.ch/twiki/bin/view/CMSPublic/FWMultithreadedConsumesJetCorrectorMigration

Jet Energy Corrections in FWLite

Simple jet corrections, which are dependent from jet properties only, may be directly accessed from ROOT scripts running in FWLite environment. The class that delivers the jet correction is called FactorizedJetCorrector and is located in the CondFormats/JetMETObjects package.

Step by step instructions for use in a ROOT macro.

  • Step1 (Load the FWLite libraries)
   gSystem->Load("libFWCoreFWLite.so");
   AutoLibraryLoader::enable(); 

  • Step2 (Construct a vector with the JetCorrectorParameters objects.)
   // Create the JetCorrectorParameter objects, the order does not matter.
   // YYYY is the first part of the txt files: usually the global tag from which they are retrieved
   JetCorrectorParameters *ResJetPar = new JetCorrectorParameters("YYYY_L2L3Residual_AK5PF.txt"); 
   JetCorrectorParameters *L3JetPar  = new JetCorrectorParameters("YYYY_L3Absolute_AK5PF.txt");
   JetCorrectorParameters *L2JetPar  = new JetCorrectorParameters("YYYY_L2Relative_AK5PF.txt");
   JetCorrectorParameters *L1JetPar  = new JetCorrectorParameters("YYYY_L1FastJet_AK5PF.txt");
   //  Load the JetCorrectorParameter objects into a vector, IMPORTANT: THE ORDER MATTERS HERE !!!! 
   vector<JetCorrectorParameters> vPar;
   vPar.push_back(*L1JetPar);
   vPar.push_back(*L2JetPar);
   vPar.push_back(*L3JetPar);
   vPar.push_back(*ResJetPar);
  • Step3 (Construct a FactorizedJetCorrector object)
   FactorizedJetCorrector *JetCorrector = new FactorizedJetCorrector(vPar)
  • Step4 (Set the necessary values, for every jet, inside the jet loop)
   JetCorrector->setJetEta(eta);
   JetCorrector->setJetPt(pt);
   JetCorrector->setJetA(area);
   JetCorrector->setRho(rho); 
  • Step5 (Get the correction factor or a vector of the individual correction factors)
   double correction = JetCorrector->getCorrection();
OR
   vector<double> factors = JetCorrector->getSubCorrections();

IMPORTANT: the getSubCorrections member function returns the vector of the subcorrections UP to the given level. For example in the example above, factors[0] is the L1 correction and factors[3] is the L1+L2+L3+Residual correction.

Instructions for use in CRAB.

  • Step1 (Add the relative file path to the EDAnalyzer's configuration parameters in python)
   // YYYY is the first part of the txt files: usually the global tag from which they are retrieved
   L1File = cms.string("path/to/YYYY_L1FastJet_AK4PFchs.txt")
  • Step2 (Construct a vector with the JetCorrectorParameters objects.)
   // Create the JetCorrectorParameter objects, the order does not matter.
   JetCorrectorParameters *L1Parms;
   std::string l1file;
   l1file = edm::FileInPath(iConfig.getParameter<std::string> ("L1File")).fullPath();
   L1Parms = new JetCorrectorParameters(l1file);

   //  Load the JetCorrectorParameter objects into a vector, IMPORTANT: THE ORDER MATTERS HERE !!!! 
   vector<JetCorrectorParameters> vPar;
   vPar.push_back(*L1Parms);
  • Step3 (Continue using the ROOT macro procedure)

Jet Correction Service

The foundamental unit for the application of jet corrections in CMSSW is the Jet Correction Service. There is one service per level of correction plus a chain service that allows to apply several corrections sequentially. The typical structure of a service is the following (example with L2 Relative correction):

ak5CaloL2Relative = cms.ESSource(
    'LXXXCorrectionService',
    era = cms.string('Jec11V12'),
    section   = cms.string(''),
    level     = cms.string('L2Relative'),
    # the above 3 elements are needed only when the service is initialized from local txt files
    algorithm = cms.string('AK5PF'),
    # the 'algorithm' tag is also the name of the DB payload
    useCondDB = cms.untracked.bool(True)
    )
)

Modular application: corrected jet collection (UPDATED for CMSSW 7.6.X)

Once a jet correction service has been defined, as described above, the correction can be applied to create a corrected jet collection. More specifically, in every event all the jets are corrected and put into the event as a new collection. The corrected jet collection is sorted in decreasing pt. With this method, analysis must be done using the corrected jet collection. A typical module that produces the correction is the following:

process.load('JetMETCorrections.Configuration.JetCorrectors_cff')

process.ak4PFchsCorrectedJets   = cms.EDProducer('CorrectedPFJetProducer',
    src         = cms.InputTag('ak4PFchsJets'),
    correctors  = cms.VInputTag('ak4PFCHSL1FastL2L3Corrector')
    )

If you are not using unscheduled mode, you'll need to add process.ak4PFchsCorrectedJets to your path, as well the chain of correctors before your analyzer / producer. Relevant chain of correctors are process.ak4PFCHSL1FastL2L3CorrectorChain or process.ak4PFCHSL1FastL2L3ResidualCorrectorChain.

The corrected collection producer is templated to account for CaloJets, PFJets, JPTJets and TrackJets. The instances are named CorrectedCaloJetProducer, CorrectedPFJetProducer, CorrectedJPTJetProducer, CorrectedTrackJetProducer. In the above definition, the src is the name of the jet collection where the correction will be applied and the correctors is the name of the predefined corrections. You can find a list of all these corrections here.

Correcting jets "on-the-fly" (UPDATED for CMSSW 7.6.X)

You can also apply the correction jet by jet directly in your analysis code. Two parts are needed for this to work.

  • First, you need to load the necessary jet corrector you want to use. These are now independent modules which must be ran before your analyzers. This line is generally enough if you run in unscheduled mode.

process.load('JetMETCorrections.Configuration.JetCorrectors_cff')

You can find the complete list of all the predefined modules here. If you are not running in unscheduled mode, then you also need to add the sequence of correctors to your path. The complete list is available on the previous link, but relevant sequences would probably be process.ak4PFCHSL1FastL2L3CorrectorChain and process.ak4PFCHSL1FastL2L3ResidualCorrectorChain.

  • In your analyzer, you need to retrieve the jet corrector module. You first have to get a token to the module through the consume interface, and them retrieve the content of the token in the event loop.
    • The needed include file is:
#include "JetMETCorrections/JetCorrector/interface/JetCorrector.h"
    • The token you need:
edm::EDGetTokenT<reco::JetCorrector> mJetCorrector;
    • Retrieve the token (usually in your analyzer constructor). You'll need to replace CORRECTOR_LABEL by the name of the jet corrector you want to use (something like ak4PFCHSL1FastL2L3Corrector or ak4PFCHSL1FastL2L3ResidualCorrector):
mJetCorrector  = consumes<reco::JetCorrector>(edm::InputTag("CORRECTOR_LABEL"));
    • Inside your analyze or produce methode, retrieve the jet corrector
edm::Handle<reco::JetCorrector> corrector;
iEvent.getByToken(mJetCorrector, corrector);
    • Use it:
for (const auto& jet: jets) {
    double jec = corrector->correction(jet);
}

IMPORTANT: after applying corrections "on the fly", the resulting jets are NOT sorted by pt.

Re-correcting pat::Jets and jets from MiniAOD (UPDATED for CMSSW 7.6.4)

This recipe can be used to apply a new set of jet energy corrections, to the already corrected pat::Jets or to slimmedJets from MiniAOD, starting from CMSSW_7_4_0. The pat::Jets or slimmedJets already contain a set a jet energy correction. The following code reverts these corrections and applies the new ones, producing as output an new collection of pat::Jets which have the same content as the input jet, but new jet energy corrections applied. These modules can for example be placed in the configuration sequence before your ntuplizer.

There's two different recipes based on your CMSSW version. In both case, you first need to load a global tag or sqlite file file containing the jet energy correction if you want to see any difference. Instruction and recommendations for this are given on this TWiki page: WorkBookJetEnergyCorrections#JecGlobalTag, WorkBookJetEnergyCorrections#JecSqliteFile.

Before CMSSW 7.6.4

You need to add the following python code into your configuration. The new jets collection, with the updated JEC, is patJetsReapplyJEC

from PhysicsTools.PatAlgos.producersLayer1.jetUpdater_cff import patJetCorrFactorsUpdated
process.patJetCorrFactorsReapplyJEC = process.patJetCorrFactorsUpdated.clone(
  src = cms.InputTag("slimmedJets"),
  levels = ['L1FastJet', 
        'L2Relative', 
        'L3Absolute'],
  payload = 'AK4PFchs' ) # Make sure to choose the appropriate levels and payload here!

from PhysicsTools.PatAlgos.producersLayer1.jetUpdater_cff import patJetsUpdated
process.patJetsReapplyJEC = process.patJetsUpdated.clone(
  jetSource = cms.InputTag("slimmedJets"),
  jetCorrFactorsSource = cms.VInputTag(cms.InputTag("patJetCorrFactorsReapplyJEC"))
  )

process.p += cms.Sequence( process.patJetCorrFactorsReapplyJEC + process.patJetsReapplyJEC )

CMSSW 7.6.4 and above

Starting from CMSSW_7_6_4, the updateJetCollection function was added to PhysicsTools/PatAlgos/python/tools/jetTools.py which allows easy re-correction of pat::Jets as well as adding extra information to them. An example of its use can be found in PhysicsTools/PatAlgos/test/patTuple_updateJets_fromMiniAOD_cfg.py. The function is by default configured for pat::Jets stored in MiniAOD but can be used for any collection of pat::Jets with appropriately set input arguments.

If you just want to update the JEC in the MiniAOD, using the following python code is enough:

from PhysicsTools.PatAlgos.tools.jetTools import updateJetCollection

updateJetCollection(
   process,
   jetSource = cms.InputTag('slimmedJets'),
   labelName = 'UpdatedJEC',
   jetCorrections = ('AK4PFchs', cms.vstring(['L1FastJet', 'L2Relative', 'L3Absolute', 'L2L3Residual']), 'None')  # Update: Safe to always add 'L2L3Residual' as MC contains dummy L2L3Residual corrections (always set to 1)
)

The new jets collection, with the updated JEC, is updatedPatJetsUpdatedJEC, where by default no selection is applied (as in the standard PAT jet workflow). More generally, the final updated jet collection will be called updatedPatJets+labelName+postfix, with labelName and postfix set by default to an empty string.

If you are not using unscheduled mode (you really should using it), you need to add the following modules to your execution path (can be different if you change the labelName):

process.jecSequence = cms.Sequence(process.patJetCorrFactorsUpdatedJEC * process.updatedPatJetsUpdatedJEC)

Accessing the JEC uncertainties

There are two ways to access the JEC uncertainties:

A) from the data base, directly in an EDAnalyzer:

edm::ESHandle<JetCorrectorParametersCollection> JetCorParColl;
iSetup.get<JetCorrectionsRecord>().get("AK5PF",JetCorParColl); 
JetCorrectorParameters const & JetCorPar = (*JetCorParColl)["Uncertainty"];
JetCorrectionUncertainty *jecUnc = new JetCorrectionUncertainty(JetCorPar);

B) from a local txt file

JetCorrectionUncertainty *jecUnc = new JetCorrectionUncertainty("Jec11_V12_Uncertainty_AK5PF.txt")

Note: JEC uncertainty sources (i.e. correlations, for advanced users) for final 2011 JEC are only available as text files at https://twiki.cern.ch/twiki/bin/view/CMS/JECUncertaintySources.

Please use for 2012 data the new uncertainty files that can be found at https://twiki.cern.ch/twiki/bin/view/CMS/JECUncertaintySources#2012_JEC.

In both cases above, the JetCorrectionUncertainty object must be initialized once but used inside the jet loop, by passing each time the jet pt (corrected) and eta:

for (PFJetCollection::const_iterator jet = jets->begin(); jet != jets->end(); jet++)  {
  ...............................
  jecUnc->setJetEta(eta);
  jecUnc->setJetPt(ptCor); // here you must use the CORRECTED jet pt
  double unc = jecUnc->getUncertainty(true);
  double ptCor_shifted = ptCor(1+shift*unc) ; // shift = +1(up), or -1(down)
}

FINAL JEC for the 2010 data/MC (and approximately for the 41x 2011 data)

The final JEC for the 2010 data and MC refers to the 38x reconstruction and was derived using the Fall10 MC truth. The constants and the uncertainties correspond to the content of the JME-10-011 paper. These constants are also approximately suitable for the 41x 2011 data (but not necessarily within the small uncertainties).

For publications, please refer to the JINST paper based on JME-10-011 analysis:
"Determination of Jet Energy Calibration and Transverse Momentum Resolution in CMS", http://arxiv.org/abs/1107.4277, JINST 6 (2011) 11002.

Global tags for 41x have been prepared (many thanks to the AlCa team, as always!). Please use these in your analysis.

Data:
GR_R_41_V0

MC:
START41_V0
DESIGN41X_V0
MC_41_V0

In order to use the 41x JEC, use these global tags in release 4.1.4, and the tags to use are

RecoJets/Configuration                           V02-04-17
RecoJets/JetAlgorithms                           V04-01-00      
RecoJets/JetProducers                            V05-05-03-00     

Final JEC set for 42x 2011 data (and approximately for 44x, 50x)

This is the final JEC set for 42x 2011 data. The calibration was derived on the 4.7/fb mixture of PromptReco and re-reco (May10, Aug5) data. The set includes updated L1Offset/L1FastJet corrections with in-time and out-of-time pile-up, newly derived monolithic L2Relative/L3Absolute corrections from simulation, and L2L3Residuals based on dijet, photon+jet and Zmumu+jet data. The uncertainties are similar or smaller than those for the 2010 final JEC, with the exception of 2.4<|eta|<3 region, where JEC time-dependence and poorly understood pile-up corrections have necessitated increasing uncertainties. Uncertainty correlations are now also provided as separate txt files for AK5PF and AK7PF.

This JEC is also approximately applicable to 44X and 5X data. The main expected difference is that the preshower has been added back in the reconstruction in 44X and 50X, which would make the 42X JEC overcorrect in the 2.4<|eta|<3 region. However, this region is already covered by the large time-dependence and pile-up systematics. Other expected changes in the future are the update of L2 corrections that are now affected by the low response in the end caps in Prompt V4 era, and possible updates to L1Offset corrections following better understanding of biases in this region.

For publications, please refer to the JINST paper for 2010 data that used the same calibration techniques:
"Determination of Jet Energy Calibration and Transverse Momentum Resolution in CMS", http://arxiv.org/abs/1107.4277, JINST 6 (2011) 11002.

For additional details and comparison to 2011 initial JEC, see e.g. the following presentation:
https://indico.cern.ch/getFile.py/access?contribId=1&resId=0&materialId=slides&confId=146434

Caveat: the L5Flavor and L7Parton corrections have not been updated for several years now, and are seriously outdated. Please do NOT use them for the time being. If you need new L5Flavor corrections from MC, please let us know, and we'll see what we can do to fast track the updates.

For analysis, please use the following global tags in 42X:

  • Monte Carlo
    DESIGN42_V17
    START42_V17
    MC_42_V17
    
  • Data
    GR_R_42_V23
    

For 44X, we have the following global tags:

  • Monte Carlo with 44X, where X>=1
    DESIGN44_V12
    START44_V12
    MC_44_V12
    
  • For the Fall11_Chamonix MC production in CMSSW_442patch9
    DESIGN44_V10D
    MC_44_V10D
    START44_V10D
    
  • Monte Carlo with samples from the Fall11_R3 MC production
    DESIGN44_V5D
    START44_V5D
    MC_44_V5D
    
  • Monte Carlo with samples from the Fall11_R4 MC production
    DESIGN44_V9C
    START44_V9C
    MC_44_V9C
    
  • Data
    GR_R_44_V13
    

For 50X, we have the following global tags:

  • Monte Carlo
    DESIGN50_V12
    START50_V12
    MC_50_V12
    
  • Data
    GR_R_50_V9
    

To access JEC uncertainty sources (correlations) retrieve the text files from and follow the instructions at
https://twiki.cern.ch/twiki/bin/view/CMS/JECUncertaintySources

  • There has been a numerical instability with respect to 64-bit versus 32-bit in the Voronoi tessellation used by fastjet. The fastjet authors are aware of the situation and are fixing it now. In the meantime, we recommend to switch to use the ACTIVE AREA (with deterministic seeding) for the KT6 algorithm for the "rho" computation.

  • These tags in CMSSW 4.2.4 will use a deterministic seeding to the fastjet active-area rho and area computations in the instructions above.
The configuration files for examples are found in:

RecoJets/Configuration                           V02-04-17

If you are using a different CMSSW release previous to 4.2.4 then you also should check out:

RecoJets/Configuration                           V02-04-17
RecoJets/JetAlgorithms                           V04-01-00      
RecoJets/JetProducers                            V05-05-03

First complete JEC set for 42x 2011 data

The first complete JEC for 42x 2011 data was still based on MC truth from pre42X technical release that had preshower in the reconstruction, while the actual 42X (accidentally) did not. The MC truth corrections also had problems at |eta|>4.7. The offset corrections did not include out-of-time pile-up and had PF in-time pile-up scaled down by 20% at |eta|<3 compared to 2011 final JEC. While this JEC release is still satisfactory within the increased uncertainties compared to 2010 final JEC, we recommend all new users to directly use the final 42x JEC for 2011, listed above.

Global tags for 42x have been prepared (many thanks to the AlCa team, as always!). Please use these in your analysis.
  • These now include the L2L3Residual corrections and the first estimate of the uncertainties in the 2011 data (42x)
  • Monte Carlo
    DESIGN42_V12
    MC_42_V13
    START42_V13
    
  • Data
    GR_R_42_V19
    

The first rereco of 2011 data, and the recent Prompt Reco is done with 42X that contains new HCAL and PF cluster calibrations, which cause substantial changes to JEC. To facilitate the transition, an approximate JEC set has been derived using a special 3_11_1_hclpatch1 MC sample which is a technical one, closer to the response expected in 4_2_x. The new constants are currently available through the global tags. Below are the instructions. By default in 4.2.4 this will run the active area computation with deterministic seeds.

  • Edit your configuration file and make the connection to the global tags.
    ## Geometry and Detector Conditions (needed for a few patTuple production steps)
    process.load("Configuration.StandardSequences.FrontierConditions_GlobalTag_cff")
    process.GlobalTag.globaltag = cms.string( 'GR_R_42_V19::All' )
    ##-------------------- Import the JEC services -----------------------
    process.load('JetMETCorrections.Configuration.DefaultJEC_cff')
    ##-------------------- Import the Jet RECO modules -----------------------
    process.load('RecoJets.Configuration.RecoPFJets_cff')
    ##-------------------- Turn-on the FastJet density calculation -----------------------
    process.kt6PFJets.doRhoFastjet = True
    ##-------------------- Turn-on the FastJet jet area calculation for your favorite algorithm -----------------------
    process.ak5PFJets.doAreaFastjet = True
    .............................................................................................
    ##-------------------- User analyzer  --------------------------------
    process.MyAnalyzer  = cms.EDAnalyzer('MyAnalyzer',
    ...............................................................................................
    JetCorrectionService = cms.string('ak5PFL1FastL2L3'), 
    ...............................................................................................
    ##-------------------- Include in the path the jet reconstruction  --------------------------------
    process.p = cms.Path(process.kt6PFJets * process.ak5PFJets * process.MyAnalyzer)
    )
    

The first 2011 data have been prompt reconstructed with the 4_1_2 with conditions similar to those in 2010. Therefore, all the corrections (MCtruth+residuals) used in 2010 can still be applied to 2011 prompt data. For 41X, follow the instructions above. Users should be aware of four caveats, however:

  • The increased pile-up profile necessitates the use of PU subtraction with either L1Offset or L1FastJet.
  • There are no "rho" corrections by default in RECO in 42x, so the user must re-run them.
  • There has been a numerical instability with respect to 64-bit versus 32-bit in the Voronoi tessellation used by fastjet. The fastjet authors are aware of the situation and are fixing it now. In the meantime, we recommend to switch to use the ACTIVE AREA (with deterministic seeding) for the KT6 algorithm for the "rho" computation.

First JEC set for 52x 2012 data

The first complete 52X set of JEC is based on 0.57-1.6/fb of 2012 data at 8 TeV. The new corrections come separately for data and MC to accommodate observed differences in pile-up corrections (L1). The main changes for AK5PF compared to running 42X corrections on 2012 data or MC are the following
  • L1 corrections in end caps reduced due HBHE switching to 2 time-slice reco (was 4 TS), which removes practically all late out-of-time pile-up
  • L1 corrections have slight overall increase due to higher sqrt(s) (7 TeV to 8 TeV), which is absorbed by L1FastJet except for above change in eta-dependence
  • L1 corrections for data and MC observed to deviate at high PU and now provided separately for each
  • Missing preshower was added back in RECO and increases end cap response compared to 42X
  • HF response changed by ~5%

The slides shown at JetMET object approval on May 30 are available here: JetMET object approval at GWM.

Update June 11: The Global Tag has now been prepared (was requested on June 8). See information below:
(NB: all GTs below contain the same JEC, so any GT can be used if only correcting jets. If running re-reco, select the suitable GT)

On Sat, Jun 9, 2012 at 12:45 PM, Rovelli Chiara <chiara.rovelli@cern.ch> wrote:

For data:
GR_R_52_V9 is consistent with the new H->gg rereco and the prompt reco starting from run 195536.
GR_R_52_V7C is consistent with the prompt reco up to run 195535.

For MC:
START52_V9B is consistent with the conditions used for Summer12 montecarlo production.
For more recent 52X releases we prepared START52_V11
(with also MC_52_V11 and DESIGN52_V11 for ideally aligned and calibrated detector with and without bad channels respectively).

As usual you can find all details in
https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideFrontierConditions#52Y_Releases_MC

For what concerns prompt reco, we'd prefer to wait for the technical stop before changing the JECs to have consistency - unless
there are reasons to believe it is crucial to have them now. Is that fine? We'll let you know when you can append the new IOVs.

The global tag corresponds to our sqlite files for JEC V7: Summer12_V7_DATA.db and Summer12_V7_MC.db. The contents of the sqlite files are described in SQL_Summer12_V7.pdf. See How to connect to a local sqlite file for instruction on how to connect a local sqlite file.

Note that the first sqlite for JEC V3 provided immediately after object approval had older L2L3Residuals than what was shown at approval and what is in current JEC V7. The differences are within 1.1%, however.

First JEC set for 53x 2012 data

The first complete 53X set of JEC is based on >11 /fb of 2012 data at 8 TeV. The new corrections come separately for data and MC to accommodate observed differences in pile-up corrections (L1).

The slides shown at JetMET object approval on Dec 5th are available here: JetMET object approval at GWM.

The latest recommended corrections and global tags for 2012 data and MC simulation can be found at the link https://twiki.cern.ch/twiki/bin/view/CMS/JECDataMC

A list of all GTs is provided on the Twiki SWGuideFrontierConditions.

More information on the usage of the JEC and latest developments are provided at the JetEnergyScale twiki.

Please note: We have identified a problem with the 2012 jec uncertainties having a runaway behavior at low pT. If your analysis is sensitive to the jec uncertainty for jets with pt < 20 GeV, please make sure to use the uncertainties from tag START53_V21 or use the new uncertainty files that can be found at https://twiki.cern.ch/twiki/bin/view/CMS/JECUncertaintySources#2012_JEC

First JEC set for 53x 2012 reprocessed data

The first complete 53X set of JEC is based on 20 /fb of 2012 reprocessed data at 8 TeV. The new corrections come separately for data and MC to accommodate observed differences in pile-up corrections (L1). These new corrections feature new pt-dependent pile-up corrections which are only available for the Fastjet approach of the L1. In addition, the JEC uncertainties got fully updated. The treatment of the flavor uncertainties was improved to reduce the flavor uncertainty of the JEC.

The slides shown at PPD approval on May 22nd are available here: PPD approval of new JEC. The new flavor treatement is described in this talk.

Please note: The new tags contains only a L1 correction based on the FastJet approch for CALO jets. Please adapt your configuration files accordingly, e.g. change patJetCorrFactors.levels to use L1FastJet instead of L1Offset.

Please note: Due to the same reason please use a global tag with the old JEC for JPT jets for the time being.

The latest recommended corrections and global tags for 2012 reprocessed data and MC simulation can be found at the link https://twiki.cern.ch/twiki/bin/view/CMS/JECDataMC

A list of all GTs is provided on the Twiki SWGuideFrontierConditions. A description of the uncertainty sources and the uncertainty files can be found on the Twiki JECUncertaintySources.

More information on the usage of the JEC and latest developments are provided at the JetEnergyScale twiki.

First JEC set for the 72X PHYS14 MC

The first complete 72X set of JEC is based solely on 25ns run-dependent MC at 13 TeV. The new corrections are only for MC. These new corrections are derived similarly to the 53X corrections, but use a new L2Relative/L3Absolute fitting function to obtain corrections down to 3 or 4 GeV. No JEC uncertainties or L5Flavor corrections have been derived for these corrections as of yet.

The slides shown at the PHYS14 status meeting on December 5th, 2014 are available here: PHYS14 status of new JEC.

Please note: There are no data corrections available for PHYS14, which means there are no L2L3Residual corrections.

Please note: These corrections have been derived for Anti-Kt {PF,PFchs}, R={0.4,0.5,0.7,0.8} jets. There are no Calo jet corrections.

The latest recommended corrections and global tags for 2012 reprocessed data and MC simulation can be found at the link https://twiki.cern.ch/twiki/bin/view/CMS/JECDataMC

A list of all GTs is provided on the Twiki SWGuideFrontierConditions.

More information on the usage of the JEC and latest developments are provided at the JetEnergyScale twiki.

The files below contain an example of how to use the PHYS14 corrections. In particular they create the necessary AK4 gen jet collection, use the AK4PF and AK4PFchs jets from a PHYS14 dataset, and and run a simple EDAnalyzer. This program also creates all of the necessary ESProducers and EDProducers needed for the L1Fastjet, L2Relative, and L3Absolute jet energy corrections. The EDAnalyzer makes use of the L1L2L3 corrected AK4PFchs jets.

Using CHS Without PAT
NEW! PF Jets with Charged Hadron Subtraction (aka "PFnoPU") in 2012
  • There are several new features in PF2PAT (now known as PFBRECO) to make this easier in 2012 than in 2011
  • You also do not need to run the "rho" variable using kt6PFJets anymore, as this is now done in RECO.
  • The charged-hadron subtraction in PFNoPU has continuing development to develop a common selection for all POG's, but for now we must continue to operate as per 2011, with updated instructions.
    • Nota Bene: current JetMET version of PFNoPU leaves about 20% pile-up charged hadrons untouched. This compromise was necessary to avoid over-subtracting high pT tracks from jets. The L1chs corrections account for these remaining pile-up charged hadrons so the following settings must be enabled (these are different from lepton isolation settings):
    • use goodOfflinePrimaryVertices collection
    • set checkClosestZVertex = False
  • There is a jet energy correction available for using PFJets with charged hadron subtraction (AK5PFchs). In order to use this, you must enable the charged hadron subtraction in particle flow.
  • There is a complete example to apply PFCHS here.
  • When these steps are followed, you can follow the same recipe as described above for accessing the jet energy corrections. Replace "AK5PF" with "AK5PFchs" variable.
  • To do this, you must process several steps in the PF2PAT chain.
    
    # 1. Create good primary vertices to be used for PF association
    from PhysicsTools.SelectorUtils.pvSelector_cfi import pvSelector
    
    process.goodOfflinePrimaryVertices = cms.EDFilter(
        "PrimaryVertexObjectFilter",
        filterParams = pvSelector.clone( minNdof = cms.double(4.0), maxZ = cms.double(24.0) ),
        src=cms.InputTag('offlinePrimaryVertices')
        )
    
    # 2. Create the "top-down projection" for the PF2PAT sequence
    from PhysicsTools.PatAlgos.tools.pfTools import *
    postfix = "PFlow"
    usePF2PAT(process,runPF2PAT=True,
              jetAlgo='AK5', runOnMC=True, postfix=postfix,
              jetCorrections=('AK5PFchs', ['L1FastJet', 'L2Relative', 'L3Absolute']),
              pvCollection=cms.InputTag('goodOfflinePrimaryVertices')
              )
    process.pfPileUpPFlow.checkClosestZVertex = False
    
    # 3. Add them all to the sequence
    process.patseq = cms.Sequence(    
        process.goodOfflinePrimaryVertices*
        getattr(process,"patPF2PATSequence"+postfix)
        )
    
    # 4. Add appropriate "keep" statements in your output
    process.out.outputCommands = [
        'keep *_selectedPat*_*_*',
        'keep *_goodOfflinePrimaryVertices*_*_*',    
        'keep double_*_rho_*'
    ]
    
    # 5. If you do not want to use the PAT part of PF2PAT, you can simply take the RECO products created directly,
    #     simply comment the above (4.) and uncomment these lines:
    #process.out.outputCommands = [
    #   'keep *_pfJetsPFlow_*_*',
    #    'keep *_goodOfflinePrimaryVertices*_*_*',    
    #    'keep double_*_rho_*'
    #]
    

There is an example of using CHS without using PAT here.

PF Jets with Charged Hadron Subtraction (aka "PFnoPU") in 2011

  • UPDATE 15-March-2012: The recipe below has been updated to use the "rho" variable from all PF candidates to be consistent with the final JEC for 2011.
  • Due to a miscommunication between the JME and TRK POG's, we were recommending an selection on the number of primary vertices that is too tight (by 5 percent or so), so we have now changed the recommendation to cut on ndof >= 4 instead of ndof >= 7. You should use ndof >= 7 ONLY if you are using a beam-constrained PV as input.

  • There is a jet energy correction available for using PFJets with charged hadron subtraction (AK5PFchs). In order to use this, you must enable the charged hadron subtraction in particle flow.
  • There is a complete example to apply PFCHS here.
  • When these steps are followed, you can follow the same recipe as described above for accessing the jet energy corrections. Replace "AK5PF" with "AK5PFchs" variable.
  • To do this, you must process several steps in the PF2PAT chain.
    1. Create good primary vertices to be used for PF association
      from PhysicsTools.SelectorUtils.pvSelector_cfi import pvSelector
      
      process.goodOfflinePrimaryVertices = cms.EDFilter(
          "PrimaryVertexObjectFilter",
          filterParams = pvSelector.clone( minNdof = cms.double(4.0), maxZ = cms.double(24.0) ),
          src=cms.InputTag('offlinePrimaryVertices')
          )
      
    2. Create the "top-down projection" for the PF2PAT sequence
      from PhysicsTools.PatAlgos.tools.pfTools import *
      postfix = "PFlow"
      usePF2PAT(process,runPF2PAT=True, jetAlgo='AK5', runOnMC=not options.useData, postfix=postfix)
      process.pfPileUpPFlow.Enable = True
      process.pfPileUpPFlow.Vertices = 'goodOfflinePrimaryVertices'
      process.pfJetsPFlow.doAreaFastjet = True
      process.pfJetsPFlow.doRhoFastjet = False
      process.patJetCorrFactorsPFlow.rho = cms.InputTag("kt6PFJets", "rho")
      
      
      • NOTA BENE! In 4.2.x AND HIGHER you also have to use this switch, but not in 4.1.x:
        process.pfPileUpPFlow.checkClosestZVertex = cms.bool(False)
        
    3. Compute the mean pt per unit area ("rho") using KT6 Jets with the active areas method.
      from RecoJets.JetProducers.kt4PFJets_cfi import kt4PFJets
      process.kt6PFJets = kt4PFJets.clone(
          rParam = cms.double(0.6),
          doAreaFastjet = cms.bool(True),
          doRhoFastjet = cms.bool(True)
          )
      
    4. Add them all to the sequence
      getattr(process,"patPF2PATSequence"+postfix).replace( getattr(process,"pfNoElectron"+postfix), getattr(process,"pfNoElectron"+postfix)*process.kt6PFJets )
      process.patseq = cms.Sequence(    
          process.goodOfflinePrimaryVertices*
          getattr(process,"patPF2PATSequence"+postfix)
          )
      
    5. Add appropriate "keep" statements in your output
      process.out.outputCommands = [
          'keep *_selectedPat*_*_*',
          'keep *_goodOfflinePrimaryVertices*_*_*',    
          'keep double_*_*_PAT'
      ]
      
    6. IF you do not want to use the PAT part of PF2PAT, you can simply take the RECO products created directly
      process.out.outputCommands = [
          'keep *_pfJetsPFlow_*_*',
          'keep *_goodOfflinePrimaryVertices*_*_*',    
          'keep double_*_*_PAT'
      ]
      

Old instructions for latest JEC, DO NOT USE:

A first version of the residuals and the JEC uncertainties are now available in global tags. Currently only in the format of an sqlite file, in anticipation of the corresponding global tags. The other correction levels (L2L3) remain identical to the existing global tags. Below are the instructions to get the new sqlite file:

  • get the file from cvs:
cvs co -d JEC UserCode/KKousour/data/Jec11V2.db

  • copy the file to your working area:
cp JEC/Jec11V2.db /my/area/

  • edit your cfg file, allowing the connection to the sqlite file:
process.load("CondCore.DBCommon.CondDBCommon_cfi")
process.jec = cms.ESSource("PoolDBESSource",
      DBParameters = cms.PSet(
        messageLevel = cms.untracked.int32(0)
        ),
      timetype = cms.string('runnumber'),
      toGet = cms.VPSet(
      cms.PSet(
            record = cms.string('JetCorrectionsRecord'),
            tag    = cms.string('JetCorrectorParametersCollection_Jec11V2_AK5PF'),
            label  = cms.untracked.string('AK5PF')
            ),
      cms.PSet(
            record = cms.string('JetCorrectionsRecord'),
            tag    = cms.string('JetCorrectorParametersCollection_Jec11V2_AK5Calo'),
            label  = cms.untracked.string('AK5Calo')
            )
      ),
      ## here you add as many jet types as you need (AK5PFchs, AK5Calo, AK5JPT, AK7PF, AK7Calo, KT4PF, KT4Calo)
      connect = cms.string('sqlite:Jec11V2.db')
)
# Add an es_prefer statement to get your new JEC constants from the sqlite file, rather than from the global tag
process.es_prefer_jec = cms.ESPrefer('PoolDBESSource','jec')

  • A tip for submitting CRAB jobs, while using the local sqlite file:
[USER]
..........
additional_input_files  = Jec11V2.db

Naming Scheme

IMPORTANT: NEW naming scheme for CMSSW_3_6_X and later. Calorimeter jets and Particle flow jets are supported, for all the default reconstructed jet algorithms in the official samples (IC5,KT4,KT6,AK5,AK7). In addition there are also available corrections on top of the JetPlusTrack algorithm and for TrackJets. The names of the corrected jet collections for the 7 TeV data and MC analysis with CMSSW_3_6_X are listed below:

  • kt4CaloJetsL2L3 (KT D=0.4 CaloJets corrected with L2+L3)
  • kt4PFJetsL2L3 (KT D=0.4 PFlow Jets corrected with L2+L3)
  • kt6CaloJetsL2L3 (KT D=0.6 CaloJets corrected with L2+L3)
  • kt6CaloJetsL2L3 (KT D=0.6 PFlow Jets corrected with L2+L3)
  • ak5CaloJetsL2L3 (anti-KT D=0.5 Calo Jets corrected with L2+L3)
  • ak5PFJetsL2L3 (anti-KT D=0.5 PFlow Jets corrected with L2+L3)
  • ak5JPTJetsL2L3 (anti-KT D=0.5 JPT Jets corrected with L2+L3)
  • ak5TrackJetsL2L3 (anti-KT D=0.5 Track Jets corrected with L2+L3)
  • ak7CaloJetsL2L3 (anti-KT D=0.7 Calo Jets corrected with L2+L3)
  • ak7PFJetsL2L3 (anti-KT D=0.7 PFlow Jets corrected with L2+L3)

Information Sources

For further reading, follow the links below.

  • Physics Analysis Summaries (data)
    • Jet Performance in pp Collisions at sqrt{s}=7 TeV (PAS-JME-10-003)
    • Single Particle Response in the CMS Calorimeters (PAS-JME-10-008)
  • Analysis Notes (data)
    • Particle Flow jet calibration with gamma+jet events: pT balance and missing-ET projection fraction (AN-2010/218)
    • Jet Response and Resolution Measurement with Photon+Jet Events at sqrt(s) = 7 TeV (AN-2010/141)
    • Measurement of the Relative Jet Energy Scale in CMS with pp Collisions at sqrt(s)=7 TeV (AN-2010/139)
    • Offset Energy Correction for Cone Jets (AN-2010/150)
  • Analysis Notes (simulation)
    • Calorimeter Jet Energy Corrections based on the Jet Width (AN-2010/223)
    • Validation of the Jet Energy Corrections in Simulated Events with Top Quarks (AN-2010/094)
    • Calibration of the absolute jet energy scale with Z(->mu+mu-) + jet events at CMS (AN-2009/057)
    • Jet Energy Correction Using Z (->e+e-) + Jet pT Balance and the Method for Combining Data Driven Corrections (AN-2009/004)
    • Flavor Specific Jet Energy Corrections and Closure Tests for Factorized Jet Energy Corrections (AN-2009/010)
    • Offset Energy Correction for Cone Jets (AN-2009/035)
    • Jet energy calibration with photon+jet events (AN-2009/012)
    • Determination of the Relative Jet Energy Scale at CMS from Dijet Balance (AN-2008/031)
    • MC Truth L2 & L3 Factorized Jet Corrections at CMS (AN-2008/003)
  • Presentations

Review status

Reviewer/Editor and Date (copy from screen) Comments
Ia Iashvili - 19 January 2016 Updated instruction on extracting JEC txt files
Alexx Perloff - 19 February 2015 Added an example for how to use the PHYS14 JEC
Mikko Voutilainen - 13 June 2012 Added plenty of TWISTY tags to hide content that is for more specific uses and for older releases
Mikko Voutilainen - 11 Jan 2012 Added global tags for 2011 final JEC in 42x
Olga Kodolova - 29 Aug 2011 Added JPT to access instruction how to get txt files from DB and access the local sql
Salvatore Rappoccio - 9 Jun 2011 Updated PF CHS and L1Fastjet instructions
Konstantinos Kousouris - 16 Sep 2010 Updated instructions and added information sources
Konstantinos Kousouris - 27 May 2010 Recipe for JEC in CMSSW_3_6_1
Konstantinos Kousouris - 18 Apr 2010 Updated the FWLite example
Konstantinos Kousouris - 18 Apr 2010 Removed obsolete instructions and examples
Konstantinos Kousouris - 18 Apr 2010 Recipe for JEC in CMSSW_3_6_0

Responsible: KonstantinosKousouris
Last reviewed by: Ia Iashvili - 19 Jan 2016

Topic attachments
I Attachment History Action Size Date Who Comment
XMLxml BuildFile.xml r1 manage 0.6 K 2015-02-19 - 21:01 AlexxPerloff Simple program to make use of the PHYS14 JEC
Texttxt CfiFile_cfi.py.txt r1 manage 0.1 K 2015-02-19 - 21:01 AlexxPerloff Simple program to make use of the PHYS14 JEC
Texttxt ConfFile_cfg.py.txt r2 r1 manage 2.6 K 2015-02-19 - 21:08 AlexxPerloff Simple program to make use of the PHYS14 JEC
Texttxt JetCorrection_cff.py.txt r2 r1 manage 2.5 K 2015-02-19 - 21:07 AlexxPerloff Simple program to make use of the PHYS14 JEC
Unknown file formatcc demo.cc r1 manage 4.6 K 2015-02-19 - 21:01 AlexxPerloff Simple program to make use of the PHYS14 JEC
Edit | Attach | Watch | Print version | History: r141 < r140 < r139 < r138 < r137 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r141 - 2017-11-27 - HenningKirschenmann
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback