Title: | Social Mixing Matrices for Infectious Disease Modelling |
---|---|
Description: | Provides methods for sampling contact matrices from diary data for use in infectious disease modelling, as discussed in Mossong et al. (2008) <doi:10.1371/journal.pmed.0050074>. |
Authors: | Sebastian Funk [aut, cre], Lander Willem [aut], Hugo Gruson [aut], Maria Bekker-Nielsen Dunbar [ctb], Carl A. B. Pearson [ctb], Sam Clifford [ctb], Christopher Jarvis [ctb], Alexis Robert [ctb], Niel Hens [ctb], Pietro Coletti [col, dtm] |
Maintainer: | Sebastian Funk <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.3.2.9000 |
Built: | 2024-08-18 05:19:09 UTC |
Source: | https://github.com/epiforecasts/socialmixr |
Checks that a survey fulfills all the requirements to work with the 'contact_matrix' function
## S3 method for class 'survey' check( x, columns, id.column = "part_id", participant.age.column = "part_age", country.column = "country", year.column = "year", contact.age.column = "cnt_age", ... )
## S3 method for class 'survey' check( x, columns, id.column = "part_id", participant.age.column = "part_age", country.column = "country", year.column = "year", contact.age.column = "cnt_age", ... )
x |
A |
columns |
deprecated argument, ignored |
id.column |
the column in both the |
participant.age.column |
the column in the |
country.column |
the column in the |
year.column |
the column in the |
contact.age.column |
the column in the |
... |
ignored |
invisibly returns a character vector of the relevant columns
data(polymod) check(polymod)
data(polymod) check(polymod)
Gets a full citation for a survey()
.
## S3 method for class 'survey' cite(x, ...)
## S3 method for class 'survey' cite(x, ...)
x |
a character vector of surveys to cite |
... |
ignored |
citation as bibentry
data(polymod) cite(polymod)
data(polymod) cite(polymod)
Cleans survey data to work with the 'contact_matrix' function
## S3 method for class 'survey' clean(x, country.column = "country", participant.age.column = "part_age", ...)
## S3 method for class 'survey' clean(x, country.column = "country", participant.age.column = "part_age", ...)
x |
A |
country.column |
the name of the country in which the survey participant was interviewed |
participant.age.column |
the column in |
... |
ignored |
a cleaned survey in the correct format
data(polymod) cleaned <- clean(polymod) # not really necessary as the 'polymod' data set has already been cleaned
data(polymod) cleaned <- clean(polymod) # not really necessary as the 'polymod' data set has already been cleaned
Samples a contact survey using a bootstrap
contact_matrix( survey, countries = NULL, survey.pop, age.limits, filter, n = 1, bootstrap, 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, sample.all.age.groups = FALSE, return.part.weights = FALSE, return.demography = NA, per.capita = FALSE, ... )
contact_matrix( survey, countries = NULL, survey.pop, age.limits, filter, n = 1, bootstrap, 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, sample.all.age.groups = FALSE, return.part.weights = FALSE, return.demography = NA, per.capita = FALSE, ... )
survey |
a |
countries |
limit to one or more countries; if not given, will use all countries in the survey; these can be given as country names or 2-letter (ISO Alpha-2) country codes |
survey.pop |
survey population – either a data frame with columns 'lower.age.limit' and 'population', or a character vector giving the name(s) of a country or countries from the list that can be obtained via |
age.limits |
lower limits of the age groups over which to construct the matrix |
filter |
any filters to apply to the data, given as list of the form (column=filter_value) - only contacts that have 'filter_value' in 'column' will be considered. If multiple filters are given, they are all applied independently and in the sequence given. |
n |
deprecated; number of bootstrap samples to generate |
bootstrap |
deprecated; whether to bootstrap contact matrices |
counts |
whether to return counts (instead of means) |
symmetric |
whether to make matrix symmetric, such that |
split |
whether to split the number of contacts and assortativity |
sample.participants |
whether to sample participants randomly (with replacement); done multiple times this can be used to assess uncertainty in the generated contact matrices. See the "Bootstrapping" section in the vignette for how to do this.. |
estimated.participant.age |
if set to "mean" (default), people whose ages are given as a range (in columns named "..._est_min" and "..._est_max") but not exactly (in a column named "..._exact") will have their age set to the mid-point of the range; if set to "sample", the age will be sampled from the range; if set to "missing", age ranges will be treated as missing |
estimated.contact.age |
if set to "mean" (default), contacts whose ages are given as a range (in columns named "..._est_min" and "..._est_max") but not exactly (in a column named "..._exact") will have their age set to the mid-point of the range; if set to "sample", the age will be sampled from the range; if set to "missing", age ranges will be treated as missing |
missing.participant.age |
if set to "remove" (default), participants without age information are removed; if set to "keep", participants with missing age are kept and treated as a separate age group |
missing.contact.age |
if set to "remove" (default), participants that have contacts without age information are removed; if set to "sample", contacts without age information are sampled from all the contacts of participants of the same age group; if set to "keep", contacts with missing age are kept and treated as a separate age group; if set to "ignore", contact with missing age are ignored in the contact analysis |
weights |
column names(s) of the participant data of the |
weigh.dayofweek |
whether to weigh social contacts data by the day of the week (weight (5/7 / N_week / N) for weekdays and (2/7 / N_weekend / N) for weekends) |
weigh.age |
whether to weigh social contacts data by the age of the participants (vs. the populations' age distribution) |
weight.threshold |
threshold value for the standardized weights before running an additional standardisation (default 'NA' = no cutoff) |
sample.all.age.groups |
what to do if bootstrapping fails to sample participants from one or more age groups; if FALSE (default), corresponding rows will be set to NA, if TRUE the sample will be discarded and a new one taken instead |
return.part.weights |
boolean to return the participant weights |
return.demography |
boolean to explicitly return demography data that corresponds to the survey data (default 'NA' = if demography data is requested by other function parameters) |
per.capita |
wheter to return a matrix with contact rates per capita (default is FALSE and not possible if 'counts=TRUE' or 'split=TRUE') |
... |
further arguments to pass to |
a contact matrix, and the underlying demography of the surveyed population
Sebastian Funk
data(polymod) contact_matrix(polymod, countries = "United Kingdom", age.limits = c(0, 1, 5, 15))
data(polymod) contact_matrix(polymod, countries = "United Kingdom", age.limits = c(0, 1, 5, 15))
Downloads survey data
download_survey(survey, dir = NULL, sleep = 1)
download_survey(survey, dir = NULL, sleep = 1)
survey |
a URL (see |
dir |
a directory to save the files to; if not given, will save to a temporary directory |
sleep |
time to sleep between requests to avoid overloading the server
(passed on to |
a vector of filenames that can be used with load_survey
## Not run: list_surveys() peru_survey <- download_survey("https://doi.org/10.5281/zenodo.1095664") ## End(Not run)
## Not run: list_surveys() peru_survey <- download_survey("https://doi.org/10.5281/zenodo.1095664") ## End(Not run)
Gets a full citation for a survey()
.
get_citation(x)
get_citation(x)
x |
a character vector of surveys to cite |
citation as bibentry
data(polymod) citation <- get_citation(polymod) print(citation) print(citation, style = "bibtex")
data(polymod) citation <- get_citation(polymod) print(citation) print(citation, style = "bibtex")
Downloads survey data, or extracts them from files, and returns a clean data set.
get_survey(survey, ...)
get_survey(survey, ...)
survey |
a DOI or url to get the survey from, or a |
... |
options for |
a survey in the correct format
## Not run: list_surveys() peru_survey <- get_survey("https://doi.org/10.5281/zenodo.1095664") ## End(Not run)
## Not run: list_surveys() peru_survey <- get_survey("https://doi.org/10.5281/zenodo.1095664") ## End(Not run)
Checks if a character string is a DOI
is_doi(x)
is_doi(x)
x |
Character vector; the string or strings to check |
Logical; TRUE
if x
is a DOI, FALSE
otherwise
Sebastian Funk
Mostly used for plot labelling
limits_to_agegroups(x, limits = sort(unique(x)))
limits_to_agegroups(x, limits = sort(unique(x)))
x |
age limits to transform |
limits |
lower age limits; if not given, will use all limits in |
Age groups (limits separated by dashes)
limits_to_agegroups(c(0, 5, 10))
limits_to_agegroups(c(0, 5, 10))
List all surveys available for download
list_surveys()
list_surveys()
character vector of surveys
## Not run: list_surveys() ## End(Not run)
## Not run: list_surveys() ## End(Not run)
Loads a survey from a local file system. Tables are expected as csv files, and a reference (if present) as JSON.
load_survey(files, ...)
load_survey(files, ...)
files |
a vector of file names as returned by |
... |
options for |
a survey in the correct format
## Not run: list_surveys() peru_files <- download_survey("https://doi.org/10.5281/zenodo.1095664") peru_survey <- load_survey(peru_files) ## End(Not run)
## Not run: list_surveys() peru_files <- download_survey("https://doi.org/10.5281/zenodo.1095664") peru_survey <- load_survey(peru_files) ## End(Not run)
This function combines the R image.plot function with numeric contact rates in the matrix cells.
matrix_plot( mij, min.legend = 0, max.legend = NA, num.digits = 2, num.colors = 50, main, xlab, ylab, legend.width, cex.lab, cex.axis, cex.text, color.palette = heat.colors, ... )
matrix_plot( mij, min.legend = 0, max.legend = NA, num.digits = 2, num.colors = 50, main, xlab, ylab, legend.width, cex.lab, cex.axis, cex.text, color.palette = heat.colors, ... )
mij |
a contact matrix containing contact rates between participants of age i (rows) with contacts of age j (columns). This is the default matrix format of |
min.legend |
the color scale minimum (default = 0). Set to NA to use the minimium value of |
max.legend |
the color scale maximum (default = NA). Set to NA to use the maximum value of |
num.digits |
the number of digits when rounding the contact rates (default = 2). Use NA to disable this. |
num.colors |
the number of color breaks (default = 50) |
main |
the figure title |
xlab |
a title for the x axis (default: "Age group (years)") |
ylab |
a title for the y axis (default: "Contact age group (years)") |
legend.width |
width of the legend strip in characters. Default is 1. |
cex.lab |
size of the x and y labels (default: 1.2) |
cex.axis |
size of the axis labels (default: 0.8) |
cex.text |
size of the numeric values in the matrix (default: 1) |
color.palette |
the color palette to use (default: |
... |
further arguments to pass to |
This is a function using the basic R graphics to make it easier for users of socialmixr to visualise social contact matrices.
Lander Willem
## Not run: data(polymod) mij <- contact_matrix(polymod, countries = "United Kingdom", age.limits = c(0, 18, 65))$matrix matrix_plot(mij) ## End(Not run)
## Not run: data(polymod) mij <- contact_matrix(polymod, countries = "United Kingdom", age.limits = c(0, 18, 65))$matrix matrix_plot(mij) ## End(Not run)
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.
polymod
polymod
A list of two data frames:
the study participant, with age, country, year and day of the week (starting with 1 = Monday)
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
doi:10.1371/journal.pmed.0050074
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)
pop_age( pop, age.limits, pop.age.column = "lower.age.limit", pop.column = "population", ... )
pop_age( pop, age.limits, pop.age.column = "lower.age.limit", pop.column = "population", ... )
pop |
a data frame with columns indicating lower age limits and population sizes (see 'age.column' and 'pop.column') |
age.limits |
lower age limits of age groups to extract |
pop.age.column |
column in the 'pop' data frame indicating the lower age group limit |
pop.column |
column in the 'pop' data frame indicating the population size |
... |
ignored |
data frame of age-specific population data
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.limit = seq(0, 100, by = 10)) # The function will also automatically interpolate if necessary pop_age(ages_it_2015, age.limit = c(0, 18, 40, 65))
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.limit = seq(0, 100, by = 10)) # The function will also automatically interpolate if necessary pop_age(ages_it_2015, age.limit = c(0, 18, 40, 65))
Operates on lower limits
reduce_agegroups(x, limits)
reduce_agegroups(x, limits)
x |
vector of limits |
limits |
new limits |
vector with the new age groups
reduce_agegroups(seq_len(20), c(0, 5, 10))
reduce_agegroups(seq_len(20), c(0, 5, 10))
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
survey(participants, contacts, reference = NULL)
survey(participants, contacts, reference = NULL)
participants |
a |
contacts |
a |
reference |
a |
a new survey object
Sebastian Funk
data(polymod) new_survey <- survey(polymod$participants, polymod$contacts)
data(polymod) new_survey <- survey(polymod$participants, polymod$contacts)
List all countries contained in a survey
survey_countries(survey, country.column = "country", ...)
survey_countries(survey, country.column = "country", ...)
survey |
a DOI or url to get the survey from, or a |
country.column |
column in the survey indicating the country |
... |
further arguments for |
list of countries
data(polymod) survey_countries(polymod)
data(polymod) survey_countries(polymod)
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.
wpp_age(countries, years)
wpp_age(countries, years)
countries |
countries, will return all if not given |
years |
years, will return all if not given |
data frame of age-specific population data
wpp_age("Italy", c(1990, 2000))
wpp_age("Italy", c(1990, 2000))
Uses the World Population Prospects data from the wpp2017
package
wpp_countries()
wpp_countries()
list of countries
wpp_countries()
wpp_countries()