The Reconstruction Output Tree

Last updated on 2026-07-10 | Edit this page

Estimated time: 40 minutes

Overview

Questions

  • What information is stored in the reconstruction output and how can we access it?

Objectives

  • Become familiar with the tree branches.

What we generally call the simulation output are root trees generated by the reconstruction software, EICrecon. The branches which appear in the output trees and their content are determined by which EICrecon factories and algorithms are run.

  • If you’re trying to open interactive windows such as a TBrowser via X-forwarding, it’s likely to be very slow. You may wish to just copy the file to your local machine and open it there.
    • The webviewer may also be quicker (just keep in mind that it’s less usable and you will struggle to do more than just browsing the tree).
      • You can’t do much more than view the files with this either. Ultimately, for the final part of the tutorial, you’ll need to be able to execute a ROOT macro/script it some way.

EICrecon Output Tree Structure

The output tree contains various branches appropriate for the individual detector subsystems. For example, the calorimeter subsystems will have branches for reconstructed hits and clusters. In addition to individual subsystem information, there are also branches for reconstructed quantities (e.g. reconstructed particles, inclusive kinematics, and jets) which may combine information from several subsystems. There are also branches encoding relationships between different reconstructed quantities as well as reconstructed and truth quantities.

Challenge

Exercise

  • Stream a simulation output tree from within root (see previous lesson) and browse the structure by calling new TBrowser()
  • Take some time to explore the branches of the tree. What information is included for various subsystems? What are some of the reconstructed quantities?
  • Try plotting some basic quantities. Plot the cluster energy of the negative endcap ECal - do you see the peak from the scattered electron?

Opening the file and calling new TBrowser() shows the full list of branches. Double-clicking EcalEndcapNClusters.energy draws the cluster energy distribution for the negative endcap ECal, in which you should be able to identify the peak from the scattered electron. Take your time exploring the subsystem branches (hits, clusters) and reconstructed quantities (reconstructed particles, inclusive kinematics, jets).

For the last part, some extra tips are included below.

Browsing the file - ROOT Tips

We can navigate around the TBrowser and get it to draw quantities by simply double clicking them. However, sometimes the auto binning can be off or we might want to look at a specific range. We can do this to some extent directly from the TBrowser.

Alternatively, we can also plot variables to histograms of our own choosing on the fly. We can do this via -

CPP 

root $FILE
events->Draw("QUANTITY")

where $FILE is the file we want to open and “QUANTITY” is the thing we want to draw. For example -

CPP 

events->Draw("MCParticles.momentum.z")

will draw the MCParticles.momentum.z branch. So far, so much like just double clicking the TBrowser. However, we could define a new histogram and fill this variable to it -

CPP 

events->Draw("MCParticles.momentum.z>>h1(100,0,100)")

where h1 is our new histogram. This has 100 bins from 0 to 100. We can also apply selection criteria (i.e. cuts) on the fly. These do not need to be on the same variable we are drawing! For example -

CPP 

events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0")

will fill our histogram only with negatively charged particles. We can add more conditions if we want -

CPP 

events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0 && MCParticles.mass>1")

where we now also require that the particle mass is >1.

We can also add drawing options -

CPP 

events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0", "HISTERR")

such as adding error bars. We can also make 2D histograms in the same way -

CPP 

events->Draw("MCParticles.momentum.z:MCParticles.charge>>h2(40,-2,2, 360,-60,300)", "", "COLZ")

note the order of defining the binning. It’s not what you might expect. Also, to interpret the result (as is often the case with 2D histograms), you might want to set a log Z scale -

CPP 

gPad->SetLogz()

Which branches do I need?

As you have probably seen by now, the tree in our file contains a lot of information!

For the rest of the tutorial, we will be focusing on a relatively small subset. This is generally true with most analyses, it’s rare we’ll be retaining and looking at every branch. A brief (and incomplete!) dictionary of commonly used branches, including those we’ll need in this tutorial, is included in the “Extras” section. See the tab at the top of the page or follow the branch dictionary.

To find out more about a particular collection, you could also take a look at the edm4eic datamodel. For some definitions and explanations, you may need to refer to the edm4hep datamodel.

The MCParticles Record

In the last section, the example quantities we were plotting involved the MCparticles branch. Nearly every analysis will include some comparison to the truth level, so it is important to understand how to access generator level information. Particles produced by the Monte Carlo Event Generator and during the interaction of these primary particles with the detector material as modelled by GEANT are stored in the MCParticles branch, this structure is defined by the datatype edm4hep::MCParticle. The particle’s PDG code, charge, production time, mass, production vertex, endpoint, momentum at the production vertex, and momentum at the endpoint are all available. In addition, the status of the particle as defined by the event generator and the detector simulation are stored. For example, if one wanted to look at stable particles from the event generator, they would require MCParticles.generatorStatus == 1. The field MCParticles.simulatorStatus is a bit-field which encodes some information on how the particle propagated through the detector. The detailed definition of the bit assignments can be found in the edm4hep yaml file.

How is the tree populated?

You may wonder how the specific branches of the tree have actually been populated. As this is the output after EICrecon, the trees in the file are those specified as EICrecon was run by the algorithms and factories that were enabled at run time.

This is covered in more detail in the Understanding the Simulation Output tutorial. In particular, Episode 3 of that tutorial details how you can identify the sequence of algorithms utilised to generate a specific output branch. In the case of the example in this tutorial, the track reconstruction is detailed.

Callout

Work through the algorithms and factories tutorial. Afterwards, take a closer look at this file. See if you can figure out which algorithm or factory was responsible for creating some of the included branches in this file.

Key Points
  • Output trees contain a lot of information. Take time to explore what is available, identify what you want to try and do, find the relevant branches.
  • The MCParticles branch holds information on generator level particles, critical for use in comparing to what we actually detect!