Returns a per-column audit data.table, with table-level checks attached, and
prints a severity-grouped report.
Auto-runs in mode = "collaborate" at mask() time and stores the
result on the masque object (m@audit); for local-mode audits or
explicit re-audits, pass the original data frame via original.
Arguments
- m
A
masqueobject frommask(), or amasque_setfrommask_set().- original
Optional. Required when
m@auditis NULL (typically in local mode). Used to recompute exact-match-pct etc. on demand. The original data frame for amasque; for amasque_set, a named list holding the original table of every table in the set.Logical; if TRUE (default), print a styled report.
Value
The audit data.table, returned invisibly. For a masque_set, a
named list of per-table audit data.tables, printed table by table.
Details
Each row of the returned data.table holds:
col: column name in the original.role: assigned role.kind: storage kind.leakage_class:low,medium, orhigh.n_unique_levels: distinct non-NA values (categorical only).freq_min: minimum per-level frequency (categorical only).exact_match_pct: percentage of synthetic cells equal to the original cell (numeric only; cell-by-cell).na_pct: percentage of NA cells in the original column.na_pattern_uniqueness: fraction of rows in the original with a globally unique NA pattern (one number per data frame, repeated on every row).alias_status:aliased,permuted,passthrough, ordropped.notes: short human summary.same_row_pct: percentage of rows where the clone value equals the original value in the same row, read back through the level map (categorical, logical, date and two-valued numeric columns).baseline_pct: the same share expected by chance, under a random permutation of the original column: \(100 \sum_k p_k^2\) over its level frequencies (within the conditioning strata for a scrambled numeric column of a conditional clone).excess_pct:same_row_pct - baseline_pct.
The table-level checks sit in attr(audit, "joint"), a data.table with
one row per check (check, cols, observed, baseline, excess,
sd, leakage_class, notes). Each baseline comes from independent
permutations of the original content columns (outcomes, covariates,
dates, kept text), drawn under a fixed internal seed that leaves the
caller's random number stream untouched; design, treatment, id, aliased
text and linked columns are held fixed:
same_row_joint: rows whose every content column equals the original row.whole_row: clone rows equal to some original row on every retained column.rare_cross: in the cross of visible (not aliased) categorical covariates and outcomes, clone cells holding one row whose combination is also a single row in the original.unit_sizes: a note, never graded, when design units differ in size, since the multiset of sizes can link a clone to a public trial list.
Classification heuristics:
Retained PII-pattern column ->
high.Outcome with action
keepin collaborate ->high, ormediumwhenmask()was called withallow_kept_outcome = TRUE, which the recipe records.Treatment unaliased in collaborate ->
high. A numeric treatment (a dose) is aliased like a categorical one.Categorical covariate with a frequency-1 level in collaborate ->
high.Outcome with exact-match-pct > 1\
Numeric covariate with exact-match-pct > 5\
medium.Two-valued numeric columns skip the two exact-match rules: a 0/1 column matches its own cell about half the time by chance. So do columns synthesised once per design unit (see
graininmask()) and whole-valued numeric covariates, which repeat real values by construction; all three are graded onexcess_pctinstead.Content column whose
excess_pctis at least 10 points and four binomial standard deviations in collaborate ->medium.Joint match excess of at least 20 points and four permutation standard deviations ->
high(5 points ->medium); rare-cross excess of at least 3 cells and four standard deviations ->high(1 cell and three ->medium). In collaborate mode these verdicts raisemasque_high_leakageand block package-managed writers; in local mode they are reported in the notes and gradedlow.Ignore column retained in local ->
low(informational).
A column constant within a design unit that was synthesised row by row
(grain = FALSE, or a collaborate grain with fewer than five units) carries
a note saying the clone does not keep that grain.
As a reference point, a collaborate-mode clone of agridat::besag.met
(yield as the outcome, design columns kept) scores low on every
column, and none of its yields equals the original value.
Examples
r <- propose_roles(iris)
r$role[r$col == "Sepal.Length"] <- "outcome"
r$role[r$col == "Species"] <- "covariate"
m <- mask(iris, r, mode = "collaborate", seed = 1)
#> Re-resolved default actions for mode "collaborate" (explicit edits always win):
#> • Species: scramble -> alias
audit_mask(m)
#>
#> ── masque audit (mode = collaborate) ───────────────────────────────────────────
#> • 0 HIGH, 0 medium, 5 low across 5 columns
#> • Rows with a globally unique NA pattern: 0.0%
#>
#> ── LOW (5) ──
#>
#> ℹ outcome Sepal.Length ok
#> ℹ covariate Sepal.Width ok
#> ℹ covariate Petal.Length ok
#> ℹ covariate Petal.Width ok
#> ℹ covariate Species levels aliased
#>
#> ── Table-level checks ──
#>
#> ℹ LOW same-row joint match 0.0% vs chance 0.0% (sd 0.7)
#> ℹ LOW whole-row match 0.0% vs chance 0.0% (sd 0.7)
