Package {flexsynth}

A synth_result.

Unused.

A synth_linked_result.

Unused.

A synth_linked_result, or a named list of data.frames.

When object is a raw list of tables, a named list of key columns (as passed to synth_linked()). Ignored for a result object.

Logical; print a short summary. Defaults to TRUE.

The real data.frame.

A synth_result (pooled) or a synthetic data.frame.

A function of one data.frame returning a fitted model (coef()/vcov()) or a list(estimate =, variance =).

Passed to pool_synth() when syn is a multi-dataset result.

Confidence level for both intervals (default 0.95).

Reserved.

The real data.frame (or a named list of them for linked data).

The synthetic data: a data.frame, a synth() synth_result, a named list of tables, or a synth_linked() synth_linked_result.

Optional character vector restricting the variables compared; defaults to all columns present in both.

Propensity model for the pMSE, "logistic" (default) or "cart" (needs the rpart package).

Unused.

The real data.frame (or named list) the data was synthesised from.

The synthetic data: a data.frame, synth() synth_result, named list, or synth_linked() synth_linked_result.

Character vector of quasi-identifier columns; defaults to all columns present in both frames.

Optional single sensitive column for the attribute-disclosure (TCAP) measure; the quasi-identifiers minus target are used as the keys. NULL (default) skips it. For a linked (list) input it is assessed only on the table that contains it.

Optional data.frame of real records excluded from synthesis, enabling the membership-inference check. For linked input, a named list containing a holdout data.frame for every evaluated table.

Cap on the number of rows used for the distance computations (each of real / synthetic is sampled down to this); keeps the pairwise distances tractable. Default 2000.

Optional integer seed for the subsampling.

Unused.

Positive privacy-loss budget. Smaller = more private, less utility.

Failure probability for approximate DP; 0 requests pure \epsilon-DP (only the Laplace mechanism supports delta = 0).

Privacy unit. "person" (default) protects an individual across all their rows; "row" is weaker and cheaper (each row independent).

Cap on how many rows one person may contribute, used to bound sensitivity at unit = "person". NULL (default) uses 1 (each person contributes at most one row); rows beyond the cap are dropped by per-person subsampling before measuring. Set this from public domain knowledge when a person legitimately has several rows. For a longitudinal DP release (a structure with a nesting index), this must be ⁠>= 2⁠ — it caps the transition sensitivity — and the per-person prefix of that many rows is kept in temporal order. For a linked DP release (synth_linked()) it is the maximum children kept per parent — a single integer applied to every child table, or a named vector/list keyed by child-table name (e.g. list(admissions = 8, labs = 20)) — and the root cap is always 1.

Noise mechanism: "laplace" (pure \epsilon-DP) or "gaussian" (approximate DP with zCDP composition; needs delta > 0).

Dependence structure of the generative model: "tree" (default; a Chow-Liu tree over pairwise marginals) or "independent" (one-way marginals only).

Budget-efficient structure learning for the flat dependence = "tree" release (synth() with three or more variables). NULL (default) measures all \binom{d}{2} pairwise marginals at full fidelity and reuses them as both the Chow-Liu weights and the tree's conditionals. A number in ⁠(0, 1)⁠ instead spends only that fraction of the marginal budget on a cheap all-pairs scan used solely to select the tree, then concentrates the remaining 1 - structure_frac on re-measuring just the d - 1 chosen edges (plus the d one-way marginals) — so the budget lands on the parameters that survive into the model instead of on pairs that are discarded. Structure selection tolerates noise well, so a small slice (e.g. 0.2–0.3) usually sharpens the retained edges, more so as the number of variables grows. Both passes compose into the same exact (\epsilon, \delta) budget. Inert for dependence = "independent", for fewer than three variables (the tree is then trivial), and for longitudinal / linked DP releases (which keep the single-pass fitter).

