perturbation: Perturbations of the synthetic data distribution

In SynthesizerPlus: Synthetic Data Generation with Copulas, Evaluation and Multi-Format I/O

Perturbations of the synthetic data distribution

Description

perturbation() describes how synthetic data should deviate from the fitted model. It is passed to generate() (argument perturb) and has two groups of settings.

Record-level settings move synthetic records away from the real records while (approximately) keeping the distributions:

• noise – smoothing of numeric variables. Each value is replaced by \mu + (x - \mu + h s \varepsilon) / \sqrt{1 + h^2} with \varepsilon \sim N(0, 1), where h is noise and \mu, s are the mean and standard deviation of the variable in the fitted model. Mean and variance are approximately preserved (exactly only if \mu and s matched the generated values exactly; rounding of whole-number variables adds a little variance); the distribution becomes smoother and values move away from observed ones.

• swap – probability that a value of a categorical or discrete variable is replaced by an independent draw from its marginal distribution. The marginal distribution is preserved; the association with other variables is weakened for the affected records.

Distribution-level settings deliberately change the distributions, e.g. for stress tests or to simulate a domain shift:

• shift – shift of numeric variables, in units of their standard deviation;

• scale – multiplier of the spread of numeric variables around their median;

• temperature – reshapes the probabilities of categorical and discrete variables, p_k \propto p_k^{1/T}: T > 1 makes them more uniform, T < 1 concentrates them on the most frequent values;

• dependence – strength of the dependence between variables: 0 gives independent variables, 1 the fitted dependence, values above 1 (up to 2) strengthen it.

Numeric variables that only take whole numbers (counts, ages, dates) stay whole numbers; they are rounded stochastically after perturbation, so that shifts and noise are not biased by rounding.

noise, swap, shift, scale and temperature can be single numbers (applied to every eligible variable) or named vectors that apply to the named variables only.

Usage

perturbation(
  noise = 0,
  swap = 0,
  shift = 0,
  scale = 1,
  temperature = 1,
  dependence = 1,
  bounds = c("sign", "observed", "none")
)

Arguments

noise	Non-negative smoothing bandwidth for numeric variables.
swap	Probability in [0, 1] of independent re-drawing for categorical and discrete variables.
shift	Shift of numeric variables in standard deviations.
scale	Positive spread multiplier for numeric variables.
temperature	Positive temperature for categorical and discrete probabilities.
dependence	Dependence strength in [0, 2].
bounds	How to keep perturbed numeric values in range: "sign" (default; variables that are never negative, or never positive, keep that sign), "observed" (clip to the observed range) or "none".

Value

An object of class sp_perturbation.

See Also

generate(), calibrate_closeness()

Examples

fit <- fit_synthesizer(iris)

# records further from real ones, same distributions
far <- generate(fit, perturb = perturbation(noise = 0.5, swap = 0.2), seed = 1)

# a shifted scenario: longer petals, more uniform species, weaker dependence
p <- perturbation(shift = c(Petal.Length = 1), temperature = 3, dependence = 0.5)
p
scen <- generate(fit, perturb = p, seed = 1)
tapply(scen$Petal.Length, scen$Species, mean)

SynthesizerPlus documentation built on Oct. 16, 2026, 5:10 p.m.