macpan2/README.Rmd at main · canmod/macpan2 · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
---
output: github_document
bibliography: inst/references.bib
link-citations: TRUE
---

```{r opts, echo = FALSE}
knitr::opts_chunk$set(
  fig.path = "man/figures/"
)
```

```{r packages, echo = FALSE, eval = TRUE, message=FALSE, warning=FALSE, error=FALSE}
library(macpan2)
library(ggplot2)
library(dplyr)
theme_bw = function() ggplot2::theme_bw(base_size = 18)
```


<!-- badges: start -->
[![macpan2 status badge](https://canmod.r-universe.dev/badges/macpan2)](https://canmod.r-universe.dev/macpan2)
[![R-CMD-check](https://github.com/canmod/macpan2/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/canmod/macpan2/actions/workflows/R-CMD-check.yaml)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14796217.svg)](https://doi.org/10.5281/zenodo.14796217)
[![test coverage](https://byob.yarr.is/canmod/macpan2/coverage)](https://github.com/canmod/macpan2/actions/workflows/test-coverage.yaml)
[![commit activity](https://img.shields.io/github/commit-activity/m/canmod/macpan2)](https://github.com/canmod/macpan2/commits)
[![contributors](https://img.shields.io/github/contributors/canmod/macpan2)](https://github.com/canmod/macpan2/graphs/contributors)

![](man/figures/mp.png)

`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)](https://www.canada.ca/en/public-health.html), `macpan2` is being used to support responses to diseases such as mpox [@milwid2023mpox], measles [@phac2024measles, [interactive measles model](https://wzmli.shinyapps.io/two_pop_measles_shiny/)], and COVID-19 [@simmons2025cost;@miranda2024strategies], and internal work on [pandemic preparedness](https://phac-nml-phrsd.github.io/EPACmodel/). It has been used for a retrospective analysis of COVID-19 in Newfoundland [@Anokye2025.09.26.25336738].

The precursor to `macpan2` was [McMasterPandemic](https://github.com/mac-theobio/McMasterPandemic), which was developed to provide [forecasts](https://mac-theobio.github.io/covid-19) and insights to Canadian public health agencies throughout the COVID-19 pandemic [@phac_modelling_group]. Much was [learned](https://canmod.github.io/macpan-book/index.html#vision-and-direction) 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.


## Documentation

* [Package website](https://canmod.github.io/macpan2/)
* [Package reference and function documentation](https://canmod.github.io/macpan2/reference)
* [Quick-start guide](https://canmod.github.io/macpan2/articles/quickstart)
* [Articles describing the package](https://canmod.github.io/macpan2/articles)
* [Example starter models](https://canmod.github.io/macpan2/articles/example_models.html)
* [Frequently asked questions](https://canmod.github.io/macpan2/articles/FAQs)
* [`TMB` engine](https://canmod.github.io/macpan2/articles/cpp_side) [specification document]
* [Project history and trajectory](https://canmod.net/misc/pyRC) [slides]
* [Instructional videos](https://drive.google.com/drive/folders/1NEQf2sy6QLxMiiWBN5Yn9U7wiPMs1jiS)
* [Workshop notes](https://canmod.github.io/macpan-workshop)
* [Publications and reports](#publications-and-reports) [using `macpan2` and `McMasterPandemic`]
* [Visual `macpan2` model builder](https://canmod.github.io/macpan2-model-builder/) [proof of concept]

## Installation

Here is the recommended way to install `macpan2` (from within an R session):

```r
install.packages('macpan2'
  , repos = c(
      'https://canmod.r-universe.dev'
    , 'https://cloud.r-project.org'
  )
)
```

To get the latest development version of `macpan2`, or if the above command fails for some reason, try:
```r
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](https://cran.r-project.org/bin/windows/base/howto-R-devel.html) or [MacOS](https://mac.r-project.org/tools/) [you probably only need Xcode from this page]).

Many `macpan2` workflows also use these four popular packages:
```r
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:

```r
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("Rgraphviz")
```

## Reproducibility

The [r-universe](https://r-universe.dev), which we use to distribute `macpan2`, suggests two approaches for projects in production that need to keep track of specific versions of `macpan2`: [snapshots](https://ropensci.org/blog/2023/05/31/runiverse-snapshots/) or [`renv`](https://ropensci.org/blog/2022/01/06/runiverse-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](https://canmod.r-universe.dev/apis) 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.

## Hello World

 The following code specifies an [SI model](https://github.com/canmod/macpan2/blob/main/inst/starter_models/si/README.md), which is the simplest model of epidemiological transmission.
```{r hello-world}
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)
```

See [this article](https://canmod.github.io/macpan2/articles/example_models.html) 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](https://canmod.github.io/macpan2/articles/quickstart.html#processing-results), as we demonstrate with the following code.
```{r plot-tmb-si, fig.height=3, dpi=600}
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()
)
```


## Workshops

We have delivered several `macpan2` workshops. Here are the [current workshop
notes](https://canmod.github.io/macpan-workshop/).

```{r workshops, echo = FALSE, message = FALSE}
library(readr); library(knitr)
read_csv("misc/build/workshops.csv") |> kable()
```

On June 16-27, 2025, the [International Clinics on Infectious Disease Dynamics and Data (ICI3D) Program](https://www.ici3d.org/) included labs using `macpan2` to [specify simple compartmental models and simulate from them](https://github.com/ICI3D/RTutorials/blob/master/mpLabCompartmental.R) and [specify an HIV model and fit it to data](https://github.com/ICI3D/RTutorials/blob/master/mpLabFitting.R).

## Product Management

The [project board](https://github.com/orgs/canmod/projects/2/views/6) tracks the details of bugs, tasks, and feature development.

## Publications and Reports