tutorial-analysis/_episodes/02-reconstruction-output.md

0001 ---
0002 title: "The Reconstruction Output Tree"
0003 teaching: 20
0004 exercises: 20
0005 questions:
0006 - "What information is stored in the reconstruction output and how can we access it?"
0007 objectives:
0008 - "Become familiar with the tree branches"
0009
0010 keypoints:
0011 - "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."
0012 - "The MCParticles branch holds information on generator level particles, critical for use in comparing to what we actually detect!"
0013 ---
0014 <!--
0015   Commenting out for now until the final content of this part of the lesson is decided. Leaning towards not including the locating factory/algorithm as a core part of the tutorial. - SJDK 29/03/24
0016 - "Locate the EICrecon factory/algorithm used to fill a specific branch"
0017 - "Become familiar with the edm4hep and edm4eic data models"
0018 - "Understand associations and relations"
0019 -->
0020
0021 What we generally call the simulation output are root trees generated by the reconstruction software, [EICrecon](https://github.com/eic/EICrecon/tree/main). The branches which appear in the output trees and their content are determined by which EICrecon factories and algorithms are run.
0022
0023 - Note, root 6.30.02 which is now used by eic-shell has some backwards compatibility issues. If you try to open a file produced with root 6.30.02 in an older version of root, you may get some errors/warnings and unpredictable behaviour when browsing files/trees.
0024 - 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.
0025   - The [webviewer](https://eic.phy.anl.gov/geoviewer/) 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).
0026     - 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.
0027
0028 ## EICrecon Output Tree Structure
0029
0030 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.
0031
0032 > Exercise
0033 > - Stream a simulation output tree from within root (see previous lesson) and browse the structure by calling `new TBrowser()`
0034 > - Take some time to explore the branches of the tree. What information is included for various subsystems? What are some of the reconstructed quantities?
0035 > - Try plotting some basic quantities. Plot the cluster energy of the negative endcap ECal - do you see the peak from the scattered electron?
0036 {: .challenge}
0037
0038 For the last part, some extra tips are included below.
0039
0040 ## Browsing the file - ROOT Tips
0041
0042 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.
0043
0044 Alternatively, we can also plot variables to histograms of our own choosing on the fly. We can do this via -
0045
0046 ```console
0047 root $FILE
0048 events->Draw("QUANTITY")
0049 ```
0050 where $FILE is the file we want to open and "QUANTITY" is the thing we want to draw. For example -
0051
0052 ```console
0053 events->Draw("MCParticles.momentum.z")
0054 ```
0055 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 -
0056
0057 ```console
0058 events->Draw("MCParticles.momentum.z>>h1(100,0,100)")
0059 ```
0060 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 -
0061
0062 ```console
0063 events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0")
0064 ```
0065 will fill our histogram only with negatively charged particles. We can add more conditions if we want -
0066
0067 ```console
0068 events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0 && MCParticles.mass>1")
0069 ```
0070 where we now also require that the particle mass is >1.
0071
0072 We can also add drawing options -
0073
0074 ```console
0075 events->Draw("MCParticles.momentum.z>>h1(360,-60,300)", "MCParticles.charge<0", "HISTERR")
0076 ```
0077 such as adding error bars. We can also make 2D histograms in the same way -
0078
0079 ```console
0080 events->Draw("MCParticles.momentum.z:MCParticles.charge>>h2(40,-2,2, 360,-60,300)", "", "COLZ")
0081 ```
0082 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 -
0083
0084 ```console
0085 gPad->SetLogz()
0086 ```
0087 ## The MCParticles Record
0088
0089 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 modeled by GEANT are stored in the MCParticles branch, whoes structure is defined by the datatype [edm4hep::MCParticle](https://github.com/key4hep/EDM4hep/blob/main/edm4hep.yaml#L140). The particle's [PDG](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-monte-carlo-numbering.pdf) 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](https://github.com/key4hep/EDM4hep/blob/main/edm4hep.yaml#L140).
0090
0091 ## How is the tree populated?
0092
0093 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.
0094
0095 > Work through the algorithms and factories tutorial. Afterwards, take a closer look at this file.
0096 > See if you can figure out which algorithm or factory was responsible for creating some of the included branches in this file.
0097 {: .callout}