View source: R/propose_roles.R
| propose_roles | R Documentation |
Generates a heuristic two-axis classification for every column of
df: a role (what the column is) and an action (what mask()
will do to it). The user is expected to inspect this table and edit
it - directly or via set_role() - before passing it to mask().
propose_roles(df, mode = c("local", "collaborate"), detect = TRUE)
df |
A data frame. Must have at least one column. |
mode |
The masking mode the table is being prepared for:
|
detect |
Logical scalar (default |
A data.table with one row per column: col, role, action,
kind (storage kind: numeric, integer, factor, character,
logical, date, datetime, other), freq_or_range,
pii_suspected, and notes. The target mode is stored as
attr(roles, "mode").
role describes the column and determines the mechanics of any
synthesis:
designExperimental / structural columns (site, block,
rep, plot, year). Mechanics of alias: labels are substituted in
place, structure intact.
treatmentAssignment columns (variety, genotype, dose).
Labels are remapped in place - the assignment structure never
moves. scramble = seeded label permutation; alias = opaque
labels (trt_001).
outcomeNumeric response columns. scramble re-simulates
via the Gaussian copula, jointly with scrambled numeric
covariates. Multiple outcomes are supported.
covariateEverything measured alongside. Numeric:
copula re-simulation. Categorical: row permutation, plus opaque
label aliasing under alias.
dateDate / POSIX / difftime columns. scramble row-
permutes within the observed values; class and NA pattern are
preserved.
idIdentifier columns. Never scrambled (that would break
row linkage); alias substitutes opaque per-value labels in
place, preserving linkage.
textFree-text columns. scramble row-permutes; alias
tokenises each distinct string.
otherClasses masque cannot synthesise (list columns, exotic S4, ...). Keep or drop only.
action sets the masking depth per column:
keepByte-identical pass-through, both modes.
scrambleRe-simulate (numeric) or row-permute (categorical / date / text); original label vocabulary remains visible.
aliasScramble where applicable, plus opaque label substitution - the vocabulary itself is hidden.
dropColumn excluded from the synthetic, both modes.
The proposed action column is resolved for mode, so the table you
edit shows the actual masking plan. Re-assigning a column's role
with set_role() re-resolves its default action; a direct
roles$role[...] <- ... edit leaves action untouched (set it to
NA to have mask() re-resolve the default).
PII-pattern column names (contact, email, phone, gps,
latitude / longitude, postcode, ssn, password, owner,
farmer, operator, etc., case-insensitive substring) ->
pii_suspected = TRUE and action drop in both modes.
Re-role deliberately if the column must survive.
Date / POSIXct / POSIXlt / difftime columns -> role date,
action scramble (row permutation).
ID-pattern names (\\bid\\b, _id$, ^id_) -> role id; kept
in local mode, dropped in collaborate mode.
Design-pattern names (rep, block, row, col(umn)?,
range, plot(no)?, site, site_name, trial_site,
env(ironment)?, trial, year, season, colrep, tos; the
two-word names also spaced or dotted, as in Site Name and
Site.Name) -> role design, action keep.
Treatment-pattern names (treatment, variety, cultivar,
genotype, ^trt, ^dose) -> role treatment; kept in local
mode, aliased in collaborate mode.
Numeric columns with an outcome-pattern name (yield, yield_t_ha,
Yield..t.ha., grain_yield, response, outcome) -> role
outcome, action scramble.
Character columns with > 50% unique values on non-NA -> role
text; kept in local mode, dropped in collaborate mode.
Unsupported classes -> role other, action keep, with a note.
Everything else -> role covariate, action scramble. Re-role
other response variables as outcome.
No outcome is required: with no column roled outcome, the copula
simply re-simulates all scrambled numeric columns jointly.
Since masque 0.3.0, propose_roles() also calls detect_design() by
default (detect = TRUE) and applies the detected design's
recommended_roles on top of the name-based heuristic, re-resolving
the default action for any promoted column. The design summary is
stashed as attr(roles, "design"). Pass detect = FALSE for the
name-only heuristic.
For a column without a treatment-pattern name, a treatment hint from the
design rules is applied only when the column is crossed with a design
column: a design-pattern name, a column roled design, or a detected
environment. A column with one value per level of a design
column is a unit-level covariate and is never promoted. Hints that fail
are listed in attr(roles, "design")@recommended_roles with
auto_apply = FALSE and the reason.
Since masque 0.9.1, high-confidence environment columns detected by
detect_design() are promoted to role design. In local mode their values
remain byte-identical. In collaborate mode categorical environment labels
default to alias, which preserves row assignment and factor codes while
hiding the vocabulary. Numeric environment columns default to keep and
raise a masque_environment_disclosure warning for explicit review.
Weak or competing environment candidates never change roles automatically.
Inspect attr(roles, "design") and use set_role() when domain knowledge
should override an uncertain result. Preserving environment allocation does
not imply that synthesised outcomes preserve treatment-by-environment
effects.
An explicitly chosen action is pinned and is not overwritten by a later
design-role promotion.
set_role() to edit; roles_validate() for the fail-closed
validation applied at mask() time.
propose_roles(iris)
propose_roles(iris, mode = "collaborate")
met <- expand.grid(
env = factor(c("E1", "E2")),
rep = factor(seq_len(2L)),
gen = factor(c("G1", "G2", "G3"))
)
propose_roles(met, mode = "collaborate")[, c("col", "role", "action")]
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.