Tuberculosis PBPK/PD Model Platform

A physiologically-based pharmacokinetic / pharmacodynamic (PBPK/PD) simulation platform for anti-tuberculosis drugs built in PK-Sim® and MoBi® and driven by the esqlabsR R package.

The platform integrates drug-specific PBPK models with a bacterial killing model to simulate Early Bactericidal Activity (EBA) for isoniazid (INH), rifampicin (RIF), pyrazinamide (PZA), ethambutol (EMB), moxifloxacin (MOX), and bedaquiline (BDQ) — as monotherapy and in combination regimens. Simulated EBA trajectories are compared against observed clinical data from published studies.

---

Prerequisites

Tool	Version	Notes
R	4.5.0	Exact version required by renv
Open Systems Pharmacology Suite	12	Required only to re-run simulations; not needed to reproduce reports from pre-computed results
RStudio (recommended)	any	Or another IDE that supports Quarto
Quarto	≥ 1.4	For rendering the reports

---

Getting started

1. Clone the repository

git clone https://github.com/esqLABS/Tuberculosis-model.git
cd Tuberculosis-model

2. Restore R packages

Open the project in RStudio (double-click projects-template.Rproj) and run:

renv::restore()

This installs all required R packages at the exact versions recorded in renv.lock.

3. Restore the project configuration

ProjectConfiguration.xlsx is not stored in the repository but can be regenerated from the committed ProjectConfiguration.json snapshot. Run once after cloning:

esqlabsR::restoreProjectConfiguration()

---

Repository structure

├── Code/
│   ├── workflowConfig.R              # User-editable inputs for all workflow steps
│   ├── runTBScenarios.R              # Step 4 — run TB regimen scenarios
│   ├── runDoseSensitivity.R          # Step 3 — dose–sensitivity analysis
│   └── utils/
│       ├── utils.R                   # Shared helpers: EBA calculation, plot formatting
│       ├── transformDrugParams.R     # Step 1 — convert raw parameter files to Excel
│       └── generateDrugModulePkmls.R # Step 2 — generate drug PKML building blocks
├── Data/
│   ├── EBA_dose.csv                  # Observed clinical EBA values (digitised)
│   └── originalParameters/           # Raw drug parameter text files (input for Step 1)
├── Documentation/
│   ├── Tuberculosis_workflow.qmd     # End-to-end workflow guide (executable Quarto doc)
│   ├── TBModule_ModelDescription.qmd # Mathematical description of the TB disease module
│   └── DRUGModule_ModelDescription.qmd # Mathematical description of the drug PK/PD module
├── Models/
│   ├── PKML/
│   │   └── Modules/
│   │       └── Drug and resistance extension [DRUG].pkml  # Generic drug template
│   ├── Simulations/                  # Ready-to-run mono and combination regimen PKMLs
│   └── Snapshots/                    # MoBi project snapshots
├── Reports/
│   ├── TBScenarios_report.qmd        # EBA scenario results report
│   ├── doseSensitivity_report.qmd    # Dose–response analysis report
│   └── references.bib               # BibTeX references
├── Results/
│   ├── SimulationResults/            # Scenario simulation output CSVs
│   └── Figures/                      # Exported PNG plots
├── ProjectConfiguration.json         # Committed snapshot of ProjectConfiguration settings
├── projects-template.Rproj           # RStudio project file
└── renv.lock                         # Reproducible R package snapshot

---

Reproducing the reports

Pre-simulated results are included under Results/, so PK-Sim/MoBi is not required to render the reports.

From the project root:

quarto render Reports/TBScenarios_report.qmd
quarto render Reports/doseSensitivity_report.qmd

Or render the full workflow document, which sources all steps in order:

quarto render Documentation/Tuberculosis_workflow.qmd

---

Re-running simulations

To re-run scenarios from scratch (requires the OSP Suite):

1. Edit Code/workflowConfig.R to set loadPreSimulatedResults <- FALSE and adjust outputFolder.
2. Open Documentation/Tuberculosis_workflow.qmd and execute the chunks interactively, or render it directly.

The workflow proceeds in four steps:

Step	Script	What it does
1	Code/utils/transformDrugParams.R	Convert raw drug parameter text files to MoBi-compatible Excel
2	Code/utils/generateDrugModulePkmls.R	Generate drug-specific PKML building blocks from a template
3	Code/runDoseSensitivity.R	Simulate EBA across a dose range for each drug
4	Code/runTBScenarios.R	Run all clinical scenario comparisons

---

Running your own simulations

1. Add a new scenario in ProjectConfiguration.xlsx (Scenarios sheet) following the existing entries.
2. Define a plot grid in the PlotGrid sheet if you want a comparison figure.
3. Add the scenario name to Code/workflowConfig.R (or leave scenariosToRun <- NULL to run all).
4. Run Step 4 or render the report with loadPreSimulatedResults <- FALSE.

---

Citation

If you use this platform in your work, please cite the repository:

ESQlabs GmbH. Tuberculosis PBPK/PD Model Platform. GitHub. https://github.com/esqLABS/Tuberculosis-model

A Zenodo DOI for a versioned release will be added here upon publication.

---

License

To be added.