*JESUncertaintyProvider*

JoeTaenzerSandbox

JES Uncertainty Provider Usage Instructions

This page contains only the basic instructions for checking out, compiling, and running the JES Uncertainty Provider. For more specific recommendations, please refer to the twiki page relevant to your needs:

How to use the JESUncertaintyProvider

 

About the JESUncertaintyProvider

Introduction

The JESUncertaintyProvider is a C++/ROOT compatible class to access the current estimate of the uncertainty on the Jet Energy Scale for the full 2011 dataset in R17. The uncertainty is valid for AntiKt4/6 jets calibrated with EM+JES and LC+JES calibration schemes, with pile-up correction and additional in-situ calibration described in

https://twiki.cern.ch/twiki/bin/viewauth/AtlasProtected/JetCalibrationToolsWinter2011#Instructions_on_how_to_use_the_j

using tag 00-07-00 of the ApplyJetCalibration package.

The estimate of the JES uncertainty is based on Monte-Carlo studies and in-situ measurements as described in these slides and it will be documented in an upcoming CONF note.

Further information on the MultijetJESUncertaintyProvider, the tool that should be used for uncertainties in topologies and flavour that are different from those used to derive the JES calibration can be found on this twiki. Analyses should use this class in order to include all uncertainty sources.

Instructions for use

Checking out the code and preparing your work area:

Set up your ATHENA work area as usual, and check out the ATHENA package Reconstruction/Jet/JetUncertainties:

cmt co -r JetUncertainties-00-07-00 Reconstruction/Jet/JetUncertainties
or
svn co $SVNOFF/Reconstruction/Jet/JetUncertainties/tags/JetUncertainties-00-07-00 JetUncertainties

Prepare your work area and code for ROOT/C++ analysis

The JESUncertaintyProvider/MultijetJESUncertaintyProvider base classes are ROOT/RootCore-compatible.

The .root file with the uncertainty plots (JESUncertainty_Preliminary.root) is located in the share/ directory.

Instructions for RootCore

The JetUncertainties package can be compiled within RootCore:

https://twiki.cern.ch/twiki/bin/viewauth/Atlas/RootCore#Setting_up_RootCore

Standalone instructions

The whole package can also be compiled into a standalone C++ library with the Makefile.Standalone provided in the cmt/ directory:

make -f Makefile.Standalone

The final library will be located in:

JetUncertainties/StandAlone/libJetUncertainties.so

and can be linked in your analysis executable or used in your ROOT session with gSystem->Load("(/StandAlone/libJetUncertainties.so"). This library can also be used in pyROOT.

Prepare your work area and code for Athena analysis

In the requirements file of your package, add the line:

use JetUncertainties            JetUncertainties-*              Reconstruction/Jet

Include the JESUncertaintyProviderAthena header file in your ATHENA algorithm/tool header.

#include "JetUncertainties/JESUncertaintyProviderAthena.h"

Use as detailed below.

Using the JESUncertaintyProvider

The main change in accessing the uncertainty with respect to the R16 (tags 00-03-04/05-01) is that the individual sources of the systematic uncertainties (nuisance parameters) can be retrieved separately in the JESProvider. The complete list of nuisance parameters can be found in the JESUncertainty2011NuisanceParameters page. The total uncertainty can still be retrieved, but this will not contain any information about the bin-to-bin correlations in pT.

Initialising the JESUncertaintyProvider

Please see the twiki page relevant to your needs:

Configuration files

The configuration file (e.g. InsituJES2011_AllNuisanceParameters.config) contains the full list of nuisance parameters that will be used by the instance of the the JESUncertaintyProvider. These are the nuisance parameters that:

  • are read in by the code
  • are added in quadrature when asking for the total uncertainty using the functions getRelUncert/getAbsUncert
  • can be accessed separately using the function getRelUncertComponent.

As explained in this presentation, configurations with a reduced number of nuisance parameters that still mantain reasonable correlation information are now available.

The full set of NP has been used to compute the original covariance matrix. The covariance matrix has then been diagonalized to obtain the eigenvectors and the corresponding eigenvalues. We obtain the final (reduced) set of NP from the eigenvectors with the largest N corresponding eigenvalues (with N=6, 9 for this tag). The remaining nuisance parameters are then merged in the last nuisance parameter, which should not be profiled and ideally would need to be considered as uncorrelated to better reproduce the original covariance matrix . For the time being and for these tests, all nuisance parameters can be treated as correlated, and if your analysis is profiling then more care needs to be taken.

