%CERTIFY%

MultijetJESUncertaintyProviderSandbox

Introduction

The MultijetJESUncertaintyProvider is a C++/ROOT compatible class to access the estimate on the JES uncertainty for EM+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.

The current tag is JetUncertainties-00-03-03.

This twiki refers to the latest release 16 MultijetJESUncertaintyProvider. The twiki for release 15 has been moved here.

Extended pT/eta range: The JES uncertainty provided via the MultijetJESUncertaintyProvider is now available for jets of 15 GeV < pT < 7000 GeV and |eta| < 4.5.

Close-by jets uncertainty

Based on the studies detailed in these slides and this CONF note the close-by jets uncertainty has been updated w.r.t. release 15. The final numbers have been updated in JetUncertainties-00-03-03.

Please note: The close-by jets uncertainty is now provided as an uncertainty on the data/MC agreement. As such it is applicable to jets after correcting for the response of close-by jets / after unfolding the data to MC prediction.

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.

To retrieve the close-by jets uncertrainty the distance to the closest reconstructed jet with em scale pT > 7 GeV (= dR_min) has to be specified. Jets are considered as isolated if dR_min > 2.5R (where R=0.4/0.6 depending on the jet size).

Flavour composition uncertainty

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 have not been included so far.

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).

Note: Due to several changes to the analysis input histograms any release 15 input files are NOT compatible with the latest release 16 MultijetJESUncertaintyProvider.

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)

The 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 files JESUncertaintyProvider.h/cxx are required to run the MultijetJESUncertaintyProvider. The uncertainty as given by the MultijetJESUncertaintyProvider already includes the global uncertainty from the JESUncertaintyProvider. Please do not add the uncertainty from the JESUncertaintyProvider on top of the uncertainty provided by 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, ie:
      MultijetJESUncertaintyProvider myJES("myCollectionName","mySampleFile.root");

  • Set "myCollectionName" according to your input collection (currently only EM+JES):

         //AntiKt4 EM+JES calibrated jets:
        "AntiKt4EMJESTopoJets"
         //or
        "AntiKt4H1TopoJets"
         //AntiKt6 EM+JES calibrated jets:
        "AntiKt6EMJESTopoJets"
         //or
        "AntiKt6H1TopoJets"

  • Set "mySampleFile.root" according to the name of the root file with your analysis plots (average response, gluon fraction and gluon fraction uncertainty), see below for further information

  • Initialize the instance:
      myJES.init();

  • To retrieve the JES uncertainty (by default no pile-up term and no close-by jets systematic) of a jet with pT = myPt and Eta = myEta call one of the functions (with pT in MeV):
     myJES.getRelPosUncert(myPt, myEta); // for the relative positive uncertainty
     //or
     myJES.getAbsPosUncert(myPt, myEta); // for the relative positive uncertainty*pT(jet) 
     //or
     myJES.getRelNegUncert(myPt, myEta); // for the relative negative uncertainty
     //or
     myJES.getAbsNegUncert(myPt, myEta); // for the relative negative uncertainty*pT(jet) 

  • To include the pile-up term add it to the list of desired uncertainty components (e.g. MultijetJESUncertaintyProvider::ALL to include all uncertainty components - further information on how to access the various uncertainty components separately can be found here) and specifiy the number of vertices nVtx = myNVtx . The number of vertices should include all vertices (primary vertex + pile-up vertices) with number of tracks N > 4. To also include the close-by jets uncertainty specifiy the distance to the closest jet dR_min= myDR (consider all reconstructed jets with emscale pT>7GeV to calculate dR_min). Call one of the following functions:
     myJES.getRelPosUncert(myPt, myEta, MultijetJESUncertaintyProvider::ALL, myNVtx, myDR);
     //or
     myJES.getAbsPosUncert(myPt, myEta, MultijetJESUncertaintyProvider::ALL, myNVtx, myDR);
     //or
     myJES.getRelNegUncert(myPt, myEta, MultijetJESUncertaintyProvider::ALL, myNVtx, myDR);
     //or
     myJES.getAbsNegUncert(myPt, myEta, MultijetJESUncertaintyProvider::ALL, myNVtx, myDR);

  • According to the procedure described in the JESUncertaintyProvider twiki the user can choose a combination of uncertainty components (as defined in the Components enumerator of the JESUncertaintyProvider base class) to be included into the calculation of the overall JES uncertainty.

Retrieving the uncertainty WITHOUT 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, ie:
      MultijetJESUncertaintyProvider myJES("myCollectionName");

  • Set "myCollectionName" according to your input collection (currently only EM+JES):

         //AntiKt4 EM+JES calibrated jets:
        "AntiKt4EMJESTopoJets"
         //or
        "AntiKt4H1TopoJets"
         //AntiKt6 EM+JES calibrated jets:
        "AntiKt6EMJESTopoJets"
         //or
        "AntiKt6H1TopoJets"

  • Exclude the flavour composition uncertainty (important: this step needs to be done before initializing the provider):
      myJES.includeFlavorComposition(false);

  • Initialize the instance:
      myJES.init();

  • To retrieve the JES uncertainty call one of the getRelPosUncert(...), getAbsPosUncert(...), getRelNegUncert(...), getAbsNegUncert(...) funtions as descriped above. Since the flavour composition uncertainty is excluded, getRelPosUncert(...) and getRelNegUncert(...) (getAbsPosUncert(...) and getAbsNegUncert(...)) will give the same result.

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 < 500 GeV and |eta| < 4.5. If the jet pT/eta is outside this range, the following errors will be printed and the relative uncertainty returned will be -1 (the absolute uncertainty will just be the negative pT).

    pT outside of covered range (15-7000): Returning -1
    Eta outside of covered range (0.0<|eta|<4.5): Returning -1

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!

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

For the full tag history, see JESUncertaintyProvider#TagHistory

JetUncertainties-00-01-03 - DO NOT USE THIS TAG! - Introduced MultijetJESUncertaintyProvider

JetUncertainties-00-02-00 - Current tag for release 15 - JESUncertaintyProvider: Updated JES uncertainty for May reprocessed data; MultijetJESUncertaintyProvider: Removed flavour response term

JetUncertainties-00-03-00 - DO NOT USE THIS TAG! - JESUncertaintyProvider: Updated JES uncertainty for full 2010 ATLAS data; MultijetJESUncertaintyProvider: Updated flavour composition uncertainty for release 16, preliminary numbers for updated close-by jets uncertainty

JetUncertainties-00-03-03 - MultijetJESUncertaintyProvider: Updated flavour composition uncertainty for release 16, updated numbers for close-by jets uncertainty according to ATLAS-CONF-2011-062


Major updates:
-- StefanieAdomeit - 13-Dec-2010

%RESPONSIBLE% CaterinaDoglioni
%REVIEW% Never reviewed

-- CaterinaDoglioni - 28-Apr-2011

Edit | Attach | Watch | Print version | History: r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r1 - 2011-04-28 - CaterinaDoglioni
 
    • 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