Skip to content

Commit 6586d89

Browse files
stevencarlislewalkerstevencarlislewalker
committed
edits
1 parent 9c49a17 commit 6586d89

File tree

1 file changed

+37
-110
lines changed

1 file changed

+37
-110
lines changed

‎companion-materials.md‎

Lines changed: 37 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Workshop on `macpan2` – Companion Materials
33

44
Author: [Steve Walker](https://github.com/stevencarlislewalker)
55

6-
Last Updated: 2025-01-10
6+
Last Updated: 2025-03-19
77

88
[![CC BY-NC-SA
99
4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](http://creativecommons.org/licenses/by-nc-sa/4.0/)
@@ -24,7 +24,7 @@ this)
2424
- [Philosophy](#philosophy)
2525
- [Organization](#organization)
2626
- [Code Style](#code-style)
27-
- [Dependencies](#dependencies)
27+
- [Technical Setup](#technical-setup)
2828
- [Exploration](#exploration)
2929
- [Starter Model Library](#starter-model-library)
3030
- [Simulating Dynamics](#simulating-dynamics)
@@ -46,7 +46,7 @@ this)
4646
Concentrations](#wastewater-pathogen-concentrations)
4747
- [Vital Dynamics](#vital-dynamics)
4848
- [Importation and Stochasticity](#importation-and-stochasticity)
49-
- [Parameterization](#parameterization)
49+
- [Calibration](#calibration)
5050
- [Modify Default Values](#modify-default-values)
5151
- [Express Uncertainty in Model
5252
Parameters](#express-uncertainty-in-model-parameters)
@@ -76,56 +76,29 @@ participating in this workshop. The instructor will review this syllabus
7676
with participants before the sessions start.
7777

7878
The syllabus provides a roadmap for the workshop, guiding participants
79-
through the exploration-parameterization-inference-stratification
80-
strategy essential for compartmental modeling using the `macpan2`
81-
package. Each session is organized around these steps, offering a
82-
structured approach to model refinement. Participants will follow a
83-
practical example that demonstrates each phase of the strategy, with
84-
companion materials available for deeper exploration of related skills.
85-
Each session contains exercises designed to reinforce key concepts and
86-
encourage participants to apply lessons to their own compartmental model
87-
diagrams. For those without a pre-existing model or whose models are not
88-
applicable, a detailed example model is provided to ensure a hands-on
89-
learning experience. By the end of the workshop, participants will have
90-
the skills to evaluate the suitability of compartmental modeling for
91-
public health problems, develop models using macpan2, navigate its
92-
documentation to address challenges, and provide constructive feedback
93-
for improving the tool.
79+
through the exploration-calibration-inference-stratification strategy
80+
that can be used for compartmental modeling. By the end of the workshop,
81+
participants will have the skills to develop compartmental models using
82+
macpan2, navigate its documentation to address challenges, and provide
83+
constructive feedback for improving the tool.
9484

9585
### Philosophy
9686

97-
The goal of `macpan2` is *not* to implement cutting edge modelling and
98-
statistical techniques. Instead the goal is to implement well-understood
99-
techniques, optimized for use by epidemiologists who are tasked with
100-
answering real-world public health questions using data-calibrated
101-
compartmental models.
87+
The goal of `macpan2` is to implement well-understood techniques, for
88+
use by epidemiologists who are tasked with using data-calibrated
89+
compartmental models to answer public health questions.
10290

10391
### Organization
10492

105-
Our effort to present standard tools in a convenient manner has led us
106-
to develop concepts that encapsulate how I believe modellers do (or
107-
should) think. By building and updating our software with these concepts
108-
in mind, I seek to converge on a tool that will help modellers focus
109-
more on epidemiology and less on computational details. We highlight
110-
these concepts in special boxes.
111-
112-
| <img src="images/concept.svg" width="120" /> |
113-
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
114-
| **User Feedback**<br>Our modelling concepts are hypotheses that I would like feedback on. What concepts seem helpful/useful and what concepts seem harmful/useless? |
115-
116-
Ideally these concepts would lead to a perfectly intuitive tool. In
117-
reality I recognize that there are important technical details that you
118-
will need to learn to use the tool effectively. We try to collect the
119-
more technical ideas in tip boxes.
93+
We collect some of the more technical ideas in tip boxes.
12094

12195
| <img src="images/tip.svg" width="120" /> |
12296
|:-------------------------------------------------------------------------------------------------------------------------------------|
12397
| Tip boxes like this contain technical information that could interrupt the flow of ideas, but is too important to bury in footnotes. |
12498

125-
If you’re attending this workshop, you’re already a highly skilled
99+
If you’re attending this workshop, you’re already an experienced
126100
modeller. Many of the concepts will be familiar to you, so you may gain
127-
more by actively engaging with the tool itself. To support this process
128-
of self-discovery, I have designed a series of exercises.
101+
more by doing illustrative exercises.
129102

130103
| <img src="images/exercise.svg" width="120" /> |
131104
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -140,73 +113,27 @@ We will often use the [base R pipe
140113
operator](https://www.tidyverse.org/blog/2023/04/base-vs-magrittr-pipe/#pipes),
141114
`|>`, when it improves readability.
142115

143-
### Dependencies
144-
145-
The `macpan2` package is designed to be used with two other standard
146-
packages, and so all of the code in these materials assumes that the
147-
following packages are loaded.
148-
149-
``` r
150-
library(macpan2) ## obviously
151-
library(ggplot2)
152-
library(dplyr)
153-
library(lubridate)
154-
```
155-
156-
This document was produced with the following R environment.
157-
158-
``` r
159-
sessionInfo() |> print()
160-
```
116+
### Technical Setup
161117

162-
## R version 4.4.2 (2024-10-31)
163-
## Platform: x86_64-apple-darwin20
164-
## Running under: macOS Sequoia 15.0.1
165-
##
166-
## Matrix products: default
167-
## BLAS: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRblas.0.dylib
168-
## LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib; LAPACK version 3.12.0
169-
##
170-
## locale:
171-
## [1] en_CA.UTF-8/en_CA.UTF-8/en_CA.UTF-8/C/en_CA.UTF-8/en_CA.UTF-8
172-
##
173-
## time zone: America/New_York
174-
## tzcode source: internal
175-
##
176-
## attached base packages:
177-
## [1] stats graphics grDevices utils datasets methods base
178-
##
179-
## other attached packages:
180-
## [1] lubridate_1.9.3 dplyr_1.1.4 ggplot2_3.5.1 macpan2_1.13.0
181-
##
182-
## loaded via a namespace (and not attached):
183-
## [1] vctrs_0.6.5 cli_3.6.3 knitr_1.49 rlang_1.1.4
184-
## [5] xfun_0.49 generics_0.1.3 jsonlite_1.8.9 glue_1.8.0
185-
## [9] colorspace_2.1-1 TMB_1.9.15 htmltools_0.5.8.1 fansi_1.0.6
186-
## [13] scales_1.3.0 rmarkdown_2.29 grid_4.4.2 tibble_3.2.1
187-
## [17] evaluate_1.0.1 munsell_0.5.1 MASS_7.3-61 fastmap_1.2.0
188-
## [21] yaml_2.3.10 lifecycle_1.0.4 memoise_2.0.1 compiler_4.4.2
189-
## [25] timechange_0.3.0 pkgconfig_2.0.3 lattice_0.22-6 digest_0.6.37
190-
## [29] R6_2.5.1 tidyselect_1.2.1 utf8_1.2.4 oor_0.0.2
191-
## [33] pillar_1.9.0 magrittr_2.0.3 Matrix_1.7-1 withr_3.0.2
192-
## [37] tools_4.4.2 gtable_0.3.6 cachem_1.1.0
118+
Instructions for setting your computer for using `macpan2` are
119+
[here](https://canmod.github.io/macpan-workshop/technical-preparation).
193120

194121
## Exploration
195122

196-
Participants will learn how to explore and modify models, and informally
197-
compare them with observed data.
123+
Participants will learn how to explore and modify model specification
124+
objects, and informally compare them with observed data.
198125

199-
At the core of macpan2 are model specifications, which primarily define
200-
the flows between compartments and set default values for parameters.
201-
These specifications offer a clear and systematic way to describe the
202-
behavior of a system, starting with the foundational elements of
203-
compartmental models. While additional complexities, such as vital
204-
dynamics, external sources and sinks, or initialization of state
205-
variables, are often necessary, I begin with simple specifications.
126+
At the core of macpan2 are model specifications, which define
127+
compartment flows and set default parameter values. These specifications
128+
provide a systematic framework for describing system behavior, starting
129+
with the foundational elements of compartmental models. While additional
130+
complexities like vital dynamics, external sources, sinks, or state
131+
variable initialization are often required, I begin with simple
132+
specifications.
206133

207-
| <img src="images/concept.svg" width="120" /> |
208-
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
209-
| **Parsimony**<br>Starting with simplicity reflects an essential modelling principle: begin with a straightforward model and gradually add complexity as the situation demands, whether for specific data, additional details, or particular public health objectives. This approach will help you quickly get started with macpan2 and transition smoothly to more intricate applications. It also highlights the value of abstract compartmental models that can be stored in a library of reusable templates. These templates can be adapted to different scenarios, allowing for efficient modelling tailored to public health challenges.<br><br>TODO: link to model modification section. |
134+
| <img src="images/concept.svg" width="120" /> |
135+
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
136+
| **Parsimony**<br>Starting simple reflects a core modeling principle: begin with a straightforward model and add complexity as needed for specific data, details, or public health objectives. This approach enables a quick start with `macpan2` and a smooth transition to more intricate applications. It also underscores the value of abstract compartmental models stored as reusable templates, which can be efficiently adapted to diverse public health challenges. |
210137

211138
### Starter Model Library
212139

@@ -254,13 +181,13 @@ print(sir)
254181

255182
## ---------------------
256183
## Default values:
257-
## ---------------------
258184
## quantity value
259185
## beta 0.2
260186
## gamma 0.1
261187
## N 100.0
262188
## I 1.0
263189
## R 0.0
190+
## ---------------------
264191
##
265192
## ---------------------
266193
## Before the simulation loop (t = 0):
@@ -525,7 +452,7 @@ functions, which take a loaded model specification object (like the
525452
### Compare Simulated and Observed Incidence
526453

527454
Now we are getting to the interesting stuff in this first `Exploration`
528-
section of the `Exploration-Parameterization-Inference-Stratification`
455+
section of the `Exploration-Calibration-Inference-Stratification`
529456
methodology: using data (and other empirical information) and
530457
simulations together to understand a system. This step is critical in
531458
epidemiological modelling for applied public health work. No matter how
@@ -642,14 +569,14 @@ print(sir_covid)
642569

643570
## ---------------------
644571
## Default values:
645-
## ---------------------
646572
## quantity value
647573
## beta 1.785714e-01
648574
## gamma 7.142857e-02
649575
## N 1.400000e+07
650576
## I 5.000000e+01
651577
## R 0.000000e+00
652578
## report_prob 1.000000e-01
579+
## ---------------------
653580
##
654581
## ---------------------
655582
## Before the simulation loop (t = 0):
@@ -883,8 +810,8 @@ happen when the simulated number of `S` individuals drops below the
883810
number of doses per day. This issue could be addressed by using the
884811
minimum of `S` and the known number of doses as the realized number of
885812
doses. However this approach has severe drawbacks when calibrating,
886-
because as we will learn in the [Parameterization](#parameterization)
887-
section `macpan2` uses the
813+
because as we will learn in the [Calibration](#calibration) section
814+
`macpan2` uses the
888815
[TMB](https://kaskr.github.io/adcomp/_book/Introduction.html) package
889816
for optimizing fit to data and TMB becomes much less efficient when we
890817
use discontinuous functions like this. To address this complexity we can
@@ -931,7 +858,7 @@ however are more strongly impacted by stochasticity.
931858
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
932859
| The [awareness](https://github.com/canmod/macpan2/tree/main/inst/starter_models/awareness) model in the library illustrates how `macpan2` can be used in these cases. |
933860

934-
## Parameterization
861+
## Calibration
935862

936863
Participants will learn how to parameterize models for making inferences
937864
about a particular population and public health problem.
@@ -1142,7 +1069,7 @@ matrices of transmission parameters. This approach is desecribed
11421069
- [Philosophy](#philosophy)
11431070
- [Organization](#organization)
11441071
- [Code Style](#code-style)
1145-
- [Dependencies](#dependencies)
1072+
- [Technical Setup](#technical-setup)
11461073
- [Exploration](#exploration)
11471074
- [Starter Model Library](#starter-model-library)
11481075
- [Simulating Dynamics](#simulating-dynamics)
@@ -1164,7 +1091,7 @@ matrices of transmission parameters. This approach is desecribed
11641091
Concentrations](#wastewater-pathogen-concentrations)
11651092
- [Vital Dynamics](#vital-dynamics)
11661093
- [Importation and Stochasticity](#importation-and-stochasticity)
1167-
- [Parameterization](#parameterization)
1094+
- [Calibration](#calibration)
11681095
- [Modify Default Values](#modify-default-values)
11691096
- [Express Uncertainty in Model
11701097
Parameters](#express-uncertainty-in-model-parameters)

0 commit comments

Comments
 (0)