Internal function to get survey data

Description

Internal function to get survey data

Usage

.get_survey(survey, ...)

Arguments

Add age column from exact age (generic helper)

Description

Generic function to add an age column from an exact age column. Works for both participant and contact data by specifying the column prefix. If ⁠<prefix>_exact⁠ exists, it overwrites ⁠<prefix>⁠ with its values. Otherwise, it creates ⁠<prefix>⁠ with NA values if it doesn't exist.

Usage

add_age(data, prefix)

Arguments

Value

The data with the age column set from exact ages or initialised to NA

Check contact survey data

Description

Checks that a survey fulfills all the requirements to work with the 'contact_matrix' function

Usage

as_contact_survey(
  x,
  id_column = "part_id",
  country_column = NULL,
  year_column = NULL,
  ...,
  id.column = deprecated(),
  country.column = deprecated(),
  year.column = deprecated()
)

Arguments

Value

invisibly returns a character vector of the relevant columns

Examples

data(polymod)
check(polymod)

Assign age groups in survey data

Description

This function processes age data in a survey object. It imputes ages from ranges, handles missing values, and assigns age groups.

Usage

assign_age_groups(
  survey,
  age_limits = NULL,
  estimated_participant_age = c("mean", "sample", "missing"),
  estimated_contact_age = c("mean", "sample", "missing"),
  missing_participant_age = c("remove", "keep"),
  missing_contact_age = c("remove", "sample", "keep", "ignore")
)

Arguments

Value

The survey object with processed age data.

Examples

polymod_grouped <- assign_age_groups(polymod)
polymod_grouped
polymod_custom <- assign_age_groups(polymod, age_limits = c(0, 5, 10, 15))
polymod_custom

Check contact survey data

Description

Checks that a survey fulfills all the requirements to work with the 'contact_matrix' function

Usage

## S3 method for class 'contact_survey'
check(
  x,
  id.column = "part_id",
  participant.age.column = "part_age",
  country.column = "country",
  year.column = "year",
  contact.age.column = "cnt_age",
  ...
)

Arguments

Value

invisibly returns a character vector of the relevant columns

Examples

data(polymod)
check(polymod)

Clean contact survey data

Description

Cleans survey data to work with the 'contact_matrix' function

Usage

## S3 method for class 'contact_survey'
clean(
  x,
  participant_age_column = "part_age",
  ...,
  participant.age.column = deprecated()
)

Arguments

Value

a cleaned survey in the correct format

Examples

data(polymod)
cleaned <- clean(polymod) # not really necessary as the 'polymod' data set has already been cleaned

Generate a contact matrix from diary survey data

Description

Samples a contact survey

Usage

contact_matrix(
  survey,
  countries = NULL,
  survey_pop = NULL,
  age_limits = NULL,
  filter = NULL,
  counts = FALSE,
  symmetric = FALSE,
  split = FALSE,
  sample_participants = FALSE,
  estimated_participant_age = c("mean", "sample", "missing"),
  estimated_contact_age = c("mean", "sample", "missing"),
  missing_participant_age = c("remove", "keep"),
  missing_contact_age = c("remove", "sample", "keep", "ignore"),
  weights = NULL,
  weigh_dayofweek = FALSE,
  weigh_age = FALSE,
  weight_threshold = NA,
  symmetric_norm_threshold = 2,
  sample_all_age_groups = FALSE,
  sample_participants_max_tries = 1000,
  return_part_weights = FALSE,
  return_demography = NA,
  per_capita = FALSE,
  ...,
  survey.pop = deprecated(),
  age.limits = deprecated(),
  sample.participants = deprecated(),
  estimated.participant.age = deprecated(),
  estimated.contact.age = deprecated(),
  missing.participant.age = deprecated(),
  missing.contact.age = deprecated(),
  weigh.dayofweek = deprecated(),
  weigh.age = deprecated(),
  weight.threshold = deprecated(),
  symmetric.norm.threshold = deprecated(),
  sample.all.age.groups = deprecated(),
  sample.participants.max.tries = deprecated(),
  return.part.weights = deprecated(),
  return.demography = deprecated(),
  per.capita = deprecated()
)

Arguments

Value

a contact matrix, and the underlying demography of the surveyed population

Author(s)

Sebastian Funk

Examples

data(polymod)
contact_matrix(
  survey = polymod,
  countries = "United Kingdom",
  age_limits = c(0, 1, 5, 15)
)

Handle deprecated argument

Description

Handle deprecated argument

Usage

deprecate_arg(old_arg, new_arg, old_name, new_name, fn_name, version = "1.0.0")

Arguments

Value

the value to use (new_arg if provided, otherwise old_arg)

Download a survey from its Zenodo repository

Description

download_survey() has been deprecated in favour of contactsurveys::download_survey().

download_survey() downloads survey data from Zenodo.

Usage

download_survey(survey, dir = NULL, sleep = 1)

Arguments

Value

a vector of filenames that can be used with load_survey

Examples

# we recommend using the contactsurveys package for download_survey()
## Not run: 
# if needed, discover surveys with:
contactsurveys::list_surveys()
peru_survey <- download_survey("https://doi.org/10.5281/zenodo.1095664")
# -->
peru_survey <- contactsurveys::download_survey(
  "https://doi.org/10.5281/zenodo.1095664"
)

