---
title: "Confidentiality and the threat model"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Confidentiality and the threat model}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- Render time: ~4 s under rmarkdown::render(); macOS arm64, R 4.5.2, one
     core. Dominated by the copula fits in the conditional-clone and
     non-monotone sections; no sampler runs. -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5,
  dpi = 150
)
old_options <- options(width = 100)
library(masque)
set.seed(1)
```

## Why

A custodian about to send a synthetic table to a collaborator needs to
know what it protects, what it does not, and what happens if a column's
sensitivity is set wrongly. This vignette covers all three, with examples
that trigger the package's safeguards.

`masque` is **not** a privacy-preserving or differential-privacy tool. It
is a structurally faithful development surrogate. Read this vignette
before sharing any `masque` output beyond your own machine.

## What

The recipe holds the real labels, the original column names and the seed.
With the synthetic it undoes every alias, so keep it with the original
data and never send it with the synthetic. The design assumes that only
the *synthetic* crosses the trust boundary:

| Actor holds | Wants to learn | What `masque` protects |
|---|---|---|
| Synthetic only | Original raw values | Aliased treatment and categorical vocabularies, jittered numerics, dropped ids and free text, and optionally the column names |
| Synthetic + recipe | Original raw values | Nothing: together they undo every alias |
| Recipe only | Original raw values | The values, which the recipe does not hold. It does hold the real labels, the original column names and the seed |
| Synthetic + external side information | Identity of treatments / sites | The label vocabulary and the order it was in. A preserved design footprint or a `keep` column is recognisable, level frequencies are unchanged, and side information wins |
| Conditional clone (`conditional = TRUE`) | Outcome mean of a treatment or design level | Nothing: the clone reproduces the outcome mean of each treatment, block and environment level. A level with only a few plots reveals close to its real mean; a level with a single plot is pooled with the other single-plot levels first |

`masque` keeps enough structure for a pipeline to run unchanged. Two modes
set the balance between privacy and fidelity, every translation is written
to a private recipe that round-trips, and the output is audited before it
is shared.

It gives no differential-privacy guarantee and does not make output safe
for public release. It does not hide rare strata, small designs, thin
site-by-year cells or contact names, and it does not change pipeline code.

Every column carries a `role` (what it is) and an
`action` (how deeply it is masked, from `role_options()`'s validated
grid: `keep`, `scramble`, `alias`, `drop`). `mask()`'s `mode` argument
chooses sensible defaults for both, so the common case is safe without
per-column work:

| Knob | `mode = "local"` | `mode = "collaborate"` |
|---|---|---|
| Treatment labels, numeric doses included | kept | aliased (`trt_001`) |
| Categorical covariate labels | kept | aliased (`<col>_L001`) |
| Date / time columns | row-permuted with class preserved | row-permuted with class preserved |
| Identifiers (`id`) | kept | dropped |
| Free text (`text`: a character column in which more than half the values are distinct) | kept | dropped |
| Numeric synthesis | Gaussian copula with empirical-quantile marginals (may emit observed values) | the same, plus within-resolution jitter, with whole numbers stochastically rounded. A value can fall up to half a measurement step outside the observed range |
| Columns constant within a design unit | one value per unit, drawn from the real unit values | one value per unit, jittered, or row by row when there are fewer than five units |
| NA mask | preserved cell-by-cell | preserved cell-by-cell |
| `audit_mask()` | on demand | automatic at `mask()` time |
| `print(recipe)` | redacted | redacted, with explicit `reveal_maps()` to inspect |

## Example

### Depth controls: hiding design structure

Design columns are byte-identical by default, which preserves the
experimental layout exactly. A publicly registered trial layout is a
fingerprint. To keep the structure but hide the site or block *labels*,
set a design column's action to `alias`:

```{r design-alias}
df <- data.frame(
  site = factor(rep(c("Roseworthy", "Minnipa", "Turretfield"), each = 6L)),
  rep = rep(seq_len(3L), 6L),
  yield = rnorm(18L)
)
plan <- propose_roles(df, detect = FALSE)
plan <- set_role(plan, "site", role = "design", action = "alias")
s <- synthetic(mask(df, plan, mode = "collaborate", seed = 1L))
site_names_gone <- !any(as.character(s$site) %in% as.character(df$site))
site_names_gone
knitr::kable(
  as.data.frame(table(s$site), stringsAsFactors = FALSE),
  col.names = c("aliased site", "plots"),
  caption = "The three-site structure survives even though the labels do not."
)
```

Aliasing a design column breaks byte-identity, so it is never a default.
Names can be hidden the same way: `mask(...,
alias_names = TRUE)` replaces every retained column name with an opaque
code that the recipe inverts on the round-trip, and a character vector
hides only the names given.

**What an alias does and does not hide.** The alias vocabulary is fixed
and sorted (`trt_001`, `trt_002`, ...), but which level receives which
alias is drawn from a random permutation, so for a six-level column there
are 720 equally likely maps. This matters because the vocabularies in
field research are routinely public: a variety roster, an N-rate ladder, a
site list. The same draw governs the join keys `mask_set()` shares across
tables. A scrambled factor keeps the original level order, so `levels()`
of a clone does not reveal the map.

Clones made with earlier versions can reveal it. In masque 0.13.0 and
earlier, a scrambled treatment listed its levels in the scrambled order.
In 0.12.0 and 0.13.0, a join key aliased by `mask_set()` listed its
aliases in the original level order. Make such a clone again with 0.14.0.

Two limits go with that, and they are the custodian's to manage:

* **The seed is confidential material.** The permutation comes from the
  seeded stream, so `mask(seed = 1L)` reproduces the same map, exactly as
  it reproduces the same synthetic values. Publishing the seed beside the
  synthetic re-opens the inversion for anyone who can also reproduce the
  draw. Keep the seed with the recipe, or pass `seed = NULL` where
  reproducibility is not required and take a fresh map each call.
* **Frequencies are not hidden.** Aliasing is a bijection on labels: the
  count of each level is unchanged by design, because the design footprint
  is what makes the clone useful. A vocabulary whose level counts are
  known and distinct is still matchable one level at a time.
  `audit_mask()` reports those counts so the exposure is visible rather
  than implicit.

An alias therefore raises the cost of re-identification. It cannot be
relied on against a determined attacker, and none of it is a
differential-privacy guarantee.

### Numeric treatments

A dose or a nitrogen rate is a numeric treatment. Its values are often the
most recognisable part of a trial, so collaborate mode aliases them by
default, as it does treatment labels. The clone carries `trt_001`,
`trt_002`, ... as text, and the recipe turns them back into the exact
numbers:

```{r numeric-treatment}
rates <- data.frame(
  block = factor(rep(seq_len(4L), each = 5L)),
  nitro = rep(c(0, 0.2, 0.4, 0.6, 0.8), 4L)
)
rates$yield <- round(80 + 40 * rates$nitro + rnorm(20L, sd = 5), 1)
plan_rates <- propose_roles(rates, mode = "collaborate")
m_rates <- mask(rates, plan_rates, mode = "collaborate", seed = 1L)
knitr::kable(
  head(synthetic(m_rates), 5L),
  digits = 1,
  caption = "The first block of the clone: each N rate is an opaque label."
)
identical(unmask(synthetic(m_rates), recipe(m_rates))$nitro, rates$nitro)
```

Every block still holds each rate once, so the design is intact. With
`action = "scramble"` the rates stay numbers and are permuted among
themselves instead. A numeric treatment left at `keep` in collaborate mode
audits HIGH.

### The conditional clone: preserving the treatment effect

The default numeric synthesis re-simulates every scrambled numeric column
from one Gaussian copula with empirical-quantile marginals, fitted on the
whole table. That preserves each column's marginal distribution and the
global covariance, which is enough to develop most pipelines. It does not
keep the relationship between treatment and outcome. The synthetic
outcomes are drawn from the pooled distribution and the treatment labels
are relabelled independently, so a causal model fitted on the clone sees
no association between an arm and its response. A pipeline whose whole
purpose is to estimate a treatment effect would silently give the wrong
answer on such a clone.

`mask()`'s `conditional = TRUE` argument fixes this. It fits and samples
the copula *within each treatment-by-design stratum* rather than pooling,
so a row's synthetic outcome inherits the location of the treatment that
row carries. The treatment effect a causal model estimates is kept, within
sampling tolerance.

The contrast is easiest to see on a two-arm trial with a known effect:

```{r conditional-fixture}
set.seed(42)
n <- 600L
arm <- factor(rep(c("ctrl", "treat"), each = n / 2L))
# A real +5-unit effect of the treated arm on yield.
yield <- 10 + 5 * (arm == "treat") + rnorm(n, sd = 2)
trial <- data.frame(genotype = arm, yield = yield)

