update practical steps

Author: avallecam

instructors/data/04-practical-activity-1.R

@@ -14,28 +14,43 @@ library(tidyverse)
 
 # (1) Contact matrix ------------------------------------------------------
 
-# step: paste the survey link for your room
+# note: all input parameters come from
+# the table of parameters of the practical document
+
+# step: paste the survey link assigned to your room
+# then run the function to download the social contact data
 socialsurvey <- socialmixr::get_survey(
   #<COMPLETE>
 )
 
-# step: generate contact matrix by defining
-# survey class object, country name, 
-# age limits from table of parameters, 
-# and whether to make a symmetric matrix
+socialsurvey
+
+# step: generate the contact matrix by defining
+# - the survey class object just downloaded,
+# - the country name, 
+# - the age limits, as in the table of parameters, and
+# - TRUE or FALSE to create a symmetric matrix.
 contact_data <- socialmixr::contact_matrix(
   #<COMPLETE>
 )
 
 contact_data
 
-# Matrix are symmetric for the total number of contacts
-# of one group with another is the same as the reverse
+# run: confirm the symmetry of the matrix
+# Matrix are symmetric for the total number of contacts.
+# The total number of contacts from one group to another is the same in both directions.
+# Check this by multiplying the mean contacts by the population size for each group.
 contact_data$matrix * contact_data$demography$proportion
 
-# Prepare contact matrix
-# {socialmixr} provides contacts from-to
-# {epidemics} expects contacts to-from
+# run: Prepare contact matrix
+#
+# - {socialmixr} provides a matrix from-to: from-participants -> to-contacts
+#   In surveys, participants report their contacts.
+#
+# - {epidemics} expects a matrix to-from: to-contacts <- from-participants
+#   Models assume that each susceptible (contact) is exposed to infection based on
+#   how often they are contacted (by participants) and how infectious (participatns) are. 
+# 
 socialcontact_matrix <- t(contact_data$matrix)
 
 socialcontact_matrix
@@ -48,6 +63,7 @@ socialcontact_matrix
 # as given in table of parameter
 initial_i <- #<COMPLETE>
 
