Common Analysis Framework

This website provides online documentation for the Common Analysis Framework, an extensive common, ROOT-based framework targeted at histogramming, nTuple and xAOD analysis with bindings to C++ and python. As the framework itself, it is constantly under developement.

Type your search query here to search the documentation with Google!

You can access further documentation under the following links:

• Documentation of Tags and Options: html
• Documentation of environment variables read by CAF: html
• Documentation of SFramework Actions: html/src
• Documentation of observables: html
• Relatively Recent Past Tutorials: CAF Tutorial 2024 CAF Tutorial 2021 (in the HWW workshop) CAF Tutorial 2020 CAF Tutorial 2018
• Older Tutorials: HWW Workshop 2016 Tutorials from 2014 and 2015: Introductory Tutorial (12/2014), Observable Tutorial (4/2015)

This section contains a number of frequently asked questions:

• How do I compile the library?
  Download the code, setup a recent RootCore release and type rc find_packages, followed by rc compile.
• What is $TQPATH?
  The string $TQPATH is used as a placeholder for the full path to the trunk of your local framework installation.
• How do I load the library in ROOT?

  From a shell, you may call

  root -l

  .L <PATH>/libQFramework.so

  at any time, where <PATH> is a placeholder for the path at which your compiled library resides. This is the lib subfolder of your checkout directory in a standalone setup, or $ROOTCOREBIN/obj/$ROOTCORECONFIG/QFramework/lib/ in a RootCore setup.

  Alternatively, you can use the tqroot script, which automatically loads the library for you and resides in the share subfolder of the package.

  However, if you want to load the library from within a macro, you should use

  gROOT->ProcessLine(".L <PATH>/libQFramework.so");

  If you are trying to compile an executable (for example with g++) against the libQFramework, you will need the flags -L<PATH> and -lQFramework. However, a more convenient way of compiling your scripts against the CAF is to use the tqcompile script.

• How can I use the library in python?

  The library ships with a python module. If you are using RootCore setup, you can simply type import QFramework, and you are done.

• Can I read xAOD files?

  The HSG3AnalysisCode knows how to handle xAOD files, but it requires the ATLAS EDM libraries to actually make sense of the containers. Hence, you need to setup an ASG RootCore release and compile the HSG3AnalysisCode as a RootCore package inside that release. After that, the code will automagically handle xAODs for you, just as if they were regular flat nTuples.

• How can I compare cutflows and counters?

  First, you should load the analysis root files of both parties:

  TQSampleFolder * samples = TQSampleFolder::newSampleFolder("samples");

  samples->importObject("samples_hww_analysis_MyAnalysis.root:samples_Nominal>>::MyAna")

  samples->importObject("samples_hww_analysis_Nominal.root:samples_Nominal>>::Nominal")

  To check whether the samples are correctly loaded, you can call

  samples->print()

  which should lead to the previously imported folders to be printed of the type TQSampleFolder.

  You can now check for differences in, i.e., the signal samples by calling

  samples->validateAllCounter("MyAna/sig/","Nominal/sig","mf[CutSomeName]dc");

  This command checks the numbers at CutSomeName and prints only the counters that:

  • m: do not match
  • f: filter (here for [CutSomeName])
  • d: additionally trace mismatch of counter that do not agree
  • c: print the counter states in additional columns

  This should lead to a detailed output on your console.

  In case you would like to get some detailed information for one particular sample (e.g. to check the crosssection value that has been used) you can use the following commend:

  samples->getSample("MyAna/sig/me/mh125/WH/161105")->print("td")

  The arguments td ensure to print the tags and details for the sample. And should lead to a detailed output of all the meta-information stored for this sample. This is useful to track down problems in case different cross-section values have been used or the generator is different.

  Another useful command is to check which samples are used in a background folder (e.g. Z+jets here) you can do that by typing:

  samples->printListOfSamples("bkg/ee/Zjets/Nom/Z/*");

