Nothing
#' Collaborate-mode opaque aliasing of categorical levels
#'
#' Replaces the level vocabulary with opaque aliases of the form
#' `<prefix>001`, `<prefix>002`, ... (`trt_001`, `site_D001`), assigned to the levels by a
#' **random permutation** drawn from the RNG stream `mask()` has already
#' seeded. The alias vocabulary itself is fixed and sorted; which level
#' receives which alias is not.
#'
#' Used by `mask(mode = "collaborate")` on `treatment` and categorical
#' `covariate` columns.
#'
#' @section Why the assignment is randomised:
#' An alias map that follows the levels' sort order is invertible without
#' the recipe by anyone who can guess the vocabulary. Variety rosters, N-rate
#' ladders and site codes are routinely public, and under a sort-order map
#' the k-th alias is by construction the k-th member of the sorted
#' vocabulary, so a holder of the synthetic recovers the whole map by
#' sorting a candidate list. Drawing the assignment from a uniform random
#' permutation removes that: for a k-level column there are `factorial(k)`
#' equally likely maps, and the vocabulary alone no longer says which alias
#' is which.
#'
#' Two consequences follow, and both are the caller's to manage:
#'
#' * The permutation comes from the seeded stream, so `mask(seed = s)`
#' reproduces the same map. **Treat the seed as recipe-grade confidential
#' material**: published alongside the synthetic it re-opens the inversion
#' for anyone who can also reproduce the draw. `mask(seed = NULL)` gives a
#' fresh map on every call and is the safer setting where reproducibility
#' is not required.
#' * Randomising the assignment hides the ordering, not the level
#' frequencies, which are preserved by design. A vocabulary whose
#' frequencies are known and distinct is still matchable one level at a
#' time; `audit_mask()` reports the per-column level counts, so this
#' exposure can be checked. This is a re-identification
#' cost, not a differential-privacy guarantee.
#'
#' A numeric vector (a dose, an N rate) is aliased through its exact
#' character form, so the map restores every value.
#'
#' @param x A factor, character, logical, or numeric vector.
#' @param prefix Character scalar used as the alias prefix (e.g., `"trt"`
#' for treatment, `"<col>_L"` for covariate level).
#' @return A list with elements:
#' \itemize{
#' \item `x`: a vector of the same type and length, with aliased values.
#' For a factor, the levels are the alias vocabulary in its own sorted
#' order, so the level order carries no trace of the original one.
#' \item `map`: a named character vector `original -> alias`.
#' }
#' @keywords internal
#' @noRd
alias_levels <- function(x, prefix) {
if (!is.character(prefix) || length(prefix) != 1L || !nzchar(prefix)) {
cli::cli_abort("`prefix` must be a non-empty character scalar.")
}
if (is.factor(x)) {
lvls <- levels(x)
if (length(lvls) == 0L) {
return(list(x = x, map = stats::setNames(character(), character())))
}
alias_pool <- .alias_pool(prefix, length(lvls))
map <- stats::setNames(alias_pool[.alias_order(length(lvls))], lvls)
out <- factor(unname(map[as.character(x)]), levels = alias_pool)
return(list(x = out, map = map))
}
if (is.numeric(x)) {
x <- .level_key(x)
}
if (is.character(x) || is.logical(x)) {
x_chr <- as.character(x)
uvals <- sort(unique(stats::na.omit(x_chr)))
if (length(uvals) == 0L) {
return(list(x = x, map = stats::setNames(character(), character())))
}
alias_pool <- .alias_pool(prefix, length(uvals))
map <- stats::setNames(alias_pool[.alias_order(length(uvals))], uvals)
out <- unname(ifelse(is.na(x_chr), NA_character_, map[x_chr]))
return(list(x = out, map = map))
}
cli::cli_abort(
paste0(
"alias_levels() supports factor, character, logical, or numeric; ",
"got {.cls {class(x)[1]}}."
)
)
}
# The sorted alias vocabulary for `n` levels, zero-padded to at least three
# digits so the codes sort in numeric order.
.alias_pool <- function(prefix, n) {
width <- max(3L, nchar(as.character(n)))
pool <- sprintf(paste0("%s%0", width, "d"), prefix, seq_len(n))
if (anyDuplicated(pool)) {
cli::cli_abort("Aliasing produced duplicate labels (internal bug).")
}
pool
}
# Uniform random permutation of the alias index from mask()'s seeded stream.
# A one-level column takes no draw, so it does not shift later columns.
.alias_order <- function(n) {
if (n <= 1L) {
return(seq_len(n))
}
sample.int(n)
}
is_aliasable_level_vector <- function(x) {
is.factor(x) || is.character(x) || is.logical(x)
}
# Exact character key of numeric values: the first form that reads back.
.level_key <- function(x) {
if (!is.numeric(x)) {
return(as.character(x))
}
key <- as.character(x)
for (fmt in c("%.16g", "%.17g", "%a")) {
inexact <- !is.na(x) & suppressWarnings(as.numeric(key)) != x
if (!any(inexact)) break
key[inexact] <- sprintf(fmt, x[inexact])
}
key
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.