KAHIBARO
20.2. ROOT Output
Table of Contents
ROOT files
In GATE, most detailed simulation data are stored in ROOT files. ROOT is a data format and analysis framework that comes from high energy physics. It is very efficient for storing large numbers of events with many variables, which is what a Monte Carlo simulation produces.
When you configure actors or digitizers in GATE, you usually specify an output filename and a format. If you use a filename that ends with .root, GATE writes a ROOT file. This file typically contains one or more ROOT trees, each tree holding a specific type of information. For example, a hit actor can create a tree with one entry per hit, while a singles or coincidence digitizer can create trees with one entry per single or coincidence event.
Most ROOT files from GATE follow a similar structure: they contain high level metadata and one or several trees. Metadata give global information about the simulation, such as the number of events, version numbers, and possibly geometry or physics settings. The trees hold the event level data that you use for analysis.
Because ROOT is a binary format, you cannot open a ROOT file with a text editor. You must use ROOT tools or compatible libraries, for example the ROOT command line, C++ or Python with ROOT, or Python with uproot. Later chapters focus on how to analyze these files, so in this chapter the focus remains on what GATE writes and how it is organized.
ROOT files are the standard way to store large, event based data in GATE. For detailed analysis, always check that the correct actors and digitizers write to .root files and that the trees they contain match your analysis plan.
A typical naming scheme is to use one ROOT file per actor or per digitizer chain. For example, you might have stats.root for simulation statistics, hits.root for raw detector hits, singles.root for processed detector events, and coincidences.root for PET coincidences. Keeping these roles separate makes analysis and file management easier.
Event trees
Inside each ROOT file, the main container used by GATE is the ROOT tree. A tree is similar to a table, but with strong support for variable length entries and many branches. Each branch represents a variable, and each row of the table is called an entry. In a Monte Carlo context, an entry often corresponds to an event, a track, a hit, or a single, depending on the actor or digitizer that produced the tree.
For example, a hits tree usually contains one entry per hit. A hit is a single energy deposition in a sensitive volume. In contrast, a singles tree contains one entry per processed detector event after digitization, which may combine several hits into one event. A coincidences tree contains one entry per coincidence, which combines two singles that occur within a coincidence time window.
An event tree typically contains both identifying information and physical quantities. Identifying information includes event ID, run ID, track ID, and detector IDs. Physical quantities include deposited energy, position, time, direction, and sometimes particle type. These arrays can be stored as simple numbers or as vectors, depending on how many values are associated with each entry.
The following table shows a simplified example of how different trees might be used in a typical PET simulation:
| Tree name | One entry represents | Typical origin |
|---|---|---|
Hits | One energy deposition in a crystal | Hit actor |
Singles | One processed detector event | Digitizer chain |
Coincidences | One coincident pair of singles | Coincidence sorter |
Stats | Global simulation statistics | Statistics actor |
In GATE, the exact tree names and branch names are defined by the actor or digitizer configuration. Some actors allow you to choose the tree name. Others use default names. It is important to know which actor created which tree, because this defines what each entry means and which branches are available.
By design, event trees are append only during the simulation. Each new event or hit is added as a new entry. This matches very well with the Monte Carlo workflow, where events are generated one by one and processed independently. After the simulation ends, the tree is closed and saved in the ROOT file, so you can process it later without running the simulation again.
A ROOT tree in GATE is usually organized so that each entry corresponds to a physically meaningful unit, such as a hit, a single, or a coincidence. When analyzing data, always confirm what one entry represents before computing spectra, rates, or efficiencies.
Detector data
Detector related information in ROOT output is central for imaging and detector development studies. GATE stores detector data at different processing levels. At the lowest level, a hits tree records raw particle interactions in sensitive detectors. Each hit entry generally includes the energy deposited in that step, the position of the interaction, the time, the particle type, and identifiers for the volume and detector.
A typical hits tree might contain branches such as eventID, trackID, edep for energy deposition, x, y, z for position, and time. In addition, detector specific identifiers appear, for example crystalID, moduleID, or a generic volumeID. These IDs allow you to trace which physical detector element registered the interaction. You use this information to build detector maps, view occupancy patterns, or study local response.
After digitization, the singles tree contains detector events that more closely represent what the electronics would output. Instead of every microscopic energy deposit, singles combine deposits that belong together in time and space. Typical singles branches include total energy in the detector element, time of the event, detector IDs, and perhaps flags or classification labels. This level is the basis for most imaging analysis, such as energy spectra and count rates.
The coincidences tree, when present, merges pairs of singles that satisfy a coincidence condition. For PET, each coincidence entry usually holds information for both detectors. Branches store the energies in each detector, their positions, and the detection times, as well as derived values such as the time difference. With this detector data, you can reconstruct lines of response, study scatter and random fractions, and compute performance metrics.
The following table summarizes common detector related branches you may find in ROOT trees:
| Branch name | Meaning |
|---|---|
eventID | Global event index of the simulation |
sourceID | ID of the primary source particle |
globalTime or time | Time of the interaction or detection |
edep or energy | Deposited or detected energy |
x, y, z | Position of interaction or detector element |
crystalID | Index of the crystal within the detector |
moduleID | Index of the detector module or block |
detectorID | Higher level detector identifier |
volumeID | Identifier of the volume where hit occurred |
For dose and phase space studies, detector data also appear as dose per voxel or full particle state. Dose actors often write voxel indices and energy deposition in each voxel, which are organized differently from individual hits but still stored in ROOT trees for advanced analysis. Phase space actors store particle state just before or after a component, including position, direction, and energy, and can also write this as ROOT data.
In practice, when you design a simulation, you decide which detector data you need. You then configure actors and digitizers accordingly so that the ROOT files contain hit, singles, coincidence, dose, or phase space trees that match your study. Later chapters show how to read these detector data in ROOT or Python and how to create spectra, maps, and performance plots from them.
Detector data in ROOT output are organized by processing level: hits, singles, and coincidences. Before running a long simulation, always verify that the ROOT branches you need, such as energy, time, and detector IDs, are present in a small test run.
Views: 11