plan <- propose_roles(trial, detect = FALSE)
plan <- set_role(plan, "genotype", role = "treatment", action = "scramble")
plan <- set_role(plan, "yield", role = "outcome")

true_effect <- coef(lm(yield ~ genotype, trial))[["genotypetreat"]]
true_effect
```

Cloning both ways from the same seed, then re-estimating the effect on
each clone:

```{r conditional-contrast}
marg <- mask(trial, plan, mode = "local", seed = 1L, conditional = FALSE)
cond <- mask(trial, plan, mode = "local", seed = 1L, conditional = TRUE)

effect_of <- function(m) {
  coef(lm(yield ~ genotype, synthetic(m)))[["genotypetreat"]]
}
effect_marg <- effect_of(marg)
effect_cond <- effect_of(cond)

knitr::kable(
  data.frame(
    clone = c("marginal (default)", "conditional"),
    estimated_effect = c(effect_marg, effect_cond),
    true_effect = true_effect
  ),
  digits = 3,
  caption = paste0(
    "The treated-arm effect, re-estimated on each clone against the ",
    "true effect fitted on the original trial."
  )
)
```

The marginal clone collapses the effect toward zero. The conditional clone
recovers it. Both clones still match the pooled marginal of the outcome:

```{r conditional-marginal-held}
knitr::kable(
  data.frame(
    source = c("original", "marginal clone", "conditional clone"),
    mean_yield = c(
      mean(trial$yield), mean(synthetic(marg)$yield),
      mean(synthetic(cond)$yield)
    ),
    sd_yield = c(
      sd(trial$yield), sd(synthetic(marg)$yield),
      sd(synthetic(cond)$yield)
    )
  ),
  digits = 3,
  caption = paste0(
    "Both clones preserve the pooled mean and SD of yield; only the ",
    "conditional clone preserves the arm-to-arm difference."
  )
)
```

### Figure: the effect on each clone

```{r fig-conditional, eval = requireNamespace("ggplot2", quietly = TRUE), fig.cap = "Estimated treatment effect (yield units) on the marginal versus conditional clone, against the true effect fitted on the original trial (dashed line). The marginal clone collapses the effect toward zero; the conditional clone recovers it."}
effect_df <- data.frame(
  clone = factor(
    c("marginal (default)", "conditional"),
    levels = c("marginal (default)", "conditional")
  ),
  estimated_effect = c(effect_marg, effect_cond)
)
ggplot2::ggplot(
  effect_df, ggplot2::aes(x = clone, y = estimated_effect, fill = clone)
) +
  ggplot2::geom_col(width = 0.6) +
  ggplot2::geom_hline(yintercept = true_effect, linetype = "dashed") +
  ggplot2::scale_fill_viridis_d(guide = "none") +
  ggplot2::labs(
    x = "clone", y = "estimated treatment effect (yield units)",
    title = "Marginal versus conditional cloning of a known treatment effect"
  ) +
  ggplot2::theme_minimal()