+# run: create an infectious vector
 initial_conditions_inf <- c(
   S = 1 - initial_i,
   E = 0,
@@ -60,6 +76,7 @@ initial_conditions_inf
 
 ## Free of infection population ---------
 
+# run: create an infection-free vector
 initial_conditions_free <- c(
   S = 1,
   E = 0,
@@ -72,31 +89,34 @@ initial_conditions_free
 
 ## Combine initial conditions ------------
 
+# note: not all the population needs to be infectious.
+# The epidemic can start with infecitous in a specific age range.
+
 # step: Combine the initial conditions
-# add initial_conditions_inf or initial_conditions_free
-# to the each age group as given in table of parameter
+# Add initial_conditions_inf or initial_conditions_free
+# to the each age group as detailed in table of parameter
 initial_conditions <- base::rbind(
   #<COMPLETE>, # age group 1
   #<COMPLETE>, # age group 2
   #<COMPLETE> # age group 3
 )
 
-# Use contact matrix to assign age group names
+# run: Use contact matrix to assign age group names
 rownames(initial_conditions) <- rownames(socialcontact_matrix)
 
 initial_conditions
 
 # (3) Population structure ------------------------------------------------
 
-# Prepare the demography vector
+# run: Prepare the demography vector
 demography_vector <- contact_data$demography$population
 names(demography_vector) <- rownames(socialcontact_matrix)
 
-# step: Prepare the population to model as affected by the epidemic
-# add the name of the country, 
-# the symmetric and transposed contact matrix,
-# the vector with the population size of each age group
-# the binded matrix with initial conditions for each age group
+# step: Prepare the population to model as affected by the epidemic adding
+# - the name of the country, 
+# - the symmetric and transposed contact matrix,
+# - the vector with the population size of each age group
+# - the binded matrix with initial conditions for each age group
 population_object <- epidemics::population(
   #<COMPLETE>
 )
@@ -105,7 +125,7 @@ population_object
 
 # (4) Model parameters ----------------------------------------------------
 
-# step: Rates
+# step: define the disease-specific parameters: the rates
 # add the values as given in table of parameter
 infectiousness_rate <- 1 / #<COMPLETE> # 1/pre-infectious period
 recovery_rate <- 1 / #<COMPLETE> # 1/infectious period
@@ -115,20 +135,22 @@ transmission_rate <- recovery_rate * #<COMPLETE> # recovery rate * R0
 # (5) Run the model --------------------------------------------------------
 
 # step: in each function argument add
-# the population object
-# each of the previously defined rates
-# the total simulation time as given in table of parameter
+# - the population object
+# - each of the previously defined disease-specific rates
+# - the total simulation time as given in table of parameter
 simulate_baseline <- epidemics::model_default(
   #<COMPLETE>
 )
 
 simulate_baseline
 
 
-# Plot all compartments --------------------------------------------------
+# (6) Plot all compartments ------------------------------------------------
 
-# step: paste plot and table output in report
+# run: paste plot in report
 
+# plot with total number of individual per compartment
+# at different points in time
 simulate_baseline %>%
   ggplot(aes(
     x = time,
@@ -142,14 +164,20 @@ simulate_baseline %>%
     labels = scales::comma
   )
 
+# (7) Peak of infectious -------------------------------------------------
+
+# run: paste table output in report
+
+# table of epidemic peak size and time
+# per demographic group
 epidemics::epidemic_peak(data = simulate_baseline)
 
 
-# Plot new infections ----------------------------------------------------
+# (8) Plot new infections -------------------------------------------------
 
-# step: paste plot output in report
+# run: paste plot output in report
 
-# New infections
+# New infections per demographic group in time
 newinfections_bygroup <- epidemics::new_infections(data = simulate_baseline)
 
 # Visualize the spread of the epidemic in terms of new infections

instructors/data/04-practical-activity-2.R

@@ -8,20 +8,27 @@ room_number <- #<COMPLETE> replace with 1/2/3/4
 
 # Intervention ---------------------------------------------------------
 
+# note: all input parameters come from
+# the table of parameters of the practical document
+  
 rownames(socialcontact_matrix)
 
 # step: create the intervention object:
+# 
 # identify if you need to keep: 
 # epidemics::intervention() or epidemics::vaccination()
+#
 # then add:
 # - name of the intervention
 # - type of intervention ("rate" or "contacts"), if needed
 # - time when the intervention begins and ends (as values or matrix*)
-# as given in table of inputs
 # - reduction or vaccination rate (as values or matrix*)
+# 
 # *if matrix, values follow same order as in the social contact matrix
+#  
 test_intervention <- epidemics::intervention(#<COMPLETE>
 )
+# or
 test_intervention <- epidemics::vaccination(#<COMPLETE>
 )
 
@@ -30,8 +37,10 @@ test_intervention
 # Run {epidemics} ---------------------------------------------------------
 
 # step: add the intervention argument
+# 
 # as a list (for interventions against contacts or transmission rate) 
 # or as an object (for vaccination)
+# 
 simulate_intervention <- epidemics::model_default(
   population = population_object,
   transmission_rate = transmission_rate,
@@ -47,7 +56,7 @@ simulate_intervention
 
 # Plot all compartments --------------------------------------------------
 
-# step: paste plot and table output in report
+# run: paste plot in report
 
 simulate_intervention %>%
   ggplot(aes(
@@ -67,16 +76,21 @@ simulate_intervention %>%
     labels = scales::comma
   )
 
+
+# Peak of infectious -----------------------------------------------------
+
+# run: paste table output in report
+
 epidemics::epidemic_peak(data = simulate_intervention)
 
 # Visualize effect --------------------------------------------------------
 # Plot new infections 
 
 # step: 
-# add intervention name
-# if your intervention is vaccination, then
-# activate the argument exclude_compartments
-# run and paste plot output in report
+# - add intervention name
+# - if your intervention is vaccination, then
+# - activate the argument "exclude_compartments"
+# - run and paste plot output in report
 
 infections_baseline <- epidemics::new_infections(
   data = simulate_baseline,