• How can I compare shapes of different variables or at different cut stages?

  Load the library and instantiate an instance of a TQPlotter, for example like this:

  TQHWWPlotter pl(samples_Nominal)

  If your plotter comes with a preinitialized process list, you should clear it before proceeding.

  pl.reset()

  Now you can add the path to your samples. In order to obtain a ratio plot, you should choose data for the numerator and background for the denominator. If the paths are identical, you might want to add a title.

  pl.addData("bkg/[em+me]/diboson/NonWW/ZW","title='rescaled'")

  pl.addBackground("bkg/[em+me]/diboson/NonWW/ZW","title='original'")

  Note that neither the variable name nor the cut name are specified directly in the configuration. Both are defined only when you actually produce the plot, which you can do like this:

  pl.plot("MyPlot","input.data='MyFirstCut/MyFirstVariable', input.bkg='MySecondCut/MySecondVariable', style.showRatio=true")

  Please note that the string "MyPlot" is just a label at this point and does not control your input data anymore, since that has been overwritten by the input.??? tags.

• How do I apply a reweighting at the analysis code stage?

  For a start, you need a 2D histogram holding the quantity you are interested in and the one you would like to use for the reweighting (e.g. W boson p_T ). Typically, such a histogram can be produced by calling TQHistoMakerAnalysisJob::bookHistogram("..."), or by adding the histogram definition to an appropriate configuration file (i.e. histograms.txt) file when running the analysis job. Histograms can be defined by simple strings, as shown in the following example.

  TH2F('PT_W_vs_DPhill_WZDilep', '', 15, 0., 300., 24, 0., 3.14) << (Pt_WZDilep / 1000. : '#it{p}_{T}(W) [GeV]', DPhi_WZDilep : '#it{#Delta#phi}_{ll, WZ OS} [rad]' )

  After you have produced your two-dimensional histogram and it resides in some sort of analysis ROOT file (for example, samples.root) you can retrieve it from the folder structure as usual.

  TString filename = "/path/to/my/file/samples.root";

  TQSampleFolder * samples = TQSampleFolder::loadSampleFolder(filename + ":samples_Nominal");

  TQSampleDataReader * rd = new TQSampleDataReader(samples);

  TH2 * hist = rd->getHistogram("bkg/?/diboson/NonWW/[ZW+ZZ]", "CutWCandPt/PT_W_vs_DPhill_WZDilep");

  Additionally, you need the one dimensional histograms that you would like to use for the reweighting: (e.g. the W boson p_T in data and Monte Carlo). Of course, you need to define them beforehand as described earlier.

  TH1 * hw_bkg = rd->getHistogram("bkg/?/diboson/NonWW/[ZW+ZZ]", "CutWCandPt/PT_WCand_Coarse");

  TH1 * hw_data = rd->getHistogram("data/? - bkg/?/Zjets - bkg/?/top - bkg/?/diboson/WW - bkg/?/diboson/NonWW/Wgamma", "CutWCandPt/PT_WCand_Coarse");

  You might want to create a copy of the data histogram that will hold the ratio data/MC afterwards:

  TH1 * hw = TQHistogramUtils::copyHistogram(hw_data);

  hw->Divide(hw_bkg);

  Now you can employ the following, very handy functionality that uses the 2D histogram and the 1D histogram with the weights and yields a 1D histogram that is reweighted.

  TH1 * h_DPhill_bkg_rew = TQHistogramUtils::getReweightedHistogramY(h_bkg_WZ_CutWCandPt_PT_W_vs_DPhill_WZDilep , hw);

• How can I read nTuples residing on EOS?

  Usually, it should be sufficient to prefix any paths you use with root://eosatlas/ to access any files residing on EOS. The corresponding sections of the code will recognize the prefix and act accordingly.

  However, you might wish to download the nTuples to your local machine - either because this allows faster and offline file access, or because you might want to replace or modify files. Since downloading extensive folder structures from EOS can be cumbersome, a script by the name eosget residing in the share subfolder will do the job for you. Just type

  share/eosget eos/atlas/some/path my/local/target

  and you are good to go. If you forget the syntax, the script will echo usage information when invoked eosget help.

Additional Links:

• Bug tracker JIRA
• Project on gitlab
• PAT User Analysis Tools List Entry TWiki

To update this page:

• This page is created by the script makedoc.py
• You can make changes, commit, push to the CAFCore repo, and hit the 'pages' button in the CI to update this site.