```

```{r fig-conditional-skip, eval = !requireNamespace("ggplot2", quietly = TRUE), echo = FALSE, results = "asis"}
cat("ggplot2 is not installed on this build, so the effect-comparison",
    "figure is skipped; the table above carries the same numbers.\n")
```

The conditioning columns (the treatment plus any retained design
columns) are recorded on the recipe, so the choice is auditable:

```{r conditional-recipe}
recipe(cond)@conditional
recipe(cond)@conditioning_cols
recipe(cond)@conditioning_used
recipe(cond)@fallback_frac
```

`conditioning_cols` is what the call asked for; `conditioning_used` is the
stratum the clone actually got, and `fallback_frac` is the share of rows
that did not get a stratum at all. They differ because a conditional clone
needs enough rows per stratum to fit a stratum-local copula, and the
finest stratum available is rarely the one that has them. On a
replicated factorial of six N rates by three varieties by four replicates,
treatment crossed with every retained design column is seventy-two cells
of one row. `mask()` therefore walks a **coarsening ladder**: it drops
design columns until the cells hold at least five rows. Treatment columns are never dropped. Rows still in cells that are too
small at the last rung are pooled into one fallback stratum.

The default ladder (`ladder = "hierarchy"`) drops plot coordinates first,
then blocking columns, then environment columns, so a site or a county
is never given up before the replicates inside it. It carries the main
effect of every dropped column into the clone as an additive shift. The
county, replicate and block means of the original therefore survive even
when the copula is fitted within the treatment alone; the threat table
above lists what that discloses. The recipe lists the shifted terms as
`conditioning_shifted`. `ladder = "levels"` reproduces clones made with
masque 0.11.1 to 0.12.0: it drops the column with the most levels first and
keeps nothing of it.

Any coarsening, and any residual pooling, raises a classed
`masque_conditional_degraded` warning naming the columns given up and the
pooled share, and both facts are written onto the recipe. A pipeline can
catch the class if it should stop when its clone is less conditional than
it asked for:

```r
withCallingHandlers(
  mask(trial, plan, seed = 1L, conditional = TRUE),
  masque_conditional_degraded = function(w) stop(conditionMessage(w))
)
```

Conditional cloning composes with both modes and with `mask_set()` (each
table is stratified by its own treatment and design columns). With no
treatment or design column to condition on at all, the path degrades to
the global copula and raises the same classed warning. It is worth
reaching for whenever the development pipeline estimates an effect, not
just a distribution.

### What the copula carries: monotone, not non-monotone, association

Numeric columns that are kept and re-simulated together share one Gaussian
copula, fitted on the normal scores of their ranks. A Gaussian copula
holds a single correlation per pair, so it reproduces a *monotone*
association (linear, or any order-preserving curve) but not a
dependence that a correlation cannot express. A non-monotone relationship,
such as a U-shaped dependence of an outcome on a covariate, reads as
near-zero rank correlation and is reproduced as near-independence.

```{r nonmonotone}
set.seed(7)
n <- 2000L
x_lin <- rnorm(n)
y_lin <- 2 * x_lin + rnorm(n, sd = 0.5)     # monotone (linear)
x_u <- runif(n, -3, 3)
y_u <- x_u^2 + rnorm(n, sd = 0.5)           # non-monotone (U-shaped)
d <- data.frame(x_lin, y_lin, x_u, y_u)

