| Title: | Fast and Effortless Calibration of Agent-Based Models using Machine Learning |
|---|---|
| Description: | Provides tools and pre-trained Machine Learning [ML] models for calibration of Agent-Based Models [ABMs] built with the R package 'epiworldR'. Implements methods described in Najafzadehkhoei, Vega Yon, Modenesi, and Meyer (2025) <doi:10.48550/arXiv.2509.07013>. Users can automatically calibrate ABMs in seconds with pre-trained ML models, effectively focusing on simulation rather than calibration. Bridges a gap by allowing public health practitioners to run their own ABMs without the advanced technical expertise often required by calibration. |
| Authors: | Sima Najafzadehkhoei [aut, cre] (ORCID: <https://orcid.org/0009-0002-6253-2910>), George Vega Yon [aut] (ORCID: <https://orcid.org/0000-0002-3171-0844>), Jake Wagoner [aut], Bernardo Modenesi [aut], Centers for Disease Control and Prevention [fnd] (Award number 1U01CK000585; 75D30121F00003) |
| Maintainer: | Sima Najafzadehkhoei <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3 |
| Built: | 2026-06-01 09:40:11 UTC |
| Source: | https://github.com/sima-njf/epiworldrcalibrate |
Results from Approximate Bayesian Computation (ABC) calibration of an SIR network model fitted to Utah COVID-19 incidence data.
abc_calibration_paramsabc_calibration_params
A named list with the following elements:
Posterior median of the contact rate.
Posterior median of the recovery rate.
Posterior median of the transmission probability.
Basic reproduction number computed from posterior medians.
95 percent credible interval for the contact rate.
95 percent credible interval for the recovery rate.
95 percent credible interval for the transmission probability.
Total runtime of the ABC calibration (seconds).
Number of MCMC samples used in calibration.
Number of burn-in iterations discarded.
ABC tolerance parameter.
Random seed used for reproducibility.
Matrix of post-burn-in accepted parameter samples.
Acceptance rate of the ABC-MCMC algorithm (percent).
Generated internally using the script
data-raw/process_covid_calibration.R.
data("abc_calibration_params") str(abc_calibration_params)data("abc_calibration_params") str(abc_calibration_params)
Optionally initializes the BiLSTM model and then calls
estimate_sir_parameters on the provided data.
calibrate_sir( daily_cases, population_size, recovery_rate, model_dir = NULL, auto_init = TRUE )calibrate_sir( daily_cases, population_size, recovery_rate, model_dir = NULL, auto_init = TRUE )
daily_cases |
Numeric vector of length 61 containing daily incidence counts (day 0 to day 60). |
population_size |
Single numeric value giving the total population size. |
recovery_rate |
Single numeric value giving the recovery rate parameter. |
model_dir |
Optional path to the directory containing the trained
BiLSTM model and scaler files. If |
auto_init |
Logical; if |
Named numeric vector: ptran, crate, R0.
Check model status
check_model_status()check_model_status()
A list describing model load status and Python config.
Reports whether Python is available, which package-managed Python target is in use, and whether each required Python package is importable.
check_python_setup()check_python_setup()
A list with Python runtime details and package status.
Unload the model from memory
cleanup_model()cleanup_model()
Invisibly TRUE on success.
Estimate SIR Parameters from 61-day incidence
estimate_sir_parameters(daily_cases, population_size, recovery_rate)estimate_sir_parameters(daily_cases, population_size, recovery_rate)
daily_cases |
Numeric vector of length 61 containing daily incidence counts for days 0 to 60. |
population_size |
Single numeric value giving the total population size used in the SIR model. |
recovery_rate |
Single numeric value giving the recovery rate parameter of the SIR model. |
Named numeric vector: ptran, crate, R0.
Loads the trained BiLSTM model and associated scaler objects into memory.
Requires that Python dependencies have been set up via
setup_python_deps.
init_bilstm_model(model_dir = NULL, force_reload = FALSE)init_bilstm_model(model_dir = NULL, force_reload = FALSE)
model_dir |
Optional path to model directory. Defaults to the package's bundled model files. |
force_reload |
Logical; reload even if already loaded. |
Invisibly returns TRUE on success.
This function declares Python requirements through \'reticulate\' using \'py_require()\' (uv-backed in reticulate >= 1.41), then validates imports for all required modules (numpy, scikit-learn, joblib, PyTorch). Run this once after installing the package. This is kept separate from model functions so that package installation never happens automatically during normal use.
setup_python_deps(force = FALSE)setup_python_deps(force = FALSE)
force |
Logical; if |
The function performs the following steps:
Declares requirements with reticulate::py_require().
Initializes Python through reticulate's managed environment.
Verifies all packages can be imported.
Invisibly returns TRUE on success.
## Not run: # First-time setup (run once after installing the package) setup_python_deps() # Force reinstall if something went wrong setup_python_deps(force = TRUE) ## End(Not run)## Not run: # First-time setup (run once after installing the package) setup_python_deps() # Force reinstall if something went wrong setup_python_deps(force = TRUE) ## End(Not run)
Daily COVID-19 epidemic indicators for the state of Utah, obtained from the Utah Department of Health COVID-19 dashboard.
utah_covid_datautah_covid_data
A data frame with 365 rows and 5 variables:
Date of the observation (Date).
Number of newly reported COVID-19 cases (numeric).
Smoothed daily cases using a 3-day moving average (numeric).
Alternative 3-day moving average of daily cases (numeric).
Indicator of reporting or epidemic status (character or factor).
Utah Department of Health COVID-19 Dashboard.
data("utah_covid_data") head(utah_covid_data)data("utah_covid_data") head(utah_covid_data)