The suggested default is the configuration containing 6 in-situ nuisance parameters as differences in correlations with respect to the full nuisance parameter configuration are below 10%. The total number of nuisance parameters is 11 when considering the remaining uncertainties not coming from the in-situ combination. This is reflected in the name of the configuration InsituJES2011_11NP_Preliminary.config.

This configuration is described in detail on this page and can be found in SVN here. In order to use this configuration, follow the same instructions as explained in this page that apply to the full-nuisance-parameter configuration, making sure the provider is initialised with the InsituJES2011_11NP_Preliminary.config file that can be found in the share/ directory of the JetUncertainties package.

Configuration files: more information

Depending on your setup, you might have to softlink the configuration and root files in the share/ directory to the directory where you're running.

Important note: In most cases, users will not have to deal with the configuration files as they will be provided centrally - send an e-mail to atlas-cp-jet-calibration AT cern.ch for questions on your specific use case.

Nuisance parameters can also be combined as in the example in InsituJES2011_Option2.config.

Retrieving the total uncertainty in C++/Athena code

To retrieve the JES uncertainty for a jet with pT = myPt and Eta = myEta (by default including the pile-up term):

  • Call one of the functions below, with pT being the default, calibrated jet transverse momentum that is in MeV by default, and myEta the detector pseudorapidity.
     j.getRelUncert(myPt, myEta, NPV, mu); // for the fractional uncertainty
     //or
     j.getAbsUncert(myPt, myEta, NPV, mu); // returns the absolute uncertainty, i.e. "relative uncertainty" * pT(jet) 

  • Note: As explained below, some of the components have been derived using the calibrated pseudorapidity, but at first order the two are equivalent in the central region. If you are using jets beyond eta=2.8 it would be better to split the uncertainty in components in order to have the correct treatment in the calorimeter transition region where detector eta and calibrated eta have differences of up to 15%.

  • Note 2: By default the JES provider assumes that the jet pT is in MeV, if you wish to use GeV, call useGeV(true)

  • Note 3: It is recommended to consider the pile-up uncertainty separately (see below). To access the JES uncertainty without the pile-up term, use:
     j.getRelUncert(myPt, myEta); // for the fractional uncertainty, excluding pile-up

Accessing the various uncertainty components for the baseline uncertainty separately

Each component of the baseline uncertainty except the pile-up ones can be accessed separately via any of the getRelUncertComponent methods:

     j.getRelUncertComponent(componentName, myPt, myEta); 
     j.getRelUncert(componentIndex, myPt, myEta); // componentIndex is an integer. See example below.

(with pT being the default, calibrated jet transverse momentum that is in MeV by default, and myEta is either the detector pseudorapidity or the calibrated (final) pseudorapidity):

* the parameter componentName needs to correspond to that of the nuisance parameter in the configuration file, e.g. Zjet_MC for the uncertainty due to changing the MC generator in the Z+jet analysis, or one of the effective nuisance parameters.

The list of baseline components except for pile-up can be also iterated on using the combination of functions getNUncertaintyComponents (returns the total number of uncertainty components) and getComponentNames (returns a std::vector with the component names):


int Ncomp=j.getNUncertaintyComponents();

for (int icomp=0;icomp<Ncomp;++icomp) {

  TString compName = j.getComponentNames().at(icomp); // returns the name of the nuisance parameter
  TString compDesc = j.getComponentDescriptions().at(icomp); // returns a one-sentence description of the nuisance parameter
  double unc = j.getRelUncertComponent(icomp, myPt, myeta); // nuisance paramter amplitude ("relative uncertainty" of component) 
  // can also use  j.getRelUncertComponent(compName, myPt, myeta);

  // print the uncertainty and information
  printf("JES uncertainty source %2d: %s\n",icomp,compName.Data());  
  printf("Description : %s\n",compDesc.Data());
  printf("The uncertainty for (pT,eta) = (%.1f,%5.1f) is %.1%%\n",myPt,myeta,unc*100);

}

Pile-up uncertainty