s <- synthetic(mask(d, propose_roles(d, detect = FALSE), seed = 1L))

# R-squared of a quadratic fit captures association of any curvature.
fit_r2 <- function(x, y) summary(lm(y ~ poly(x, 2)))$r.squared
knitr::kable(
  data.frame(
    pair = c("monotone (y = 2x)", "non-monotone (y = x^2)"),
    original = c(fit_r2(x_lin, y_lin), fit_r2(x_u, y_u)),
    clone = c(fit_r2(s$x_lin, s$y_lin), fit_r2(s$x_u, s$y_u))
  ),
  digits = 3,
  caption = paste0(
    "R-squared of a quadratic fit, original versus clone, for a ",
    "monotone and a non-monotone pair."
  )
)
```

The monotone pair keeps its association almost exactly. The non-monotone
pair loses it entirely, so on the clone the covariate carries no
information about the outcome. `conditional = TRUE` does not repair this:
it preserves the outcome's location within each treatment-by-design
stratum, not the curvature of the outcome's dependence on a continuous
covariate. A pipeline whose modelling step is non-linear (a smoothing
spline, a generalised additive model, a tree, an interaction term) sees
on the synthetic only the monotone part of any relationship in the
original. A good fit there is not evidence that the step behaves correctly
on the real data. Validate such a step by running it on the original
through the recipe.

### Columns constant within a trial: the grain

Some columns describe a whole unit rather than a row: the rainfall of a
trial, the soil type of a site, a sowing date. Re-simulated row by row,
such a column would vary inside the trial, which no real trial does.
`mask()` finds the design unit within which a column holds a single value
and synthesises the column once per unit, writing each unit's new value to
all its rows. This is the column's *grain*:

```{r grain}
set.seed(3)
trials <- data.frame(
  trial = factor(rep(sprintf("T%d", seq_len(8L)), each = 12L)),
  rep = factor(rep(rep(seq_len(3L), each = 4L), 8L)),
  gen = factor(rep(sprintf("G%d", seq_len(4L)), 24L))
)
trial_rain <- round(runif(8L, 250, 550))
trials$rainfall <- trial_rain[as.integer(trials$trial)]
trials$yield <- round(2 + trials$rainfall / 200 + rnorm(96L, sd = 0.4), 2)

plan_trials <- propose_roles(trials, mode = "collaborate")
by_unit <- mask(trials, plan_trials, mode = "collaborate", seed = 1L)
by_row <- mask(trials, plan_trials, mode = "collaborate", seed = 1L,
               grain = FALSE)
