R/roles_validate.R

Defines functions .reresolve_for_mode roles_validate

Documented in roles_validate

#' Validate a roles table
#'
#' Fail-closed validation of a two-axis `roles` table before [mask()]
#' consumes it. Returns the validated table - with any `NA` actions
#' resolved to their (role, kind, mode) defaults - so callers can use
#' the return value directly.
#'
#' Tables produced by masque 0.5.0 and earlier (no `action` column;
#' v1 vocabulary with `keep` / `ignore` roles and the optional
#' `mask_levels` column) are upgraded in place with a deprecation
#' warning. The upgrade preserves the v1 semantics exactly: v1 `keep`
#' becomes action `keep`; v1 `ignore` becomes role `id` / `text` /
#' `other` with action `keep` in local mode and `drop` in collaborate
#' mode; v1 treatment `mask_levels = "permute"` becomes action
#' `scramble`.
#'
#' Hard errors:
#'
#' \itemize{
#'   \item missing required columns (`col`, `role`, `action`, `kind`);
#'   \item unknown role (not in `design`, `treatment`, `outcome`,
#'     `covariate`, `date`, `id`, `text`, `other`) or unknown action
#'     (not in `keep`, `scramble`, `alias`, `drop`);
#'   \item any `NA` role (an `NA` *action* is allowed - it resolves to
#'     the default for the row's role and kind);
#'   \item an incompatible (role, action, kind) combination, e.g.
#'     `design` + `scramble`, numeric + `alias`, `id` + `scramble`,
#'     `other` + anything but keep / drop;
#'   \item duplicate `col` entries;
#'   \item if `df` supplied: any `df` column missing from `roles`, or
#'     any `roles` column missing from `df`.
#' }
#'
#' Loud advisories (warnings, not errors):
#'
#' \itemize{
#'   \item every action is `keep` - the "synthetic" would equal the
#'     original byte-for-byte;
#'   \item the table was proposed for one mode but is being validated
#'     for another (actions are taken as-is; defaults are not
#'     re-resolved).
#' }
#'
#' @param roles A roles table from [propose_roles()] (possibly edited),
#'   or a v1 roles table (deprecated, upgraded with a warning).
#' @param df Optional data frame. If supplied, `roles` is checked for
#'   one-to-one column-name correspondence with `df`.
#' @param mode Optional mode (`"local"` or `"collaborate"`) used to
#'   resolve `NA` actions and to upgrade v1 tables. Defaults to
#'   `attr(roles, "mode")`, falling back to `"local"`.
#'
#' @return The validated (and possibly upgraded / resolved) roles
#'   table, invisibly.
#'
#' @examples
#' r <- propose_roles(iris)
#' r <- set_role(r, "Sepal.Length", role = "outcome")
#' roles_validate(r, iris)
#'
#' @seealso [propose_roles()], [set_role()].
#'
#' @export
roles_validate <- function(roles, df = NULL, mode = NULL) {
  if (!is.data.frame(roles)) {
    cli::cli_abort(
      "`roles` must be a data frame; got {.cls {class(roles)[1]}}."
    )
  }
  if (is.null(mode)) {
    mode <- attr(roles, "mode") %||% "local"
  }
  if (!(mode %in% c("local", "collaborate"))) {
    cli::cli_abort("`mode` must be {.val local} or {.val collaborate}.")
  }

  required <- c("col", "role")
  missing <- setdiff(required, names(roles))
  if (length(missing)) {
    cli::cli_abort(
      "`roles` is missing required column{?s}: {.field {missing}}."
    )
  }

  if (anyNA(roles$role)) {
    cli::cli_abort(
      paste0(
        "`roles$role` is NA for: ",
        "{.field {roles$col[is.na(roles$role)]}}."
      )
    )
  }

  # v1 tables (masque <= 0.5.0): no action column, keep/ignore vocabulary.
  if (!("action" %in% names(roles))) {
    if (!("kind" %in% names(roles))) {
      cli::cli_abort(
        "`roles` is missing required columns: {.field {c('action', 'kind')}}."
      )
    }
    v1_vocab <- c(
      "design", "keep", "treatment", "outcome", "covariate", "ignore"
    )
    role_vocab <- .roles_vocab()
    bad_v1 <- setdiff(unique(roles$role), v1_vocab)
    if (length(bad_v1)) {
      cli::cli_abort(c(
        "Unknown role{?s} in `roles$role`: {.val {bad_v1}}.",
        i = "Valid roles: {.val {role_vocab}}."
      ))
    }
    cli::cli_warn(c(
      paste0(
        "`roles` has no {.field action} column (masque <= 0.5.0 ",
        "format); upgrading to the two-axis schema for mode ",
        "{.val {mode}}."
      ),
      i = "Re-run {.fun propose_roles} to silence this warning."
    ), class = "masque_roles_upgraded")
    roles <- .roles_upgrade(roles, mode)
  }

  if (!("kind" %in% names(roles))) {
    cli::cli_abort("`roles` is missing required column {.field kind}.")
  }

  role_vocab <- .roles_vocab()
  action_vocab <- .actions_vocab()

  bad_role <- setdiff(unique(roles$role), role_vocab)
  if (length(bad_role)) {
    hint <- if (any(bad_role %in% c("keep", "ignore"))) {
      paste0(
        "{.val keep} and {.val ignore} are masque <= 0.5.0 roles: use ",
        "{.code action = \"keep\"} / {.code action = \"drop\"} instead."
      )
    } else {
      "Valid roles: {.val {role_vocab}}."
    }
    cli::cli_abort(c(
      "Unknown role{?s} in `roles$role`: {.val {bad_role}}.",
      i = hint
    ))
  }

  bad_action <- setdiff(
    unique(roles$action[!is.na(roles$action)]), action_vocab
  )
  if (length(bad_action)) {
    cli::cli_abort(c(
      "Unknown action{?s} in `roles$action`: {.val {bad_action}}.",
      i = "Valid actions: {.val {action_vocab}}."
    ))
  }

  roles <- .resolve_na_actions(roles, mode)
  roles <- .reresolve_for_mode(roles, mode)

  if (anyDuplicated(roles$col)) {
    dups <- roles$col[duplicated(roles$col)]
    cli::cli_abort("Duplicate column name{?s} in `roles$col`: {.field {dups}}.")
  }

  if (!is.null(df)) {
    if (!is.data.frame(df)) {
      cli::cli_abort("`df` must be a data frame; got {.cls {class(df)[1]}}.")
    }
    missing_in_roles <- setdiff(names(df), roles$col)
    extra_in_roles <- setdiff(roles$col, names(df))
    if (length(missing_in_roles)) {
      cli::cli_abort(
        "`df` column{?s} not in `roles`: {.field {missing_in_roles}}."
      )
    }
    if (length(extra_in_roles)) {
      cli::cli_abort(
        "`roles` column{?s} not in `df`: {.field {extra_in_roles}}."
      )
    }
  }

  # (role, action, kind) compatibility - collect every problem, then
  # fail once with the full list.
  problems <- character(0L)
  for (i in seq_len(nrow(roles))) {
    p <- .action_problem(roles$role[i], roles$action[i], roles$kind[i])
    if (!is.na(p)) {
      problems <- c(
        problems,
        sprintf("%s (%s + %s): %s",
          roles$col[i], roles$role[i], roles$action[i], p
        )
      )
    }
  }
  if (length(problems)) {
    names(problems) <- rep("x", length(problems))
    cli::cli_abort(c(
      paste0(
        "{cli::qty(length(problems))}Incompatible role, action and kind ",
        "combination{?s}:"
      ),
      problems
    ))
  }

  if (nrow(roles) > 0L && all(roles$action == "keep")) {
    cli::cli_warn(c(
      "Every action is {.val keep}: nothing will be masked.",
      i = "The synthetic output will equal the original byte-for-byte."
    ), class = "masque_all_keep")
  }

  invisible(roles)
}