Given that the pile-up correction has been derived with respect to certain reference values of NPV and mu, the sign of the pile-up uncertainty is important and should be kept when propagating the NPV/mu-dependent uncertainty through the analysis. One should then envisage four 'runs' of the analysis to keep track of these correlations, one for each one-sigma upwards and downwards deviations of mu and NPV. As an example for NPV (it's the same for mu), one should shift NPV one-sigma up by doing for each jet in the analysis:

  double shift = j->getRelNPVOffsetTerm(jet.Pt(),jet.Eta(),NPV);
  jet *= (1.0+shift);

and repeat the analysis with the downwards shift:

  double shift = j->getRelNPVOffsetTerm(jet.Pt(),jet.Eta(),NPV);
  jet *= (1.0-shift);

this will correctly keep track of the sign of the uncertainty. Note the same should be done also for the μ-dependent component, which is accessed by j>getRelMuOffsetTerm(jet.Pt(),jet.Eta(),mu).

Treatment of detector and calibrated pseudorapidity.

In a thread with Jean-Baptiste Sauvan and Jim Lacey, we have clarified the use of detector vs calibrated pseudorapidity in the JESUncertaintyProvider and MultijetJESUncertaintyProvider.

The detector pseudorapidity should be used for the in-situ and pile-up uncertainty, while the calibrated pseudorapidity should be used for the MC-based uncertainties (non-closure, flavor, topology).

At first order the two eta values are very similar, except for the transition region between HEC and FCal where we have the biggest eta correction (up to 15% as found by Jim). The eta intercalibration uncertainty would therefore be the component that is most affected.

For this reason it would be better to distinguish the in-situ and intercalibration components (identified by the string InSitu or Effective and EtaIntercalibration respectively) and the other uncertainties in the loop on the uncertainties detailed above. For the former, the pseudorapidity used should be the detector eta, corresponding to the branch jet_AntiKt4TopoEM_emscale_eta or jet_AntiKt4LCTopo_constscale_eta. For the latter, the calibrated eta should be used, corresponding to the branch jet_AntiKt4TopoEM_eta or jet_AntiKt4LCTopo_eta.

However, there is an eta interpolation built in the providers, so even a 15% change in where eta is picked shouldn't make a large difference in the magnitude of the uncertainties.

Notes and known issues

JES uncertainty for jets with pT in the 15-20 GeV bin

The first 15-20 GeV bin where the uncertainty is provided might suffer from biases due to the jet calibration and reconstruction threshold cut for low pT jets. More informations below and in this hypernews thread.

Uncertainty provided down to pT(jet) = 15 GeV

The JES uncertainty is provided down to 15 GeV. The estimate from 15 to 20 GeV has to be used with caution (~only for fluctuating pseudoexperiments ) because:

  1. the EM+JES calibration are constants only calculated down to 10 GeV at EM (LC) scale, which corresponds to about 20 (15) GeV at calibrated scale.
  2. in-situ measurements only go down to 17 TeV
  3. (relevant for the non-closure term) the 7 GeV reco jet cut is the jet reconstruction threshold --> there are possible threshold effects
  4. (relevant for the non-closure term) the presence of very different weights in this bin (all the JX can radiate down here, but the hard scattering is provided by J0, and this has a weight many orders of magnitude higher than the higher JX samples) generally leads to fits that are not well constrained if using QCD dijets.

Uncertainty outside the range

The JES uncertainty for jets outside the range of the current estimate (15-2500 GeV, |\eta|<4.5) is the same uncertainty as jets at the boundary. E.g. a 14 GeV jet will have the same uncertainty as a 15 GeV jet, a 3000 GeV jet will get the same uncertainty as a 2500 GeV jet, and same will happen for jets with eta > 4.6 -> eta=4.5).

Old versions of the code

The JESUncertaintyProvider for release 16 can be found here.

The JESUncertaintyProvider for release 15 can be found here.

Tag History

Whenever the uncertainty changes, it will be notified here with the label 'UNCERTAINTY UPDATE'. Changes are also communicated on the JetEtMiss hypernews. A full list of the changes in each tag can be seen in the SVN package Changelog. Here are reported only the tags that are in use by current analyses, for full tag history related to older versions of the code please have a look in the old versions of the code.

JetUncertainties-00-07-00 - Current tag: ??

JetUncertainties-00-06-04 - ??

JetUncertainties-00-05-10 - Fixed full nuisance parameter configuration file. Note that there are no changes wrt tag JetUncertainties-00-05-09 unless you were using the InsituJES2011_AllNuisanceParameters.config configuration file to initialise the tool.

