Skip to contents

Generate a contact matrix from diary survey data

Source: R/contact_matrix.r
contact_matrix.Rd

Samples a contact survey using a bootstrap

Usage

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,
  ...
)

Arguments

survey

a survey() object

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 wpp_countries; if not given, will use the country populations from the chosen countries, or all countries in the survey if countries is not given

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 \(c_{ij}N_i = c_{ji}N_j\).

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 survey() object with user-specified weights (default = empty vector)

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 get_survey(), check() and pop_age() (especially column names)

Value

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

Author

Sebastian Funk

Examples

data(polymod)
contact_matrix(polymod, countries = "United Kingdom", age.limits = c(0, 1, 5, 15))
#> Removing participants that have contacts without age information. To change this behaviour, set the 'missing.contact.age' option
#> $matrix
#>          contact.age.group
#> age.group      [0,1)     [1,5)   [5,15)      15+
#>    [0,1)  0.40000000 0.8000000 1.266667 5.933333
#>    [1,5)  0.11250000 1.9375000 1.462500 5.450000
#>    [5,15) 0.02450980 0.5049020 7.946078 6.215686
#>    15+    0.03230337 0.3581461 1.290730 9.594101
#> 
#> $participants
#>    age.group participants proportion
#>       <char>        <int>      <num>
#> 1:     [0,1)           15 0.01483680
#> 2:     [1,5)           80 0.07912957
#> 3:    [5,15)          204 0.20178042
#> 4:       15+          712 0.70425321
#>