Command line and errors

Errors

Exception hierarchy raised by the package.

All errors reported by the library derive from GateTreeError, so code using the package as a library can catch every package-specific failure with a single except clause.

The hierarchy deliberately does not derive from ValueError. A file that cannot be opened is not an invalid value, and merging both cases would make it impossible to tell argument validation apart from input/output failures.

Public objects:

GateTreeError

Base class for every error raised by the package.

RootFileError

The ROOT file cannot be opened or is not a valid ROOT file.

TreeNotFoundError

The requested tree is not present in the ROOT file.

AmbiguousTreeError

Several trees in the file could be the requested one.

BranchNotFoundError

One or more requested branches are not present in the tree.

UnsupportedBranchTypeError

A branch uses a type that the package does not support.

UnknownHitsVariantError

The structure of a “Hits” tree could not be recognised, or was recognised as one the package does not support.

HitsTreeValidationError

A “Hits” tree does not match the structure it was recognised as.

TreeMergeError

Trees cannot be placed one after another into a single dataset.

ExportError

The output file cannot be written.

exception opengate_gate_tree.errors.GateTreeError

Bases: Exception

Base class for every error raised by the package.

exception opengate_gate_tree.errors.RootFileError

Bases: GateTreeError

Raised when a ROOT file cannot be opened or is not a valid ROOT file.

exception opengate_gate_tree.errors.TreeNotFoundError

Bases: GateTreeError

Raised when the requested tree is not present in the ROOT file.

exception opengate_gate_tree.errors.AmbiguousTreeError

Bases: GateTreeError

Raised when several trees in a file could be the requested one.

A file can hold the hits of one run per tree, or of one sensitive detector per tree. Picking one of them would decide something the caller never asked the package to decide, so they are all reported instead.

exception opengate_gate_tree.errors.BranchNotFoundError

Bases: GateTreeError

Raised when requested branches are not present in the tree.

exception opengate_gate_tree.errors.UnsupportedBranchTypeError

Bases: GateTreeError

Raised when a branch uses a type that the package does not support.

exception opengate_gate_tree.errors.UnknownHitsVariantError

Bases: GateTreeError

Raised when the structure of a “Hits” tree is not a supported one.

Covers both a tree whose branches match none of the known structures and one recognised as a structure the package does not support, such as the output of the Compton camera actor.

exception opengate_gate_tree.errors.HitsTreeValidationError

Bases: GateTreeError

Raised when a “Hits” tree does not match its recognised structure.

Covers a branch the structure describes but the tree does not hold, and a branch stored with a type other than the expected one. Branches beyond the structure are reported as a warning instead, because GATE builds routinely add them.

exception opengate_gate_tree.errors.TreeMergeError

Bases: GateTreeError

Raised when trees cannot be merged into a single dataset.

Trees stored under several names hold the same structure when they come from one simulation. Different branches, or a branch stored with another type, mean they do not, and concatenating them would produce a dataset that describes nothing.

exception opengate_gate_tree.errors.ExportError

Bases: GateTreeError

Raised when the output file cannot be written.

Run configuration

Tool runtime configuration.

The module defines RunConfig, which stores parsed runtime arguments: input/output paths, optional output title, and operation mode flags.

Public objects:

RunConfig

Immutable set of parameters for a single tool run.

class opengate_gate_tree.config.RunConfig(input_gate_root_file, output_dir, output_file_title, gate_tree, output_file_format, branches_to_extract=<factory>, input_tree_name=None, merge_hits_trees=False, write_statistics=False, skip_hits_validation=False)

Parameters for a single tool run.

Parameters:

• input_gate_root_file (Path | None)

• output_dir (Path | None)

• output_file_title (str | None)

• gate_tree (GateTree | None)

• output_file_format (OutputFileFormat | None)

• branches_to_extract (list[str])

• input_tree_name (str | None)

• merge_hits_trees (bool)

• write_statistics (bool)

• skip_hits_validation (bool)

input_gate_root_file

Path to the gate *.root file to process.

Type:

Path

output_dir

Path to the directory where the output files will be saved.

Type:

Path

output_file_title

Title of the output file (without extension).

Type:

str | None

gate_tree

The gate tree structure loaded from the input file.

Type:

GateTree

output_file_format

Format of the output file.

Type:

OutputFileFormat | None

branches_to_extract

List of branch names to extract from the gate tree.

Type:

list[str]

input_tree_name

Name of the tree in the input file, when it differs from the standard one or when the file holds several trees of hits.

Type:

str | None

merge_hits_trees

Whether to read every tree of hits in the file as a single dataset.

Type:

bool

write_statistics

Whether to write a report describing the extracted data.

Type:

bool

skip_hits_validation

Whether to extract the branches without recognising and checking the structure of the “Hits” tree.

Type:

bool

Entry point

Package command-line interface.

The module defines the entry point used by python -m opengate_gate_tree and the opengate-gate-tree console script.

Public functions:

build_parser() -> argparse.ArgumentParser

Builds the command-line argument parser.

main(argv: list[str] | None = None) -> int

Parses arguments, runs the processing pipeline, and returns an exit code.

opengate_gate_tree.cli.build_parser()

Build the command-line argument parser.

Returns:

Configured parser with all tool flags.

Return type:

argparse.ArgumentParser

opengate_gate_tree.cli.main(argv=None)

Run the tool from the command line.

Parameters:

argv (list[str] | None) – List of arguments to parse. If None, arguments from sys.argv are used.

Returns:

Process exit code (0 means success, 1 means processing error).

Return type:

int

Logging

Logging configuration for the tool.

The module configures the package logger (level, format, stream) so diagnostics and user messages use the logging module instead of print.

Public functions:

configure_logging(level: int = logging.INFO) -> None

Configure the package logger (idempotent).

get_logger(name: str) -> logging.Logger

Return a logger with the given name.

opengate_gate_tree.logging_setup.configure_logging(level=20)

Configure the package logger.

This function is idempotent: calling it repeatedly does not add duplicate handlers, it only updates the logging level.

Importing the package attaches a NullHandler so that library use stays silent. That placeholder does not count as a handler here, otherwise configuring the logger after the import would leave it without any output.

Parameters:

level (int) – Logging level (for example logging.INFO).

Return type:

None

opengate_gate_tree.logging_setup.get_logger(name)

Return a logger with the given name.

Parameters:

name (str) – Logger name (usually __name__ of the calling module).

Returns:

Logger with the given name.

Return type:

logging.Logger

Convenience access to the package logger.

opengate_gate_tree.logger.log()

Return the package logger configured under the package logger name.

Return type:

Logger