Deprecate missing_contact_age = 'sample' option

The 'sample' option requires the participant-contact merge to have
happened first, which prevents modular pre-processing of survey data.
Users should use 'remove', 'keep', or 'ignore' instead.

Fixes #273

Co-authored-by: sbfnk-bot <242615673+sbfnk-bot@users.noreply.github.com>

Author: sbfnk

NEWS.md

@@ -26,6 +26,8 @@
 
 ## Deprecations
 
+* The `missing_contact_age = "sample"` option in `contact_matrix()` and `assign_age_groups()` has been soft-deprecated and will be removed in a future version. 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).
+
 * 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).
 
 * We have soft-deprecated `get_survey()`, `download_survey()`, `get_citation()` and `list_surveys()` and moved these to [contactsurveys](https://github.com/epiforecasts/contactsurveys). We have also soft-deprecated `survey_countries()` as this called `get_survey()` internally. This is part of decoupling these features from socialmixr to reduce dependencies (#207 and #179). These will continue to be supported until we move to a major release (version 1.0.0) of socialmixr. In the meantime, we recommend that users use the [contactsurveys](https://github.com/epiforecasts/contactsurveys) package, as these functions have improved caching and support there.

R/assign-age-groups.R

@@ -54,6 +54,18 @@ assign_age_groups <- function(
   missing_participant_age <- rlang::arg_match(missing_participant_age)
   missing_contact_age <- rlang::arg_match(missing_contact_age)
 
+  if (missing_contact_age == "sample") {
+    lifecycle::deprecate_warn(
+      "0.5.0",
+      "assign_age_groups(missing_contact_age = 'sample')",
+      details = paste(
+        "Sampling missing contact ages will be removed in a future version.",
+        "Use 'remove' to exclude contacts with missing ages, 'keep' to retain",
+        "them as a separate age group, or 'ignore' to drop only those contacts."
+      )
+    )
+  }
+
   ## set contact age and participant age if it's not in the data
   survey$participants <- add_part_age(survey$participants)
   survey$contacts <- add_contact_age(survey$contacts)

R/contact_matrix.R

@@ -211,6 +211,18 @@ contact_matrix <- function(
   missing_participant_age <- match.arg(missing_participant_age)
   missing_contact_age <- match.arg(missing_contact_age)
 
+  if (missing_contact_age == "sample") {
+    lifecycle::deprecate_warn(
+      "0.5.0",
+      "contact_matrix(missing_contact_age = 'sample')",
+      details = paste(
+        "Sampling missing contact ages will be removed in a future version.",
+        "Use 'remove' to exclude contacts with missing ages, 'keep' to retain",
+        "them as a separate age group, or 'ignore' to drop only those contacts."
+      )
+    )
+  }
+
   survey <- copy(survey)
 
   check_if_contact_survey(survey)

R/globals.R

@@ -94,7 +94,6 @@ utils::globalVariables(c(
   "..original.lower.age.limit", # <pop_age>
   "..segment", # <pop_age>
   "..upper.age.limit", # <pop_age>
-  "population", # <pop_age>
   "population", # <survey_country_population>
   "sex", # <wpp_age>
   "country", # <wpp_age>