Getting started with masque

The one-call path

f <- system.file("extdata", "john_alpha.csv", package = "masque")
df <- read.csv(f, stringsAsFactors = TRUE)
knitr::kable(
  head(df),
  caption = "The first six plots of the alpha-design trial."
)

m <- masque(df, mode = "collaborate", seed = 1L, ask = FALSE)
#> ℹ Using the proposed masking plan (pass `roles` or set `ask = TRUE` to review).
#> ✔ Masked 7 columns in "collaborate" mode - audit: 0 HIGH, 0 medium, 7 low.
#> ℹ Recipe is private - keep it. Review `audit_mask(m)` before any release decision; masque informs that decision, it does not make it.

ask = FALSE skips the interactive review, which is what a vignette needs; in an interactive console, masque(df) shows the proposed plan and a prompt to proceed, edit, or stop. The message above is the summary masque() prints for every guided run: how many columns were masked, in which mode, and the leakage-audit tally.

The result carries the synthetic data and the private recipe:

synth <- synthetic(m)
knitr::kable(
  head(synth),
  caption = paste0(
    "The first six plots of the synthetic clone: `gen` is aliased, ",
    "`yield` is re-simulated."
  )
)

The masking plan: roles and actions

Under the one-call path, masque() built the roles table without asking. Building and reviewing it directly gives full control:

roles <- propose_roles(df, mode = "collaborate")
knitr::kable(
  roles[, c("col", "role", "action", "kind")],
  caption = paste0(
    "The proposed masking plan for the alpha-design trial ",
    "(collaborate mode)."
  )
)

propose_roles() fills in a sensible action for each column given the mode, so the table reviewed here is the plan that will run. yield was proposed as a covariate. Naming it the trial’s outcome does not change how it is masked. It records intent, and the conditional clone (see Confidentiality and the threat model) reads it to find the response:

roles <- set_role(roles, "yield", role = "outcome")
knitr::kable(
  roles[, c("col", "role", "action")],
  caption = "The plan after naming `yield` as the trial outcome."
)

Re-assigning a role re-resolves the default action; passing an explicit action pins the column instead. There is no requirement to name an outcome: with none marked, every scrambled numeric is re-simulated jointly.

Editing the plan as code

The plan is a data.table, so you can edit it in code. The spreadsheet the guided prompt opens when the custodian chooses e edits the same table. set_role() is vectorised over columns:

r2 <- set_role(roles, c("row", "col"), action = "drop")

Direct edits work too. A direct role edit leaves action untouched, so setting the action back to NA tells mask() to re-resolve the default for the new role:

r2[col == "rep", `:=`(role = "covariate", action = NA_character_)]
knitr::kable(
  r2[, c("col", "role", "action")],
  caption = paste0(
    "A hand-edited plan: `row`/`col` dropped, `rep` re-roled to a ",
    "covariate."
  )
)

The kind column comes from the column’s class and cannot be edited. If it is wrong, convert the column in the data and run propose_roles() again.

role_options() lists the pairs the package accepts, here for a factor column:

knitr::kable(
  role_options(kind = "factor"),
  caption = paste0(
    "Every (role, action) pair the validator accepts for a factor ",
    "column."
  )
)

Finally, pii_suspected. propose_roles() sets it from the column name (email, phone, owner, …), and the leakage audit treats a flagged column that survives into the synthetic as a HIGH finding. The scan reads names, not content, so when a harmlessly named column holds sensitive values, flagging it by hand is the correct fix:

roles[col == "comments", pii_suspected := TRUE]

Passing the edited table back to mask() (or to masque(df, roles = roles)) runs the plan:

m <- mask(df, roles, mode = "collaborate", seed = 1L)
synth <- synthetic(m)
byte_identical_plot <- identical(synth$plot, df$plot)
gen_levels_changed <- !setequal(levels(synth$gen), levels(df$gen))
byte_identical_plot
#> [1] TRUE
gen_levels_changed
#> [1] TRUE
head(levels(synth$gen))
#> [1] "trt_001" "trt_002" "trt_003" "trt_004" "trt_005" "trt_006"

A plan the package refuses

plot is a design column. Scrambling it would break the trial’s layout, and mask() refuses:

bad_roles <- set_role(roles, "plot", role = "design", action = "scramble")
mask(df, bad_roles, mode = "collaborate", seed = 1L)
#> Error in `roles_validate()`:
#> ! Incompatible role, action and kind combination:
#> ✖ plot (design + scramble): design columns are structure, not content - they cannot be scrambled;
#>   use keep, alias (labels hidden, structure intact), or drop

The call stops before any masking, names the column and the combination at fault, and lists the three actions that do work for a design column (keep, alias, drop). The same check runs whether the plan came from propose_roles(), a hand edit or the guided spreadsheet.

