Jet Energy Resolution: Official Software Tools for retrieving JER and scale factors

Contact: Sébastien Brochet

Introduction

Measurements show that the jet energy resolution (JER) in data is worse than in the simulation and the jets in MC need to be smeared to describe the data. This page provides software instruction on how-to retrieve the JER smearing factors. For details on how to use these factors, see JetResolution twiki page

Installation recipe

CMSSW 7.4.X

export SCRAM_ARCH=slc6_amd64_gcc491
cmsrel CMSSW_7_4_15_patch1

cd CMSSW_7_4_15_patch1/src
cmsenv

git cms-merge-topic blinkseb:jer_gt_74x_fix

scram b -j4

CMSSW 7.6.X and CMSSW 8.0X

Available in official release since CMSSW 7.6.3 patch1 and CMSSW 8.0.0

Software reference

A full demo code on how-to use the software can be found here: https://github.com/blinkseb/cmssw/blob/jer_fix_76x/JetMETCorrections/Modules/plugins/JetResolutionDemo.cc#L74

Accessing factors from Global Tag

Jet pt and phi resolution, as well as jet resolution scale factors are stored inside the global tags. A simple interface is provided to easily retrieve the necessary object:

JME::JetResolution resolution = JME::JetResolution::get(iSetup, "AK4PFchs_pt");
JME::JetResolutionScaleFactor resolution_sf = JME::JetResolutionScaleFactor::get(iSetup, "AK4PFchs");

The first argument, iSetup, is an instance of edm::EventSetup that you can access via the produce or analyze method. The second argument is the label, a string describing the payload. The label you should use depends on what you want to retrieve. Allowed values are:

  • For the scale factors, the label is always the jet algorithm. Possible values are AK4PF, AK4PFchs, AK8PF and AK8PFchs (no PUPPI for the moment)
  • For the pt resolution, the label is the the jet algorithm, with the _pt suffix. Possible values are AK4PF_pt, AK4PFchs_pt, AK8PF_pt and AK8PFchs_pt
  • For the phi resolution, the label is the the jet algorithm, with the _phi suffix. Possible values are AK4PF_phi, AK4PFchs_phi, AK8PF_phi and AK8PFchs_phi

Description on how-to get factors from the JME::JetResolution and JME::JetResolutionScaleFactor objects is provided below.

Accessing factors from text files

You can also directly access resolution and scale factors from text files:

JME::JetResolution resolution = JME::JetResolution("/path/to/a/file.txt");
JME::JetResolutionScaleFactor resolution_sf = JME::JetResolutionScaleFactor("/path/to/a/file.txt");

Only one argument is needed, the path to the text file containing the values. Description on how-to get factors from the JME::JetResolution and JME::JetResolutionScaleFactor is provided below.

Accessing factors from database

This method allows the user to easily override the values of the Global Tag. Some configuration is needed on the python configuration:

process.load('Configuration.StandardSequences.Services_cff')
process.load("JetMETCorrections.Modules.JetResolutionESProducer_cfi")
from CondCore.DBCommon.CondDBSetup_cfi import *

process.jer = cms.ESSource("PoolDBESSource",
        CondDBSetup,
        toGet = cms.VPSet(
            # Resolution
            cms.PSet(
                record = cms.string('JetResolutionRcd'),
                tag    = cms.string('JR_Summer15_25nsV6_MC_PtResolution_AK4PFchs'),
                label  = cms.untracked.string('AK4PFchs_pt')
                ),

            # Scale factors
            cms.PSet(
                record = cms.string('JetResolutionScaleFactorRcd'),
                tag    = cms.string('JR_Summer15_25nsV6_MC_SF_AK4PFchs'),
                label  = cms.untracked.string('AK4PFchs')
                ),
            ),
        connect = cms.string('sqlite:Summer15_25nsV6.db')
        )

process.es_prefer_jer = cms.ESPrefer('PoolDBESSource', 'jer')

You need to tweak the tag fields if you use a different database. To get the list of tags inside a database, you can run conddb --db <database> listTags

Retrieve factors

Use the method getResolution(const JME::JetParameters& parameters) from JME::JetResolution(const JME::JetParameters& parameters) to retrieve the jet resolution, and the method getScaleFactor to retrieve the scale factors. Since these values depends on various parameters, you'll need to pass some information about the jet to these functions. For that, a simple and unique interface exists, JME::JetParameters. The full definition of the class is available here: https://github.com/cms-sw/cmssw/blob/CMSSW_7_6_X/CondFormats/JetMETObjects/interface/JetResolutionObject.h#L92.

Jet resolution

