KAHIBARO
39.4. Reproducible Research
Table of Contents
Saving configuration
Reproducible research in GATE starts with treating your simulation setup as a first‑class result. Anyone, including your future self, should be able to re‑run exactly the same simulation and obtain statistically compatible results. This is only possible if the entire configuration is saved in a clear and machine‑readable way.
In Python‑based GATE simulations, the simulation configuration usually lives inside a script that creates the simulation object, defines geometry, materials, sources, physics, actors, digitizers, and output. The script itself is already a form of configuration, but you should not rely on code alone. Code can change silently over time, and you may run the same script with different parameters without leaving a trace. For proper reproducibility, treat the simulation parameters as data that you save together with the results.
A common strategy is to separate parameters from code. The Python script defines the structure of the simulation, while a configuration file contains all values for scanner dimensions, source activity, physics list choices, number of events, and so on. Typical text formats that work well with GATE are JSON, YAML, or simple INI‑style files. The script reads this configuration at runtime, constructs the simulation, and writes a copy of the used configuration into the output directory. This makes it obvious which exact configuration produced a given dataset.
You should also consider how to manage multiple runs. For example, if you scan several values of activity or different geometries, you can create a directory structure such as results/sim_001, results/sim_002, and so on, where each directory contains both the simulation outputs and a dedicated configuration file that fully describes that run. Using a systematic naming scheme for runs and including a short text description in each folder helps you to track the purpose of each simulation later.
An important part of saving configuration is versioning. If you use version control software like Git, each commit represents a specific state of your simulation scripts and helper modules. By recording the Git commit hash in your configuration or output files, you can always return to the exact code that generated a dataset. It is good practice to only produce "official" results from clean, committed code, so that every run can be traced back to a versioned snapshot.
In addition to code and parameter files, record environment information that can influence results. This includes the versions of GATE, Geant4, Python, and major Python packages. For long‑term reproducibility, small changes in physics lists or random number engines between software versions can lead to slightly different results. If you record the full software environment, you can later rerun with the same versions, for example using containers such as Docker or Singularity on a computing cluster.
Finally, consider exporting a minimal summary of configuration in a human‑readable text file in the result directory. This summary can list the main choices: geometry model name, source type and activity, energy window, physics list, production cuts, random seed strategy, number of events, and so on. Such a summary offers a quick overview without opening any code.
For reproducible research, always save:
- The simulation scripts or their version control reference.
- A machine‑readable configuration file used in the run.
- The software environment versions, including GATE and Geant4.
- A human‑readable configuration summary stored with the outputs.
Recording simulation parameters
Saving configuration defines what should be reproducible. Recording simulation parameters documents what actually happened in each run. These parameters include not only the intended settings but also all relevant details that may vary between runs, such as random seeds, event counts, timing information, and resource usage.
In a typical GATE workflow, you can record parameters at several levels. At the start of the simulation, you can write out the initial conditions: random seed values, number of events or total activity, acquisition duration, geometry identifiers, physics list name, and any region specific cut values. At the end of the run, you can record outcome metrics: total number of generated primaries, number of simulated tracks and steps, number of hits, singles, coincidences, or dose voxels with nonzero values. Many of these quantities are already collected by simulation statistics actors. You can treat their outputs as part of your reproducibility record.
It is helpful to store these parameters in structured formats that are easy to inspect and analyze, such as JSON or CSV. A simple JSON file per simulation run can contain keys like "random_seed", "n_events", "world_size_mm", "physics_list", "source_activity_Bq", "acquisition_time_s", and so on. When you need to reproduce a study or debug unexpected results, you can load this file and compare it with another run to see what changed.
Random seeds deserve special attention. To reproduce exactly the same stochastic history, you must record the initial seed or seeds used by the random engines. In multithreaded GATE simulations, each worker thread can have its own seed sequence. GATE and Geant4 can automatically manage thread seeds starting from a global seed. For precise reproducibility, write the global seed and, if available, the per thread seeds into your parameter record. When you re run with the same seeds, you should obtain the same sequences of random numbers and therefore the same event histories.
Another useful category of parameters is derived quantities that characterize the simulation conditions. For instance, if you define a source in terms of activity and acquisition time, you can record the implied expected number of decays as $N = A \times T$, where $A$ is activity and $T$ is acquisition duration. If you use a fixed number of primary particles instead, record both the requested and actually simulated numbers, because early termination or failures might lead to fewer events than specified.
For long runs or parameter studies performed on clusters, you should also store information about where and how the simulation ran. This can include the host name or cluster node, number of threads, wall time, CPU time, and memory usage. Although these do not change the physics, they are important for method sections of publications and for planning future simulations.
To make recorded parameters directly useful, integrate them into your analysis scripts. For example, your plotting code can read the parameter file alongside the simulation output and automatically include labels such as activity, acquisition time, or beam energy in figure titles and axis labels. This reduces manual copying of values and helps to avoid reporting mistakes.
You can summarize the essential parameters in a single dictionary in your Python script and write it to disk before starting the simulation. You can then add additional fields, such as final statistics, after the run completes. This approach guarantees that at least the intended setup is recorded even if the simulation fails or is interrupted.
Always record at least:
- Random seed values.
- Number of primary events or total activity and acquisition time.
- Geometry and physics list identifiers.
- Key actor and digitizer settings, such as dose grid size or energy windows.
- Basic performance metrics, such as number of hits or coincidences.
These recorded parameters are essential to reproduce, compare, and interpret GATE simulations reliably.
Views: 4