The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.