values_per_trial <- function(m) {
  s <- synthetic(m)
  as.vector(tapply(s$rainfall, s$trial, function(x) length(unique(x))))
}
knitr::kable(
  data.frame(
    clone = c("grain = TRUE (default)", "grain = FALSE"),
    distinct_rainfall_per_trial = c(
      paste(values_per_trial(by_unit), collapse = " "),
      paste(values_per_trial(by_row), collapse = " ")
    )
  ),
  caption = "Distinct rainfall values in each of the eight trials of the clone."
)
```

`propose_roles()` notes such a column ("Constant within trial; synthesised
per trial"), and the recipe records each grain. The clone keeps one value
per unit, the frequencies of a categorical column across units, and the
correlation among columns of the same grain. It does not keep the
correlation between a grained column and the row-level columns, so the
link between rainfall and yield above is lost, and grained columns are
not conditioned on treatment when `conditional = TRUE`.

In local mode the unit values are drawn from the real unit values. In
collaborate mode they are jittered, and a grain with fewer than five units
is synthesised row by row instead, with a `masque_grain_small_units`
warning, because resampling so few real values would disclose them. The
audit then notes that the clone does not keep that grain. `grain = FALSE`
gives the row-by-row clone of masque 0.15.0.

### Time-to-event outcomes

A clinical table often holds several event times on one row, such as time
to recurrence and time to death, each with a status. Re-simulated as
independent columns, the times would fall out of order. Declaring them to
`events` keeps them linked. The times are listed in the order the events
occur:

```{r events}
set.seed(5)
n_pat <- 300L
arm <- rep(c("A", "B"), length.out = n_pat)
t_rec <- rexp(n_pat, ifelse(arm == "A", 1 / 900, 1 / 1400))
t_death <- rexp(n_pat, 1 / 2500)
censor <- runif(n_pat, 30, 3000)
status_death <- as.integer(t_death <= censor)
time_death <- round(pmin(t_death, censor))
status_rec <- as.integer(t_rec < pmin(t_death, censor))
time_rec <- ifelse(status_rec == 1L, pmin(round(t_rec), time_death),
                   time_death)
patients <- data.frame(arm, time_rec, status_rec, time_death, status_death)

plan_pat <- propose_roles(patients, mode = "collaborate", detect = FALSE)
plan_pat <- set_role(plan_pat, "arm", role = "treatment")
for (cn in c("time_rec", "status_rec", "time_death", "status_death")) {
  plan_pat <- set_role(plan_pat, cn, role = "outcome", action = "scramble")
}
m_pat <- mask(
  patients, plan_pat, mode = "collaborate", seed = 1L,
  events = list(time = c("time_rec", "time_death"),
                status = c("status_rec", "status_death"))
)
s_pat <- synthetic(m_pat)
all(s_pat$time_rec <= s_pat$time_death)
pattern <- function(d) paste(d$status_rec, d$status_death, sep = "/")
knitr::kable(
  data.frame(
    pattern = names(table(pattern(patients))),
    original = as.vector(table(pattern(patients))),
    clone = as.vector(table(pattern(s_pat)))
  ),
  caption = "Rows in each recurrence/death status pattern."
)
```

Within each status pattern the gaps between events are re-simulated and
summed back into times, so the times stay in order, a patient without a
recurrence keeps both times equal, and the count of each pattern is exact.
No final time runs past the longest follow-up observed in its pattern. The
status patterns move across rows, within each arm when
`conditional = TRUE`, so no real patient keeps their own outcome. No
hazard model is fitted, and the clone keeps no relation between a
covariate and the events.

### The leakage audit, and a refused write

`audit_mask()` inspects the synthetic against the original and grades
the leakage of each column. In collaborate mode it runs automatically and
warns at `mask()` time. The fixture below is built to trip it: a
PII-suspected column the user retains against the default, and a
categorical covariate with a frequency-one level.

```{r leaky-fixture}
df <- data.frame(
  rep = rep(seq_len(3L), each = 20L),
  variety = factor(rep(paste0("V", seq_len(6L)), 10L)),
  contact_email = factor(rep(c("a@x", "b@y"), 30L)),
  rare_treatment = factor(c(
    "only_one",
    sample(c("alpha", "beta", "gamma"), 59L, replace = TRUE)
  )),
  yield = rnorm(60L, 5, 1),
  stringsAsFactors = FALSE
)

plan <- propose_roles(df, mode = "collaborate")
knitr::kable(
  plan[, c("col", "role", "action", "pii_suspected")],
  caption = paste0(
    "The proposed plan: `contact_email` is auto-flagged ",
    "`pii_suspected` and dropped."
  )
)
```

Suppose the custodian overrides the flag, keeps `contact_email`, and makes
the rare column a covariate:

```{r leaky-mask}
plan <- set_role(plan, "yield", role = "outcome")
plan <- set_role(plan, "contact_email", role = "covariate", action = "keep")
plan <- set_role(plan, "rare_treatment", role = "covariate")
m <- mask(df, plan, mode = "collaborate", seed = 1L)
knitr::kable(
  audit_mask(m)[, c("col", "leakage_class", "notes")],
  caption = paste0(
    "The mask-time audit: `contact_email` and `rare_treatment` both ",
    "flag HIGH."
  )
)
```

`contact_email` (real values kept across the trust boundary) and
`rare_treatment` (a frequency-one level) are flagged. `mask()` raised a
classed `masque_high_leakage` warning above and recorded the findings in
`recipe@warnings`; the guided `masque()` flow never silences it. While a
HIGH finding stands, the package will not write the synthetic to disk:

```{r leaky-write, error = TRUE}
out_dir <- tempfile()
masque(df, roles = plan, out = out_dir, mode = "collaborate", seed = 1L,
       quiet = TRUE)
