R/roles_actions.R

Defines functions .resolve_na_actions .reorder_roles_cols .roles_upgrade .action_problem .default_action .conditioning_cols .strip_roles_provenance .kinds_vocab .date_kinds .numeric_kinds .categorical_kinds .actions_vocab .roles_vocab set_role

Documented in set_role

#' Set the role and action of one or more columns in a roles table
#'
#' Ergonomic editor for the two-axis roles table returned by
#' [propose_roles()]. Setting a `role` without an explicit `action`
#' re-resolves the action to the default for the new role, the column's
#' kind, and the mode the table was proposed for -- so a re-roled column
#' never silently carries a stale action from its previous role.
#'
#' Direct edits (`roles$role[roles$col == "x"] <- "outcome"`) also work,
#' but leave `roles$action` unchanged.
#'
#' @param roles A roles table from [propose_roles()] (possibly edited).
#' @param cols Character vector of column names to edit. Every entry
#'   must be present in `roles$col`.
#' @param role Optional single role to assign to all of `cols`. One of
#'   `"design"`, `"treatment"`, `"outcome"`, `"covariate"`, `"date"`,
#'   `"id"`, `"text"`, `"other"`.
#' @param action Optional single action to assign to all of `cols`. One
#'   of `"keep"`, `"scramble"`, `"alias"`, `"drop"`. When `NULL` (the
#'   default) and `role` was supplied, the action is re-resolved to the
#'   default for the new role.
#'
#' @return The edited roles table.
#'
#' @examples
#' r <- propose_roles(iris)
#' r <- set_role(r, "Sepal.Length", role = "outcome")
#' r <- set_role(r, "Species", action = "keep")
#' r[, c("col", "role", "action")]
#'
#' @seealso [propose_roles()], [roles_validate()].
#' @export
set_role <- function(roles, cols, role = NULL, action = NULL) {
  if (!is.data.frame(roles) || !all(c("col", "role") %in% names(roles))) {
    cli::cli_abort(
      "`roles` must be a roles table from {.fun propose_roles}."
    )
  }
  if (!is.character(cols) || length(cols) == 0L) {
    cli::cli_abort("`cols` must be a non-empty character vector.")
  }
  unknown <- setdiff(cols, roles$col)
  if (length(unknown)) {
    cli::cli_abort("Column{?s} not in `roles`: {.field {unknown}}.")
  }
  if (is.null(role) && is.null(action)) {
    cli::cli_abort("Supply at least one of `role` or `action`.")
  }
  role_vocab <- .roles_vocab()
  action_vocab <- .actions_vocab()
  if (!is.null(role)) {
    if (!is.character(role) || length(role) != 1L ||
      !(role %in% role_vocab)) {
      cli::cli_abort(c(
        "`role` must be one of {.val {role_vocab}}.",
        i = "Got {.val {role}}."
      ))
    }
  }
  if (!is.null(action)) {
    if (!is.character(action) || length(action) != 1L ||
      !(action %in% action_vocab)) {
      cli::cli_abort(c(
        "`action` must be one of {.val {action_vocab}}.",
        i = "Got {.val {action}}."
      ))
    }
  }

  mode <- attr(roles, "mode") %||% "local"
  pa <- attr(roles, "proposed_actions")
  idx <- match(cols, roles$col)
  if (!is.null(role)) {
    roles$role[idx] <- role
  }
  if (!is.null(action)) {
    if (!("action" %in% names(roles))) roles$action <- NA_character_
    roles$action[idx] <- action
    # An explicit action pins the column: it no longer follows the
    # mode's defaults if the table is later used with the other mode.
    if (!is.null(pa)) {
      attr(roles, "proposed_actions") <- pa[setdiff(names(pa), cols)]
    }
  } else if (!is.null(role) && "action" %in% names(roles)) {
    kind <- if ("kind" %in% names(roles)) roles$kind[idx] else
      rep("other", length(idx))
    new_actions <- vapply(
      kind, function(k) .default_action(role, k, mode), character(1L)
    )
    roles$action[idx] <- new_actions
    # A re-roled column keeps tracking its (new) default.
    if (!is.null(pa)) {
      pa[cols] <- new_actions
      attr(roles, "proposed_actions") <- pa
    }
  }
  .as_owned_dt(roles)
}

