AMR Hub ABM

An agent-based model (ABM) for simulating the spread of Antimicrobial Resistant (AMR) infections in hospital settings.

This project is developed in collaboration with the Centre for Advanced Research Computing, University College London.

Overview

amr-hub-abm is a Python package that provides a framework for modeling and analyzing the transmission dynamics of antimicrobial-resistant pathogens within healthcare facilities. The simulation incorporates spatial modeling, agent behavior, and task management to provide realistic representations of hospital environments and infection spread patterns.

Key Features

Spatial modeling: Representation of hospital buildings, floors, and room layouts
Agent-based simulation: Model individual agents (patients, healthcare workers) with distinct behaviors
Task management: Simulate realistic workflow patterns with priority-based task assignment
Flexible architecture: Extensible design for incorporating custom behaviors and scenarios

Installation

Prerequisites

amr-hub-abm requires Python 3.13 or higher.

We recommend using a virtual environment manager such as Conda or venv to create an isolated environment for the package.

Install from GitHub

To install the latest development version directly from GitHub:

pip install git+https://github.com/UCL-ARC/amr-hub.git

Install from Source (Development)

For development or to make local modifications:

Clone the repository:

git clone https://github.com/UCL-ARC/amr-hub.git
cd amr-hub/python-code

Install in editable mode:

pip install -e .

Optional Dependencies

Install additional dependencies for development and documentations:

# For development tools (testing, linting, etc.)
pip install -e ".[dev]"

# For building documentation
pip install -e ".[docs]"

# For running tests
pip install -e ".[test]"

Usage

Running the simulation

The simulation is driven by simulate() in src/amr_hub_abm/run.py, which is called by example driver scripts in examples/.

Configuration

Simulation parameters are defined in tests/inputs/simulation_config.yml:

mode: data driven # "data driven" or "rule based"
location_data:
  format: duckdb
  path: tests/inputs/location_timeseries.duckdb
  table: location_timeseries
  schema_version: 1
buildings_path: tests/inputs/buildings.yml # building/floor/room layout
start_time: 2024-01-01 00:00:00
end_time: 2024-01-02 00:00:00
length_of_timestep_in_seconds: 1

The location-event table defines the schedule for each healthcare worker (HCW): which patient to attend, when, which doors to access, and where to sit. The DuckDB file is opened read-only and checked before the simulation starts. Schema, version, event values, timestamps, and references to rooms, doors, and room content must all pass validation.

The expected DuckDB database contains an amr_hub_schema metadata table and a location_timeseries event table or trusted view. Events are processed deterministically using the explicit event_sequence column. The synthetic test database at tests/inputs/location_timeseries.duckdb is an example of schema version 1.

Legacy CSV input remains available during the migration period:

location_timeseries_path: tests/inputs/location_timeseries.csv

That setting is deprecated and emits a DeprecationWarning. CSV input is normalized to the same in-memory columns and goes through the same preflight validation as DuckDB input.

Running from the terminal

The simplest way to run a simulation is via examples/simple.py:

uv run python examples/simple.py

This calls simulate() with default flags. To customize, edit simple.py and pass arguments to simulate():

Flag	What it does
`live=True`	Opens a matplotlib window that updates every step. Blocks until window closed.
`plot=True`	Saves a PNG of the floorplan to `simulation_outputs/` every step.
`record=True`	Records each agent's position trajectory at every step.
`plot_trajectory=True`	At end of run, saves a PNG showing all agent trajectories overlaid.
`seed_infections=True`	Manually set agent[0] to INFECTED and agent[1] to EXPOSED for viz testing.

For example, to record trajectories and produce a final overlay PNG:

simulate(record=True, plot_trajectory=True)

Output files

Running with record=True and/or plot_trajectory=True produces files in simulation_outputs/ (relative to repo root):

agent_<type>_<id>_trajectory.csv — per-agent positions over time
Sample Hospital_time_<N>.png — per-step floorplan snapshots (with plot=True)
Sample Hospital_trajectories.png — overlay of all agent paths (with plot_trajectory=True)

These are gitignored — they're generated artifacts.

Browser-based visualization (SolaraViz)

For an interactive browser-based view with play/pause/step controls, use the Solara app:

uv run solara run /full/path/to/examples/solara_app.py

This opens a web page at http://localhost:8765 showing the floorplan, agents, and infection status updating in real time. Use the controls panel to play, pause, step, or reset the simulation, and adjust the render interval to balance speed and smoothness.

The Solara app currently seeds two agents with infection status (one INFECTED, one EXPOSED) for visualization testing. Disease dynamics are not yet implemented in the simulation itself.

Development

Running Tests

Tests can be run across all compatible Python versions in isolated environments using tox:

tox

To run tests manually with pytest:

pytest tests

To run tests with coverage reporting:

pytest --cov --cov-report=xml

Building Documentation

Build the MkDocs HTML documentation locally:

tox -e docs

The built documentation will be written to the site/ directory.

Alternatively, to build and preview the documentation with live reloading:

mkdocs serve

Then open your browser to http://localhost:8000.

Code Quality

This project uses several tools to maintain code quality:

pre-commit: Git hooks for automatic code formatting and linting
ruff: Fast Python linter and formatter
mypy: Static type checker

To set up pre-commit hooks:

pre-commit install

To manually run all pre-commit hooks:

pre-commit run --all-files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to:

Update tests as appropriate
Follow the existing code style
Run the test suite before submitting

Contributors

_{Arindam Saha} 💻 📖 ⚠️ 🚧 🔬 🐛 👀	_Dependabot 🛡️	_{Ed Manley} 🔍 🤔 🧑‍🏫	_{George Svarovsky} 🚇	_{James Hetherington} 🤔 🧑‍🏫 🔍	_{Keiran Suchak} 💻 📖 ⚠️ 🔌 🔬 👀	_{Lauren Sheridan} 🚇
_Marlon 🚇	_MonikaSvata 📆	_{Paul Smith} 🔣 🚇	_{Sarah Keating} 🚇	_{Sarah Wise} 🤔 🧑‍🏫	_nicolin 👀	_yidilozdemir 📖 🔬 💻