Tutorial

This tutorial (as well as the Artus, HarryPlotter and Excalibur documentation in general) is incomplete. Please add any information that you think is missing or talk to the main developers.

TODO: update the following sections

This tutorial will show you how to use Excalibur for (1) data analysis and (2) plotting. Please make sure you have successfully installed and compiled Artus and sourced the ini script according to the instructions above. Have a look at this Readme and the documentation for Artus and HarryPlotter in case of questions.

(1) Data Analysis with Artus

The excalibur.py script, located in the scripts/ folder, takes care of creating a .json config file and running artus with it. artus will read in some skim files and process the events: Several processors filter undesired events or calculate additional quantities. The result is written into a ROOT output file.

• Execute excalibur.py data -f 3 to run over three input files with data config. The terminal output will tell you some general information, e.g. which files are used or how many events per second are processed.
• Have a look at the used configuration file in cfg/excalibur/data.py. From these few lines of code, the full json config is created according to cfg/python/defaultconfig.py. Have a look at the defaultconfig.py and the relevant sections in there (data, data_mm, ...). Where is e.g. the setting for the MuonID defined?
• Have a look at the json file cfg/excalibur/data.py.json. This configuration contains general settings and a list of pipelines. What is the difference between the pipelines (look at the list of Quantities and Processors for each pipeline)?
• Use 'grep' or the search on github to find out at which positions a certain config setting is used (This can be in the Artus or Excalibur repositories!). Where e.g. is 'MuonID' used?
• Open the 'data.root' output file with a ROOT TBrowser. Have a look at the contents of the different folders which correspond to the different Pipelines. What is the difference between the pipelines/folders?
• Open the ntuple in one of the folders and examine the different variables. An explanation of the quantities is given above. What does e.g. 'mupluspt' mean?
• Type excalibur.py -h and read the full list of command line arguments.
• Execute excalibur with the data config in batch mode: excalibur.py data -b (make sure you have followed the instructions for the batch functionality).

(2) Plotting with HarryPlotter/Merlin

After the data processing with Artus, you need to use merlin.py to create plots from the output ROOT files. Have a look at the documentation for HarryPlotter and merlin (above) for basic installation and usage help and also if you have questions during the tutorial.

• The basic parameters you need are a root file, the path to an ntuple and a quantity name. Type merlin.py -i data.root -x zmass to plot the Z boson mass.
• Read the merlin documentation above to understand how the folder name is put together from the --zjetfolder, --algorithms and --corrections arguments. Repeat the plotting command for a different zjetfolder, e.g. 'nocuts'.
• Use the --x-bins argument to plot the zmass with a different equidistant (e.g. --x-bins "10,71,111") or custom (e.g. --x-bins "71 81 86 91 96 101 111") binning. Type merlin.py -h to get a list of the command line options to get further information on how to use --x-bins.
• Create a 2D plot of the Z boson pT versus the leading jet pT by specifying zpt and jet1pt for the -x and -y arguments.
• The --weights/-w argument can be used for weighting of events and thereby for cutting out certain events, e.g. -w "jet1pt>80&&zpt>100". Use this argument to create the 2D plots only with events with zpt>100 and jet1pt>80.
• Create a profile plot by using --tree-draw-options prof.
• Create two histograms from the same file by specifying two weights, e.g. -w "zpt<70" "zpt>120"
• Try merlin.py --list-available-modules and have a look at the available input/analysis/plot modules. Try to use the Ratio module by creating two distributions and adding a ratio subplot with --analysis-module Ratio.
• In addition to the command line usage, Merlin also allows plotting a configuration from a python file. Have a look at the Plotting/configs/tutorial.py file and add the missing keys to recreate the previous plot with merlin.py --py tutorial (but don't commit your changes).
• The --live (optionally with --userpc) or --www arguments are handy to directly open plots or upload them to your webspace.
• Have a look at the full list of command line arguments: merlin.py -h

Congratulations! You have completed the Excalibur tutorial! 👏 👍