Fan-in of the Bayesian network fitted for a flat synth() dependence = "tree" release. 1 (default) keeps the Chow-Liu tree exactly as before (each variable conditions on at most one parent). 2 or more opts into PrivBayes' GreedyBayes: a degree-k Bayesian network in which each variable may condition on up to degree of the already-generated variables, its parent set chosen greedily with the exponential mechanism (the parents whose joint the variable depends on most, crediting the parents\tochild association only). Because a tree gives a variable a single parent, it cannot represent a variable that genuinely depends on two otherwise-unrelated predecessors (a "v-structure", e.g. C a noisy XOR of independent A and B); a degree-2 network takes both parents and recovers it. Construction measures the d one-way marginals plus one ⁠(parents, node)⁠ family joint per non-root node (⁠2d - 1⁠ marginals total) and spends a select_frac slice on the d - 1 greedy picks; every slice composes into the same exact (\epsilon, \delta) (zCDP for Gaussian, pure \epsilon for Laplace). The network is forward-sampled ancestrally (no PGM inference), so like the tree it stays inference-free. degree is capped to d - 1, and a high fan-in makes each family a (degree + 1)-way histogram — the same bins^(degree + 1) cell-count warning as treewidth applies. Requires dependence = "tree"; it is an alternative to structure_frac and to select = "adaptive" (setting either alongside degree > 1 is an error), and is refused on longitudinal / linked releases. Ignored when degree = 1.

How the marginals that make up the model are chosen, for a flat synth() release. "fixed" (default) measures a predetermined set (all one-way marginals, plus — for dependence = "tree" — pairwise marginals), exactly as described above; every existing path is unchanged. "adaptive" opts into an AIM-style iterative selector: after measuring the one-way marginals it builds the dependency model one marginal at a time, at each step using the exponential mechanism to privately pick the marginal whose true value the model-so-far fits worst, then measuring that marginal under the main mechanism. Selection and measurement each spend budget and compose exactly into the same (\epsilon, \delta) (zCDP for Gaussian, pure \epsilon for Laplace); the number of rounds is fixed in advance from the variable count and treewidth, so the accounting is data-independent. Unlike structure_frac (which picks a tree from one free noisy scan), adaptive selection is model-error-guided and — at treewidth >= 2 — can measure marginals that form loops, capturing higher-order interactions a Chow-Liu tree structurally cannot. Ignores dependence and structure_frac (supply treewidth / select_frac instead — setting structure_frac alongside is an error). "aim" is Full AIM: it lifts the adaptive selector's running-intersection constraint, so the exponential mechanism may pick loopy marginals — a pair between two variables already in the model, the cycle a junction-tree selector structurally cannot close. Because a loopy set has no forward junction-tree sampler, "aim" reconciles the whole measured set (the d one-way marginals plus the selected pairs) into one graphical model over a triangulated junction tree by Private-PGM (belief propagation + mirror descent; see estimator) and samples from that. It runs a data-independent min(d (d - 1) / 2, treewidth * (d - 1)) selection rounds, each rejecting any new pair whose triangulated clique would exceed treewidth + 1; at treewidth = 1 no loop can be closed, so it reduces to an adaptively-selected tree. Like "adaptive" it uses treewidth / select_frac (not structure_frac / degree), and the reconciliation is budget-neutral. All selectors are currently flat-table only: "adaptive" / "aim" on a longitudinal or linked structure is refused.

Adaptive selection only. Maximum clique size minus one in the junction-tree model — the ceiling on interaction order the model can hold. 1 (default) builds a tree (each measured marginal is a pair; equivalent model class to dependence = "tree", but selected adaptively). 2 lets the selector measure three-way marginals whose variables form triangles, so pairwise-invisible three-way structure survives, and 3 measures four-way cliques (interactions no three-way marginal can see, e.g. a 3-bit parity). Higher clique orders cost more per cell — a (w+1)-way histogram over bins cells per axis is bins^(w+1) cells, so the per-cell DP noise grows fast; a warning is raised when that count is large (bins is the numeric proxy; low-cardinality factor cliques are smaller). Raise it only when interactions of that order genuinely matter. For select = "aim" it bounds the model's triangulated clique size the same way (so 1 forbids loops and 2 permits triangles). Ignored unless select = "adaptive" or select = "aim".

