Add initial feedback

Author: adamkucharski

episodes/compare-interventions.Rmd

@@ -109,21 +109,19 @@ Learners should familiarise themselves with following concept dependencies befor
 
 ## Introduction
 
-In this tutorial we will compare intervention scenarios against each other. To quantify the effect of the intervention we need to compare our intervention scenario to a counter factual (baseline) scenario. The *counter factual* here is the scenario in which nothing changes, often referred to as the 'do nothing' scenario. The counter factual scenario may feature no interventions at all or, if we are investigating the potential impact of an additional intervention in the later stages of an outbreak, there may be existing interventions in place. 
+In this tutorial, we will compare intervention scenarios against each other. To quantify the effect of an intervention, we need to compare our intervention scenario to a counterfactual (baseline) scenario. The *counterfactual* here is the scenario in which nothing changes, often referred to as the "do-nothing" scenario. The counterfactual scenario may feature:
+- No interventions at all, or
+- Existing interventions in place (if we are investigating the potential impact of an additional intervention)
 
-We must also decide what our *outcome of interest* is to make comparisons between intervention and counter factual scenarios. The outcome of interest can be:
+We must also define our *outcome of interest* to make comparisons between intervention and counterfactual scenarios. The outcome of interest can be:
+- Direct model outputs (e.g., number of infections, hospitalizations)
+- Epidemiological metrics (e.g., epidemic peak time, final outbreak size)
+- Health impact measures (e.g., Quality-Adjusted Life Years [QALYs] or Disability-Adjusted Life Years [DALYs])
+- Economic measures (e.g., healthcare costs, productivity losses)
 
-+ a model outcome, e.g. number of infections or hospitalisations,
-+ a metric such as the epidemic peak time or size,
-+ a measure that uses the model outcomes, such as QALY/DALYs.
-
-In this tutorial we are going to learn how to use the `{epidemics}` package to compare the effect of different interventions on simulated disease trajectories. We will access social contact data with `{socialmixr}`. We'll use `{dplyr}`, `{ggplot2}` and the pipe `%>%` to connect some of their functions, so let's also call to the `{tidyverse}` package:
-
-```{r,message=FALSE,warning=FALSE}
-library(epidemics)
-library(socialmixr)
-library(tidyverse)
-```
+In this tutorial, we will learn how to use the `{epidemics}` package to compare the effect of different interventions on simulated disease trajectories. We will use:
+- `{socialmixr}` for social contact data
+- `{tidyverse}` (including `{dplyr}` and `{ggplot2}`) for data manipulation and visualization
 
 
 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor
@@ -234,15 +232,16 @@ output %>%
 
 ### Vacamole model
 