dir.exists(out_dir)
```

Nothing is written: the refusal fires before the writer touches disk, the
two flagged columns are named in the message, and the remedy is spelled
out (re-role, alias, or drop the column, then mask again). A custodian who
has reviewed the findings and still wants to proceed can pass `allow_high
= TRUE`; the override is itself raised as a classed `masque_high_override`
warning and recorded in the recipe's warnings, so the exception stays
auditable rather than silent.

The audit also checks the table as a whole. Each column is graded on how
far its row-by-row match with the original exceeds what chance gives, and
`attr(audit, "joint")` holds table-level checks: rows whose every re-simulated
column equals the original, and rare combinations of retained values. A
HIGH table-level finding blocks the writers as a column finding does.

An outcome left at `keep` in collaborate mode hands over the real
responses, so it audits HIGH:

```{r kept-outcome}
trial_kept <- data.frame(
  block = factor(rep(seq_len(4L), each = 6L)),
  variety = factor(rep(sprintf("V%d", seq_len(6L)), 4L)),
  height = round(rnorm(24L, 90, 8)),
  yield = round(rnorm(24L, 5, 1), 2)
)
plan_kept <- propose_roles(trial_kept, mode = "collaborate")
plan_kept <- set_role(plan_kept, "yield", role = "outcome", action = "keep")
m_kept <- mask(trial_kept, plan_kept, mode = "collaborate", seed = 1L)
knitr::kable(
  audit_mask(m_kept, print = FALSE)[col == "yield", c("col", "leakage_class")],
  caption = "A kept outcome in a collaborate clone."
)
```

If the custodian has decided the real outcome may be shared, passing
`allow_kept_outcome = TRUE` grades the column medium and records the
choice on the recipe:

```{r kept-outcome-allowed}
m_allowed <- mask(trial_kept, plan_kept, mode = "collaborate", seed = 1L,
                  allow_kept_outcome = TRUE)
knitr::kable(
  audit_mask(m_allowed, print = FALSE)[
    col == "yield", c("col", "leakage_class")
  ],
  caption = "The same outcome, allowed by the custodian."
)
recipe(m_allowed)@allow_kept_outcome
```

The table-level checks still apply. When the kept outcome is the only
column that would otherwise be re-simulated, the clone matches the
original row for row, the whole-row check stays HIGH, and the writers stay
blocked.

### Small tables

Re-simulating a column of a few rows returns the original values in a new
order. Collaborate mode therefore refuses a table of fewer than five rows
when any column would be re-simulated:

```{r small-table, error = TRUE}
tiny <- trial_kept[1:4, c("block", "yield")]
mask(tiny, propose_roles(tiny, mode = "collaborate"), mode = "collaborate",
     seed = 1L)
