Part 1: Study Setup
Before simulating, we define four components: the study timeline, external surveillance data, the household composition rules, and the within-household contact structure.
1.1 Study Timeline
All simulations are anchored to a calendar start and end date. These dates define the duration of the simulation in days.
1.2 Surveillance Data (Community Forcing)
Community-acquired infections are driven by an external surveillance
curve. Supply a dataframe with two columns: date and
cases. The case counts are automatically normalized to [0,
1] and interpolated to daily resolution inside the simulator.
Here we create a synthetic Gaussian-shaped epidemic curve peaking in the middle of the study:
dates_weekly <- seq(from = as.Date(study_start),
to = as.Date(study_end), by = "week")
surveillance_data <- data.frame(
date = dates_weekly,
cases = 0.1 +
100 * exp(-0.0002 * (as.numeric(dates_weekly - mean(dates_weekly)))^2) +
abs(rnorm(length(dates_weekly), mean = 0, sd = 10))
)
plot(surveillance_data$date, surveillance_data$cases,
type = "l", lwd = 2, col = "steelblue",
xlab = "Date", ylab = "Weekly cases",
main = "Synthetic Surveillance Curve")
If you have real surveillance data, simply replace this dataframe. If no surveillance data or seasonal forcing is provided, the community force of infection remains constant throughout the study.
1.3 Contact Matrix (Role Mixing Weights)
Within a household, not all members contact each other equally. A
role_mixing_matrix defines the relative contact intensity
between each pair of roles. Rows represent the source
(infector) and columns represent the target
(infectee):
role_mixing_weights <- matrix(c(
# Target: Infant Toddler Adult Elderly
0.0, 0.5, 1.0, 0.5, # Source: Infant
0.5, 0.9, 0.7, 0.5, # Source: Toddler
1.0, 0.7, 0.6, 0.7, # Source: Adult
0.5, 0.5, 0.7, 0.0 # Source: Elderly
), nrow = 4, byrow = TRUE,
dimnames = list(
c("infant", "toddler", "adult", "elderly"),
c("infant", "toddler", "adult", "elderly")))
role_mixing_weights
#> infant toddler adult elderly
#> infant 0.0 0.5 1.0 0.5
#> toddler 0.5 0.9 0.7 0.5
#> adult 1.0 0.7 0.6 0.7
#> elderly 0.5 0.5 0.7 0.0Reading this matrix:
- Adult -> Infant = 1.0 (high): Adults are primary caregivers for infants.
- Toddler -> Toddler = 0.9 (high): Toddler siblings play together frequently.
- Elderly -> Infant = 0.5 (moderate): Some grandparent caregiving.
- Elderly -> Elderly = 0.0 (none): In this scenario, we assume at most one elderly per household, so self-contact is irrelevant.
- Infant -> Infant = 0.0 (none): Infants do not infect each other directly.
When a household is generated (e.g., with roles
c("adult", "adult", "infant", "toddler")), the simulator
expands this 4x4 role matrix into a 4x4 individual-level contact matrix
by looking up each pair’s roles.
1.4 Household Composition
Each household is randomly assembled according to a demographic
profile. The household_profile_list controls the
probability distribution over household compositions:
household_profile <- list(
prob_adults = c(0, 0, 1), # P(0, 1, 2 adults) — always 2 parents
prob_infant = 1.0, # P(infant present) — always 1 infant
prob_siblings = c(0, 0.8, 0.2), # P(0, 1, 2 toddlers) — 80% one, 20% two
prob_elderly = c(0.7, 0.1, 0.2) # P(0, 1, 2 elderly) — 70% none
)With this profile, most households will have 2 adults + 1 infant + 1 toddler (the most common draw), with some households also including 1-2 elderly members.
You can modify this to represent different demographic settings:
# Nuclear Western family
nuclear <- list(
prob_adults = c(0.05, 0.15, 0.80),
prob_infant = 0.5,
prob_siblings = c(0.40, 0.45, 0.15),
prob_elderly = c(0.95, 0.04, 0.01)
)
# Multi-generational Asian family
multigenerational <- list(
prob_adults = c(0, 0, 1),
prob_infant = 1.0,
prob_siblings = c(0.05, 0.30, 0.65),
prob_elderly = c(0.20, 0.50, 0.30)
)1.5 Intervention Strategies (Covariates)
Interventions are defined via covariates_config. Each
entry specifies:
name: Column name in the output data.efficacy: Fractional reduction (0 to 1). A value of 0.6 means 60% reduction.effect_on: What is reduced —"susceptibility","infectivity", or"both".coverage: Role-specific probability of receiving the intervention.
sim_config <- list(
list(
name = "vacc_status",
efficacy = 0, # Set to 0 for baseline (no effect)
effect_on = "both",
coverage = list(
infant = 0,
toddler = 0,
adult = 0,
elderly = 0
)
)
)In this baseline example, efficacy = 0 means the
vaccination covariate column is created in the output but has no actual
effect on transmission. This is useful for testing the pipeline before
introducing real intervention effects.
To simulate an actual intervention, set nonzero efficacy and coverage:
# Real vaccination scenario
vacc_config <- list(
list(
name = "vacc_status",
efficacy = 0.5, # 50% reduction in susceptibility and infectivity
effect_on = "both",
coverage = list(
infant = 0.00, # Not eligible
toddler = 0.30,
adult = 0.80,
elderly = 0.90
)
),
# You can add multiple interventions — they stack multiplicatively
list(
name = "masked",
efficacy = 0.3,
effect_on = "both",
coverage = list(infant = 0, toddler = 0.1, adult = 0.7, elderly = 0.6)
)
)How stacking works: A vaccinated (efficacy = 0.5)
and masked (efficacy = 0.3) adult has their susceptibility multiplied by
(1 - 0.5) * (1 - 0.3) = 0.35, i.e., a 65% total
reduction.