## End(Not run)

Find the minimal unique key for a data.table

Description

Given a data.table and a base identifier column, finds the minimal set of additional columns needed to uniquely identify each row.

Usage

find_unique_key(data, base_id = "part_id")

Arguments

Value

A character vector of column names that form the unique key

Citation for a survey

Description

get_citation() has been deprecated in favour of contactsurveys::get_citation().

Gets a full citation for a survey().

Usage

get_citation(x)

Arguments

Value

citation as bibentry

Examples

# we recommend using the contactsurveys package for get_citation()
## Not run: 
data(polymod)
citation <- contactsurveys::get_citation(polymod)
print(citation)
print(citation, style = "bibtex")

## End(Not run)

Get a survey, either from its Zenodo repository, a set of files, or a survey variable

Description

get_survey() has been deprecated in favour of using contactsurveys::download_survey() and then load_survey().

Downloads survey data, or extracts them from files, and returns a clean data set. If a survey URL is accessed multiple times, the data will be cached (unless clear_cache is set to TRUE) to avoid repeated downloads.

If survey objects are used repeatedly the downloaded files can be saved and reloaded between sessions then survey objects can be saved/loaded using base::saveRDS() and base::readRDS(), or via the individual survey files that can be downloaded using download_survey() and subsequently loaded using load_survey().

Usage

get_survey(survey, clear_cache = FALSE, ...)

Arguments

Value

a survey in the correct format

Examples

## Not run: 
list_surveys()
peru_doi <- "https://doi.org/10.5281/zenodo.1095664"
peru_survey <- get_survey(peru_doi)
## --> We now recommend:
peru_survey <- contactsurveys::download_survey(peru_doi)
peru_data <- load_survey(peru_survey)

## End(Not run)

Impute ages from ranges (generic helper)

Description

Generic function to impute ages from min/max ranges. Works for both participant and contact data by specifying the column prefix.

Usage

impute_ages(data, prefix, estimate = c("mean", "sample", "missing"))

Arguments

Value

The data with ages imputed according to the specified method

Impute contact ages

Description

Imputes contact survey data, where variables are named: "cnt_age_est_min" and "cnt_age_est_max". Uses mean imputation, sampling (hot deck), or leaves them as missing. These are controlled by the estimate argument.

Usage

impute_contact_ages(contacts, estimate = c("mean", "sample", "missing"))

Arguments

Value

The contact data, potentially with contact ages imputed depending on the estimate method and whether age columns are present in the data.

Impute participant ages

Description

Imputes participant survey data, where variables are named: "part_age_est_min" and "part_age_est_max". Uses mean imputation, sampling (hot deck), or leaves them as missing. These are controlled by the estimate argument.

Usage

impute_participant_ages(
  participants,
  estimate = c("mean", "sample", "missing")
)

Arguments

Value

The participant data, potentially with participant ages imputed depending on the estimate method and whether age columns are present in the data.

Checks if a character string is a DOI

Description

Checks if a character string is a DOI

Usage

is_doi(x)

Arguments

Value

Logical; TRUE if x is a DOI, FALSE otherwise

Author(s)

Sebastian Funk

Convert lower age limits to age groups.

Description

Mostly used for plot labelling

Usage

limits_to_agegroups(
  x,
  limits = sort(unique(x)),
  notation = c("dashes", "brackets")
)

Arguments

Value

Age groups as specified in notation

Examples

limits_to_agegroups(c(0, 5, 10))

List all surveys available for download

Description

list_surveys() has been deprecated in favour of contactsurveys::list_surveys().

Usage

list_surveys(clear_cache = FALSE)

Arguments

Value

character vector of surveys

Examples

# we recommend using the contactsurveys package now for listing surveys.
## Not run: 
contactsurveys::list_surveys()

## End(Not run)

Load a survey from local files

Description

Loads a survey from a local file system. Tables are expected as csv files, and a reference (if present) as JSON.

Usage

load_survey(files, participant_key = NULL, ...)

Arguments

Value

a survey in the correct format. For longitudinal surveys with multiple observations per participant, the returned object includes an observation_key field containing the column names (excluding part_id) that distinguish observations for the same participant.

Examples

## Not run: 
list_surveys()
peru_files <- download_survey("https://doi.org/10.5281/zenodo.1095664")
peru_survey <- load_survey(peru_files)

# For longitudinal surveys, specify the unique key explicitly:
france_files <- download_survey("https://doi.org/10.5281/zenodo.1157918")
france_survey <- load_survey(france_files,
  participant_key = c("part_id", "wave", "studyDay")
)

## End(Not run)

Draws an image plot of a contact matrix with a legend strip and the numeric values in the cells.

Description

This function combines the R image.plot function with numeric contact rates in the matrix cells.

Usage

matrix_plot(
  mij,
  min.legend = 0,
  max.legend = NA,
  num.digits = 2,
  num.colors = 50,
  main,
  xlab,
  ylab,
  legend.width,
  legend.mar,
  legend.shrink,
  cex.lab,
  cex.axis,
  cex.text,
  color.palette = heat.colors
)