```

Local mode warns instead. Kept, aliased and dropped columns are not
re-simulated, so a short lookup table of site codes masks in either mode.
Five rows is a floor, not a guarantee. A column of a few dozen rows still
carries values close to the real ones, and jitter within a measurement
step does little to hide them. The same applies to small strata of a
conditional clone, which is why its cells hold at least five rows.

Beyond that gate the release decision stays with the custodian. Whether
a synthetic table is appropriate for a given collaborator, environment, or
jurisdiction depends on context the package cannot see. `masque` informs
that decision. It does not make it.

### Multi-table sets

When several tables share a key, `mask_set()` aliases that key
*identically across all of them* so the synthetic tables still join. A
linked key is the join surface, aliased consistently rather than permuted
(permuting a key would break the join regardless of masking).

```{r set}
set_dir <- system.file("extdata", "met_set", package = "masque")
tabs <- read_set(set_dir)
tabs$agronomy[, year := factor(year)]
ms <- mask_set(tabs, mode = "collaborate", seed = 1L, quiet = TRUE)
ag <- synthetic(ms)$agronomy
qa <- synthetic(ms)$quality
join_survives <- setequal(unique(ag$gen), unique(qa$gen))
join_survives
head(unique(ag$gen), 3L)
```

`year` is converted to a factor first. As a number it would be kept
with its real values, with a warning, because a numeric environment column
cannot be aliased. A linked key gets aliases of the form `<col>_K001`,
such as `gen_K001`, from one map shared by every table.

The recipe bundle is private exactly as a single recipe is; `write_set()`
never writes it. `save_recipe()` and `read_recipe()` keep it as one
`.rds` file, `audit_mask(ms)` returns one audit per table, and
`reveal_maps(recipe(ms), table = "agronomy")` reveals the maps of one
table.

### Geographic coordinates

Latitude and longitude are treated as sensitive: `propose_roles()` flags a
column whose name looks like a coordinate (`gps`, `lat`/`latitude`,
`lon`/`longitude`) as `pii_suspected` and proposes `drop`. Dropping is the
safest choice when the synthetic does not need locations.

**A coordinate is masked unless told otherwise.** If a column whose name
says coordinate would be written through with `action = "keep"`, the call
stops. There are three ways to say what happens to it:

1. Declare the pair to `coords`, which coarsens it.
2. Give the column `drop` or `scramble`, which masks it.
3. Pass `allow_unmasked_coords = TRUE` after deciding the position is not
   sensitive. The recipe records this, so the decision is visible later.

A column that looks like a coordinate only by the shape of its
values raises a warning instead of stopping, because that detection is a
guess and a false positive should not block a legitimate mask.

When the synthetic does need plausible coordinates, to exercise a
spatial pipeline say, a plain scramble is the wrong tool: the copula
re-simulates each axis and smears a latitude/longitude pair into a
continuous cloud that can land in the sea. `masque` offers two
purpose-built alternatives.

`jitter_coordinates()` coarsens coordinates in place by a
geographic-masking jitter. The default donut scheme displaces every point
by a random distance drawn uniformly by area from an annulus, in a random
direction, and re-draws until the point falls on land, so a coastal site
is never pushed offshore. The longitude step is corrected by
`cos(latitude)` so the ground distance matches the requested kilometres at
any latitude, and the NA pattern and the latitude/longitude pairing are
preserved.

```{r geo-coords, eval = requireNamespace("maps", quietly = TRUE)}
sites <- data.frame(
  site = c("A", "B", "C"),
  lat  = c(-34.9, -35.2, -33.6),
  lon  = c(138.6, 142.0, 148.2)
)
knitr::kable(
  jitter_coordinates(sites, "lat", "lon", min_km = 5, max_km = 20, seed = 1L),
  digits = 4,
  caption = paste0(
    "Three sites, each displaced 5-20 km in a random direction and ",
    "re-drawn until on land."
  )
)
```

```{r geo-coords-skip, eval = !requireNamespace("maps", quietly = TRUE), echo = FALSE, results = "asis"}
cat("maps is not installed on this build, so the coordinate-jitter demo",
    "is skipped.\n")
```

**A coordinate belongs to a site, not to a row.** One displacement is
drawn per site and broadcast to every row of that site, so a table holding
many rows per physical place (plots within a trial, samples within a
paddock) comes back with one masked coordinate per place, exactly as the
source table has one true coordinate per place. By default a site is a set
of rows sharing an identical input coordinate, which needs no user action
and cannot alter genuinely point-level data. Where a site's recorded
coordinates differ slightly between rows, naming the site columns
consolidates the group to its centroid.

```{r geo-by, eval = requireNamespace("maps", quietly = TRUE)}
plots <- data.frame(
  trial = rep(c("T1", "T2"), each = 4L),
  lat   = rep(c(-34.9, -35.2), each = 4L),
  lon   = rep(c(138.6, 142.0), each = 4L)
)
masked <- jitter_coordinates(plots, "lat", "lon", by = "trial", seed = 1L)
one_coord_per_trial <- nrow(unique(masked[c("lat", "lon")]))
one_coord_per_trial
```

```{r geo-by-skip, eval = !requireNamespace("maps", quietly = TRUE), echo = FALSE, results = "asis"}
cat("maps is not installed on this build, so the site-grouping demo is",
    "skipped.\n")
```

Grouping is a confidentiality control, not only a fidelity one. Donut
displacement is isotropic, so the mean of many independent draws around
one true site converges on that site. Displacing a 360-row trial row by
row leaves its centroid a median 0.58 km from the truth, against the 5 km
floor the donut was asked for. One draw per site removes that estimator
and leaves the full displacement in place. The unit has to be chosen
carefully: it is the finest grouping denoting one physical place at one
time, so for a multi-year trial series it is location by year rather than
location alone, because trials at one named location in different seasons
legitimately sit in different paddocks.

A site that cannot be placed on land within `max_tries` re-draws is set to
`NA` on both axes, with a warning. `masque` does not emit a true
coordinate inside a table the caller believes is masked.

Declaring the pair to `mask()` applies the same coarsening as part of
masking, so the coordinates never pass through the copula:

```{r geo-mask, eval = FALSE}
plan <- set_role(plan, c("GPS_S", "GPS_E"), action = "keep")
m <- mask(df, plan, mode = "collaborate",
          coords = list(list(lat = "GPS_S", lon = "GPS_E", by = "TRIAL")),
          seed = 1L)