.roles_vocab <- function() {
  c(
    "design", "treatment", "outcome", "covariate",
    "date", "id", "text", "other"
  )
}

.actions_vocab <- function() {
  c("keep", "scramble", "alias", "drop")
}

.categorical_kinds <- function() c("factor", "character", "logical")
.numeric_kinds <- function() c("numeric", "integer")
.date_kinds <- function() c("date", "datetime")

# The full storage-kind vocabulary col_kind() can assign. role_options()
# renders the option grid against it.
.kinds_vocab <- function() {
  c(
    "numeric", "integer", "factor", "character",
    "logical", "date", "datetime", "other"
  )
}

# Strip the provenance attributes ("design", "proposed_actions", "mode")
# before a roles table is stored on a recipe; the design object can be large.
.strip_roles_provenance <- function(roles) {
  for (a in c("design", "proposed_actions", "mode")) {
    attr(roles, a) <- NULL
  }
  roles
}

# Columns that define the conditional clone's strata: treatments and retained
# design columns. Dropped columns are not in the synthetic and are left out.
.conditioning_cols <- function(roles) {
  keep <- roles$role %in% c("treatment", "design") &
    roles$action != "drop"
  roles$col[keep]
}

# Per-mode default action for a (role, kind) pair, used by propose_roles(),
# set_role(), the v1 upgrade and NA-action resolution.
.default_action <- function(role, kind, mode) {
  collab <- identical(mode, "collaborate")
  switch(role,
    design = "keep",
    treatment = {
      if (collab && kind %in% c(.categorical_kinds(), .numeric_kinds())) {
        "alias"
      } else {
        "keep"
      }
    },
    outcome = {
      if (kind %in% .numeric_kinds()) "scramble" else "keep"
    },
    covariate = {
      if (kind %in% .numeric_kinds()) {
        "scramble"
      } else if (collab && kind %in% .categorical_kinds()) {
        "alias"
      } else {
        "scramble"
      }
    },
    date = "scramble",
    id = if (collab) "drop" else "keep",
    text = if (collab) "drop" else "keep",
    other = "keep",
    cli::cli_abort("Unknown role {.val {role}} (internal).")
  )
}

# Check one (role, action, kind) triple: NA_character_ when workable, else a
# short reason. `keep` and `drop` always work.
.action_problem <- function(role, action, kind) {
  if (action %in% c("keep", "drop")) {
    return(NA_character_)
  }

  # Columns of an unsupported class can only be kept or dropped, whatever
  # role they carry - masque has no synthesiser for them.
  if (kind == "other") {
    return(paste0(
      "columns of an unsupported class can only be kept or dropped; ",
      "masque does not know how to synthesise them"
    ))
  }

  if (role == "design") {
    if (action == "scramble") {
      return(paste0(
        "design columns are structure, not content - they cannot be ",
        "scrambled; use keep, alias (labels hidden, structure intact), ",
        "or drop"
      ))
    }
    if (!(kind %in% .categorical_kinds())) {
      return(paste0(
        "design label aliasing requires a factor / character / logical ",
        "column; numeric design columns can only be kept or dropped. To ",
        "hide the labels, convert the column to a factor in the data, re-run ",
        "propose_roles() and set action \"alias\", or drop it"
      ))
    }
  }

  if (role == "treatment" &&
    !(kind %in% c(.categorical_kinds(), .numeric_kinds()))) {
    return(paste0(
      "treatment scramble / alias requires a factor / character / ",
      "logical or numeric column"
    ))
  }

  if (role == "outcome") {
    if (action == "alias") {
      return("outcomes carry no label vocabulary to alias; use scramble")
    }
    if (!(kind %in% .numeric_kinds())) {
      return(paste0(
        "only numeric / integer outcomes can be scrambled; re-role a ",
        "categorical outcome as treatment or covariate"
      ))
    }
  }

  if (role == "covariate" && action == "alias" &&
    !(kind %in% .categorical_kinds())) {
    return(paste0(
      "covariate aliasing requires a factor / character / logical ",
      "column; numeric covariates use scramble"
    ))
  }

  if (role == "date") {
    if (action == "alias") {
      return(paste0(
        "date/time columns carry no label vocabulary to alias; use ",
        "scramble (row permutation), keep, or drop"
      ))
    }
    if (!(kind %in% .date_kinds())) {
      return(paste0(
        "role \"date\" with scramble requires a Date / POSIX column; ",
        "parse the column to a date class first, or use role ",
        "\"covariate\""
      ))
    }
  }

  if (role == "id") {
    if (action == "scramble") {
      return(paste0(
        "ids cannot be scrambled - permuting identifiers silently ",
        "breaks row linkage; use alias, keep, or drop"
      ))
    }
    if (!(kind %in% c("factor", "character", "integer", "numeric"))) {
      return("id aliasing requires a character, factor, or integer column")
    }
  }

  if (role == "text" && action == "alias" &&
    !(kind %in% c("factor", "character"))) {
    return("text aliasing requires a character or factor column")
  }

  if (role == "other") {
    return(paste0(
      "columns of unsupported classes can only be kept or dropped; ",
      "masque does not know how to synthesise them"
    ))
  }

  NA_character_
}

