opengate-gate-tree

opengate-gate-tree is a utility for processing GATE 9 output ROOT file with trees (Hits, Singles,Coincidences)

Supported GATE Versions

The package targets the C++ line of GATE, version 9.4.2 and newer. GATE 10, the Python implementation, is not supported.

Output files are not meant to be read back by GATE. They are conversions of the simulation output into whichever format suits the analysis that follows:

Quick Start

Install From PyPI

pip3 install opengate-gate-tree

Install From Source

make init
make install

Command-Line Options

The CLI accepts the following options:

Validation behavior:

• the input file must exist, end with .root and be readable as a ROOT file
• the output directory is created if it does not exist
• an existing output file is overwritten without a prompt
• all required options above must be provided
• the selected tree must be present in the input file; if it is not, the error lists the trees the file actually holds
• branch names are validated against the branches present in the input file
• branches whose length varies per entry are reported as unsupported

The output file holds the extracted tree only. Histograms stored next to the trees in a GATE file are not copied over.

Fixed-width array branches, such as volumeID, keep their shape in the root and hdf5 output. CSV has no cell for an array, so they are written there as one column per component, named volumeID_0 to volumeID_9.

Examples:

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

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

Library Usage

Besides the command-line interface, the package can be used directly from Python code. Everything the command line does is reachable from opengate_gate_tree.

Loading And Exporting Files

from pathlib import Path

from opengate_gate_tree import (
    GateTree,
    OutputFileFormat,
    read_tree,
    write_tree,
)

# Load selected branches of the "Hits" tree from a GATE ROOT file.
data = read_tree(
    Path("simulation.root"),
    GateTree.HITS,
    ["eventID", "edep", "posX", "posY", "posZ"],
)

print(data.entry_count, data.branch_names)

# Work with the data as NumPy arrays or as a pandas.DataFrame.
energies = data["edep"]
frame = data.to_dataframe()

# Export to the format that fits the downstream analysis.
write_tree(data, Path("out/hits.hdf5"), OutputFileFormat.HDF5)

Omit the branch list to read every branch of the tree:

data = read_tree(Path("simulation.root"), GateTree.HITS)

When several trees come from the same file, open it once with RootFile:

from opengate_gate_tree import RootFile

with RootFile(Path("simulation.root")) as root_file:
    print(root_file.tree_names)
    hits = root_file.read(GateTree.HITS, ["eventID", "edep"])

Failures while reading or writing files are reported through a subclass of GateTreeError, so one except clause covers them. Malformed arguments, such as an empty branch name, raise ValueError instead:

from opengate_gate_tree import GateTreeError, TreeNotFoundError

try:
    data = read_tree(Path("simulation.root"), GateTree.SINGLES)
except TreeNotFoundError as error:
    print(f"tree missing: {error}")
except GateTreeError as error:
    print(f"could not process the file: {error}")

The package does not configure logging on import. Applications that want the defaults used by the command line can ask for them:

from opengate_gate_tree.logging_setup import configure_logging

configure_logging()

The package ships a py.typed marker, so type checkers see its annotations.

Available Package Capabilities (Cumulative)

This section is append-only. Add a capability entry only when its roadmap stage status changes from planned to completed.

Current development stage: version-0.2.1

Available capabilities:

• 0.1.0: project structure initialized and minimal buildable package code added.
• 0.2.0: GATE ROOT files can be loaded and validated, trees and branches extracted into a NumPy-backed representation with a pandas view, and written to ROOT, HDF5 or CSV. Usable both as a command-line tool and as a library, with user documentation on ReadTheDocs.

Development

Common development commands:

make lint
make format
make typecheck
make test
make check

Pre-commit setup

You can install and activate pre-commit in two supported ways.

Option A (recommended): use uv in this repository

uv add --dev pre-commit
uv sync
uv run pre-commit install --hook-type pre-commit

Optional one-time verification on all files:

uv run pre-commit run --all-files

Option B: install pre-commit from Debian packages

sudo apt update
sudo apt install -y pre-commit
pre-commit --version
pre-commit install --hook-type pre-commit

Optional one-time verification on all files:

pre-commit run --all-files

The configured hook runs make check before each commit and blocks the commit if validation fails.

Documentation

The user documentation is built with Sphinx:

make docs        # build docs/_build/html
make docs-check  # build with warnings treated as errors, as ReadTheDocs does

Project conventions and contribution standards:

• Coding conventions
• Testing conventions
• Commit conventions
• Contribution guide

License

MIT License

Contact: GitHub

Author

The project was designed and implemented by Mateusz Jakub Bała.

Contact: GitHub

Contribution

To contribute new functionality:

• create a branch from develop
• follow the commit conventions
• open a PR using the PR template
• follow the contribution guide