# A table proposed for the other mode: columns still on their proposed default
# take the new mode's default, edited ones keep theirs; hand-built ones warn.
.reresolve_for_mode <- function(roles, mode) {
  proposed_mode <- attr(roles, "mode")
  if (is.null(proposed_mode) || identical(proposed_mode, mode)) {
    return(roles)
  }

  if (identical(proposed_mode, "collaborate") && identical(mode, "local")) {
    cli::cli_warn(c(
      paste0(
        "A roles table prepared for {.val collaborate} is being used in ",
        "{.val local} mode."
      ),
      "i" = paste0(
        "Collaborate defaults may be downgraded to values that expose real ",
        "labels. Confirm this mode change before sharing output."
      )
    ), class = "masque_mode_downgrade")
  }

  pa <- attr(roles, "proposed_actions")
  if (is.null(pa)) {
    cli::cli_warn(c(
      paste0(
        "`roles` was prepared for mode {.val {proposed_mode}} but is ",
        "being used with mode {.val {mode}}; actions are taken as-is."
      ),
      i = paste0(
        "Re-run {.code propose_roles(df, mode = \"{mode}\")} if you ",
        "want the {.val {mode}} defaults."
      )
    ), class = "masque_roles_mode_mismatch")
    return(roles)
  }

  changed <- character(0L)
  for (i in seq_len(nrow(roles))) {
    col_i <- roles$col[i]
    if (!(col_i %in% names(pa))) next
    if (!identical(unname(pa[[col_i]]), roles$action[i])) next
    kind_i <- if ("kind" %in% names(roles)) roles$kind[i] else "other"
    new_a <- .default_action(roles$role[i], kind_i, mode)
    if (!identical(new_a, roles$action[i])) {
      changed <- c(
        changed,
        sprintf("%s: %s -> %s", col_i, roles$action[i], new_a)
      )
      roles$action[i] <- new_a
    }
    pa[[col_i]] <- new_a
  }
  attr(roles, "proposed_actions") <- pa
  attr(roles, "mode") <- mode

  if (length(changed)) {
    names(changed) <- rep("*", length(changed))
    cli::cli_inform(c(
      paste0(
        "Re-resolved default actions for mode {.val {mode}} ",
        "(explicit edits always win):"
      ),
      changed
    ))
  }
  roles
}

Try the masque package in your browser

Any scripts or data that you put into this service are public.

masque documentation built on Nov. 19, 2026, 1:06 a.m.