14.5. Analysis Workflow

Table of Contents

Input

In an event based analysis you always begin by defining clearly what your input is. In ROOT this almost always means one or more ROOT files that contain TTrees, often with names like "Events", "tree", "Data" or similar. Each row of the TTree is an event, and each branch stores a variable or a group of variables that describe that event.

Before doing any physics, you should list which files you will read, which TTree you will use, and which branches you actually need. It is usually better to read fewer branches rather than everything, because this reduces memory usage and speeds up the analysis. In traditional ROOT you open a TFile, retrieve the TTree, and set branch addresses or use high level methods like TTree::Draw for quick checks. In more modern workflows you may also construct a TChain to merge many files logically into a single tree, or you may build an RDataFrame from the tree as a higher level entry point.

Your input definition is also the right place to document basic sample information, for example whether the data are real detector data or simulation, which run period they come from, and which calibration or reconstruction version was used. This context does not appear in the ROOT objects automatically, so keeping it together with your input configuration helps with reproducibility.

The key idea is that a complete analysis should be reproducible from a small set of well defined inputs: a list of ROOT files, the tree name, and the set of branches that will be used. Once this is written clearly, every later step of the workflow becomes easier to understand and to repeat.

Selection

After defining what you read, you define which events you keep. Event selection is where you turn a very large and mostly generic dataset into a sample that is relevant for a specific physics question. Conceptually, you apply a sequence of logical conditions on the event variables stored in the tree. Only events that satisfy all required conditions are passed to the next stages of the workflow.

Simple selections can be written as cuts on single variables. For example, you might require an energy variable E to lie in a certain range, $E_{\min} \leq E \leq E_{\max}$, or demand that a quality flag variable is equal to 1. More realistic analyses combine many such conditions. You can express them as logical expressions that use comparison operators and logical operators such as && for logical AND and || for logical OR. In ROOT these same expressions can often be passed directly as strings to methods like TTree::Draw or, in RDataFrame, to Filter.

It is good practice to separate different categories of selection. For instance, you might distinguish basic data quality cuts that remove clearly problematic events, from physics selection cuts that define the actual signal or control regions for your measurement. By structuring selections in stages you can more easily study their effect, for example by checking how many events are removed by each group of cuts, or by looking at distributions before and after a particular selection.

Event selection is not just a technical step, it is a source of systematic effects. If your selection has sharp thresholds, like $p_T > 25$ GeV, small changes in calibration or resolution can move events across the threshold and change yields. For that reason, selections should be chosen deliberately, documented clearly, and kept in one place in your analysis code rather than being spread across many files.

Selection cuts define which events contribute to your final physics result. Always make them explicit, centralize them in your code, and avoid silently changing them while comparing different analyses.

Processing

Processing is the step where you transform the selected raw variables into higher level quantities that are closer to the physics you want to study. Technically, this often means computing new variables for each event based on the existing branches in the tree, then either using those new variables immediately or storing them as additional branches or columns.

Typical processing tasks include converting detector units to physical units, combining several measured quantities into one observable, applying calibration constants, and computing basic kinematic quantities such as invariant masses or angular differences. In ROOT, you may implement this either through explicit C++ event loops where you read branch values, perform calculations, and then fill results, or through higher level constructs such as RDataFrame::Define, which attaches new columns computed from existing ones.

Processing can also include more advanced operations that still follow the event based pattern. For example, you may calculate per event weights that account for efficiencies or luminosity normalization, or you may classify events by assigning categories based on their properties. Many analyses also apply small corrections or scale factors that have been derived in dedicated calibration studies. These corrections are usually functions of the original variables and are evaluated during processing.

A key feature of the processing stage is that it is deterministic given the input and the selection: the same input events, run through the same processing code, must always give the same processed quantities. To maintain this property, avoid hidden state, random decisions without fixed seeds, or dependencies on external mutable configuration that are not recorded.

Processed quantities are derived from the original detector measurements. Keep the formulas for these derived variables in one well defined place and avoid duplicating the same calculation in different parts of the code.

Histogramming

Once events are selected and processed, you convert the resulting variables into histograms or related binned distributions. Histogramming is where event by event information is summarized into distributions that can be visually inspected and statistically analyzed.

In ROOT, histogramming usually happens inside event loops. For each event that passes selection, you take one or more variables and call Fill on the corresponding TH1 or TH2 objects, optionally with a weight. In RDataFrame workflows you instead define histograms declaratively with methods like Histo1D or Histo2D, and the framework handles the looping internally.

At this stage you must choose binning schemes, ranges, and whether to use uniform or variable bin widths. These choices affect both the visual appearance and the statistical precision of your results. Too few bins can hide structure, while too many bins with limited statistics can produce noisy and unstable fits. You must also keep track of whether histograms represent absolute counts or normalized distributions for shape comparisons.

Event weights are particularly important in histogramming. In simulated samples, each event may carry a weight that represents its contribution to a target luminosity or cross section. When such weights are used, each call to Fill usually passes the weight so that the bin contents correspond to weighted yields rather than simple counts. This affects the interpretation of statistical uncertainties, which may differ from simple Poisson expectations.

Histogramming is also the right place to separate logically different categories into different histograms. For example, you might maintain separate histograms for signal regions and control regions, or for different detector configurations, but still fill them from the same main event loop or RDataFrame pipeline. Doing so preserves a single, clear flow of data while producing multiple outputs for different parts of the analysis.

Once you fill histograms you lose individual event information. Before finalizing binning and ranges, check that they are appropriate for your statistics and physics questions, because you cannot fully recover event level detail from histograms alone.

Output

The workflow ends by collecting your results and writing them out in a form that you and others can reuse. In ROOT based analyses the main persistent output is usually a ROOT file that contains all histograms, graphs, fitted functions, and sometimes reduced TTrees or derived RDataFrames. This output file is what you use for plotting, fitting, and producing final numbers without reprocessing the full raw input.

When designing output, think about what you will need later. Often you want to store both intermediate and final objects. Intermediate outputs can include histograms before some corrections, or trees that contain a subset of branches plus a few derived quantities. Final outputs can include combined histograms ready for fitting, covariance matrices, and any summary numbers that are needed for a publication or internal note. ROOT provides TFile and TDirectory to help you organize these logically in a hierarchy of directories within a single file.

Alongside ROOT files you typically also write human readable summaries. These can be text files with numbers, CSV tables, or LaTeX tables that capture event yields, efficiencies, and fit results. Storing these externally allows collaborators who do not use ROOT directly to inspect and reuse your findings. For plots, you usually save canvases in common image formats such as PNG for quick viewing and PDF or SVG for publication quality vector graphics.

For a complete workflow, the output should not only contain the data products but also enough information to understand how they were produced. That can include configuration files that list input samples and cuts, small log files that record software versions and command line options, and even scripts that regenerate all plots. Grouping these elements into a structured directory together with the ROOT outputs helps ensure that results remain reproducible long after the initial analysis is finished.

Treat your ROOT output file as part of the final scientific result. Organize it carefully, include all objects that are needed for checks and reinterpretations, and always keep a clear link between the output and the code and configuration that produced it.