Jet resolution depends on the pt and eta of the jet. You'll need to initialize the JetParameters object with the correct quantities. Below you can find many ways to initialize the object. All methods are equivalent, so choose the one you prefer:

// First, using 'set' functions
JME::JetParameters parameters_1;
parameters_1.setJetPt(jet.pt());
parameters_1.setJetEta(jet.eta());

// You can also chain calls
JME::JetParameters parameters_2;
parameters_2.setJetPt(jet.pt()).setJetEta(jet.eta());

// Second, using the set() function
JME::JetParameters parameters_3;
parameters_3.set(JME::Binning::JetPt, jet.pt());
parameters_3.set({JME::Binning::JetEta, jet.eta()});

// Or

JME::JetParameters parameters_4;
parameters_4.set(JME::Binning::JetPt, jet.pt()).set(JME::Binning::JetEta, jet.eta());
    
// Third, using a initializer_list
JME::JetParameters parameters_5 = {{JME::Binning::JetPt, jet.pt()}, {JME::Binning::JetEta, jet.eta()}};

Then, to obtain the resolution, use:

float r = resolution.getResolution(parameters_1); // Or parameters_2, ...

Scale factors

Scale factors only depend on eta and rho, so you just need to define the JME::JetParameters like this

JME::JetParameters parameters = {{JME::Binning::JetEta, jet.eta()}, {JME::Binning::Rho, rho}};

To obtain the jet resolution scale factor, simply call:

float sf = resolution.getScaleFactor(parameters);

You can also obtain the up and down variation by adding a second argument to the function call:

float sf_up = resolution.getScaleFactor(parameters, Variation::UP);
float sf_down = resolution.getScaleFactor(parameters, Variation::DOWN);

Note: this directly returns the scale factors, not the error itself

List of supported parameters

  • JetPt (setJetPt) : jet pt
  • JetEta (setJetEta) : jet eta
  • JetAbsEta (setJetEta) : absolute jet eta
  • JetE (setJetE) : jet energy
  • JetArea (setJetArea) : jet area
  • Mu (setMu) : mu
  • Rho (setRho) : rho
  • NPV (setNPV) : number of primary vertices

Text files format

The format used for storing JER factors is very similar to the one used for storing JEC. This section describes the format of such file.

First, an example of text file can be found here:

Header

Let's start with the header:

{1    JetEta     1     JetPt     sqrt([0]^2/x^2+[1]^2/x+[2]^2)    Resolution}

The first number, 1, is the number of bin N. After, you find the list of binning variable. The list length must be N, and each bin name must be a supported binning variable (see here for a complete list). In this case, there's only one eta bin.

After the bin list, you find the number of variables, V. Like for the binning, you find directly after the list of variables (length must be V). Up to four variables can be supported (this is a limitation of ROOT). Inside the formula, the first variable will be mapped to x, the second to y, the third to z and the fourth to t. In our example, we define 1 variable, pt.

After the variable list comes the formula definition. Note than you cannot put any space into the formula definition or you'll break the file parsing. This is a standard ROOT TFormula definition, and it can depends on any number of parameters.

The last argument must be Resolution.

Content

After the header follow a unlimited number of lines. Each line describes a given bin. The format is the following:

-5.0   -3.2      5     10     200    4.5    0.1    0.05

At the beginning, you find 2*N numbers (N is the number of bins). Each couple of number describes the range of the current bin. In this case, it's the eta bin from -5.0 to -3.2.

After the binning definition, you have one number (5 in this case), which is simply the number of remaining values in the line. Here, we tell the parser that there's 5 numbers left to read.

After come the range definition for all the variables. The parser expects to find 2 * V numbers (V is the number of variables), where the first number is the lower range of the variable, and the upper range of the variable. Here, it's pt is allowed to vary from 10 to 200 GeV. Note: If the variable is out of this range,it's automatically clamped.

All the remaining number are the parameters of the formula.

Scale factors file format

Scale factors file format is the same as resolution file format. A typical file looks like

{1 JetEta 0 None ScaleFactor}
-4.7    -3.2  3   1.320     1.034     1.606
-3.2    -3.0  3   1.303     1.192     1.414
-3.0    -2.5  3   1.343     1.220     1.466
...

The header tells us that we have one bin in eta of the jet, followed by 0 variables. The formula is None, a special value telling the parser there's no formula.

On each line you find the scale factors. First two numbers are the binning, and then 3 values to read. The first one is the nominal scale factor, the second the down variation, and the third one the up variation.

-- SebastienBrochet - 2015-07-24

Edit | Attach | Watch | Print version | History: r15 < r14 < r13 < r12 < r11 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r15 - 2016-05-25 - SebastienBrochet
 
    • 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