Jet calibration tools for physics analyses

Jet Calibration Tools General Instructions

This page contains only the basic instructions for checking out, compiling, and running the software packages for applying jet calibrations. For physics analysis specific recommendations, please refer to the the following twiki pages:

For information on the JES uncertainty provider please refer to this twiki page:

For information related to the JER uncertainty provider and Jet resolution smearing tool please refer to these twiki pages:



This picture shows an overview of the ATLAS jet calibration. The full calibration can be reapplied at D3PD level using the software tool described below. The calibration factors for the pile-up and absolute JES corrections are stored inside the calibration tool, and can hence be easily updated. The origin correction can not be reapplied from scratch as it's calculated from topoclusters, but the correction is stored as a jet moment and is available in D3PD. The residual in-situ calibration is available in ApplyJetCalibration-00-01-02 and later, and is applied to data only when initiating the tool with any of the InsituJES_* configurations.

Note: Since May 14, 2012, a preliminary in-situ jet calibration for 2011 data, derived from a harder smoothing of slide 3 of this talk, is available in tag ApplyJetCalibration-00-01-06 and following (so it is also there in tag 00-02-07 which is recommended for 2012 analysis). The uncertainty of this calibration is available in JESUncertainty-00-07-01, see the JetUncertainties2011 twiki pages.

The in-situ calibration will be applied as part of the default ApplyOffsetEtaJES(...) call when the tool is initiated with an insitu configuration (such as the new default InsituJES_2011_Preliminary) and the parameter isData=true in the constructor. For technical details see below.

Software Tools and Recommendations

Stand-alone tools to apply various jet calibrations and energy resolution smearing to D3PD-based analyses have been developed. These tools are compatible with RootCore. Below are instructions how to check out the latest tools (as of September 30, 2012).
svn co $SVNOFF/PhysicsAnalysis/D3PDTools/RootCore/tags/RootCore-00-00-29 RootCore  # can use a more recent version as well
svn co $SVNOFF/Reconstruction/Jet/ApplyJetCalibration/tags/ApplyJetCalibration-00-02-07 ApplyJetCalibration
svn co $SVNOFF/Reconstruction/Jet/JetResolution/tags/JetResolution-01-00-01 JetResolution # continue using tag 01-00-00 if it hasn't been problematic
svn co $SVNGRP/CombPerf/JetETMiss/JetCalibrationTools/ApplyJetResolutionSmearing/tags/ApplyJetResolutionSmearing-00-00-03 ApplyJetResolutionSmearing

In order to compile the tools (more instructions on the RootCore page):

cd RootCore; ./configure ; cd .. ;    ## only the very first time after checking out Rootcore
source RootCore/scripts/ ## first thing to do every time one opens a new shell
./RootCore/scripts/  ## identifies and compiles all RootCore compatible packages in the area
To only compile individual packages you can use the Makefile.Standalone files in the cmt folders.

The jet calibration tool

Documentation of the tool is available in these slides. You can also browse the code in SVN here.

Instructions on how to use the jet calibration tool

First of all, the tool needs to be initialised, in the header file:

   #include "ApplyJetCalibration/ApplyJetCalibration.h"
   JetCalibrationTool *myJES;
Before the event loop
   // initiate the calibration tool
   TString jetAlgo="AntiKt4TopoEM";
   TString JES_config_file="ApplyJetCalibration/data/CalibrationConfigs/JES_August2012.config";
   bool isData = true; // if running on data
   // bool isData = false; // if running on MC
   myJES = new JetCalibrationTool(jetAlgo,JES_config_file, isData);// 

The JES_config_file is a TEnv-based configuration file so that the JetCalibrationTool object picks up the correct calibration constants. It generally does not need to be modified by the user. By default all energies are assumed to be in MeV, but this can be changed using myJES->UseGeV(true).

When looping over all events, one needs to retrieve the average number of interactions and the number of primary vertices with 2 or more tracks in the event, as these are inputs for extracting the right pile-up correction.

   // loop over events
   for (Long64_t jentry=0; jentry<nentries;jentry++) {

     // For the pile-up correction, we need mu and NPV(2+ tracks)
     double mu = averageIntPerXing;
     int NPV=0; // count the number of vertices with 2 or more tracks
     for ( unsigned tracki=0; tracki<vxp_nTracks->size(); tracki++)
       if ( vxp_nTracks->at(tracki) >= 2 ) NPV++;

Then one needs to apply the JES to the jets in the event (one assumes they have been saved as TLorentzVector). The variables needed are both the energy and eta at the EM scale (before any calibration) and those after the origin correction. The ApplyOffsetEtaJES function will take care of all the corrections at once: in the case of MC11a, only the pile-up correction will be applied (on top of the existing EM+JES calibration), but in the future it will apply offset correction, JES correction and residual correction from in-situ techniques.

     // 1. Apply JES
     vector<TLorentzVector> theJets;
     int Njets=jet_AntiKt4TopoEM_E->size();
     for ( int jeti=0; jeti<Njets; jeti++ ) {
       double Eraw    = jet_AntiKt4TopoEM_emscale_E->at(jeti);
       double eta_det = jet_AntiKt4TopoEM_emscale_eta->at(jeti);
       double eta     = jet_AntiKt4TopoEM_EtaOrigin->at(jeti);
       double phi     = jet_AntiKt4TopoEM_PhiOrigin->at(jeti);
       double m       = jet_AntiKt4TopoEM_MOrigin->at(jeti);

       // Calibrate the jet!
       // Pile-up, origin, EtaJES correction applied, i.e. to OFFSET_ORIGIN_ETAJES scale
       TLorentzVector jet = myJES->ApplyOffsetEtaJES(Eraw,eta_det,eta,phi,m,mu,NPV);


For LC+JES jets (e.g. AntiKt4LCTopo), make sure that instead of the emscale variables you are using the constscale variables. This is because the scale at which the JES has been derived already assumes that the clusters have been calibrated with the LCW scheme.

At this point one can smear jets (following the instructions at the JetSmearingTool twiki page), select events, fill histograms and continue with the event loop. As the pT of the jets changed from the one saved in the D3PD (according to which jets are ordered), one might need to re-sort the jets:

#include <algorithm>;

bool ComparePt(TLorentzVector a, TLorentzVector b) { return a.Pt() > b.Pt(); }


     // (Re-)sort the jets as their pt has changed!
     sort(theJets.begin(), theJets.end(), ComparePt);

Slimming/Thinning suggestions

All variables mentioned above are needed for the baseline calibration, so keep them in your slims.

It is suggested not to thin the jet branches as the entire jet vector will be needed for the estimate of the close-by jets uncertainty (see: JetUncertainties#CloseBy).

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r6 - 2012-12-03 - unknown
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Sandbox All webs login

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