Arguments

Details

This is a function using basic R graphics to visualise a social contact matrix.

Author(s)

Lander Willem

Examples

## Not run: 
data(polymod)
mij <- contact_matrix(polymod, countries = "United Kingdom", age_limits = c(0, 18, 65))$matrix
matrix_plot(mij)

## End(Not run)

Contact survey

Description

Deprecated. A survey object contains the results of a contact survey. In particular, it contains two data frames called participants and contacts that are linked by a column specified as id.column

Usage

new_contact_survey(participants, contacts, reference = NULL)

Arguments

Value

a new survey object

Author(s)

Sebastian Funk

Normalise country names

Description

Uses the countrycode package to standardise country names. This handles 2-letter ISO codes, 3-letter ISO codes, and full country names, converting them all to standardised country names.

Usage

normalise_country_names(countries)

Arguments

Value

A character vector of normalised country names

Social contact data from 8 European countries

Description

A dataset containing social mixing diary data from 8 European countries: Belgium, Germany, Finland, Great Britain, Italy, Luxembourg, The Netherlands and Poland. The Data are fully described in Mossong J, Hens N, Jit M, Beutels P, Auranen K, Mikolajczyk R, et al. (2008) Social Contacts and Mixing Patterns Relevant to the Spread of Infectious Diseases. PLoS Med 5(3): e74.

Usage

polymod

Format

A list of two data frames:

participants

the study participant, with age, country, year and day of the week (starting with 1 = Monday)

contacts

reported contacts of the study participants. The variable phys_contact has two levels (1 denotes physical contact while 2 denotes non-physical contact), duration_multi has five levels (1 is less than 5 minutes while 5 is more than 4 hours, increasing in the order found in Figure 1 in Mossong et al.), and frequency_multi has five levels (1 is daily, 2 is weekly, 3 is monthly, 4 is less often, and 5 is first time)

All other variables are described on the Zenodo repository of the data, available at doi:10.5281/zenodo.1043437

Source

doi:10.1371/journal.pmed.0050074

Change age groups in population data

Description

This changes population data to have age groups with the given age_limits, extrapolating linearly between age groups (if more are requested than available) and summing populations (if fewer are requested than available)

Usage

pop_age(
  pop,
  age_limits = NULL,
  pop_age_column = "lower.age.limit",
  pop_column = "population",
  ...,
  age.limits = deprecated(),
  pop.age.column = deprecated(),
  pop.column = deprecated()
)

Arguments

Value

data frame of age-specific population data

Examples

ages_it_2015 <- wpp_age("Italy", 2015)

# Modify the age data.frame to get age groups of 10 years instead of 5
pop_age(ages_it_2015, age_limits = seq(0, 100, by = 10))

# The function will also automatically interpolate if necessary
pop_age(ages_it_2015, age_limits = c(0, 18, 40, 65))

Reduce the number of age groups given a broader set of limits

Description

Operates on lower limits

Usage

reduce_agegroups(x, limits)

Arguments

Value

vector with the new age groups

Examples

reduce_agegroups(seq_len(20), c(0, 5, 10))

Contact survey

Description

Deprecated. Use as_survey instead.

Usage

survey(participants, contacts, reference = NULL)

Arguments

Value

a new survey object

Author(s)

Sebastian Funk

List all countries contained in a survey

Description

Usage

survey_countries(survey, country.column = "country", ...)

Arguments

Details

survey_countries() has been deprecated in favour of using contactsurveys::download_survey(), and load_survey(), and then exploring the country column yourself.

Value

list of countries

Examples

data(polymod)
survey_countries(polymod)
## --> we now recommend
## Not run: 
doi_peru <- "10.5281/zenodo.1095664" # nolint
# download the data with the contactsurveys package
peru_survey <- contactsurveys::download_survey(doi_peru)
# load the survey with socialmixr
peru_data <- socialmixr::load_survey(peru_survey)
# find the unique country - assuming your data has a "country" column:
unique(peru_data$participants$country)

## End(Not run)

Get survey country population data

Description

Looks up the country and year inside a survey, or a provided "countries" value, and determines the corresponding demographics in the world population prospects data using wpp_age().

Usage

survey_country_population(survey, countries = NULL)

Arguments

Value

A data table with population data by age group for the survey countries, aggregated by lower age limit. The function will error if no country information is available from either the survey or countries argument.

Examples

survey_country_population(polymod)
survey_country_population(polymod, countries = "Belgium")
survey_country_population(polymod, countries = c("Belgium", "Italy"))

Get age-specific population data according to the World Population Prospects 2017 edition

Description

This uses data from the wpp2017 package but combines male and female, and converts age groups to lower age limits. If the requested year is not present in the historical data, wpp projections are used.

Usage

wpp_age(countries, years)

Arguments

Value

data frame of age-specific population data

Examples

wpp_age("Italy", c(1990, 2000))

List all countries and regions for which socialmixr has population data

Description

Uses the World Population Prospects data from the wpp2017 package

Usage

wpp_countries()

Value

list of countries

Examples

wpp_countries()