KAHIBARO
20.5. Organizing Simulation Results
Table of Contents
Output directories
When you start running more than a few simulations, keeping your output organized is essential. In GATE you are free to choose directory structures, so it is good practice to decide on a simple and consistent scheme and follow it from the beginning.
A common approach is to create a top-level results directory for your project and then one subdirectory per simulation run. For example, you might have a main folder named results or output, then subfolders grouped by study type, geometry version, or major parameter, and finally per-run folders inside. This lets you keep ROOT files, images, logs, and configuration files together for each run and avoids mixing files from different simulations.
A useful pattern for beginners is:
- A single base directory for all runs of a given project, for example
pet_scanner_sim/results. - Inside it, one directory per run, with a unique run identifier such as a date-time stamp or incrementing run number.
- Within each run directory, separate subfolders for data and plots if needed, for example
root,images,logs,figures.
A simple directory layout can look like this:
| Level | Example name | Typical contents |
|---|---|---|
| Project root | pet_scanner_sim/ | Code, configuration, README |
| All results | pet_scanner_sim/results/ | One folder per run or study |
| Single run | results/run_2024_09_01_01/ | Output files, logs, stored configuration |
| Within a run | root/, images/, logs/ | ROOT data, dose images, text logs, figures |
In Python GATE scripts, always assemble output paths using standard path utilities (for example os.path.join or pathlib) and avoid hard-coding absolute paths. This makes your simulations portable between machines and easier to run on clusters. It is also helpful to let your script create the run directory automatically when you execute it and store all outputs there. That way you never accidentally overwrite results from a previous run.
Finally, if you run parameter sweeps or multi-run studies, add one more level grouping runs by the parameter you change. For instance, a folder per energy window configuration or per scanner geometry version. This helps you quickly find all runs that belong to a given study when you analyze results later.
File naming
Within each output directory, clear and consistent file names are just as important as the directory structure. File names should tell you at a glance what the file contains and which run or configuration it belongs to.
For beginners, a good pattern uses a base name describing the dataset, followed by short tags for key parameters, and ending with the file type. For example:
pet_hits_E350_650keV_run001.rootdose_patientA_beam1_6MV_run003.mhdsingles_ring1_E400_600keV_run010.root
Think about which parameters are most important for interpreting the file without opening it. Typical choices in GATE simulations are:
- The main observable stored in the file, such as
hits,singles,coincidences,dose,phase_space. - The imaging or treatment modality when a project mixes different types, for example
pet,spect,ct,rt. - Key physics or acquisition settings, for example energy window
E350_650keV, a beam energy like150MeV, or a specific radionuclide such asF18orTc99m. - A run identifier, such as
run001or a time stamp like20240901_1530.
You can combine these in a fixed order. A typical naming template is:
<project>_<observable>_<key_parameters>_<run_id>.<extension>
Choosing a consistent order for the pieces makes sorting and filtering easier, both by eye and with scripts.
In Python scripts, try to build file names automatically from variables that already describe your run. For instance, if your configuration dictionary holds energy_window_low, energy_window_high, and run_id, then construct the output names from these variables. This reduces mistakes and keeps names and metadata synchronized.
Use file extensions that clearly reflect the format, for example .root for ROOT trees, .mhd or .nii for images, .csv or .txt for text-based summaries, and .json or .yaml for configuration or metadata files.
Always avoid overwriting important files. Include a unique run identifier in each file name or keep each run in its own directory so that rerunning the same script does not silently replace existing results.
Simulation metadata
Raw data files alone are often not enough to understand or reproduce a simulation. You also need to know how they were produced, which requires simulation metadata. Metadata is all descriptive information that explains the context of the run, such as geometry version, physics list, source details, and random seed.
Good practice is to save this information automatically each time you run a simulation. A simple and flexible way is to collect metadata in a Python dictionary and then write it to a text-based format in the run directory, such as JSON or YAML. This file can include:
- A short description of the purpose of the run.
- The date and time of execution.
- The GATE version and Geant4 version.
- The main geometry version or configuration name.
- Key source parameters, for example radionuclide, activity, energy window, acquisition time.
- Physics list name and any special physics settings.
- Important actor and digitizer settings, for example dose voxel size, energy thresholds, timing windows.
- Random seed values and number of threads.
- The script name and any external configuration file names.
You can also record the exact git commit of your project if you use version control, plus any relevant comments about changes compared with previous runs. This is extremely helpful in long projects where you may revisit results weeks or months later.
Storing metadata in a machine-readable format lets you use it directly during analysis. You can read the metadata file together with your ROOT or image outputs, attach it to plots as labels, and group or filter runs by their recorded parameters. This avoids manual copying of settings into analysis scripts and reduces the risk of confusion.
Whenever possible, keep metadata close to the data. For example, put a metadata.json file next to each ROOT file in the same run directory, or have one run_config.yaml that describes the whole run and lists the produced output files. If you produce several different data types in one run, you can add a small index inside the metadata that maps logical names, such as hits_file or dose_image, to the actual file paths.
For reproducible simulations, always save enough metadata to reconstruct the run: geometry and source configuration, physics list, random seeds, and software versions. Without this information you may not be able to reproduce or validate your own results later.
Views: 12