Adaptive selection only. Fraction of the marginal budget spent on the private selection (the exponential-mechanism rounds); the remaining 1 - select_frac is spent measuring the chosen marginals (and the one-way marginals). Default 0.25. Selection tolerates noise well, so a modest slice usually gives the best fidelity (the same intuition as structure_frac); both slices compose into the same exact (\epsilon, \delta). Ignored unless select = "adaptive" or select = "aim".

Adaptive ("adaptive" / "aim") selection only. FALSE (default) uses a fixed-round schedule with a uniform per-round budget. TRUE opts into AIM-style budget annealing — a data-adaptive round schedule: the d one-way marginals take a fair fixed share, then the marginal measurements and their exponential-mechanism selections start at a small per-round quantum (large noise) and double whenever a round's measured signal fails to beat its noise floor (AIM's \sigma-halving rule). After a baseline number of selection rounds — the spanning cliques for "adaptive", the treewidth-capped new pairs for "aim" — any surplus budget is spent on extra rounds that re-measure the worst-fit already-measured marginal (inverse-variance combined, so \rho / \epsilon adds exactly). The final round absorbs the exact remainder, so the total spend is still exactly (\epsilon, \delta) — now over a variable number of rounds chosen from the data. For select = "adaptive" the model stays a spanning junction tree (no PGM inference), so refinement can only sharpen the measured cliques; for select = "aim" the annealed set is triangulated and reconciled with Private-PGM exactly as in the fixed-round AIM, so refinement sharpens loopy marginals too. It is most useful when there are few variables and the fixed schedule would otherwise leave budget on the table. Ignored unless select = "adaptive" or select = "aim"; setting it otherwise is an error.

How the measured marginals are turned into the generative model, for a flat synth() tree or adaptive release. "local" (default) is every existing path unchanged: each marginal is used locally — the tree takes the root's one-way and each edge's raw noisy 2-way as P(\text{child} \mid \text{parent}), the adaptive junction tree each clique's own array — so the other one-way marginals, and the disagreement between overlapping noisy marginals, are discarded. "pgm" opts into Private-PGM inference (McKenna et al.'s MST / graphical-model estimation): the whole set of measured marginals is reconciled into the single graphical-model distribution that best fits all of them at once (least squares), by belief propagation on a junction tree of the measured cliques plus entropic mirror descent, and the model is sampled from that. Because a tree (or the adaptive junction tree) has bounded treewidth, the inference is exact and cheap. Reconciliation is pure post-processing of the already-privatised marginals, so it spends no extra budget — the (\epsilon, \delta) is identical to the same release with "local"; only the fitted model changes. It denoises (overlapping marginals are made mutually consistent) and lets the otherwise-discarded one-way marginals actually constrain the model, usually sharpening both the marginals and the conditionals at the same budget. Available for the flat dependence = "tree" release (degree-1) and for select = "adaptive"; it is an alternative to structure_frac, to degree > 1, and to anneal = TRUE (setting any of those alongside estimator = "pgm" is an error), and there is nothing to reconcile in dependence = "independent". Refused on longitudinal / linked releases (flat-table only). Ignored (no-op) for "local". select = "aim" always reconciles with Private-PGM by construction (a loopy marginal set has no local sampler), so estimator is moot there.

