-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
96 lines (76 loc) · 5.81 KB
/
README.Rmd
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
---
title: "macpan2"
output: github_document
---
```{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)
[![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)
[McMasterPandemic](https://github.com/mac-theobio/McMasterPandemic) was developed to provide forecasts and insights to Canadian public health agencies throughout the COVID-19 pandemic. [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.
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](https://github.com/kaskr/adcomp) as the sole engine. Template model builder (TMB) is an `R` modelling package based on a `C++` framework incorporating mature [automatic differentiation](https://cppad.readthedocs.io/en/latest/user_guide.html) and [matrix algebra](http://eigen.tuxfamily.org/index.php?title=Main_Page) libraries.
The [Public Health Risk Sciences Division](https://github.com/phac-nml-phrsd) at the [Public Health Agency of Canada](https://www.canada.ca/en/public-health.html) uses `macpan2` (for example, [here](https://phac-nml-phrsd.github.io/EPACmodel/)).
## Documentation
* [Package reference](https://canmod.github.io/macpan2/)
* [Quick-start guide](https://canmod.github.io/macpan2/articles/quickstart)
* [`TMB` engine](https://canmod.github.io/macpan2/articles/cpp_side) [specification document]
* [Project history and trajectory](https://canmod.net/misc/macpan2_presentation) [slides]
## Installation
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](https://canmod.r-universe.dev/api). Please see [this article](https://ropensci.org/blog/2022/01/06/runiverse-renv/) 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"))
```
## Hello World
The following code specifies an SI model, 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
, abs_rate = "infection" ## name for _absolute_ flow rate = beta * I * S
)
, default = list(I = 0.01, beta = 0.2)
)
print(si)
```
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}
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()
)
```
## Product Management
The [project board](https://github.com/orgs/canmod/projects/2/views/6) tracks the details of bugs, tasks, and feature development.