AMMPER-2

Agent-Based Model for Microbial Populations Exposed to Radiation

AMMPER-2 is a research simulation for studying how ionizing radiation affects microbial populations. It models cell growth, direct radiation damage, reactive oxygen species (ROS), and DNA repair on a three-dimensional lattice. The model supports wild-type and rad51 yeast phenotypes, proton and gamma exposures, ground-test and deep-space environments, and both basic static and diffusion-and-decay ROS treatments.

The repository contains the simulation engine, command-line and graphical interfaces, bundled RITRACKS radiation-track inputs, experimental data, analysis code, and scripts used to reproduce manuscript figures. AMMPER is research software and is not intended for clinical or operational radiation risk decisions.

Repository contents

Path	Contents
src/	Simulation entry points and the ammper model modules
gui/	PyQt5 graphical interface and GUI assets
data/	Experimental data, fluence tables, and radiation-track inputs
analysis/	Growth-curve, alamarBlue, ROS, gamma, and statistical analyses
results/	Archived simulation results and figure source assets
figures/	Generated publication figures
revisions_2026/	Manuscript-revision code, figures, and source files
ammper_paths.py	Repository-relative path helpers

Installation

AMMPER's supplied environment targets Python 3.10. The versions in requirements.txt are used for the main simulation and GUI.

1. Clone the repository and enter it:

   git clone https://github.com/nasa/AMMPER.git
   cd AMMPER

2. Create and activate a virtual environment:

   python3.10 -m venv .venv
   source .venv/bin/activate

   On Windows PowerShell:

   .venv\Scripts\Activate.ps1

3. Install the dependencies:

   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

Run commands from the repository root. Scripts use ammper_paths.py to find bundled inputs and output directories independent of the clone location.

Dependencies

Dependency	Version	Purpose
Matplotlib	3.7.2	Plotting and figure generation
MoviePy	1.0.3	GUI video generation
NumPy	1.25.2	Arrays and numerical simulation
pandas	2.1.0	Experimental and simulation data handling
PyQt5	5.15.9	Graphical interface
scikit-learn	1.3.0	Data splitting and analysis utilities
SciPy	1.11.2	Scientific calculations and ROS distributions

FFmpeg is also needed to export videos through MoviePy. Some specialist or legacy analysis scripts have dependencies not installed by requirements.txt, including SMAC/ConfigSpace, OpenPyXL, statsmodels, pingouin, COBRApy, and R packages. Inspect the imports in the particular script before running it. The core simulation and figure commands below use the pinned requirements.

Usage

Interactive command-line simulation

Start the prompt-driven interface:

python src/AMMPERCLI.py

The program asks for the radiation environment, dose where applicable, cell type, and ROS model. Interactive runs write their description, cell-state data, and plots beneath a timestamped Results/ directory.

Scripted simulation

For a non-interactive proton run:

python src/AMMPERBulk_aB.py a a a 2.5 WT_Basic_25

The five positional arguments are:

1. radiation: a = 150 MeV proton, b = GCRSim, c = deep space, d = gamma;
2. cell type: a = wild type, b = rad51;
3. ROS model: a = basic, b = diffusion and decay;
4. dose in Gy (proton mode supports 0, 2.5, 5, 10, 20, and 30); and
5. output-group name.

This example writes timestamped output under results/bulk_aB/WT_Basic_25/. The bulk runner intentionally waits 61 seconds at the end to prevent timestamp collisions. Pass the single-letter codes shown above; expanded names are not accepted.

Graphical interface

python gui/AMMPERGUI.py

A desktop session is required. Video export also requires FFmpeg on the system path.

Reproduce the main figure panels

The repository includes the required archived output and panel assets:

python analysis/growth_curves/stack_growth_curves.py
python analysis/aB/ab_final_plots_panel.py
python analysis/aB/stack_ab_figures.py

Generated PDF, PNG, and SVG files are written to figures/. The manuscript and revision-specific reproduction scripts are in revisions_2026/; those scripts may require the optional dependencies noted above.

Contributing

Contributions that improve correctness, reproducibility, documentation, or usability are welcome.

1. Open an issue describing the bug or proposed change. For model changes, explain the scientific rationale and expected effect on results.
2. Fork the repository, create a focused branch, and keep unrelated changes in separate commits.
3. Use four-space indentation, descriptive names, docstrings for reusable functions, and repository-relative paths through ammper_paths.py. Do not introduce machine-specific absolute paths.
4. Update documentation and dependency declarations when setup or behavior changes. Do not commit local environments, caches, or newly generated bulk results unless they are required reference data.
5. Submit a pull request summarizing the change and validation commands. Identify altered numerical output or regenerated figures, and include before-and-after output when scientific results change.

Because the project does not yet have a license, prospective contributors should confirm contribution and redistribution terms with the maintainers before submitting code.

License

Contact

For scientific or project questions, contact the manuscript's corresponding author, Jessica Lee, at jessica.a.lee@nasa.gov.

For bug reports, feature requests, and contribution proposals, use the GitHub issue tracker so discussion and resolution remain visible to the project team.