The set-level counterpart to mask(). Takes a folder of tabular
files, an Excel workbook, or a named list of data frames and produces
one synthetic table per input table plus a single private recipe
bundle. Columns that are shared across tables - a site code, a
genotype name, a plot id appearing in several tables - are aliased
identically everywhere they occur, so a join written against the
synthetic set still resolves on the masked data.
Arguments
- input
A folder path, an
.xlsx/.xlspath, or a named list of data frames - anythingread_set()accepts. A list element may also be aconform_table()result: its cleaning record and conform decisions are used for that table and recorded on its recipe.- roles
Optional named list of roles tables, one per input table (names must match). When
NULL(default),propose_roles()runs on each table for the chosenmode. Supply edited tables for full control.- links
Optional override for link detection: a character vector of column names to treat as cross-table links, or
FALSEto disable linking entirely (each table masked independently). WhenNULL(default), links are detected automatically.- mode
Either
"local"or"collaborate". When omitted androlesare supplied, inherit their common mode. Tables prepared for different modes must be reconciled explicitly. Otherwise default to"local".- seed
Optional integer for reproducibility.
- clean
Hygiene mode passed to
clean_table()for every table ("auto","report", or"off").- alias_names
Hide column names.
FALSE(default) keeps them;TRUEaliases every non-link column (linked join keys keep their names so the synthetic set stays joinable).- conditional
Logical scalar (default
FALSE). Passed through to each per-tablemask()call: whenTRUE, every table's numeric block is re-simulated within its own treatment-by-design strata so the treatment-to-outcome relationship survives the clone. Seemask()for the full account.- ladder
Drop order of the conditioning ladder,
"hierarchy"(default) or"levels"; passed through to eachmask()call.- grain
Single logical (default
TRUE); passed through to eachmask()call, which synthesises a unit-constant column once per unit.- allow_kept_outcome
Single logical, passed to each
mask()call:TRUEallows a kept outcome in a collaborate clone and records it.- quiet
Logical; suppress the link / hygiene report, including the hint that a table looks like documentation.
- sheets
For an Excel workbook, the sheets to read (default: all); passed to
read_set().- info
Optional character vector of table names (sheet names, or file names without extension) to set aside as documentation, for example a data dictionary. They are set aside before masking: not masked, not in the synthetic set, not written by
write_set(), and their content is not kept. Their names are recorded on the recipe bundle. A table that looks like documentation and is not named here raises a hint (a message of classmasque_info_hint); the hint decides nothing.- ...
Must be empty: any argument here is refused with
masque_unused_arg_refusal.
Value
A masque_set S7 object. Use synthetic() for the named list
of synthetic tables and recipe() for the private recipe bundle.
Links
A link is a column name that appears in two or more tables with a
compatible kind and overlapping values - the join keys of the set.
mask_set() proposes links automatically and prints them; pass
links to override. Linked columns are aliased in place with a shared
map (built over the union of values across all tables), so identical
original values map to identical aliases in every table. The aliases
read <col>_K001, <col>_K002, ..., assigned at random and, when seed
is set, the same for the same seed. Set a linked column's action to
keep in its roles table to pass it through unmasked instead.
Examples
tables <- list(
plots = data.frame(
site = rep(c("A", "B", "C", "D", "E"), each = 2),
gen = rep(c("x", "y"), 5),
yield = c(3.1, 2.9, 4.0, 3.7, 3.3, 3.5, 2.8, 3.0, 3.9, 3.6)
),
sites = data.frame(
site = c("A", "B", "C", "D", "E"),
rainfall = c(420, 560, 390, 610, 480)
)
)
roles <- lapply(tables, propose_roles, mode = "collaborate")
roles <- lapply(roles, set_role, "site", action = "alias")
m <- mask_set(tables, roles = roles, seed = 1, quiet = TRUE)
synthetic(m)$plots$site
#> [1] "site_K002" "site_K002" "site_K001" "site_K001" "site_K005" "site_K005"
#> [7] "site_K004" "site_K004" "site_K003" "site_K003"
synthetic(m)$sites$site # same aliases -> the join still works
#> [1] "site_K002" "site_K001" "site_K005" "site_K004" "site_K003"
