MultijetJESUncertaintyProviderSandbox < Sandbox

<!-- This is the default ATLAS template. 
Please modify it in the sections indicated to create your topic! In particular, notice that at the bottom there are some sections that must be filled for publicly accessible pages.
If you have any comments/complaints about this template, then please email : Patrick Jussel (patrick dot jussel at cern dot ch) and/or Maria Smizanska (maria dot smizanska at cern dot ch)--> 

<!-- By default the title is the WikiWord used to create this topic !-->
<!-- if you want to modify it to something more meaningful, just replace %TOPIC% below with i.e "My Topic"!-->
<!---------------------------------------------------------  snip snip ----------------------------------------------------------------->
%CERTIFY%
---+!!<nop>%TOPIC% 



%TOC%     <!--optional-->
%STARTINCLUDE%
---+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 [[Rel15MultijetJESUncertaintyProvider][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 [[https://indico.cern.ch/getFile.py/access?contribId=2&resId=0&materialId=slides&confId=127422][these slides]] and [[http://cdsweb.cern.ch/record/1345091][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.

%RED%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. %ENDCOLOR% 

*Note*: As recommended in [[https://indico.cern.ch/getFile.py/access?contribId=2&resId=0&materialId=slides&confId=127422][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
#FlavComp
The basic ideas underlying the estimate on the flavour composition contribution to the JES uncertainty are described in [[http://indico.cern.ch/getFile.py/access?contribId=3&resId=0&materialId=slides&confId=95052][these slides]], [[http://indico.cern.ch/getFile.py/access?contribId=8&sessionId=1&resId=0&materialId=slides&confId=102861][these slides]] and this [[http://cdsweb.cern.ch/record/1342550][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 [[MJESInputGraphs][here]] (in case you want to use the !MultijetJESUncertaintyProvider without the flavour composition contribution as describe [[#RetrieveDefaultUncertWithout][below]] you do not have to provide such an input file, of course).

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

---+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
#UsingTheProvider
---++Retrieving the uncertainty WITH the flavour composition contribution
#RetrieveDefaultUncertWith
First of all, follow the [[#CheckingOutCode][instructions]] on checking out the code and preparing your work area.

   * Create an instance of the !MultijetJESUncertaintyProvider, ie:
<verbatim>
      MultijetJESUncertaintyProvider myJES("myCollectionName","mySampleFile.root");
</verbatim>

   * Set ="myCollectionName"= according to your input collection (currently only *EM+JES*):
   
<verbatim>
         //AntiKt4 EM+JES calibrated jets:
        "AntiKt4EMJESTopoJets"
         //or
        "AntiKt4H1TopoJets"
</verbatim>
<verbatim>
         //AntiKt6 EM+JES calibrated jets:
        "AntiKt6EMJESTopoJets"
         //or
        "AntiKt6H1TopoJets"
</verbatim>

   * Set ="mySampleFile.root"= according to the name of the root file with your analysis plots (average response, gluon fraction and gluon fraction uncertainty), see [[#RequiredInputGraphs][below]] for further information 
 
   * Initialize the instance:
<verbatim>
      myJES.init();
</verbatim>

   * 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*):
<verbatim>
     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) 
</verbatim>

   * 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 [[https://twiki.cern.ch/twiki/bin/view/AtlasProtected/JESUncertaintyProvider#Accessing_the_various_uncertaint][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:
<verbatim>
     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);
</verbatim>


   * According to the procedure described in the  [[https://twiki.cern.ch/twiki/bin/view/AtlasProtected/JESUncertaintyProvider#Accessing_the_various_uncertaint][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
#RetrieveDefaultUncertWithout

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

   * Create an instance of the !MultijetJESUncertaintyProvider, ie:
<verbatim>
      MultijetJESUncertaintyProvider myJES("myCollectionName");
</verbatim>

   * Set ="myCollectionName"= according to your input collection (currently only *EM+JES*):
   
<verbatim>
         //AntiKt4 EM+JES calibrated jets:
        "AntiKt4EMJESTopoJets"
         //or
        "AntiKt4H1TopoJets"
</verbatim>
<verbatim>
         //AntiKt6 EM+JES calibrated jets:
        "AntiKt6EMJESTopoJets"
         //or
        "AntiKt6H1TopoJets"
</verbatim>

   * Exclude the flavour composition uncertainty (*important*: this step needs to be done *before* initializing the provider):
<verbatim>
      myJES.includeFlavorComposition(false);
</verbatim>

   * Initialize the instance:
<verbatim>
      myJES.init();
</verbatim>

   * To retrieve the JES uncertainty call one of the getRelPosUncert(...), getAbsPosUncert(...), getRelNegUncert(...), getAbsNegUncert(...) funtions as descriped [[#RetrieveDefaultUncertWith][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). 

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

---++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:
<verbatim>
    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!
</verbatim>

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:
<verbatim>
    Problem finding Required Input Graph responseSample_AntiKt4Topo_EMJES in input file mySampleFile.root! Setting response_sample/r_incl = 1!
</verbatim>

---++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 ([[http://indico.cern.ch/getFile.py/access?contribId=8&sessionId=1&resId=0&materialId=slides&confId=102861][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:
<verbatim>
    gluon fraction = 0/1: setting alphaC = 1 to avoid division by zero!
</verbatim>

   * 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=:
<verbatim>
    Problem finding Required Input Graph: gluonFractionError_AntiKt4TopoJetsJES in input file mySampleFile.root
    Not enough information to calculate prefactor alphaC: Setting alphaC = 1!
</verbatim>


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

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


<!--***********************************************************-->
<!--Do NOT remove the remaining lines, but add requested info as appropriate-->
<!--***********************************************************-->

-----
<!--For significant updates to the topic, consider adding your 'signature' (beneath this editing box)-->
*Major updates*:%BR%
-- Main.StefanieAdomeit - 13-Dec-2010

<!--Please add the name of someone who is responsible for this page so that he/she can be contacted if changes are needed.
The creator's name will be added by default, but this can be replaced if appropriate.
Put the name first, without dashes.-->
%RESPONSIBLE% %REVINFO{"$wikiusername" rev="1.1"}% %BR%
<!--Once this page has been reviewed, please add the name and the date e.g. Main.StephenHaywood - 31 Oct 2006 -->
%REVIEW% *Never reviewed*

%STOPINCLUDE%


-- Main.CaterinaDoglioni - 28-Apr-2011
Topic revision: r1 - 2011-04-28 - CaterinaDoglioni
Account
- Log In
- Cern Search
- TWiki Search
- Google Search
Sandbox All webs
Edit
Attach
Copyright &© 2008-2021 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