Skip to contents

epiworldRcalibrate

epiworldRcalibrate: Fast and Effortless Calibration of Agent-Based Models using Machine Learning

From the DESCRIPTION:

The ‘epiworldRcalibrate’ package provides tools and pre-trained Machine Learning [ML] models for calibration of Agent-Based Models [ABMs] built with the R package ‘epiworldR’. It implements methods described in Najafzadehkhoei, Vega Yon, Modenesi, and Meyer (2025) doi:10.48550/arXiv.2509.07013. Using ‘epiworldRcalibrate’, users can automatically calibrate ABMs in seconds with its pre-trained ML models, effectively focusing on simulation rather than calibration. This tool bridges a gap by allowing public health practitioners to run their own ABMs without the advanced technical expertise often required by calibration.

epiworldRcalibrate provides fast, data-driven calibration of SIR epidemic parameters using a pretrained Bidirectional LSTM (BiLSTM) model. Given a single incidence time series, the package estimates:

  • Transmission rate (ptran)
  • Contact rate (crate)
  • Basic reproduction number (R0)

The package is fully integrated with epiworldR and requires no external Python setup.

🚀 Features

  • One-line calibration via calibrate_sir()
  • Automatic deep learning backend (initialized on demand)
  • Compatible with all epiworldR SIR simulations
  • Designed for reproducible epidemic modeling workflows

📦 Installation 

# Install from GitHub
devtools::install_github("sima-njf/epiworldRcalibrate")

🔧 Quick Example 

library(epiworldR)
library(epiworldRcalibrate)

# simulate SIR model
m <- ModelSIRCONN("sim", n=8000, prevalence=0.01,
                  contact_rate=3, transmission_rate=0.25,
                  recovery_rate=0.1)
run(m, ndays = 60)

inc <- plot_incidence(m)[,1]

# one-line calibration
calibrate_sir(
  daily_cases = inc,
  population_size = 8000,
  recovery_rate = 0.1
)

🎯 What This Package Is For

Use epiworldRcalibrate when you want to:

  • Extract SIR parameters directly from simulated incidence curves
  • Compare ground-truth vs. calibrated dynamics
  • Avoid heavy Bayesian/likelihood-based fitting
  • Teach or study calibration in infectious disease modeling
  • Perform fast approximate inference in simulation studies

📘 Documentation

Full website, reference, and vignette: 👉 https://sima-njf.github.io/epiworldRcalibrate/

👤 Author

Developed by Sima Najafzadehkhoei 🔗 https://github.com/sima-njf