VOxA — Voxel-Aware Oxygen Model

Code and data for "Voxel-aware oxygen kinetics resolves radiation-induced DNA damage retention across LET–oxygen conditions" (Bolo & Bagunu, 2026, submitted to Physics in Medicine and Biology).

Overview

VOxA predicts the oxygen enhancement ratio (OER) for DNA double-strand break (DSB) retention at particle-therapy-relevant LET and oxygen tension. It has two tiers:

• Oxygen Model (OM): Population-level OER via dual sigmoidal LET transitions with Z-ordering constraints and Michaelis–Menten oxygen kinetics. Calibrated on 233 OER observations from 29 published sources spanning 10 particle types.
• Voxel-Aware (VA) extension: Per-DSB retention probability using local energy heterogeneity from TOPAS-nBio 4.0 track-structure simulations.

Repository structure

├── README.md
├── .gitignore
├── session_info.txt
│
├── step1_extract_furusawa_complete.R
├── step2_compile_literature.R
├── step3_particle_specific_dual_transitions.R
├── step4_comprehensive_validation.R
├── step5_comprehensive_validation_extended.R
├── step6_uncertainty_analysis.R
├── step7_bootstrap_ci_analysis.R
├── step8_cross_validation.R
├── step9_recalibrate_voxel_aware.R
├── step10_voxa_va_diagnostics.R
├── step11_voxa_scaling_validation.R
├── step12_dsb_retention_table.R
│
├── extract_energy_features_voxa.py
├── voxa_model.py
├── voxa_manuscript_figures.py
│
├── calibration_data/
│   ├── {electron,proton,carbon}_EnergyDeposit.csv   # Raw TOPAS-nBio energy deposits
│   └── {electron,proton,carbon}_dsb_complexity.csv  # DSB complexity per track (~2500 DSBs)
│
├── validation_data/
│   ├── {electron,proton,carbon}_EnergyDeposit.csv   # Independent simulation run
│   └── {electron,proton,carbon}_dsb_complexity.csv  # (~400 DSBs, same format)
│
├── voxa_features_output_calibration/
│   ├── all_particles_calibration_energy_features.csv
│   ├── combined_calibration_statistics.json
│   └── {electron,proton,carbon}_calibration_{dsb_energy_features.csv,energy_statistics.json}
│
└── voxa_features_output_validation/
    ├── all_particles_validation_energy_features.csv
    ├── combined_validation_statistics.json
    └── {electron,proton,carbon}_validation_{dsb_energy_features.csv,energy_statistics.json}

The data/, results/, and figures/ directories are generated by the scripts and are not tracked.

Data description

calibration_data/ and validation_data/ contain the raw TOPAS-nBio 4.0 simulation output for electron, proton, and carbon ions. The calibration arm has ~2500 DSBs per particle and was used to fit the VA delta_f parameters (step 9). The validation arm has ~400 DSBs per particle and was used for the sample-size invariance tests (step 11). The files have the same names across both folders but contain independent simulation runs.

voxa_features_output_calibration/ and voxa_features_output_validation/ contain the per-DSB local energy features extracted from the raw simulation files by extract_energy_features_voxa.py. These are the direct inputs to steps 9–12. They are included here so the VA analysis can be reproduced without re-running the feature extraction.

Running the analysis

Run R scripts in order from the project root:

Rscript step1_extract_furusawa_complete.R
Rscript step2_compile_literature.R
# ... through step12

Before running the manuscript figure script, export model parameters from R (see the docstring at the top of voxa_manuscript_figures.py). Then:

python voxa_manuscript_figures.py

Step 7 (bootstrap) takes 20–60 minutes. All other steps are fast.

Requirements

R (≥ 4.3):

install.packages(c("tidyverse", "MASS", "minpack.lm", "boot",
                   "jsonlite", "gridExtra", "car", "cowplot",
                   "scales", "viridis"))

Python 3.14:

numpy
pandas
scipy
matplotlib

See session_info.txt for exact package versions.

OER calibration data sources

The 233-observation OER calibration dataset for the OM tier is compiled from the sources listed in Appendix C of the manuscript. Furusawa et al. (2000) data (He, C, Ne ions; V79 and HSG cells) were extracted directly from published D₁₀ tables. Tinganelli et al. (2015) data for intermediate oxygen levels extend the coverage beyond the standard Wenzl & Wilkens (2011) compilation. These are assembled by steps 1–2 and written to data/ at runtime.

Contact

Renato III Fernan Bolo
Department of Physical Sciences and Mathematics, University of the Philippines Manila
rfbolo@up.edu.ph