```

The recipe records the grouping each declared pair was masked under, so a
clone carries the account of its own coordinate structure. A coordinate
declared to `coords` is retained in the synthetic, so `audit_mask()`
reports it as *medium*, noting that the column was coarsened in place. A
coordinate kept with its real values would be HIGH.

`synthesise_geospatial()` is the alternative when it is preferable to
re-anchor points around fake centroids supplied for each region.

**How far to displace.** The right magnitude is not a constant. It is
calibrated to the density of the entities being protected, so that the
masked point is spatially k-anonymous: roughly, at least *k* comparable
entities lie closer to the masked point than the true one (Hampton et al.,
2010). Individual-level urban health data is typically masked with a
standard deviation of about one kilometre, because cities are dense.
Fields and farms are far sparser, so comparable protection needs a much
larger displacement; a donut of roughly 5 to 20 km (the default) moves a
point across several properties while keeping it in the same agroclimatic
region (Zandbergen, 2014). A formal guarantee needs the radii calibrated
to the local field density rather than the default.

## Results

Aliasing a design column hides the site names and keeps the layout. The
alias map hides which label is which, but not how often each occurs.

The default clone keeps the pooled mean and SD of yield but loses the
treatment effect (`r round(effect_marg, 2)` against a true
`r round(true_effect, 2)`), and a pipeline that checks only marginal
fidelity would not notice. The conditional clone keeps it
(`r round(effect_cond, 2)`). Neither keeps a non-monotone relationship
between two numeric columns.

A column constant within a trial stays constant within it, and linked
event times stay in order with exact pattern counts.

The audit caught both planted problems and the write was refused:
`dir.exists(out_dir)` is `r dir.exists(out_dir)`. A kept outcome audits
HIGH unless the custodian allows it, and a collaborate table of fewer than
five rows is refused. Linked tables share one alias map for their key, so
they still join.

A synthetic clone therefore protects the labels and the raw values behind
them. It does not hide the design footprint or the level frequencies, and
without `conditional = TRUE` it does not keep a treatment effect. A column
whose sensitivity was set wrongly is caught by the audit before anything
is written.

## Limits

Everything demonstrated here is a development safeguard, not a
disclosure-control guarantee in the formal sense. The alias map raises the
cost of a public-vocabulary attack, but a bijection preserves level
frequencies. A determined attacker with strong side information about
frequencies and structure is not stopped by an alias alone. The Gaussian
copula keeps only monotone association, so a pipeline whose core modelling
step is non-linear should be validated on the original data through the
recipe. The donut jitter's k-anonymity property
is a rule of thumb tied to entity density, not a certified guarantee, and
the right radius for a given dataset needs to be chosen with that density
in mind rather than left at the package default. The leakage audit reads
what the mask-time comparison can see (flagged names, frequency-one
levels, retained coordinates). It cannot detect a disclosure risk that
depends on information outside the table, such as an outside dataset an
attacker might already hold. These limits are part of the method.

## What to read next

*Getting started with masque* covers the custodian's side of a first
masking run: `masque()`, the roles-and-actions plan, and
multi-environment detection.
*Recipe anatomy and the round-trip* is the analyst's side: what the
recipe stores and how a pipeline built on the synthetic re-targets to the
original.

## Reproduce

`set.seed(1)` is set once for the whole document; the conditional-clone
fixture reseeds explicitly with `set.seed(42)` and the copula-shape fixture
with `set.seed(7)`, so both sections are self-contained regardless of
chunk execution order. The grain fixture reseeds with `set.seed(3)` and the
events fixture with `set.seed(5)`. Every
`mask()`/`mask_set()`/`jitter_coordinates()` call also passes `seed = 1L`
explicitly. Package versions follow.

```{r session-info}
sessionInfo()
```

## References

Hampton, K. H., Fitch, M. K., Allshouse, W. B., Doherty, I. A., Gesink, D. C.,
Leone, P. A., Serre, M. L., & Miller, W. C. (2010). Mapping health data:
improved privacy protection with donut method geomasking. *American Journal of
Epidemiology, 172*(9), 1062-1069. <https://doi.org/10.1093/aje/kwq248>

Zandbergen, P. A. (2014). Ensuring confidentiality of geocoded health data:
assessing geographic masking strategies for individual-level data. *Advances in
Medicine, 2014*, 567049. <https://doi.org/10.1155/2014/567049>

```{r reset-options, include = FALSE}
options(old_options)
```