# Upgrade a roles table from masque 0.5.0 or earlier (no `action` column) to
# role + action, keeping the old mode behaviour of keep, ignore and treatment.
.roles_upgrade <- function(roles, mode) {
  kind <- if ("kind" %in% names(roles)) {
    roles$kind
  } else {
    rep("other", nrow(roles))
  }
  role2 <- character(nrow(roles))
  action2 <- character(nrow(roles))
  pinned <- logical(nrow(roles))

  for (i in seq_len(nrow(roles))) {
    r <- roles$role[i]
    k <- kind[i]
    pinned[i] <- r %in% c("keep", "ignore")
    if (r %in% c("design", "treatment", "outcome")) {
      role2[i] <- r
      action2[i] <- .default_action(r, k, mode)
    } else if (r == "covariate") {
      role2[i] <- if (k %in% .date_kinds()) "date" else "covariate"
      action2[i] <- .default_action(role2[i], k, mode)
    } else if (r == "keep") {
      role2[i] <- if (k %in% .date_kinds()) {
        "date"
      } else if (k == "other") {
        "other"
      } else {
        "covariate"
      }
      action2[i] <- "keep"
    } else if (r == "ignore") {
      role2[i] <- if (matches_pattern(roles$col[i], ID_PATTERN)) {
        "id"
      } else if (k %in% c("character", "factor")) {
        "text"
      } else {
        "other"
      }
      action2[i] <- if (identical(mode, "collaborate")) "drop" else "keep"
    } else {
      role2[i] <- r
      action2[i] <- NA_character_
    }
  }

  if ("mask_levels" %in% names(roles)) {
    permuted <- !is.na(roles$mask_levels) & roles$mask_levels == "permute" &
      role2 == "treatment" & action2 == "keep"
    action2[permuted] <- "scramble"
    pinned[permuted] <- TRUE
    roles$mask_levels <- NULL
  }

  roles$role <- role2
  roles$action <- action2
  roles <- .cols(roles, .reorder_roles_cols(names(roles)))
  attr(roles, "mode") <- mode
  attr(roles, "proposed_actions") <- stats::setNames(
    action2[!pinned], roles$col[!pinned]
  )
  roles
}

# Canonical column order: col, role, action first, the rest preserved.
.reorder_roles_cols <- function(nms) {
  lead <- intersect(c("col", "role", "action", "kind"), nms)
  c(lead, setdiff(nms, lead))
}

# Resolve NA actions to the (role, kind, mode) default. Users signal
# "use the default for my edited role" by setting action to NA.
.resolve_na_actions <- function(roles, mode) {
  nas <- which(is.na(roles$action))
  for (i in nas) {
    kind <- if ("kind" %in% names(roles)) roles$kind[i] else "other"
    roles$action[i] <- .default_action(roles$role[i], kind, mode)
  }
  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.