KAHIBARO
21.2. Inspecting Output
Table of Contents
Event IDs
When you open a GATE ROOT file in ROOT, you will usually find one or more trees that store simulation data, for example Hits, Singles, Coincidences, Stats, or similar names depending on the actor. Each entry in these trees corresponds to a recorded entity such as a hit, a single, or a coincidence line. To make sense of these entries you need to understand the event identifiers that GATE stores.
A typical hits or singles tree contains several ID fields. The most important is usually called something like eventID or event_id. This value links all interactions that belong to the same primary event in the Monte Carlo simulation. In a PET simulation, for example, all particles created from the decay of a single radionuclide atom share the same eventID. When you inspect the tree in ROOT, you can view the definitions and types with:
TFile *f = TFile::Open("output.root");
TTree *t = (TTree*) f->Get("Singles");
t->Print();
In the printed list of branches, look for fields containing the word event. To check how many different events are present, you can draw a simple histogram or profile. For example, to see the distribution of event IDs:
t->Draw("eventID");
This quickly confirms whether the simulation produced the expected number of events and whether the data are evenly spread across events. For coincidence trees, you will usually find two event IDs, for example eventID1 and eventID2. In GATE PET simulations, true coincidences typically have the same event ID for the two photons, whereas random coincidences usually have different event IDs. Inspecting these fields in ROOT allows you to verify that the coincidence sorter is working as intended.
Besides eventID, you may see other identifiers such as trackID, parentID, or detector related IDs like crystalID, moduleID, or ringID. In the context of ROOT inspection, use eventID primarily to group and filter data. For instance, to look only at entries from a single event, you can set a cut:
t->Draw("edep", "eventID==42");This way you can debug individual events and verify that particles behave as expected. It also helps you check that actors and digitizers are not mixing information from different events.
In ROOT inspections, always verify that the event ID fields are present and consistent. Use eventID and related IDs to group entries, distinguish primary events, and separate true from random coincidences.
Energy
Most GATE ROOT trees contain one or more branches that store deposited or detected energies. Typical names include edep for deposited energy in hits and energy or E for energy in singles or coincidences. When you inspect output, you often start by drawing basic energy distributions to confirm that the simulation physics and digitization behave as expected.
After opening the file and tree, you can create an energy spectrum with a single ROOT command. For hits:
t->Draw("edep");For singles or coincidences:
t->Draw("energy");ROOT will automatically create a histogram over a default range. To choose ranges and bins that match medical physics problems, you can specify them explicitly, for example:
t->Draw("energy>>hE(400,0,800)");
This defines a histogram hE with 400 bins from 0 to 800 keV, useful for PET or SPECT detectors where you expect a 511 keV photopeak or radionuclide specific peaks. Inspecting the shape of this spectrum in ROOT tells you whether the correct photopeak appears, whether there is a realistic Compton continuum, and whether your energy window and energy blurring settings are reasonable.
If your tree stores energy in units of MeV rather than keV, you need to apply the conversion when drawing in ROOT. For example, to draw energy in keV when stored in MeV:
t->Draw("energy*1000 >> hEkeV(400,0,800)");This type of check is particularly important when you first connect a digitizer or modify physics lists. Comparing spectra from hits, singles, and coincidences helps you follow how energy information flows through the simulation pipeline.
You can also combine energy and other quantities to inspect more complex behavior. For example, to see how energy depends on detector crystal ID:
t->Draw("energy:crystalID >> h2E(128,0,128,400,0,800)","energy>0","colz");This creates a two dimensional histogram that shows which crystals receive events at different energies. Such ROOT plots help diagnose geometry or identification problems in detectors.
When inspecting energy in ROOT, always verify the unit used in the tree and adjust the histogram range accordingly. Use simple spectra and two dimensional plots to confirm that photopeaks, continua, and energy windows match your simulation design.
Position
Spatial information is one of the key reasons to inspect ROOT output. GATE typically records positions as three separate coordinates, for example x, y, and z, often in millimeters. In hits trees, these give the location where the interaction occurred, while in singles or coincidences they may represent detector or crystal positions.
Once you have a pointer to the tree in ROOT, you can check the ranges of each coordinate with one dimensional histograms:
t->Draw("x");
t->Draw("y");
t->Draw("z");The resulting histograms show where most events occur inside your geometry. If you know the expected detector and phantom positions, you can immediately see whether the coordinates are consistent. For a planar gamma camera, for example, one coordinate should cluster around the detector plane, while the others span the field of view.
ROOT also allows quick two dimensional position plots, which are extremely useful for imaging simulations. To view an x y distribution:
t->Draw("y:x >> hXY(200,-300,300,200,-300,300)","","colz");
This plot acts as a flood image or projection of event locations. For PET scanner hits, it should show ring or block patterns, while for dose actors output converted to ROOT it can show voxel patterns. You can also visualize axial distributions with z:x or z:y plots. If your positions are stored in centimeters rather than millimeters, scale appropriately in the draw expression.
In coincidence trees, you often find positions for two detectors, for example x1, y1, z1 and x2, y2, z2. By drawing their distributions separately, you can verify that both sides of the scanner are active and aligned as expected. You can also reconstruct simple lines of response inside ROOT by selecting pairs of positions and plotting derived quantities such as midpoints. Although detailed reconstruction belongs elsewhere, ROOT inspection at this stage helps confirm that the detector geometry is correct.
It is also common to combine position with energy or time. For example, to see how the axial position of hits depends on deposited energy:
t->Draw("z:edep >> hZE(200,0,800,200,-300,300)","edep>0","colz");Such plots can reveal non uniformities in detector response or edge effects. When positions appear outside the expected range, check unit consistency and whether the tree stores global or local coordinates. GATE actors can sometimes export local positions relative to a volume, while others record global coordinates in the world frame. The names of the branches or actor configuration tell you which system is used, and ROOT inspection then confirms the result.
Always confirm the coordinate system and units of position branches before interpreting ROOT plots. Use one and two dimensional histograms of x, y, and z to validate detector placement, field of view, and overall geometry consistency.
Time
Time information in GATE ROOT output is essential for simulations that involve acquisition windows, coincidences, and time of flight. Most trees contain a time branch such as time, usually expressed in seconds. Some digitized data also include time1 and time2 for coincidence partners, or additional timing fields that represent processed times.
To inspect the time distribution in ROOT, start with a simple histogram:
t->Draw("time");If your simulation runs over seconds or minutes of activity, the range of this histogram should match the acquisition duration you configured in GATE. You can refine the view with specific ranges and binning:
t->Draw("time >> hT(1000,0,1.0)");This example focuses on the first second of acquisition. Checking this histogram helps you ensure that events are produced throughout the intended time window and that the activity and time configuration are consistent.
In coincidence trees, inspecting the time difference between the two detected photons is a standard step. You can calculate it directly in the draw expression:
t->Draw("(time2 - time1) >> hDT(400,-5e-9,5e-9)");This creates a timing spectrum centered around zero, typically in seconds. The width of this distribution reflects the coincidence timing resolution. If you have enabled timing blurring in the digitizer, this check confirms that the applied resolution matches expectations. For time of flight PET simulations, you can later relate these time differences to spatial localization along the line of response, but at the ROOT inspection stage you mainly verify that the shape and width are reasonable.
Time can also be combined with energy or position to detect drifts or instabilities. For example, to check whether energy changes over time:
t->Draw("energy:time >> hET(200,0,1.0,400,0,800)","","colz");This plot should show a stable energy distribution across the acquisition period. Any strong trend may indicate a configuration problem in activity, source motion, or digitizer settings. Similarly, inspecting count rates over time can be done by drawing a simple time histogram and examining how the number of entries per bin evolves.
Timing cuts are another important aspect of ROOT inspection. Before using the data for later analysis, you might select a specific time interval with a cut expression:
t->Draw("energy", "time>0.1 && time<0.2");This allows you to focus on a well defined acquisition window, to study transient effects, or to simulate gated acquisitions.
Treat all time values in ROOT as physical quantities with units, usually seconds. Inspect basic time distributions and time differences to verify acquisition duration, coincidence sorting behavior, and timing resolution before using the data for further analysis.
Views: 13