Quickstart

Requirements

  • Python 3.12 or newer

  • a GATE output ROOT file produced by GATE 9.4.2 or newer, C++ line

GATE 10, the Python implementation, is not supported.

Installation

From PyPI:

pip3 install opengate-gate-tree

From source:

make init
make install

First Run From The Command Line

Extract the whole Hits tree and write it as CSV:

opengate-gate-tree \
	--input-gate-root-file ./data/simulation.root \
	--output-dir ./out \
	--output-file-title patient_01 \
	--gate-tree Hits \
	--output-file-format csv

The run writes ./out/patient_01.hits.csv. The output directory is created if it does not exist, and an existing output file is overwritten without a prompt.

Reading the “Hits” tree recognises which structure the simulation wrote and checks the tree against it, so the run reports what it found before extracting anything:

Hits tree variant: System (A2), stored as 'Hits', system cylindricalPET / OPET, 46 branches

Add --branches-to-extract to keep only what the analysis needs:

opengate-gate-tree \
	--input-gate-root-file ./data/simulation.root \
	--output-dir ./out \
	--output-file-title patient_01 \
	--gate-tree Hits \
	--output-file-format hdf5 \
	--branches-to-extract eventID edep posX posY posZ

Every option is described in Command line.

First Script

The same run from Python:

from pathlib import Path

from opengate_gate_tree import GateTree, OutputFileFormat, read_tree, write_tree

data = read_tree(
    Path("data/simulation.root"),
    GateTree.HITS,
    ["eventID", "edep", "posX", "posY", "posZ"],
)
print(data.entry_count, data.branch_names)

write_tree(data, Path("out/patient_01.hdf5"), OutputFileFormat.HDF5)

Using the package as a library covers this in full.

Where To Go Next