JetUncertainties-00-03-07 - JES uncertainty for R16, including the LC pile-up uncertainties

Credits

Code by Caterina Doglioni, Dag Gillberg and Pier-Olivier DeViveiros. Uncertainties components provided by Bogdan Malaescu, Dag Gillberg, Caterina Doglioni, John Backus Mayes, Carlos Sandoval, Giovanni Zevi Della Porta, Peter Manning, Toshi Sumida, Fabrice Balli, Stefanie Adomeit, Attilio Picazio, Jiri Kvita, Lucy Kogan, Francesc Vives, Jean-Baptiste Sauvan, Jean-Francois Grivaz, Andres Tanaszjcuk, Koji Terashi, James Lacey

Low-lying bug reports/Comments/suggestions to Caterina Doglioni and Dag Gillberg


Major updates:
-- CaterinaDoglioni - 10-Jun-2010

%RESPONSIBLE% JoeTaenzer
%REVIEW% Never reviewed

*MultijetJESUncertaintyProvider*

%CERTIFY%

JoeTaenzerSandbox

Multijet JES Uncertainty Provider Usage Instructions

This page contains only the basic instructions for checking out, compiling, and running the Multijet JES Uncertainty Provider. For more specific recommendations, please refer to the twiki page relevant to your needs:

How to use the MultijetJESUncertaintyProvider

 

About the MultijetJESUncertaintyProvider

Introduction

The MultijetJESUncertaintyProvider is a C++/ROOT compatible class to access the estimate on the JES uncertainty for EM+JES/LC+JES calibrated jets in multi-jet environments. The uncertainty provided via the MultijetJESUncertaintyProvider includes the global JES uncertainty from the JESUncertaintyProvider as well as two additional terms accounting for flavor composition and close-by jets effects.

Close-by jets uncertainty (Preliminary 2011 estimate)

The technique to evaluate the close-by jet uncertainty is detailed in these slides and this CONF note. The estimate has been updated for 2011 data and MC, and it will be documented in the multijet balance CONF note (link to CDS will be added once available). The use of isolated jets as a baseline is justified by in-situ analyses: the cut on third jet radiation is effectively acting as an isolation cut.

Please note: The close-by jets uncertainty is now provided as an uncertainty on the data/MC agreement. As such it does not cover for effects on the absolute jet energy scale due to the presence of close-by jets.

Note: As recommended in slide 15 of this talk each analysis should check whether the provided numbers for the close-by jets uncertainty are applicable to their analysis sample.

Flavour composition uncertainty (Preliminary 2010 estimate, validated with 2011 MC)

The basic ideas underlying the estimate on the flavour composition contribution to the JES uncertainty are described in these slides, these slides and this CONF note. Currently, the flavour composition term only accounts for gluon and light quark jets - b-jets are not included in this uncertainty source and they are considered below.

Since the flavour composition uncertainty is an analysis specific term depending on the fraction of gluon initiated jets, the uncertainty assigned to the gluon fraction and the average response of jets in the analysis sample of interest an additional input .root file containing these values has to be provided. For testing purpose you can use one of the example input files located in the analysisPlots/ directory of the package. Further information on the required analysis input plots can be found here (in case you want to use the MultijetJESUncertaintyProvider without the flavour composition contribution as describe below you do not have to provide such an input file, of course).

Flavour response uncertainty (Preliminary 2011 estimate)

The reason for the flavor response uncertainty is detailed in the the presentations linked above under the flavor composition uncertainty. For the 2011 insitu measurements, the most precise methods to set the JES using gamma+jet and Z+jet, have a large fraction of quark jets. Initial studies based on track jet/calorimeter jet momentum ratios indicate that the gluon jet response is slightly underestimated by Pythia (unlike the response in Z/gamma+jet).

The uncertainty is evaluated by taking the difference in gluon response between Pythia and Herwig++, scaled by the fraction of gluons in the analysis.

Note in the testing version of the 2011 JES (JetUncertainties-00-05-00 up and including 00-05-06), an additional uncertainty of 2% is assigned to gluon jets to account for this flavor response uncertainty. This uncertainty is taken as uncorrelated with respect to the flavor composition uncertainty. The magnitude of this uncertainty is read as fixed value in via the configuration file.

bJES uncertainty (2010 estimate)

The preliminary b-jet energy scale uncertainty is estimated using MC systematic variations in MC10 (from 2010, analysis for the 2011 dataset is in progress). It should be applied to MC jets matched to B hadrons.

