edit tutorials with new socialmixr and contactsurveys interoperability

[avallecam]

after #139, standardize:

• object names
• start episodes from zenodo links, instead of socialmixr::polymod
• add text regarding return_demography
• add warning on the requirement of adding the country name
• translate to instructor files in tutorials
  • start with age.limits
• upate howto entries

use reprex as a guide

library(contactsurveys)
library(socialmixr)
#> 
#> Attaching package: 'socialmixr'
#> The following objects are masked from 'package:contactsurveys':
#> 
#>     download_survey, get_citation, list_surveys

survey_files <- contactsurveys::download_survey(
  survey = "https://doi.org/10.5281/zenodo.3874557",
  verbose = FALSE
)

# survey_files # shows local temporal path

survey_load <- socialmixr::load_survey(files = survey_files)
#> Warning: No reference provided.

# survey_load # long output

levels(survey_load$participants$country)
#> [1] "Belgium"        "Finland"        "Germany"        "Italy"         
#> [5] "Luxembourg"     "Netherlands"    "Poland"         "United Kingdom"

contacts_byage <- socialmixr::contact_matrix(
  survey = survey_load,
  countries = "Italy",
  age_limits = c(0, 20, 40),
  return_demography = TRUE # new argument, must for {epidemics}
)

contacts_byage
#> $matrix
#>          contact.age.group
#> age.group    [0,20)  [20,40)      40+
#>   [0,20)  14.306502 3.055728 5.325077
#>   [20,40)  2.411168 9.126904 7.101523
#>   40+      3.888199 4.664596 8.900621
#> 
#> $demography
#>    age.group population proportion  year
#>       <char>      <num>      <num> <int>
#> 1:    [0,20)   11204261  0.1905212  2005
#> 2:   [20,40)   16305622  0.2772665  2005
#> 3:       40+   31298598  0.5322123  2005
#> 
#> $participants
#>    age.group participants proportion
#>       <char>        <int>      <num>
#> 1:    [0,20)          323  0.3836105
#> 2:   [20,40)          197  0.2339667
#> 3:       40+          322  0.3824228

contacts_byage_matrix <- t(contacts_byage$matrix)

contacts_byage_matrix
#>                  age.group
#> contact.age.group    [0,20)  [20,40)      40+
#>           [0,20)  14.306502 2.411168 3.888199
#>           [20,40)  3.055728 9.126904 4.664596
#>           40+      5.325077 7.101523 8.900621

contacts_byage$demography$population
#> [1] 11204261 16305622 31298598

^{Created on 2026-02-05 with reprex v2.1.1}

[avallecam]

Implementation plan

Commit strategy: 3 atomic commits

Commit 1: Fix deprecated age.limits → age_limits

Files: compare-interventions.Rmd, template.Rmd

Pure mechanical fix, independent of the rest.

---

Commit 2: Update contact-matrices.Rmd with the new pattern

File: contact-matrices.Rmd only

This is the teaching episode — it introduces the pattern and has the most content-heavy changes:

• Add library(contactsurveys)
• Replace socialmixr::polymod loading with contactsurveys::download_survey() + socialmixr::load_survey() using the POLYMOD Zenodo DOI
• Replace socialmixr::get_survey() for the Zambia survey with the same new pattern
• Add return_demography = TRUE to all contact_matrix() calls
• Standardize object names: contacts_byage, contacts_byage_matrix
• Add callout warning users to always specify countries = (a single survey file can contain data from multiple countries)
• Add text explaining that return_demography = TRUE is required when using the output with {epidemics}

---

Commit 3: Apply the new pattern to all downstream episodes

Files: simulating-transmission.Rmd, modelling-interventions.Rmd, compare-interventions.Rmd, disease-burden.Rmd, vaccine-comparisons.Rmd, template.Rmd

Uniform mechanical update across all episodes: swap loading code, add return_demography = TRUE, rename objects.

---

Object name convention (from the reprex)

Old name	New name
polymod / survey_data / zambia_sa_survey	survey_files → survey_load
contact_data / cm_results	contacts_byage
contact_matrix / socialcontact_matrix / cm_matrix	contacts_byage_matrix

---

Out of scope for this PR

• Changes to the tutorials instructor files (separate repo)
• Updating external howto entries (separate repo)

---

🤖 Plan designed with Claude Code