TBsim

TBsim is an agent-based model for simulating tuberculosis transmission, disease progression, and treatment outcomes in populations. Built on the Starsim agent-based modeling platform, it enables researchers to evaluate intervention strategies, explore disease dynamics under different conditions, and inform TB control policy decisions.

Note: TBsim is still under active development; results may change without warning.

Introduction

Tuberculosis is a major global health problem, and understanding its dynamics can help in developing better strategies for control and treatment. This project uses the Starsim package to simulate TB spread in a population, considering factors like transmission rates, treatment efficacy, and social dynamics.

TBsim uses an agent-based implementation of the LSHTM “spectrum of TB disease” natural history (susceptible → infection/cleared → non-infectious → asymptomatic → symptomatic → treatment/treated/death), designed to support evaluating active case-finding / population-wide screening algorithms (e.g., CXR and NAAT workflows) as in Schwalb et al. 2025 (PLOS Glob Public Health).

Getting started

Installation

TBsim is not yet released on PyPI, so you need to install from source:

Clone the repository:

git clone https://github.com/starsimhub/tbsim.git
cd tbsim

Install the required packages:
```
pip install -e .
```

Project structure

tbsim/ – Core package (disease models, interventions, analyzers, networks, comorbidities)
tbsim_examples/ – Ready-to-run example scripts
tests/ – Test suite
docs/ – Documentation source (Quarto)

Running a sample simulation

Navigate to the folder tbsim_examples
Run the script:
```
python run_tb.py
```
Running this script should result in basic charts being displayed.

Or run directly in Python:

import starsim as ss
import tbsim

sim = ss.Sim(diseases=tbsim.TB(), networks='random', demographics=True, start=2000, stop=2010, dt='month')
sim.run()
sim.plot()

Usage

Usage examples are available in the tbsim_examples folder.

Documentation

TBsim documentation is available at starsim.org/tbsim.

TBsim is based on Starsim; please refer to Starsim documentation for additional information.

Contributing

Contributions to the TBsim project are welcome! Please read contributing.md for details on our code of conduct, and the process for submitting pull requests.