-The Vacamole model is a deterministic model based on a system of ODEs in [Ainslie et al. 2022](https://doi.org/10.2807/1560-7917.ES.2022.27.44.2101090) to describe the effect of vaccination on COVID-19 dynamics. The model consists of 11 compartments, individuals are classed as one of the following:
+The Vacamole model is a deterministic model based on a system of Ordinary Differential Equations (ODEs) developed by [Ainslie et al. (2022)](https://doi.org/10.2807/1560-7917.ES.2022.27.44.2101090) to describe the effect of vaccination on COVID-19 dynamics. The model consists of 11 compartments, where individuals are classified as:
 
-+ susceptible, $S$,
-+ partial vaccination ($V_1$), fully vaccination ($V_2$),
-+ exposed, $E$ and exposed while vaccinated, $E_V$,
-+ infectious, $I$ and infectious while vaccinated, $I_V$,
-+ hospitalised, $H$ and hospitalised while vaccinated, $H_V$,
-+ dead, $D$,
-+ recovered, $R$.
++ Susceptible ($S$)
++ Partially vaccinated ($V_1$)
++ Fully vaccinated ($V_2$)
++ Exposed ($E$) and exposed while vaccinated ($E_V$)
++ Infectious ($I$) and infectious while vaccinated ($I_V$)
++ Hospitalized ($H$) and hospitalized while vaccinated ($H_V$)
++ Dead ($D$)
++ Recovered ($R$)
 
 The diagram below describes the flow of individuals through the different compartments.
 
@@ -305,17 +304,23 @@ DiagrammeR::grViz("digraph{
 
 ## Running a counterfactual scenario using the Vacamole model
 
-1. Run the model with the default parameter values for the UK population assuming that :
+1. Run the model with the default parameter values for the UK population assuming that:
 
-+ 1 in a million individual are infectious (and not vaccinated) at the start of the simulation
-+ The contact matrix for the United Kingdom has age bins:
-  + age between 0 and 20 years,
-  + age between 20 and 40,
-  + 40 years and over.
++ One in every million individuals (0.0001%) is infectious (and not vaccinated) at the start of the simulation
++ The contact matrix for the United Kingdom has the following age bins:
+  + 0-20 years
+  + 20-40 years
+  + 40+ years
 
-For scenarios :
-+ baseline : two dose vaccination program. Dose 1 (vaccination rate 0.01) starts from day 30, dose 2 (vaccination rate 0.01) starts from day 60. Both programs run fro 300 days. 
-+ intervention :a mask mandate starting from time 60 for 100 days, assuming a reduction in the transmission rate of 0.163
+For the following scenarios:
++ Baseline: Two-dose vaccination program
+  - Dose 1 (vaccination rate 0.01) starts from day 30
+  - Dose 2 (vaccination rate 0.01) starts from day 60
+  - Both programs run for 300 days
++ Intervention: Mask mandate
+  - Starts from day 60
+  - Lasts for 100 days
+  - Reduces transmission rate by 16.3% (based on empirical studies of mask effectiveness)
 
 There is no vaccination scheme in place
 
@@ -476,33 +481,9 @@ output_vacamole %>%
 
 ## Calculating outcomes averted
 
-Visualisations are a useful tool to compare intervention scenario model predictions through time. In addition to visualisations, we also want to quantify the impact of interventions. An outcome of interest we can use is the number of infections averted. This measure allows us to quantify the difference between different intervention scenarios.
-
-In `{epidemics}`, we can use the function `outcomes_averted()` to calculate the number of infections averted while accounting for uncertainty in key parameter values. We will extend the COVID-19 example in [Modelling interventions](../episodes/modelling-interventions.md) to account for some uncertainty in the parameter values, specifically in the basic reproduction $R_0$. We do this as follows: 
-
-```{r}
-# time periods
-preinfectious_period <- 4.0
-infectious_period <- 5.5
+While visualizations are useful for comparing intervention scenarios over time, we also need quantitative measures of intervention impact. One such measure is the number of infections averted, which helps us understand the difference between intervention scenarios.
 
-# specify the mean and standard deviation of R0
-r_estimate_mean <- 2.7
-r_estimate_sd <- 0.05
-
-# generate 100 R samples
-r_samples <- withr::with_seed(
-  seed = 1,
-  rnorm(
-    n = 100, mean = r_estimate_mean, sd = r_estimate_sd
-  )
-)
-
-beta <- r_samples / infectious_period
-
-# rates
-infectiousness_rate <- 1.0 / preinfectious_period
-recovery_rate <- 1.0 / infectious_period
-```
+The `{epidemics}` package provides the `outcomes_averted()` function to calculate infections averted while accounting for parameter uncertainty. Let's extend our COVID-19 example from [Modelling interventions](../episodes/modelling-interventions.md) to account for uncertainty in the basic reproduction number ($R_0$).
 
 We use these parameter values alongside the population structure and contact matrix used in [Modelling interventions](../episodes/modelling-interventions.md) to run the model for the baseline scenario:
 
@@ -717,7 +698,15 @@ intervention_effect
 
 ::::::::::::::::::::::::::::::::::::: keypoints 
 
-- The counter factual scenario must be defined to make comparisons
-- Scenarios can be compared using visualisations and by calculating outcomes averted
+- A counterfactual (baseline) scenario must be clearly defined for meaningful comparisons
+- Scenarios can be compared using both visualizations and quantitative measures
+- The outcomes_averted() function helps quantify intervention effects
+- Parameter uncertainty should be considered in intervention analysis
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
+
+## References
+
+1. Ainslie, K. E., Walters, C. E., Fu, H., Bhatia, S., Wang, H., Xi, X., ... & Ferguson, N. M. (2022). Evidence of initial success for China exiting 'zero-COVID'? Modelling study. Eurosurveillance, 27(44), 2101090.
+2. Jarvis, C. I., Van Zandvoort, K., Gimma, A., Prem, K., Klepac, P., Rubin, G. J., & Edmunds, W. J. (2020). Quantifying the impact of physical distance measures on the transmission of COVID-19 in the UK. BMC medicine, 18(1), 1-10.
+3. Davies, N. G., Kucharski, A. J., Eggo, R. M., Gimma, A., Edmunds, W. J., & Centre for the Mathematical Modelling of Infectious Diseases COVID-19 Working Group. (2020). Effects of non-pharmaceutical interventions on COVID-19 cases, deaths, and demand for hospital services in the UK: a modelling study. The Lancet Public Health, 5(7), e375-e385.

episodes/contact-matrices.Rmd

@@ -50,7 +50,12 @@ library(socialmixr)
 
 ## The contact matrix
 
-The basic contact matrix represents the amount of contact or mixing within and between different subgroups of a population. The subgroups are often age categories but can also be geographic areas or high/low risk groups. For example, a hypothetical contact matrix representing the average number of contacts per day between children and adults could be:
+The basic contact matrix represents the amount of contact or mixing within and between different subgroups of a population. The subgroups are often age categories but can also be:
+- Geographic areas (e.g., different regions or countries)
+- Risk groups (e.g., high/low risk occupations)
+- Social settings (e.g., household, workplace, school)
+
+For example, a hypothetical contact matrix representing the average number of contacts per day between children and adults could be:
 
 $$
 \begin{bmatrix}
@@ -63,7 +68,9 @@ In this example, we would use this to represent that children meet, on average,
 ::::::::::::::::::::::::::::::::::::: callout
 
 ### A Note on Notation
-For a contact matrix with rows $i$ and columns $j$, we call $C[i,j]$ the average number of contacts of group $i$ with group $j$, calculated as the number of contacts between the two groups averaged across all individuals in group $i$.
+For a contact matrix with rows $i$ and columns $j$:
+- $C[i,j]$ represents the average number of contacts that individuals in group $i$ have with individuals in group $j$
+- This average is calculated as the total number of contacts between groups $i$ and $j$, divided by the number of individuals in group $i$
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 ## Using `socialmixr`
@@ -99,7 +106,15 @@ For the mathematical explanation see [the corresponding section in the socialmix
 ::::::::::::::::::::::::::::::::::::: callout
 ### Why would a contact matrix be non-symmetric?
 
-One of the arguments we gave the function `contact_matrix()` is `symmetric=TRUE`. This ensures that the total number of contacts of age group 1 with age group 2 is the same as the total number of contacts of age group 2 and age group 1 (see the `socialmixr` [vignette](https://cran.r-project.org/web/packages/socialmixr/vignettes/socialmixr.html) for more detail). However, when contact matrices are estimated from surveys or other sources, the *reported* number of contacts may differ by age group resulting in a non-symmetric contact matrix because of biases in recall or reporting across different groups and/or uncertainty from using a limited sample of participants [(Prem et al 2021)](https://doi.org/10.1371/journal.pcbi.1009098). If `symmetric` is set to TRUE, the `contact_matrix()` function will internally use an average of reported contacts to ensure resulting total number of contacts are symmetric.
+One of the arguments we gave the function `contact_matrix()` is `symmetric=TRUE`. This ensures that the total number of contacts from one group to another is equal to the total from the second group back to the first (see the `socialmixr` [vignette](https://cran.r-project.org/web/packages/socialmixr/vignettes/socialmixr.html) for more detail). 
+
+However, when contact matrices are estimated from surveys or other sources, the *reported* number of contacts may differ by age group for several reasons:
+- Recall bias: Different age groups may have different abilities to remember and report contacts accurately
+- Reporting bias: Some groups may systematically over- or under-report their contacts
+- Sampling uncertainty: Limited sample sizes can lead to statistical variations
+[(Prem et al 2021)](https://doi.org/10.1371/journal.pcbi.1009098)
+
+If `symmetric` is set to TRUE, the `contact_matrix()` function will internally use an average of reported contacts to ensure the resulting total number of contacts are symmetric.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -300,7 +315,9 @@ In this tutorial, we have learnt the definition of the contact matrix, how they
 
 ::::::::::::::::::::::::::::::::::::: keypoints 
 
-- `socialmixr` can be used to estimate contact matrices from survey data
-- Contact matrices can be used in different types of analyses
+- Contact matrices quantify the mixing patterns between different population groups
+- `socialmixr` provides tools to estimate contact matrices from survey data
+- Contact matrices can be used in various epidemiological analyses, from calculating $R_0$ to modeling interventions
+- Proper normalization is crucial when using contact matrices in transmission models
 
 ::::::::::::::::::::::::::::::::::::::::::::::::

episodes/content_reviews/review_compare-interventions.Rmd.md

@@ -0,0 +1,27 @@
+Here is a summary list of required changes based on the provided .Rmd teaching content:
+
+### Typos and Grammatical Errors
+- **"counter factual"** should be consistently written as **"counterfactual"** throughout the document.
+- In the sentence "the scenario in which nothing changes, often referred to as the 'do nothing' scenario," consider changing **"do nothing"** to **"do-nothing"** for consistency with hyphenation.
+- In the phrase **"both programs run fro 300 days,"** correct **"fro"** to **"for."**
+- In the section **"mask mandate,"** the name should be capitalized as **"Mask Mandate"** for consistency with other intervention names.
+
+### Ambiguous Statements or Unclear Explanations
+- The term **"outcome of interest"** could be better defined or exemplified earlier in the document to clarify its significance.
+- The phrase **"the outcome of interest may simply be the model output"** could be misleading; clarify that the model output is a type of outcome but not the only one.
+- In the **"Vacamole model"** section, clarify what **"ODEs"** stands for (Ordinary Differential Equations) for readers who may not be familiar with the term.
+
+### Technical Inconsistencies
+- In the **"initial_conditions_vacamole"** section, the variable **"EV"** should be consistently written as **"E_V"** to match the notation used in the model description.
+- The **"age bins"** in the challenge section should be clearly defined to match the age limits used in the contact matrix (0-20, 20-40, 40+).
+- In the **"Calculating outcomes averted"** section, ensure that the function **`outcomes_averted()`** is properly explained, including its input requirements and expected output.
+
+### Epidemiological Inaccuracies or Imprecision
+- The statement **"1 in a million individual are infectious"** should specify whether this is a proportion of the total population or a fixed number for clarity.
+- The **"mask mandate"** intervention description should clarify whether the reduction in transmission rate is based on empirical data or theoretical assumptions.
+- In the **"Ebola outbreak analysis"** challenge, clarify the implications of a negative number of infections averted, as this could confuse learners regarding the interpretation of stochastic models.
+
+### Additional Suggestions
+- Consider adding a **"References"** section at the end to cite the sources mentioned (e.g., Ainslie et al. 2022) for better academic rigor.
+- Ensure that all code snippets are properly formatted and tested to avoid runtime errors during the teaching session.
+- Include a brief **"Conclusion"** section summarizing the key takeaways from the tutorial to reinforce learning objectives.

episodes/content_reviews/review_contact-matrices.Rmd.md

@@ -0,0 +1,26 @@
+Here is a summary list of required changes based on the review of the provided .Rmd teaching content:
+
+### Typos and Grammatical Errors
+- **"the average schoolchild has many more daily contact than the average elderly person"**: Change "contact" to "contacts" for grammatical correctness.
+- **"2 adult per day"**: Change "adult" to "adults" for grammatical correctness.
+- **"the total number of contacts of one group with another is the same as the reverse"**: Consider rephrasing for clarity, e.g., "the total number of contacts from one group to another is equal to the total from the second group back to the first."
+- **"the average number of secondary cases won't be equal simply to the average number of contacts multiplied by the probability of transmission-per-contact"**: Consider rephrasing for clarity, e.g., "the average number of secondary cases cannot be simply calculated as the average number of contacts multiplied by the probability of transmission per contact."
+
+### Ambiguous Statements or Unclear Explanations
+- **"the average schoolchild has many more daily contact than the average elderly person"**: This statement could be clarified by specifying the context or providing data to support the claim.
+- **"the function `r_eff` in the package `{finalsize}` can perform this conversion"**: It may be helpful to briefly explain what `r_eff` does for learners unfamiliar with the function.
+- **"the entry $(i,j)$ in a mathematical model contact matrix represents contacts of group $i$ with group $j$"**: This could be clearer if it explicitly states that it refers to the number of contacts, e.g., "the entry $(i,j)$ in a mathematical model contact matrix represents the number of contacts of group $i$ with group $j$."
+
+### Technical Inconsistencies
+- **"the contact matrix `contact_data$matrix` is not itself mathematically symmetric"**: This statement may be misleading. If the function is set to `symmetric=TRUE`, it should ensure symmetry in the output. Clarify how the function achieves this.
+- **"the maximum eigenvalue of this matrix represents the typical magnitude of contacts, not typical magnitude of transmission"**: This could be misleading; clarify that the eigenvalue relates to the contact structure rather than the transmission dynamics directly.
+
+### Epidemiological Inaccuracies or Imprecision
+- **"the average number of secondary cases generated by a typical infectious individual"**: This could be misleading without context. It may be beneficial to clarify that this is an estimate and can vary based on multiple factors.
+- **"the scaling factor and the value of $\gamma$"**: It may be useful to explain how $\gamma$ is determined or its significance in the context of the model.
+- **"the average number of secondary cases based on this normalised matrix, the result would be 1"**: This statement could be misleading; clarify that this is under specific conditions and assumptions.
+
+### Additional Suggestions
+- Consider adding a section on common pitfalls or misconceptions related to contact matrices and their applications in epidemiology.
+- Ensure that all references are up-to-date and accessible, as some learners may not have access to certain journals or articles.
+- Provide a glossary of key terms used throughout the tutorial to aid understanding for learners who may be new to the subject matter.