LEAF: An LHC Event Analysis Framework

Welcome to the documentation for the LHC event analysis framework (LEAF)! If you have not used LEAF before, it is advisable to read the intoduction below, it will give an overview over the different purposes LEAF can be used for. Otherwise, you might as well just skip it and refer to the documentation of the individual packages for in-depth information.

tl;dr: Install LEAF and follow the quickstart example

Introduction

LEAF is a versatile, relatively lightweight framework that allows to perform multiple steps common to about every LHC data analysis. It has several "packages", each of which may be used for a different task analysts might encounter on their way from a theoretical model to a full publication. LEAF may currently only be used for CMS data analysis, as it is specific to the data format adopted in the CMS Collaboration. Additionally, it is only configured for use with the PSI Tier-3 SLURM cluster, but it is possible to extend it to different infrastructures.

Instructions on how to install and complie LEAF can be found on the Installation page. Brief introductions to all packages are given below on this page, in-depth information can be found in the pages linked in the respective section. The typical workflow from zero to a full physics result usually follows the order in which packages are introduced here. A quickstart example of an analysis is available here.

Generator

The Generator package is used in the very beginning of an analysis to generate signal samples from a theoretical model in the UFO format using the MadGraph5_aMCatNLO event generator. A UFO model is often provided by authors of phenomenological papers. With the Generator, it is possible to privately generate events of whatever process the model is able to simulate and to process them down the chain of all data formats employed by CMS.

Tuplizer

The Tuplizer packages picks up where the Generator left. It is used to convert samples from a CMS event format to the format used by LEAF. This means that it is possible to process both samples generated privately and those produced centrally. It can access files stored anywhere in the LHC computing grid (LCG), be it local, Tier-3, or Tier-2 storage elements.

Depending on the need of the users new versions of tuples can be generated in certain intervals. Using the database integrated in the Generator package, it is possible to use a common set of tuples for all users, such that it is not necessary for everyone to generate their own tuples.

Analyzer

The Analyzer package arguably is the most heavily used LEAF package. It reads events in the LEAF format generated by the Tuplizer and offers all functionalities to perform a full-fledged data analysis. Event selection and the generation of histograms in a concise and efficient way are the key features of this package. It is interfaced to the Tuplizer in order to ensure a consistent data format. However, every user is given the possibility to extend it according to their needs, making the Analyzer a very versatile tool able to accomodate various flavors of analyses.

Submitter

The Submitter package is a helper tool for the Analyzer. It allows for convenient yet efficient submission of jobs to the local cluster.

Plotter

The Plotter is the last package in the LEAF chain. Having been processed by the Analyzer and Submitter packages, all histograms stored in a file according to the LEAF format can be visualized by the Plotter. It offers customizability and a coherent style of plots as well as the option to save plots in a collated way or individually.