McMasterPandemic was
developed to provide forecasts and insights to Canadian public health
agencies throughout the COVID-19 pandemic. 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.
Impactful applied public health modelling requires many
interdisciplinary steps along the path from epidemiological research
teams to operational decision makers. Researchers must quickly tailor a
model to an emerging public-health concern, validate and calibrate it to
data, work with decision makers to define model outputs useful for
stakeholders, configure models to generate those outputs, and package up
those insights in an appropriate format for stakeholders. Unlike
traditional modelling approaches, macpan2
tackles this challenge from
a software-engineering perspective, which allows us to systematically
address bottlenecks along this path to impact in ways that will make
future solutions easier to achieve. The goal is to enable researchers to
focus on their core strengths and fill knowledge gaps efficiently and
effectively.
Although macpan2
is designed as a compartmental modelling tool that is
agnostic about the underlying computational engine, it currently uses
template model builder as the sole
engine. Template model builder (TMB) is an R
modelling package based
on a C++
framework incorporating mature automatic
differentiation
and matrix
algebra
libraries.
The Public Health Risk Sciences
Division at the Public Health
Agency of Canada uses
macpan2
(for example,
here).
TMB
engine
[specification document]The standard recommended way to install macpan2
is with the following
command.
repos = c('https://canmod.r-universe.dev', 'https://cloud.r-project.org')
install.packages('macpan2', repos = repos)
This command will install the current version of macpan2
. There is no
need to use remotes::install_github
for the latest development
version. For projects in production that need to keep track of specific
versions of macpan2
, snapshots and other reproducibility information
can be obtained here. Please see
this article for
an explanation of how to manage reproducibility using r-universe
.
Many workflows with macpan2
also make use of the following packages.
install.packages(c("dplyr", "ggplot2", "tidyr", "broom.mixed"))
The following code specifies an SI model, which is I think is the simplest possible model of epidemiological transmission.
library(macpan2)
si = mp_tmb_model_spec(
before = S ~ N - I
, during = mp_per_capita_flow("S", "I", "beta * I / N", "infection")
, default = list(N = 100, I = 1, beta = 0.2)
)
print(si)
## ---------------------
## Default values:
## ---------------------
## matrix row col value
## N 100.0
## I 1.0
## beta 0.2
##
## ---------------------
## Before the simulation loop (t = 0):
## ---------------------
## 1: S ~ N - I
##
## ---------------------
## At every iteration of the simulation loop (t = 1 to T):
## ---------------------
## 1: mp_per_capita_flow(from = "S", to = "I", rate = "beta * I / N",
## abs_rate = "infection")
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" ~ "Prevalance"
, "infection" ~ "Incidence"
))
|> ggplot()
+ geom_line(aes(time, value))
+ facet_wrap(~ quantity, scales = "free")
+ theme_bw()
)
The project board tracks the details of bugs, tasks, and feature development.