BJESUncertainty_noATLASLabel.png

The interplay between the flavor composition/response and the b-jet JES uncertainties has been somewhat simplified in the provider, since a full treatment is not possible on a jet-by-jet basis. If the jet is known to be a b-jet (only possible in Monte Carlo), the flavor composition and response systematics are not applied. The inputs to the flavor composition and response (fraction of gluon jets and error on that) should be, thus, calculated ignoring the b-jets in your sample (that is, if your sample is 80% b-jets,12% light-quark jets and 8% gluon jets, your fraction of quark jets in 60%, and of gluons 40%). This is what the MultijetJESProvider (and existing analysis files) do by default.

This is approximative, because it does not take into account that there might be an uncertainty in the fraction of b-jets arising, for instance, from the uncertainty on the b-tagging scale factors when propagating uncertainties from b jets in data. This effect can be small or big, increase or decrease the systematic uncertainty, depending on the analysis, and it should be estimated by each analysis. One way of estimating it is to vary the scale factors and the JES in a correlated way, and compare how much the JES systematic changes with respect to the nominal case. This should be the correct way of doing it, unless other correlations with other components of the JES systematic are more important. Dedicated studies can be performed to understand which correlations are important and which can be ignored for a given analysis.

Another issue with this approach is that it requires truth information about the identity of the b-jet. This cannot be performed in analyses applying the systematic uncertainties in the data. However, analyses propagating the bJES uncertainty from data should verify the effects of the JES uncertainties also in the MC, since variations of the b-tagging efficiency across pT can cause large differences between the right systematic and that obtained applying the b-jet JES systematic to tagged jets.

Checking out the code and preparing your work area:

Follow the instructions on JESUncertaintyProvider#CheckingOutCode for checking out and setting up the package, that includes MultijetJESUncertaintyProvider, for both the ROOT standalone version and the ATHENA version. In both cases, include the MultijetJESUncertaintyProvider header in your code (that already includes the JESUncertaintyProvider header).

ROOT standalone version: The input file JESUncertainty.root located in the share/ directory of the package needs to be in the same directory where the MultijetJESUncertaintyProvider is run. If you want to retrieve the uncertainty with the flavor composition contribution included you also need to copy the input file containing the analysis sample specific plots into the directory where the provider is run.

Note: The class JESUncertaintyProvider.h/cxx is required to run the MultijetJESUncertaintyProvider. The uncertainty as given by the MultijetJESUncertaintyProvider already includes the uncertainty from the JESUncertaintyProvider. Please do not add the uncertainty from the JESUncertaintyProvider on top of the uncertainty provided via the MultijetJESUncertaintyProvider!

Using the MultijetJESUncertaintyProvider

Retrieving the uncertainty WITH the flavour composition contribution

First of all, follow the instructions on checking out the code and preparing your work area.

  • Create an instance of the MultijetJESUncertaintyProvider with the MultijetJESProvider configuration file, the JESProvider configuration file containing all nuisance parameters, the collection name and the MC type, like:

      MultijetJESUncertaintyProvider j("MultijetJES_Preliminary.config","InsituJES2011_AllNuisanceParameters.config","AntiKt6TopoEM","MC11b");

For other uncertainty configurations with fewer nuisance parameters and details on the MC type, see the JESUncertaintyProvider twiki.

  • Set "myCollectionName" according to your input collection:
    • EM+JES: AntiKt4EMJESTopoJets / AntiKt6EMJESTopoJets
    • LC+JES: AntiKt4LCTopoJets / AntiKt6LCTopoJets

  • Set the location of the input files in the configuration file MultijetJES.config:

MultijetJESUncertaintyRootFile:     ../share/MJESUncertainty.root
AnalysisRootFile:            ../analysisPlots/UnknownFlavourComp.root

The AnalysisRootFile parameter is the name of the root file with your analysis plots (average response, gluon fraction and gluon fraction uncertainty), while the MultijetJESUncertaintyRootFile is the name of the root file found in the share directory of the JetUncertainties package.

    double MultijetJESUncertaintyProvider::getRelUncert(double pT, double Eta, double dRmin, bool isUp, double NPV, double mu, bool isBJet)

  • pT and Eta are the calibrated (after ApplyOffsetEtaJES) transverse momentum and pseudorapidity of the jet
  • dRMin is the distance in deltaR (eta/phi space) of the closest reconstructed jet with jet_emscale_pt > 7 GeV
  • NPV and mu are the number of primary vertices and average number of interactions retrieved as explained in the calibration twiki
  • isUp is a bool (true/false) that indicates whether the uncertainty requested is positive or negative.
  • isBJet is a bool (true/false) indicating whether the reco jet is matched to a B hadron.

