--- title: "Introduction to contactsurveys" author: "Sebastian Funk & Nicholas Tierney" date: "2025-09-08" link-citations: true bibliography: contactsurveys.bib nocite: '@*' output: rmarkdown::html_vignette: toc: true vignette: > %\VignetteIndexEntry{Introduction to contactsurveys} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- [contactsurveys](https://github.com/epiforecasts/contactsurveys) is an `R` package to download contact surveys for use in age-structured [infectious disease models](https://en.wikipedia.org/wiki/Mathematical_modelling_of_infectious_disease). This code was initially in the [socialmixr](https://github.com/epiforecasts/socialmixr) package, but the code for downloading surveys has been moved into this package. For background on age-specific mixing matrices and what data inform them, see, for example, the paper on POLYMOD by [@mossong_social_2008]. # Usage `contactsurveys` provides access to all surveys in the [Social contact data](https://zenodo.org/communities/social_contact_data) community on [Zenodo](https://zenodo.org). The available surveys can be listed (if an internet connection is available) with: ``` r list_surveys() #> Skipping download #> ℹ Files already exist at #> '/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/survey_list.rds' #> and `overwrite = FALSE` #> ℹ Set `overwrite = TRUE` to force a re-download. #> Key: #> date_added #> #> 1: 2017-11-07 #> 2: 2017-12-07 #> 3: 2017-12-22 #> 4: 2018-01-23 #> 5: 2018-02-05 #> 6: 2018-06-14 #> 7: 2018-09-05 #> 8: 2019-01-24 #> 9: 2019-08-13 #> 10: 2019-09-16 #> 11: 2020-08-06 #> 12: 2020-09-30 #> 13: 2020-09-30 #> 14: 2020-10-12 #> 15: 2020-10-16 #> 16: 2021-05-06 #> 17: 2021-05-20 #> 18: 2021-05-25 #> 19: 2021-06-07 #> 20: 2021-06-29 #> 21: 2021-06-29 #> 22: 2021-06-29 #> 23: 2021-06-29 #> 24: 2021-06-29 #> 25: 2021-06-29 #> 26: 2021-07-03 #> 27: 2021-07-26 #> 28: 2021-07-26 #> 29: 2021-08-20 #> 30: 2022-04-11 #> 31: 2022-05-10 #> 32: 2022-05-10 #> 33: 2022-05-10 #> 34: 2022-05-10 #> 35: 2022-05-12 #> 36: 2022-05-12 #> 37: 2022-05-12 #> 38: 2022-08-22 #> 39: 2023-03-13 #> 40: 2023-05-24 #> 41: 2023-07-07 #> 42: 2024-03-05 #> 43: 2024-05-08 #> 44: 2024-07-27 #> 45: 2025-01-30 #> date_added #> title #> #> 1: POLYMOD social contact data #> 2: Social contact data for Peru #> 3: Social contact data for Zimbabwe #> 4: Social contact data for France #> 5: Social contact data for Hong Kong #> 6: Social contact data for Vietnam #> 7: Social contact data for UK #> 8: Social contact data for Zambia and South Africa (CODA dataset) #> 9: Social contact data for China mainland #> 10: Social contact data for Russia #> 11: CoMix social contact data (Belgium ) #> 12: Social contact data for Belgium (2010-2011) #> 13: Social contact data for Belgium (2006) #> 14: Social contact data before and during COVID-19 in China #> 15: Social contact data for Thailand #> 16: Social contact data for Thailand (2015) #> 17: CoMix social contact data (Austria) #> 18: CoMix social contact data (Netherlands) #> 19: CoMix social contact data (UK) #> 20: CoMix social contact data (Denmark) #> 21: CoMix social contact data (Spain) #> 22: CoMix social contact data (France) #> 23: CoMix social contact data (Italy) #> 24: CoMix social contact data (Portugal) #> 25: CoMix social contact data (Poland) #> 26: Social contact data for the Netherlands #> 27: CoMix social contact data (Greece) #> 28: CoMix social contact data (Slovenia) #> 29: Social contact data for IDPs in Somaliland (2019) #> 30: Social contact data for Taiwan #> 31: CoMix social contact data (Croatia) #> 32: CoMix social contact data (Slovakia) #> 33: CoMix social contact data (Hungary) #> 34: CoMix social contact data (Estonia) #> 35: CoMix social contact data (Lithuania) #> 36: CoMix social contact data (Finland) #> 37: CoMix social contact data (Switzerland) #> 38: CoMix 2.0 social contact data #> 39: Contact data of older adults (70+) in the Netherlands in 2021 #> 40: Household contact survey (Belgium) #> 41: Contact data of Children in Belgium, Italy and Poland #> 42: Contact data of Pienter3 (2016-2017) and PiCo (2020-2023) studies in the Netherlands #> 43: CoMix data (last round in BE, CH, NL and UK) #> 44: Social contact data for the BHDSS and FWHDSS in the Gambia (2022) #> 45: Social mixing patterns of United States health care personnel at a quaternary health center #> title #> creator url #> #> 1: Joël Mossong https://doi.org/10.5281/zenodo.3874557 #> 2: Carlos G. Grijalva https://doi.org/10.5281/zenodo.3874805 #> 3: Alessia Melegaro https://doi.org/10.5281/zenodo.3886638 #> 4: Guillaume Béraud https://doi.org/10.5281/zenodo.3886590 #> 5: Kathy Leung https://doi.org/10.5281/zenodo.3874808 #> 6: Horby Peter https://doi.org/10.5281/zenodo.3874802 #> 7: Albert Jan van Hoek https://doi.org/10.5281/zenodo.3874717 #> 8: Peter J. Dodd https://doi.org/10.5281/zenodo.3874675 #> 9: Zhang, Juanjuan https://doi.org/10.5281/zenodo.3878754 #> 10: Maria Litvinova https://doi.org/10.5281/zenodo.3874674 #> 11: Pietro Coletti https://doi.org/10.5281/zenodo.10549953 #> 12: Willem Lander https://doi.org/10.5281/zenodo.4302055 #> 13: Hens Niel https://doi.org/10.5281/zenodo.4059864 #> 14: Zhang Juanjuan https://doi.org/10.5281/zenodo.7326686 #> 15: Mahikul Wiriya https://doi.org/10.5281/zenodo.4086739 #> 16: Weerasak Putthasri https://doi.org/10.5281/zenodo.4739777 #> 17: Gimma, Amy https://doi.org/10.5281/zenodo.6362906 #> 18: Backer, Jantien https://doi.org/10.5281/zenodo.7276465 #> 19: Gimma, Amy https://doi.org/10.5281/zenodo.13684044 #> 20: Gimma, Amy https://doi.org/10.5281/zenodo.6362899 #> 21: Gimma, Amy https://doi.org/10.5281/zenodo.6362898 #> 22: Gimma, Amy https://doi.org/10.5281/zenodo.6362893 #> 23: Gimma, Amy https://doi.org/10.5281/zenodo.6362888 #> 24: Gimma, Amy https://doi.org/10.5281/zenodo.6362887 #> 25: Gimma, Amy https://doi.org/10.5281/zenodo.6362879 #> 26: van de Kassteele, Jan https://doi.org/10.5281/zenodo.5062244 #> 27: Gimma, Amy https://doi.org/10.5281/zenodo.6362870 #> 28: Gimma, Amy https://doi.org/10.5281/zenodo.6362865 #> 29: van Zandvoort, Kevin https://doi.org/10.5281/zenodo.7071876 #> 30: Fu, Yang-Chih https://doi.org/10.5281/zenodo.6385759 #> 31: Gimma, Amy https://doi.org/10.5281/zenodo.7257433 #> 32: Gimma, Amy https://doi.org/10.5281/zenodo.6535357 #> 33: Gimma, Amy https://doi.org/10.5281/zenodo.6535344 #> 34: Gimma, Amy https://doi.org/10.5281/zenodo.6535313 #> 35: Gimma, Amy https://doi.org/10.5281/zenodo.6542668 #> 36: Gimma, Amy https://doi.org/10.5281/zenodo.6542664 #> 37: Gimma, Amy https://doi.org/10.5281/zenodo.6542657 #> 38: Coletti, Pietro https://doi.org/10.5281/zenodo.7331926 #> 39: Jantien A. Backer https://doi.org/10.5281/zenodo.7751724 #> 40: Goeyvaerts, Nele https://doi.org/10.5281/zenodo.7965594 #> 41: Coletti,Pietro https://doi.org/10.5281/zenodo.8123632 #> 42: Backer, Jantien https://doi.org/10.5281/zenodo.10370353 #> 43: Jarvis, Christopher https://doi.org/10.5281/zenodo.11154066 #> 44: Osei, Isaac https://doi.org/10.5281/zenodo.13101862 #> 45: Pischel, Lauren https://doi.org/10.5281/zenodo.14156576 #> creator url ``` By default, the survey data from `list_surveys()` is effectively cached, so it will run very quickly the next time you run it. This data will also persist across R sessions. To expand on this, the downloads in this package are downloaded to a default location specified by `contactsurveys_dir()`, which uses `tools::R_user_dir()` under the hood to find an appropriate place to write files. You can also control where files are saved by setting an environment variable, `CONTACTSURVEYS_HOME`. See `?Sys.setenv()` or `?Renviron` for more detail. Surveys can be downloaded using `download_survey()`. This will get the relevant data of a survey given its Zenodo DOI (as returned by `list_surveys()`). ``` r polymod_doi <- "https://doi.org/10.5281/zenodo.3874557" polymod_survey_files <- download_survey(polymod_doi) #> Fetching contact survey filenames from: https://doi.org/10.5281/zenodo.3874557. #> ℹ Successfully fetched list of published records - page 1 #> #> ✔ Successfully fetched list of published records! #> #> ✔ Successfully fetched record for DOI '10.5281/zenodo.3874557'! #> #> Downloading from https://doi.org/10.5281/zenodo.3874557. #> ! Overwrite is 'false', aborting download of existing files #> #> ℹ Download in sequential mode #> [zen4R][INFO] ZenodoRecord - Download in sequential mode #> ℹ Will download 7 files from record '3874557' (doi: '10.5281/zenodo.3874557') - total size: 7.4 MiB #> [zen4R][INFO] ZenodoRecord - Will download 7 files from record '3874557' (doi: '10.5281/zenodo.3874557') - total size: 7.4 MiB #> ℹ Downloading file '2008_Mossong_POLYMOD_hh_common.csv' - size: 120 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_hh_common.csv' - size: 120 KiB #> ℹ Downloading file '2008_Mossong_POLYMOD_contact_common.csv' - size: 6.2 MiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_contact_common.csv' - size: 6.2 MiB #> ℹ Downloading file '2008_Mossong_POLYMOD_dictionary.xls' - size: 41 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_dictionary.xls' - size: 41 KiB #> ℹ Downloading file '2008_Mossong_POLYMOD_hh_extra.csv' - size: 523 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_hh_extra.csv' - size: 523 KiB #> ℹ Downloading file '2008_Mossong_POLYMOD_participant_common.csv' - size: 153.1 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_participant_common.csv' - size: 153.1 KiB #> ℹ Downloading file '2008_Mossong_POLYMOD_participant_extra.csv' - size: 221.8 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_participant_extra.csv' - size: 221.8 KiB #> ℹ Downloading file '2008_Mossong_POLYMOD_sday.csv' - size: 188.7 KiB #> [zen4R][INFO] Downloading file '2008_Mossong_POLYMOD_sday.csv' - size: 188.7 KiB #> ℹ Files downloaded at '/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557'. #> [zen4R][INFO] Files downloaded at '/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557'. #> ℹ Verifying file integrity... #> [zen4R][INFO] ZenodoRecord - Verifying file integrity... #> ℹ File '2008_Mossong_POLYMOD_hh_common.csv': integrity verified (md5sum: d7fb1359ad84dba8cce4c444063940aa) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_hh_common.csv': integrity verified (md5sum: d7fb1359ad84dba8cce4c444063940aa) #> ℹ File '2008_Mossong_POLYMOD_contact_common.csv': integrity verified (md5sum: 52baf32033bf780786fae6604043ec00) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_contact_common.csv': integrity verified (md5sum: 52baf32033bf780786fae6604043ec00) #> ℹ File '2008_Mossong_POLYMOD_dictionary.xls': integrity verified (md5sum: 06415516c91b52dedfaa53622e352647) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_dictionary.xls': integrity verified (md5sum: 06415516c91b52dedfaa53622e352647) #> ℹ File '2008_Mossong_POLYMOD_hh_extra.csv': integrity verified (md5sum: b0063f8d1a4f391d919495493611b3f1) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_hh_extra.csv': integrity verified (md5sum: b0063f8d1a4f391d919495493611b3f1) #> ℹ File '2008_Mossong_POLYMOD_participant_common.csv': integrity verified (md5sum: ac784c281a71e15c7e64eaf2d6365709) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_participant_common.csv': integrity verified (md5sum: ac784c281a71e15c7e64eaf2d6365709) #> ℹ File '2008_Mossong_POLYMOD_participant_extra.csv': integrity verified (md5sum: 4e2dd8d6ba2d23bb5b1f236be215b936) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_participant_extra.csv': integrity verified (md5sum: 4e2dd8d6ba2d23bb5b1f236be215b936) #> ℹ File '2008_Mossong_POLYMOD_sday.csv': integrity verified (md5sum: 148c5fc86ca10d385e3d047014e14a09) #> [zen4R][INFO] File '2008_Mossong_POLYMOD_sday.csv': integrity verified (md5sum: 148c5fc86ca10d385e3d047014e14a09) #> ✔ End of download #> [zen4R][INFO] ZenodoRecord - End of download polymod_survey_files #> [1] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_contact_common.csv" #> [2] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_dictionary.xls" #> [3] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_hh_common.csv" #> [4] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_hh_extra.csv" #> [5] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_participant_common.csv" #> [6] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_participant_extra.csv" #> [7] "/Users/nick_1/Library/Application Support/org.R-project.R/R/contactsurveys/zenodo.3874557/2008_Mossong_POLYMOD_sday.csv" ``` A reference for any given survey can be obtained by passing a DOI to `get_citation()`: ``` r get_citation(polymod_doi) #> ℹ Fetching citation ✔ Citation fetched! [2.3s] #> @dataset{joel_mossong_2020_3874557, #> author = {Joël Mossong and #> Niel Hens and #> Mark Jit and #> Philippe Beutels and #> Kari Auranen and #> Rafael Mikolajczyk and #> Marco Massari and #> Stefania Salmaso and #> Gianpaolo Scalia Tomba and #> Jacco Wallinga and #> Janneke Heijne and #> Malgorzata Sadkowska-Todys and #> Magdalena Rosinska and #> W. John Edmunds}, #> title = {POLYMOD social contact data}, #> month = jun, #> year = 2020, #> publisher = {Zenodo}, #> version = 2, #> doi = {10.5281/zenodo.3874557}, #> url = {https://doi.org/10.5281/zenodo.3874557}, #> } ``` ## Using contact matrices with socialmixr You can then use the survey files downloaded with functions from [socialmixr](https://github.com/epiforecasts/socialmixr), `load_survey()` and `contact_matrix()`: ``` r library(socialmixr) # nolint #> #> Attaching package: 'socialmixr' #> The following objects are masked from 'package:contactsurveys': #> #> download_survey, get_citation, list_surveys #> The following object is masked from 'package:devtools': #> #> check polymod_loaded <- load_survey(polymod_survey_files) #> Warning: No reference provided. uk_contact_matrix <- contact_matrix( polymod_loaded, countries = "United Kingdom", age_limits = c(0, 18, 65) ) #> Removing participants that have contacts without age information. #> ℹ To change this behaviour, set the 'missing.contact.age' option. uk_contact_matrix #> $matrix #> contact.age.group #> age.group [0,18) [18,65) 65+ #> [0,18) 7.813187 5.505495 0.2664835 #> [18,65) 2.103215 8.174281 0.6463621 #> 65+ 1.160714 5.464286 1.7142857 #> #> $participants #> age.group participants proportion #> #> 1: [0,18) 364 0.3600396 #> 2: [18,65) 591 0.5845697 #> 3: 65+ 56 0.0553907 ``` # References