synthesize_file: Synthesise a file end to end

In cellsynth: Cell-Wise Synthetic Copies of De-Identified Tables

Synthesise a file end to end

Description

Reads the source (every sheet of a workbook unless sheet says otherwise), infers a spec per sheet (or reads the reviewed one), writes inferred specs for review, synthesises m independent copies and writes each as ⁠<stem>_synth<i>.<ext>⁠ (all sheets in one workbook, in the original order) with a run log.

Usage

synthesize_file(
  path,
  out_dir,
  sheet = NULL,
  spec_path = NULL,
  spec_dir = out_dir,
  id = NULL,
  text = NULL,
  id_pattern = NULL,
  text_pattern = NULL,
  m = 1,
  seed = 1,
  small_sheets = c("blank", "copy", "drop"),
  minbucket = 5,
  delim = NULL,
  encoding = NULL,
  ...
)

Arguments

path	Source .xlsx/.xlsm/.xls or .csv/.txt.
out_dir	Output folder.
sheet	Sheet names or indices to synthesise (default: all sheets). Sheets not listed are left out of the output.
spec_path	Spec CSV for a single-sheet source: read when it exists, written when it does not.
spec_dir	Folder for per-sheet specs (⁠<stem>__<position>_<sheet>_spec.csv⁠); default out_dir.
id, text	Column names forced to id / text (case-insensitive). They apply to inferred specs and also on top of reviewed specs read from disk, so identifiers named here always stay untouched.
id_pattern, text_pattern	Regular expressions on column names, same effect (see apply_role_overrides()).
m	Number of synthetic copies.
seed	Base seed; copy i, sheet k of K uses seed + K * (i - 1) + k - 1.
small_sheets	Policy for sheets too small to synthesise.
minbucket	Passed to synthesize_table() and used for the size check.
delim, encoding	CSV only, passed to read_source(); NULL detects.
...	Passed to synthesize_table().

Details

Review the spec CSVs after the first run: set role to id for every identifier the heuristics missed and to text for free text, then run again with the same spec_dir (or spec_path).

Sheets that cannot be synthesised are handled by small_sheets: empty sheets and sheets without modelled columns are copied as they are (they hold no modelled values); sheets with fewer than 4 * minbucket subject rows (legends, codebooks, lookup tables, tiny pilots) get small_sheets: "blank" (default; keeps header and identifiers, empties the rest), "copy" (verbatim, for codebooks you know hold no subject data) or "drop".

Value

list(results = list over copies of lists over sheets of synth_result, files, spec_paths).

Examples

df <- data.frame(id = sprintf("AB%03d", 1:60), value = 1:60,
                 code = rep(c(0, 1, NA), 20), group = rep(c("A", "B"), 30))
path <- file.path(tempdir(), "synthesize_file.csv")
utils::write.csv(df, path, row.names = FALSE, na = "")
out <- synthesize_file(path, out_dir = file.path(tempdir(), "synth_output"),
                       m = 1, seed = 1, n_folds = 2, verbose = FALSE)
out$files
out$spec_paths
head(out$results[[1]][[1]]$synthetic)

cellsynth documentation built on Oct. 31, 2026, 1:07 a.m.