How select = "aim" scores each candidate marginal in its exponential-mechanism rounds. "auto" (default) picks the faithful choice per selector: select = "aim" uses "model" (AIM's actual quality function), and every other selector uses "independence" (where model scoring is inert). "model" scores each candidate against the current reconciled Private-PGM model's own marginal over that pair, so a loopy pair the model already explains (through the marginals measured so far) no longer looks surprising and the budget is steered to the genuinely worst-fit interaction. "independence" is the cheaper opt-out: it scores a pair by how far its true joint sits from the product of its one-way marginals — the reference the other selectors use, and Full AIM's behaviour before this became the default. The model reference is read from the already-privatised marginals — reconciled each round and projected onto the candidate (a not-yet-measured pair projects across cliques of the junction tree) — so it is pure post-processing: the exponential mechanism's sensitivity and the exact (\epsilon, \delta) are identical to "independence"; only which marginals get selected changes. "model" costs extra computation (a reconciliation per selection round) and composes with anneal. Explicit "model" requires select = "aim" (an error otherwise); the adaptive selector's candidates always introduce a fresh variable, so its model projection reduces to the independence product anyway.

Linked DP only (synth_linked()). When TRUE, a child table's variables are conditioned on the synthetic parent's attributes: for each child table with a modellable immediate parent, parent-by-child joint marginals are measured (at the child's per-entity path-cap sensitivity, the same as a child one-way marginal) and folded into the child's Chow-Liu structure as fixed context nodes, so each child variable's single strongest predictor may be a parent variable or another child variable. The synthetic parent's already-drawn value then conditions the child draw, so cross-table statistical dependence — not just referential integrity — survives the noise. Costs extra budget (the added joints compose into the same (\epsilon, \delta)); FALSE (default) keeps child variables on their own within-table marginals. Ignored by flat / longitudinal synth() releases, which have no parent table.

Linked DP only (synth_linked()). Model a child table's repeated rows as a within-unit time series under DP, instead of exchangeable records: for such a table the children-per-parent count model doubles as a trajectory-length model, an initial-state model is measured over each unit's first (temporally earliest) child row, and a first-order Markov transition matrix P(v_t \mid v_{t-1}) is measured per variable over consecutive within-unit rows (ordered by the child's own key index). Sensitivities differ by histogram — initial marginals at the parent's path cap, transitions at path_cap[parent] * (branching_cap - 1) — and fold into the same exact (\epsilon, \delta) budget. Pass TRUE to model every eligible child table (a child with a branching cap \ge 2 and at least one variable), or a character vector of child-table names to model only those. The child's branching cap in max_rows_per_person bounds the transition sensitivity, so it must be \ge 2 for a named table, and the prefix of that many rows is kept in temporal order. Setting cross_table = TRUE together with a longitudinal model on the same table combines them: the table's initial-state model is cross-conditioned on the synthetic parent (adding the parent-by-child joints at the same first-row sensitivity as the initial marginals), and the transition chain then carries that parent dependence across the trajectory — the parent shapes where a trajectory starts, while the transitions stay parent-free, so the only extra cost is the initial-state joints. FALSE (default) treats child rows as exchangeable. Ignored by flat / longitudinal synth() releases (which pick the DP Markov engine straight from the structure formula).

Longitudinal releases. Names of subject-invariant columns — baseline covariates that do not change across a unit's rows (e.g. birth sex, a baseline measurement). These are held exactly constant within each synthetic unit: they are modelled once in the initial-state model (so their joint distribution and their correlation with the first visit are preserved) and then broadcast to every row, rather than being stepped through a transition matrix that would let them drift. Declaring a column baseline is public schema knowledge, so it costs no budget; it also removes that column's transition histogram from the release, sharpening every remaining measurement at the same (\epsilon, \delta). Applies to a longitudinal synth() release (a structure with a nesting index) and, per table, to any longitudinally-modelled linked child (the names are matched against each such child's own columns). NULL (default) treats every column as time-varying. Names that match no modelled column are ignored. Ignored by a flat synth() release (one row per unit) and by non-longitudinal linked child tables.

Longitudinal releases. Markov order of the within-unit transition model: how many of a variable's own immediately preceding values condition its next value. 1 (default) is the first-order model P(v_t \mid v_{t-1}); 2 gives P(v_t \mid v_{t-1}, v_{t-2}), and so on. Higher orders capture momentum but need a larger row cap: the order must be at most max_rows_per_person - 1 — for a linked release, one less than the branching cap of each longitudinally-modelled child (validated per table). A unit then contributes at most cap - order transition tuples per variable, so the transition sensitivity — and hence the noise — actually drops with order, at the price of a finer conditioning grid (sparser cells) and of not modelling the earliest rows' own dynamics separately: rows before position order + 1 are generated by marginalising the same measured tensor, which is post-processing and costs no budget. Applies to a longitudinal synth() release and, uniformly, to every longitudinally-modelled linked child; ignored by flat releases and non-longitudinal linked children.

Longitudinal releases. Number of other variables (each at lag 1) that additionally condition each variable's transition — moving from P(v_t \mid v_{t-1}, \dots) to also conditioning on u_{t-1} for the transition_cross most strongly associated companions u. Cross-parents are selected automatically and budget-neutrally from the pairwise marginals the Chow-Liu tree already measures (contemporaneous mutual information, a leak-free proxy for lag-1 cross-predictiveness) — for a linked child that means its own within-child pairwise marginals — so transition_cross > 0 requires dependence = "tree". Adding conditioning columns does not change the (\epsilon, \delta) budget — a transition tuple still lands in exactly one cell — it trades budget-free structure for cell sparsity, so keep it small. 0 (default) conditions each variable on its own past only. Applies to a longitudinal synth() release and to every longitudinally-modelled linked child; ignored by flat releases and non-longitudinal linked children.

Linked DP only (synth_linked()), longitudinal children. Number of immediate-parent attributes that additionally condition each time-varying child variable's transition. Today cross_table = TRUE cross-conditions only a longitudinal child's initial state on the synthetic parent; the parent's influence then rides the own-lag chain and decays. transition_parent = p instead re-injects the (subject-invariant) parent attributes into the transition tensor at every step — moving from P(v_t \mid v_{t-1}, \dots) to also conditioning on the parent's w for the p parent attributes w most strongly associated with v — so parent \to child dependence stays anchored across the whole trajectory rather than washing out. The parents are selected automatically and budget-neutrally from the parent-by-child joints that the cross-conditioned initial state already measures, so it costs nothing in the (\epsilon, \delta) budget (a transition tuple still lands in exactly one cell — same sensitivity, same histogram count), trading budget-free structure for cell sparsity. Because it reuses those joints, transition_parent > 0 requires cross_table = TRUE for the child (an error is raised otherwise). 0 (default) leaves the transitions parent-free (the initial-state cross-conditioning is unaffected). Composes with baseline, transition_order and transition_cross. Ignored by flat synth() releases and non-longitudinal linked children, which have no parent trajectory to condition.

Number of equal-width bins used to discretise each numeric variable (default 12). Finer grids sharpen one-way marginals but make the noisy two-way marginals used by dependence = "tree" weaker per cell, so a moderate value usually gives the best correlation fidelity. Means and sums are largely unaffected (bin contents are decoded uniformly within the bin).

Optional named list giving c(lower, upper) for numeric variables, used as public, data-independent bin edges. How variables not named here are handled depends on domain.

How the discrete domain is chosen for variables without public metadata: "dp" (default) estimates numeric bin edges — and discovers bare character category sets by DP set-union — under differential privacy and accounts for the cost; "public" requires bounds for every numeric variable and public factor levels for every categorical (error otherwise) and spends no budget on the domain; "data" reads edges / levels from the data with a warning and excludes that step from the accounting (non-rigorous; benchmarking only).

Fraction of the privacy budget spent learning the domain under domain = "dp" (default 0.1) — numeric bin edges (exponential-mechanism quantiles) and character category sets (DP set-union). The slice is shared across those operations and composed with the marginal measurements, so the total spend is exactly (\epsilon, \delta). Ignored unless some numeric variable needs estimating or some character column needs discovering.

A flexsynth_diagnostics object from diagnose().

Optional subset of variables to plot.

Maximum number of variables to draw (default 12).

Passed to the underlying plotting calls.

A synth_result from synth() (ideally with m >= 5).

A function of one synthetic data.frame returning a fitted model (with coef()/vcov()) or a list(estimate =, variance =).

Combining rule: "synthpop" (default, Raab/Nowok/Dibben 2016) or "reiter" (Reiter 2003 fully-synthetic; needs m >= 2).

If TRUE (default) the standard error targets the population the real data was drawn from, inflating for synthesis. If FALSE it reports only the (size-rescaled) within-synthesis variance — the standard error an analyst of the original data would have seen.

Confidence level for the intervals (default 0.95).

Reserved for future use.

Method name (a single string) used to select it.

A function ⁠function(y, x, control)⁠ returning a fitted model.

A function ⁠function(model, x, n, control)⁠ returning n values.

Logical flags declaring which target types the method supports (used for validation). Both default to TRUE.

Logical; if TRUE (default) the engine falls back to marginal sampling when the variable has no predictors.

A logical expression over the column names, e.g. dbp <= sbp. With scope = "row" it is evaluated across a unit's rows and must be TRUE for every row. With scope = "unit" it is evaluated once per unit (the columns are that unit's rows in positional order) and must return TRUE — use this for temporal logic such as all(diff(los) >= 0). Missing (NA) results are treated as satisfied.

"row" (default) or "unit".

Optional human-readable label; defaults to the deparsed expression.

A data.frame in long format.

A one-sided formula giving the nesting hierarchy, e.g. ~ id / visit. The first term is the unit identifier.

Synthesis method, "cart" (default) or "sample", applied per variable unless overridden in tuning.

Optional rule() (or list of rules) the synthetic data must satisfy. Enforced by rejection sampling at the unit grain (see rule()); constraint_max_tries in synth_control() bounds the effort.

A synth_control() object.

NULL for Track A, or a dp_control() object for Track B.

Number of synthetic datasets to produce.

Optional integer seed for reproducibility.

Reserved for future use.

Optional character vector giving the order in which variables are synthesised. NULL uses the natural (left-to-right) order.

Optional 0/1 matrix marking, for each variable, which variables may predict it (including cross-table predictors). NULL lets the engine derive a sensible default.

Optional per-variable method override; a single string applies globally. NULL uses the call-level method.

Numeric-variable kernel smoothing. NULL (default) is auto: smooth numeric variables that look continuous (more than 20 distinct values), so their draws are not confined to the observed values — improving marginal realism and reducing exact-value replication. TRUE / "density" smooths every numeric variable; FALSE / "none" disables smoothing; a character vector smooths exactly the named variables. Auto resolution applies to single-table synth(); synth_linked() children are unsmoothed unless named explicitly.

Logical; use proper (TRUE) vs improper (FALSE) synthesis.

How the number of rows per unit is drawn for nested / longitudinal data. "marginal" (default) resamples the observed unit sizes independently of any covariate. "conditional" synthesises the subject-level covariates first and draws each unit's size from a CART model of size on those covariates, so a dependence such as "sicker patients have more visits" is preserved. Only takes effect when the structure is nested and there are subject-level covariates; ignored for flat single-row-per-unit data.

Optional size of each synthetic dataset. NULL matches the input.

Named lists of hyperparameters passed to the CART / random forest backends. For forest, ntree (number of trees, default 10) and mtry (predictors tried per tree, default all) are recognised.

Integer; how many times synth() may regenerate while rejection-sampling to satisfy constraints. Defaults to 50.

Controls parallel generation of the m synthetic replicates. FALSE (default) synthesises serially. TRUE uses all available workers (getOption("mc.cores"), else parallel::detectCores()); a positive integer sets an explicit worker count. Parallelism spreads the independent replicates over a cluster, so it only helps when m > 1. A parallel run is reproducible for a fixed (seed, worker count) via independent L'Ecuyer RNG streams, but its output differs from a serial run with the same seed.

A synth_result from synth().

A model formula (e.g. y ~ x1 + x2).

A family() for glm(); default gaussian() (linear model).

Passed to pool_synth().

Further arguments to glm().

Named list of input data.frames (one per table).

Named list of one-sided formulas, one per table, giving each table's nesting hierarchy (e.g. ~ id / admission_id).

Named list of character vectors giving each table's key columns. The last column is the table's own index; the leading columns are the foreign key into its parent.

Synthesis method applied per variable unless overridden.

Optional cross-table constraints / rules. Constraint enforcement currently applies to single-table synth() only; a message is emitted if supplied here (Track A) and it is an error under privacy (DP).

A synth_control() object.

NULL for Track A, or a dp_control() object for Track B.

Number of synthetic dataset collections to produce.

Optional integer seed for reproducibility.

Reserved for future use.