socialmixr (version 0.7.0)

compute_matrix: Compute contact matrix from prepared survey data

Description

Computes a contact matrix from a contact_survey that has been processed by assign_age_groups() and optionally weigh(). This is the final step in the pipeline workflow.

For post-processing, pipe the result into symmetrise(), split_matrix(), or per_capita().

Usage

compute_matrix(survey, by = "age", counts = FALSE, weight_threshold = NULL)

Value

a contact_matrix object with elements matrix (a rank-2K

array) and participants (a long table with one row per grouping combination)

Arguments

survey

a survey() object with the columns named in by present on both participants and contacts. Age groupings come from assign_age_groups(); other groupings should already be present as part_<name> / cnt_<name> columns on the survey.

by

character vector or list of grouping specifications. Each entry is either the string "age" (uses age.group / contact.age.group), a stem string "<name>" (uses part_<name> / cnt_<name>), or an explicit c(part = "X", cnt = "Y"). Default "age" reproduces the single-grouping behaviour of previous releases.

counts

whether to return counts instead of means

weight_threshold

numeric; if provided, weights above this threshold are capped to the threshold value and then re-normalised (default NULL)

Multi-dimensional matrices

Passing more than one entry to by produces a matrix of rank 2K, where K = length(by). The first K dimensions index participants and the last K dimensions index contacts, in the order given to by. For example, by = c("age", "gender") returns an array with dimensions (age, gender, age, gender) — age and gender of the participant first, then of the contact. Dim names carry the levels of each grouping.

Examples

data.table::setDTthreads(1L)
data(polymod)

# Single-grouping (age) — default
polymod |>
  assign_age_groups(age_limits = c(0, 5, 15)) |>
  compute_matrix()

# Two-grouping (age x gender)
polymod |>
  assign_age_groups(age_limits = c(0, 5, 15)) |>
  compute_matrix(by = c("age", "gender"))