macpan2
is a software platform for building and calibrating
compartmental models of infectious disease. It supports flexible model
specification and fast parameter calibration, making it easier for
modellers to respond to emerging public health threats. Developed
through collaboration with the Public Health Agency of Canada
(PHAC), macpan2
is being
used to support responses to diseases such as mpox (Milwid et al.
2023), measles (PHAC 2024,
interactive measles
model), and COVID-19
(Simmons et al. 2025; Miranda et al.
2025), and internal work on pandemic
preparedness.
The precursor to macpan2
was
McMasterPandemic,
which was developed to provide
forecasts and insights to
Canadian public health agencies throughout the COVID-19 pandemic
(Public Health Agency of Canada Modelling Group
2020--2022). Much was
learned
about developing general purpose compartmental modelling software during
this experience, but the pressure to deliver regular forecasts made it
difficult to focus on the software itself. The goal of this macpan2
project is to re-imagine McMasterPandemic
, building it from the ground
up with architectural and technological decisions that address the many
lessons that we learned from COVID-19 about software.
- Package website
- Package reference and function documentation
- Quick-start guide
- Articles describing the package
- Example starter models
- Frequently asked questions
TMB
engine [specification document]- Project history and trajectory [slides]
- Instructional videos
- Workshop notes
- Publications and reports [using
macpan2
andMcMasterPandemic
] - Visual
macpan2
model builder [proof of concept]
Here is the recommended way to install macpan2
(from within an R
session):
repos = c('https://canmod.r-universe.dev', 'https://cloud.r-project.org')
install.packages('macpan2', repos = repos)
To get the latest development version of macpan2
, or if the above
command fails for some reason, try:
remotes::install_github("canmod/macpan2")
This command requires the remotes
package and assumes that your R
environment is set up to build packages that include compiled C++ code
(e.g. see details for
Windows
or MacOS [you probably only need
Xcode from this page]).
Many macpan2
workflows also use these four popular packages:
install.packages(c("dplyr", "ggplot2", "tidyr", "broom.mixed"))
The Rgraphviz
package is useful for plotting flow diagrams of models
(see ?dot_layout
). To install it:
if (!require("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("Rgraphviz")
The r-universe, which we use to distribute
macpan2
, suggests two approaches for projects in production that need
to keep track of specific versions of macpan2
:
snapshots
or renv
.
To take the first approach, snapshots of macpan2
(and its dependency
oor
) can be obtained using the following download link.
https://canmod.r-universe.dev/api/snapshot/zip?packages=macpan2,macpan2helpers,oor
Please see this documentation for instructions on customizing this download link.
The benefit of the first approach is that it doesn’t require users to be able to compile C++ code, whereas the second does. The benefit of the second approach is that it can be used to manage dependencies on all packages in your workflows. It might be possible to combine the two approaches to get the best of both worlds, but this isn’t tested.
The following code specifies an SI model, which is the simplest model of epidemiological transmission.
library(macpan2)
si = mp_tmb_model_spec(
before = S ~ 1 - I
, during = mp_per_capita_flow(
from = "S" ## compartment from which individuals flow
, to = "I" ## compartment to which individuals flow
, rate = "beta * I" ## expression giving _per-capita_ flow rate
, flow_name = "infection" ## name for _absolute_ flow rate = beta * I * S
)
, default = list(I = 0.01, beta = 0.2)
)
print(si)
## ---------------------
## Default values:
## quantity value
## I 0.01
## beta 0.20
## ---------------------
##
## ---------------------
## Before the simulation loop (t = 0):
## ---------------------
## 1: S ~ 1 - I
##
## ---------------------
## At every iteration of the simulation loop (t = 1 to T):
## ---------------------
## 1: mp_per_capita_flow(from = "S", to = "I", rate = "beta * I", flow_name = "infection")
See this article for more example models with documentation.
Simulating from this model requires choosing the number of time-steps to
run and the model outputs to generate. Syntax for simulating macpan2
models is designed to combine with standard data prep and plotting
tools in
R,
as we demonstrate with the following code.
library(ggplot2)
library(dplyr)
(si
|> mp_simulator(time_steps = 50, outputs = c("I", "infection"))
|> mp_trajectory()
|> mutate(quantity = case_match(matrix
, "I" ~ "Prevalence"
, "infection" ~ "Incidence"
))
|> ggplot()
+ geom_line(aes(time, value))
+ facet_wrap(~ quantity, scales = "free")
+ theme_bw()
)
We have delivered several macpan2
workshops. Here are the current
workshop notes.
Organization | Date |
---|---|
Public Health Agency of Canada | 2025-03-20 |
Memorial University | 2024-11-07 |
Simon Fraser University | 2024-13-05 |
Vancouver Machine Learning Group (VanML) | 2024-02-22 |
Canadian Network for Modelling Infectious Diseases (CANMOD) | 2023-11-14 |
On June 16-27, 2025, the International Clinics on Infectious Disease
Dynamics and Data (ICI3D) Program included labs
using macpan2
to specify simple compartmental models and simulate
from
them
and specify an HIV model and fit it to
data.
The project board tracks the details of bugs, tasks, and feature development.
Milwid, R. M., M. Li, A. Fazil, M. Maheu-Giroux, C. M. Doyle, Y. Xia, J. Cox, et al. 2023. “Exploring the Dynamics of the 2022 Mpox Outbreak in Canada.” Journal of Medical Virology 95: e29256. https://doi.org/10.1002/jmv.29256.
Miranda, Rafael N, Alison E Simmons, Michael WZ Li, Gebremedhin B Gebretekle, Min Xi, Marina I Salvadori, Bryna Warshawsky, et al. 2025. “Cost-Utility Analysis of COVID-19 Vaccination Strategies for Endemic SARS-CoV-2.” JAMA Network Open 8 (6): e2515534–34. https://doi.org/10.1001/jamanetworkopen.2025.15534.
PHAC. 2024. “Rapid Risk Assessment: Measles in Canada, Public Health Implications in 2024.” Public Health Agency of Canada. https://www.canada.ca/en/public-health/services/emergency-preparedness-response/rapid-risk-assessments-public-health-professionals/rapid-risk-assessment-measles-public-health-implications-2024.html.
Public Health Agency of Canada Modelling Group. 2020--2022. “PHAC Modelling Group Reports.” https://nccid.ca/covid-19-phac-modelling-group/.
Simmons, A. E., R. N. Miranda, M. W. Z. Li, G. B. Gebretekle, M. Xi, M. I. Salvadori, B. Warshawsky, et al. 2025. “Cost-Utility Analysis of Current COVID-19 Vaccination Program Recommendations in Canada.” Vaccine X 24: 100660. https://doi.org/10.1016/j.jvacx.2025.100660.