This release focuses on improved modularity and flexibility for contact matrix workflows. Key highlights include new standalone functions for age group assignment and population data retrieval, more intuitive handling of age limits, and the beginning of a transition to the contactsurveys package for survey downloads.
We thank Nicholas Tierney (@njtierney), Lander Willem (@lwillem), Hugo Gruson (@Bisaloo), Lloyd Chapman (@LloydChapman), James Azam (@jamesmbaazam), and Abdoelnaser Degoot (@Degoot-AM) for their contributions to this release.
contact_matrix() now preserves all user-specified
age_limits, even when no participants exist in some age
groups. Previously, age groups beyond the maximum participant age were
silently dropped. Empty age groups now show 0 participants and NA values
in the matrix. This may change matrix dimensions for existing code
(@Bisaloo, #144,
#231).
contact_matrix(counts = TRUE)$matrix now returns an
array rather than an xtabs object. This matches the existing output
format of contact_matrix(counts = FALSE)$matrix (@Bisaloo, #118).
When age_limits is not specified, it is now inferred
from both participant and contact ages, not just participant ages. This
may result in more age groups if contacts include ages beyond the
participant age range (#230).
as_contact_survey() no longer requires
country and year columns. These columns are
now auto-detected if present, but surveys without them can be loaded
successfully (#193, #199).
New assign_age_groups() and
survey_country_population() functions allow modular
pre-processing of survey data (#131, #226).
Reduced verbosity by removing messages about removing participants/contacts with missing ages (#228).
clean() now correctly processes age values with
units (e.g., “6 months”, “52 weeks”) (@LloydChapman, #250, #256).
contact_matrix() now warns when a survey contains
multiple observations per participant, as results will aggregate across
all observations (#260).
load_survey() now correctly loads longitudinal
surveys with repeated observations per participant (e.g., sday files
with wave/studyDay columns). Previously, these columns were silently
dropped (@njtierney, #192, #194).
Fixed a bug leading to excess contacts with NA age
if the lowest age group did not start at 0 (@lwillem, #170).
Argument names with dots (e.g., age.limits) have
been deprecated in favour of underscores (e.g., age_limits)
in contact_matrix(), as_contact_survey(),
pop_age(), and clean(). The old argument names
still work but will produce deprecation warnings (#160).
get_survey(), download_survey(),
get_citation(), list_surveys(), and
survey_countries() have been soft-deprecated and moved to
contactsurveys.
This is part of decoupling these features from socialmixr to reduce
dependencies (@njtierney, #179, #207). These will
continue to work until version 1.0.0.
The missing_contact_age = "sample" option in
contact_matrix() and assign_age_groups() has
been soft-deprecated. Use "remove" to exclude contacts with
missing ages, "keep" to retain them as a separate age
group, or "ignore" to drop only those contacts
(#273).
limits_to_agegroups has been changed to return
bracket notated age ranges by defaultAn error in list_surveys() was fixed which stopped
this working.
contact_matrix() was updated to only accept
survey objects, not DOIs and matches the documentation. It
is still possible to get a contact matrix from a DOI but it is necessary
to go through the get_survey() function.
```r # No longer works! contact_matrix(“10.5281/zenodo.1095664”)
get_survey(“10.5281/zenodo.1095664”) |> contact_matrix()
The efficiency of the contact_matrix() was
improved.
cite function has been deprecated and replaced with
get_citation (#84).columns argument has been removed from
check.survey() (#81).download_survey() has been reduced by
externalising the find_common_prefix() function and failing
early instead of relying on unnecessary if/else sequenceserror argument has been removed from
check() and always return warnings. If you want to turn
these warnings into errors, please have a look at
options(warn = 2)quiet argument has been removed from
check(), cite(),
contact_matrix(), and get_survey(). If you
want to silence diagnostic messages, you should use R idiomatic
mechanisms, such as suppressMessages()n and bootstrap options of
contact_matrix() have been deprecated and replaced with a
sample.participants argument; bootstrapping is now
explained in the vignette insteadmatrix_plot() function to plot contact matrixchkDots() is now used to ensure no argument is silently
ignored by S3 methodsget_survey() has been split into separate functions for
downloading and processing survey datareduce_agegroups