More than one table

A confidential dataset often arrives as several related files or a multi-sheet workbook. masque() handles those too. Point it at a folder, an .xlsx file, or a named list of tables and it masks every table at once, aliasing any shared key (a site code, a genotype name) identically across tables so a join of the synthetic tables still resolves.

set_dir <- system.file("extdata", "met_set", package = "masque")
ms <- masque(set_dir, mode = "collaborate", seed = 1L, ask = FALSE)
#> Warning: Numeric environment column year remains "keep" in collaborate mode.
#> ℹ This preserves environment structure but may disclose year or other numeric labels; review before
#>   release.
#> ℹ Using the proposed masking plan for agronomy (pass `roles` or set `ask = TRUE` to review).
#> ℹ Using the proposed masking plan for quality (pass `roles` or set `ask = TRUE` to review).
#> 
#> ── Cross-table links (2) ──
#> 
#> • "env" shared across "agronomy, quality" - aliased consistently
#> • "gen" shared across "agronomy, quality" - aliased consistently
#> ✔ Masked 2 tables in "collaborate" mode - audit: 0 HIGH, 0 medium, 12 low.
#> ℹ Recipe is private - keep it. Review `audit_mask(m)` before any release decision; masque informs that decision, it does not make it.
ms
#> 
#> ── masque_set ──────────────────────────────────────────────────────────────────────────────────────
#> • Mode: collaborate
#> • Tables: 2
#> • agronomy: 464 rows x 7 columns
#> • quality: 464 rows x 5 columns
#> 
#> ── Cross-table links (2) ──
#> 
#> • "env" shared across "agronomy, quality"
#> • "gen" shared across "agronomy, quality"
#> Use `synthetic(m)` for the tables; `recipe(m)` for the bundle.
#> 
#> ✖ The recipe bundle is PRIVATE - never share it with the synthetic set.

The genotype column gen appears in both tables and is masked to the same codes in each, so the field and laboratory tables still join. See Confidentiality and the threat model for the set-level controls.

Multi-environment structure

For a multi-environment trial, detect_design() answers three questions separately:

1. Which rows belong to each environment?
2. Do the treatments connect the environments, so that they can be compared?
3. What randomisation structure can be recovered within each environment?

A block or field layout seen in the data suggests the original randomisation but does not confirm it. A small toy with two environments and three genotypes:

met <- expand.grid(
  env = factor(c("E1", "E2")),
  rep = factor(seq_len(2L)),
  gen = factor(c("G1", "G2", "G3"))
)
met$yield <- seq_len(nrow(met)) + rep(c(0, 2), each = 6L)

ds <- detect_design(met)
ds@scope_label
#> [1] "multi_environment"
ds@env_cols
#> [1] "env"
ds@connectivity$status
#> [1] "connected"
ds@within_design_label
#> [1] "RCBD"

Automatic detection is conservative. A column named env or environment, or a common site-year pattern, is taken as the environment only when no other column explains the structure as well. A site column on its own is taken only when treatments are replicated across sites, so a nested block is not mistaken for an environment. When you know the environment columns, name them:

ds_explicit <- detect_design(met, env = "env")

Figure: the multi-environment coverage plot

plot() on a design summary, or plot_design_summary(), draws a compact environment overview in base graphics. With engine = "ggplot2" it returns a ggplot2 object you can save with ggplot2::ggsave(); printed, it is the figure below. It shows whether coverage is even across environments, which the connectivity flag alone does not.

plot(ds_explicit, df = met, engine = "ggplot2")

Genotypes observed per environment (E1, E2) for the toy multi-environment trial; the subtitle carries connectivity status, component count, and the recovered within-environment design.

Both bars are at three treatments, since every genotype in this toy trial appears in both environments. A shorter bar, or a subtitle reporting more than one component, marks environments that cannot go into one connected analysis until you have checked whether the missing coverage is real or an artefact of how the table was put together.

High-confidence environment columns feed the masking plan directly:

• Local mode keeps environment values byte-identical.
• Collaborate mode aliases categorical environment labels in place, so each row stays in its environment and missing values stay where they were. The recipe turns the aliases back into the real labels.

A numeric environment, such as year, stays at keep and raises a disclosure warning because its values are still visible. The toy’s env column is categorical:

met_roles <- propose_roles(met, mode = "collaborate")
knitr::kable(
  met_roles[met_roles$col == "env", c("col", "role", "action")],
  caption = "How the masking plan treats the `env` column."
)

This safeguard protects the allocation a pipeline reads. It does not imply that the synthesised outcomes preserve genotype-by-environment effects: sparse treatment-by-environment cells may fall back to pooled synthesis, and the clone must not be used as a substitute for the original trial in scientific inference.