Note: As explained on the JESUncertaintyProvider twiki (under "Treatment of detector and calibrated pseudorapidity"), some of the components have been derived using the calibrated pseudorapidity, but at first order the two are equivalent in the central region. If you are using jets beyond eta=2.8 it would be better to split the uncertainty in components in order to have the correct treatment in the calorimeter transition region where detector eta and calibrated eta have differences of up to 15%. MultijetJESUncertaintyProvider components should all be used with calibrated eta.

Retrieving the separate uncertainty components (close-by / flavor)

The MultijetJESUncertaintyProvider contains four additional sources of uncertainty that deal with jet topology and flavor, and need to be added in quadrature on top of the baseline uncertainties contained in the JESUncertaintyProvider. The getRelUncert function already does the addition in quadrature, and this section describes how to access the separate components of the MultijetJESUncertaintyProvider to preserve uncertainty shape information and bin-to-bin correlations. Further information on the various uncertainty components for the baseline can be found here.

How to obtain the close-by jet uncertainty

To retrieve the close-by jets uncertainty the distance to the closest reconstructed jet with em scale pT > 7 GeV (= dR_min) has to be specified. For this preliminary estimate the dRMin parameter is only used coarsely as there is no clear dependence of the uncertainty with the distance with respect to the closest jet.

Jets are considered as isolated if dR_min > 0.8 / 1.0 (for R=0.4/0.6 respectively), but in order to avoid a sharp unphysical transition the uncertainty decreases linearly from dRMin=1.0 onwards and becomes completely negligible at around dR_min = 1.5.

Once the MultijetJESProvider has been initialised as above, retrieve the uncertainty by calling the function

double MultijetJESUncertaintyProvider::getRelClosebyUncert(double pT, double dRmin) 

where pT is the calibrated (after in-situ calibration in case of data, after offset correction in case of MC) transverse momentum of the jet in question and dRMin is the distance to the closest reconstructed jet with EM scale pT > 7 GeV. The corresponding variable in D3PDs is called jet_emscale_pt (where the jet prefix will depend on the specific D3PD used).

How to obtain the flavor composition uncertainty

Once the MultijetJESProvider has been initialised as above (and, if you have them available, you have specified the analysis-specific input files), retrieve the flavor composition uncertainty by calling the functions:

double MultijetJESUncertaintyProvider::getRelFlavorCompUncert(double pT, double eta, bool isUp) 

where pT and eta are the calibrated (after in-situ calibration in case of data, after offset correction in case of MC) transverse momentum and pseudorapidity of the jet in question and isUp is a bool that specifies whether the uncertainty corresponds to the one-sigma upwards or downwards variation.

important note This uncertainty should not be applied to b jets. The MultijetJESProvider already does this in the method to access the total uncertainty.

How to obtain the flavor response uncertainty

Once the MultijetJESProvider has been initialised as above (and, if you have them available, you have specified the analysis-specific input files), retrieve the flavor composition uncertainty by calling the function:

double MultijetJESUncertaintyProvider::getRelFlavorResponseUncert(double pT, double eta) 

where pT and eta are the calibrated (after in-situ calibration in case of data, after offset correction in case of MC) transverse momentum and pseudorapidity of the jet in question.

important note This uncertainty should not be applied to b jets. The MultijetJESProvider already does this in the method to access the total uncertainty.

How to obtain the b-JES uncertainty

Once the MultijetJESProvider has been initialised as above (and, if you have them available, you have specified the analysis-specific input files), retrieve only the bJES uncertainty by calling the function:

double MultijetJESUncertaintyProvider::getRelBJESUncert(double pT, double eta) 

for jets matched to a B hadron only (i.e. do not do this for all jets). pT and eta are the calibrated (after in-situ calibration in case of data, after offset correction in case of MC) transverse momentum and pseudorapidity of the jet in question. For the time being, the pseudorapidity is not used but kept as a parameter for future iterations, and the uncertainty has been derived for AntiKt R=0.4 jets calibrated using the EM+JES scheme only, and propagated as is to other jet distance parameter/calibrations.

