Title: Download Contact Surveys for Use in Infectious Disease Modelling
Version: 0.1.0
Description: Download, cache, and manage social contact survey data from the social contact data community on Zenodo (https://zenodo.org/communities/social_contact_data) for use in infectious disease modelling. Provides functions to list available surveys, download survey files with automatic caching, and retrieve citations. Contact survey data describe who contacts whom in a population and are used to parameterise age-structured transmission models, for example via the 'socialmixr' package. The surveys available include those from the POLYMOD study (Mossong et al. (2008) <doi:10.1371/journal.pmed.0050074>) and other social contact data shared on Zenodo.
License: MIT + file LICENSE
Language: en-US
Depends: R (≥ 4.1.0)
Imports: cli (≥ 3.6.0), data.table, oai, purrr, rlang (≥ 1.0.0), stats, yesno, zen4R (≥ 0.10.3)
Suggests: socialmixr (≥ 0.5.0), knitr, rmarkdown, roxyglobals, testthat (≥ 3.0.0), withr, vcr (≥ 2.0.0)
VignetteBuilder: knitr
Encoding: UTF-8
NeedsCompilation: no
RoxygenNote: 7.3.3
URL: https://github.com/epiforecasts/contactsurveys, http://epiforecasts.io/contactsurveys/
BugReports: https://github.com/epiforecasts/contactsurveys/issues
Config/testthat/edition: 3
Config/roxyglobals/filename: globals.R
Config/roxyglobals/unique: FALSE
Packaged: 2026-01-27 20:28:25 UTC; eidesfun
Author: Sebastian Funk ORCID iD [aut, cre, cph], Nicholas Tierney ORCID iD [aut], Hugo Gruson ORCID iD [ctb]
Maintainer: Sebastian Funk <sebastian.funk@lshtm.ac.uk>
Repository: CRAN
Date/Publication: 2026-01-31 19:20:02 UTC

contactsurveys: Download Contact Surveys for Use in Infectious Disease Modelling

Description

Download, cache, and manage social contact survey data from the social contact data community on Zenodo (https://zenodo.org/communities/social_contact_data) for use in infectious disease modelling. Provides functions to list available surveys, download survey files with automatic caching, and retrieve citations. Contact survey data describe who contacts whom in a population and are used to parameterise age-structured transmission models, for example via the 'socialmixr' package. The surveys available include those from the POLYMOD study (Mossong et al. (2008) doi:10.1371/journal.pmed.0050074) and other social contact data shared on Zenodo.

Author(s)

Maintainer: Sebastian Funk sebastian.funk@lshtm.ac.uk (ORCID) [copyright holder]

Authors:

Other contributors:

See Also

Useful links:

Directory for persistent storage of contact surveys

Description

Returns a platform-specific directory for persistent storage of downloaded survey files, powered by tools::R_user_dir(). You can override this by setting the environment variable CONTACTSURVEYS_HOME.

Usage

contactsurveys_dir()

Details

By default, download_survey() and list_surveys() use tempdir() so files do not persist across R sessions. To enable persistent caching, pass contactsurveys_dir() as the directory argument, e.g. download_survey(survey, directory = contactsurveys_dir()).

Value

the active contactsurveys directory.

Examples


contactsurveys_dir()

## Override with an environment variable:
Sys.setenv(CONTACTSURVEYS_HOME = tempdir())
contactsurveys_dir()
## Unset
Sys.unsetenv("CONTACTSURVEYS_HOME")

Delete files in contactsurveys directory

Description

Delete files in contactsurveys directory

Usage

delete_contactsurveys_files(dir = contactsurveys_dir())

delete_contactsurveys_dir(dir = contactsurveys_dir())

Arguments

dir

directory to list files to delete from

Value

nothing, deletes files.

Examples


delete_contactsurveys_files()

Delete files for a given survey

Description

For when you want to delete files associated with a given survey.

Usage

delete_survey(survey)

Arguments

survey

Survey, as used in download_survey().

Value

nothing, deleted files

See Also

delete_contactsurveys_dir() delete_contactsurveys_files()

Examples


peru_doi <- "https://doi.org/10.5281/zenodo.1095664"
delete_survey(peru_doi)

Download a survey from its Zenodo repository

Description

Downloads survey data. Uses a caching mechanism via the default argument for directory.

Usage

download_survey(
  survey,
  directory = tempdir(),
  verbose = TRUE,
  overwrite = FALSE,
  timeout = 3600,
  rate = purrr::rate_backoff(pause_base = 5, max_times = 4)
)

Arguments

survey

A DOI of a survey, (see list_surveys()). If a HTML link is given, the DOI will be isolated and used.

directory

Directory of where to save survey files. Defaults to tempdir(), so files do not persist across R sessions. For persistent caching, pass contactsurveys_dir(), which uses tools::R_user_dir() and appends the survey URL/DOI basename as a subdirectory. E.g., if you provide "10.5281/zenodo.1095664" in the survey argument, it will save the surveys into a directory zenodo.1095664 under contactsurveys_dir(). You can also set an environment variable, CONTACTSURVEYS_HOME, see Sys.setenv() or Renviron for more detail.

verbose

Whether downloads should be echoed to output. Default TRUE.

overwrite

If files should be overwritten if they already exist. Default FALSE

timeout

A numeric value specifying timeout in seconds. Default 3600 seconds.

rate

a purrr rate object, to facilitate downloading if the download fails. Defaults to an exponential backoff of 5 seconds (up to 4 attempts: 1 initial + 3 retries) changed by specifying your own rate object, see ?purrr::rate_backoff() for details.

Value

a vector of filenames, where the surveys were downloaded

See Also

list_surveys()

Examples


list_surveys()
peru_survey <- download_survey("https://doi.org/10.5281/zenodo.1095664")

Get citation from a DOI

Description

This is a wrapper around zen4R::get_citation() with a couple of smaller changes. Firstly, it silences output from zen4R::get_citation(), secondly the default citation style is "apa".

Usage

get_citation(
  doi,
  style = c("bibtex", "apa", "harvard-cite-them-right", "modern-language-association",
    "vancouver", "chicago-fullnote-bibliography", "ieee"),
  verbose = TRUE
)

Arguments

doi

A string, the Zenodo DOI or concept DOI.

style

A string, the citation style. Default is "bibtex". Possible values are: "bibtex", "harvard-cite-them-right", "apa", "modern-language-association", "vancouver", "chicago-fullnote-bibliography", or "ieee".

verbose

logical. Should messages during citation fetching print to the screen? Default is TRUE.

Value

A character string containing the citation in the requested style. For "bibtex" style, returns an object of class "csbib".

Examples


polymod_doi <- "https://doi.org/10.5281/zenodo.3874557"
get_citation(polymod_doi)

Checks if a character string is a DOI

Description

Checks if a character string is a DOI

Usage

is_doi(x)

Arguments

x

Character vector; the string or strings to check

Value

Logical; TRUE if x is a DOI, FALSE otherwise

Author(s)

Sebastian Funk

List all surveys available for download

Description

List all surveys available for download

Usage

list_surveys(
  directory = tempdir(),
  overwrite = FALSE,
  verbose = TRUE,
  rate = purrr::rate_backoff(pause_base = 5, max_times = 4)
)

Arguments

directory

Directory to save the cached survey list. Defaults to tempdir(), so the cached list does not persist across R sessions. For persistent caching, pass contactsurveys_dir().

overwrite

If files should be overwritten if they already exist. Default FALSE

verbose

Whether downloads should be echoed to output. Default TRUE.

rate

a purrr rate object, to facilitate downloading if the download fails. Defaults to an exponential backoff of 5 seconds (up to 4 attempts: 1 initial + 3 retries) changed by specifying your own rate object, see ?purrr::rate_backoff() for details.

Value

data.table with columns: date_added, title, creator, url

Examples


list_surveys()

List files in contactsurveys cache

Description

It can be handy to see which files are available, sometimes to return to a clean slate and delete them via the ⁠delete_contactsurveys_*()⁠ functions.

Usage

ls_contactsurveys(dir = contactsurveys_dir())

Arguments

dir

Directory to list. Default is contactsurveys_dir().

Value

Character vector of file paths under dir (absolute paths).

See Also

delete_contactsurveys_files() delete_survey() delete_contactsurveys_dir() download_survey() contactsurveys_dir()

Examples

ls_contactsurveys()

Print a csbib citation

Description

Print a csbib citation

Usage

## S3 method for class 'csbib'
print(x, ...)

Arguments

x

A "csbib" object.

...

Additional arguments passed to methods.

Value

Invisibly returns x.