important note This uncertainty should be applied to b jets only, as an alternative to the flavor response and composition uncertainties for other jets (meaning, if you apply this uncertainty to a b-jet you should not also apply the flavor composition and response uncertainties).

Some information on the analysis specific input files

To reduce the flavour composition and response uncertainty analysers should provide an input file specifying the gluon fraction (uncertainty) and average jet response in their samples (signal + background samples after analysis cuts!).

As indicated on slide 4 of this talk one should use the unknown flavour composition file below for samples with no input files available:

This assumes a flat gluon fraction contribution of 50%+-50%. The resulting flavour composition uncertainty is about half of the size of the difference in light quark and gluon jet response (see the plots below).

To reduce this uncertainty analysers are encouraged to produce their own input files. There is work ongoing in providing some code to evaluate all the relevant input histograms required for the flavour composition uncertainty - please contact stefanie.adomeit AT cern.ch and caterina.doglioni AT cern.ch for further information.

Overview over possible errors and print-outs

pT/eta outside of covered range

The MultijetJESUncertaintyProvider returns a JES uncertainty of jets within 15 GeV < pT < 7000 GeV and |eta| < 4.5. If the jet pT/eta is outside this range, warning messages will be printed and the relative uncertainty returned will be the closest to the limit.

Response of jets in the analysis sample

  • If the ratio response_sample/r_incl as provided in the analysis input file isn't within a reasonable range, i.e. smaller than response_gluons/r_incl or larger than response_quarks/r_incl the following warnings will be printed:
    analysis sample response larger than light quark jet response: setting response(sample)/r_incl = response(light quarks)/r_incl --> Check input graph responseSample in file mySampleFile.root!
    analysis sample response smaller than gluon jet response: setting response(sample)/r_incl = response(gluons)/r_incl --> Check input graph responseSample in mySampleFile.root!

The provider will then set response_sample/r_incl = response_gluons/r_incl / response_sample/r_incl = response_quarks/r_incl and proceed with the calculation of the JES uncertainty.

  • If the response graph isn't available in the input .root file, the MultijetJESUncertaintyProvider will set response_sample/r_incl = 1 and proceed with the calculation of the uncertainty:
    Problem finding Required Input Graph responseSample_AntiKt4Topo_EMJES in input file mySampleFile.root! Setting response_sample/r_incl = 1!

Gluon fraction / gluon fraction uncertainty

Depending on the provided gluon fraction and gluon fraction uncertainty the MultijetJESUncertaintyProvider calculates a prefactor alphaC which is required for the calculation of the flavour composition uncertainty (see slides 6-8).

  • The prefactor alphaC is calculated according to 1/(gluon fraction) (if positive uncertainty is requested) and 1/(1-gluon fraction) (if negative uncertainty is requested). If the gluon fraction is 0 or 1 the following messages will be printed:
    gluon fraction = 0/1: setting alphaC = 1 to avoid division by zero!

  • Both the gluon fraction and gluon fraction uncertainty graph have to be available in the input .root file. If one or both of them is/are missing the provider will set alphaC = 1:
    Problem finding Required Input Graph: gluonFractionError_AntiKt4TopoJetsJES in input file mySampleFile.root
    Not enough information to calculate prefactor alphaC: Setting alphaC = 1!

Old versions of the code

The Rel16MultijetJESUncertaintyProvider for release 16 can be found here.

Tag History (only updates in the close-by/flavour uncertainty relevant to the MultijetJESUncertaintyProvider)

For the full tag history, see JESUncertaintyProvider#TagHistory

JetUncertainties-00-05-10 - Current tag: ??

JetUncertainties-00-06-04 - ??

JetUncertainties-00-05-10 - Fixed full nuisance parameter configuration file. Note that there are no changes wrt tag JetUncertainties-00-05-09 unless you were using the InsituJES2011_AllNuisanceParameters.config configuration file to initialise the tool.

Credits

The MultijetJESUncertaintyProvider is mantained by Stefanie Adomeit, with help from Dag Gillberg and Caterina Doglioni.


Major updates:
-- CaterinaDoglioni - 14-May-2012

%RESPONSIBLE% JoeTaenzer
%REVIEW% Never reviewed

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r3 - 2012-09-29 - JoeTaenzer
 
    • 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