Package 'DPrivStats'

Description

Computes the advanced-composition bound for $k$ homogeneous releases:

$\varepsilon' = \sqrt{2 k \log(1/\delta')} \varepsilon + k \varepsilon (e^{\varepsilon} - 1).$

Usage

advanced_composition_epsilon(prior_epsilons, new_epsilon, delta_prime = 1e-06)

Arguments

Value

Total epsilon under advanced composition.

Description

Releases f(x) plus Gaussian noise calibrated with the analytic Gaussian mechanism (Balle & Wang, 2018).

Usage

analytic_gaussian_mechanism(f, x, epsilon, delta, l2_sensitivity)

Arguments

Value

The privatized value of f(x) (scalar or vector).

Description

Solves for the smallest sigma satisfying the analytic Gaussian mechanism privacy guarantee:

$\Phi(\Delta/(2\sigma) - \epsilon\sigma/\Delta) - e^{\epsilon}\Phi(-\Delta/(2\sigma) - \epsilon\sigma/\Delta) \le \delta$

via bisection. Always at least as tight as the classic calibration.

Usage

analytic_gaussian_sigma(epsilon, delta, l2_sensitivity)

Arguments

Value

Scalar noise standard deviation.

References

Balle, B., & Wang, Y. (2018). Improving the Gaussian Mechanism for Differential Privacy via Analytic Concentration of the Gaussian Distribution. NeurIPS 2018.

Examples

analytic_gaussian_sigma(1.0, 1e-6, 1.0)
gaussian_sigma(1.0, 1e-6, 1.0) # looser

Description

Basic (sequential) composition

Usage

basic_composition(epsilons, deltas = rep(0, length(epsilons)))

Arguments

Value

List with total epsilon and delta.

Description

Check whether a release fits in the remaining budget

Usage

can_spend(budget, epsilon, delta = 0)

Arguments

Value

Logical; TRUE if the proposed release fits.

Description

Clips each row of a gradient matrix to a maximum L2 norm: $\tilde g_i = g_i \min(1, C/\|g_i\|_2)$. Used by DP-SGD.

Usage

clip_gradients(grads, max_grad_norm)

Arguments

Value

List with clipped (the clipped gradients) and norms (original norms).

Examples

g <- matrix(rnorm(30), 10, 3)
clip_gradients(g, 1)$norms

Description

Given a sequence of per-release epsilons, returns total privacy cost under basic, advanced, and RDP composition — useful for the research question of which rule dominates in practice.

Usage

compare_composition(epsilons, delta = 1e-06)

Arguments

Value

Data frame with one row per composition rule and total epsilon.

Examples

compare_composition(c(1, 0.5, 0.5, 0.25), 1e-6)

Description

Fits dp_lm at each epsilon on an epsilon grid and reports MSE of coefficients relative to the ordinary least squares fit.

Usage

compare_utility(
  formula,
  data,
  epsilon_grid,
  delta = 1e-06,
  bounds = NULL,
  n_reps = 10
)

Arguments

Value

Data frame with columns epsilon, rep, mse_coef, max_abs_error.

Examples

set.seed(1)
d <- data.frame(x = rnorm(200)); d$y <- 1 + d$x + rnorm(200)
compare_utility(y ~ x, d, c(0.5, 2), 1e-6, list(y = c(-15, 15)),
                n_reps = 3)

Description

Convenience wrapper calling dp_confint with default settings.

Usage

## S3 method for class 'dp_lm'
confint(object, parm, level = 0.95, method = "analytical", B = 200, ...)

Arguments

Value

Numeric matrix with columns estimate, lower, upper.

Description

Clips rows of a gradient matrix to a maximum L2 norm; equivalent to clip_gradients but implemented in C++.

Usage

cpp_clip_gradients(grads, max_grad_norm)

Arguments

Value

Numeric matrix of clipped gradients.

Examples

g <- matrix(rnorm(30), 10, 3)
cpp_clip_gradients(g, 1)

Description

Vectorized inverse-CDF Laplace sampler implemented in C++ via Rcpp. Equivalent to rlaplace but faster for large draws.

Usage

cpp_rlaplace(n, scale = 1)

Arguments

Value

Numeric vector of length n.

Examples

cpp_rlaplace(5, 1.0)

Description

Privatizes group counts, means and variances (equal budget splits) and computes the one-way ANOVA F statistic from privatized summaries only.

Usage

dp_anova(formula, data, epsilon, bounds, delta = NULL)

Arguments

Value

An object of class c("dp_htest", "htest").

Examples

dat <- data.frame(y = c(rnorm(60), rnorm(60, 1)),
                  g = factor(rep(c("A", "B"), each = 60)))
dp_anova(y ~ g, dat, 2.0, bounds = c(-5, 5))

Description

Privatizes each cell of a contingency table with Laplace noise (sensitivity 1 per cell), truncates negative counts (post-processing), then computes the standard chi-square test on the privatized table.

Usage

dp_chisq_test(table, epsilon)

Arguments

Value

An object of class c("dp_htest", "htest") wrapping a standard chi-square test on the privatized table.

Examples

tab <- matrix(c(30, 20, 10, 40), nrow = 2)
dp_chisq_test(tab, 1.0)

Description

Confidence intervals for dp_lm coefficients that account for both sampling variability and privacy noise.

Usage

dp_confint(
  object,
  parm,
  level = 0.95,
  method = c("analytical", "parametric_bootstrap", "privacy_aware_bootstrap"),
  B = 200,
  ...
)

Arguments

Details

Three methods:

"analytical"

Normal intervals using $\sqrt{\text{diag}(\Sigma_{\text{sampling}}) + v_{\text{privacy}}}$, where privacy noise variance is known exactly from the mechanism calibration.

"parametric_bootstrap"

Simulates $\beta^* \sim N(\hat\beta_{\text{priv}}, \Sigma_{\text{sampling}})$ and adds fresh privacy noise; returns percentile intervals.

"privacy_aware_bootstrap"

Resamples the data and refits the DP estimator on each resample with per-resample budget $\epsilon / \sqrt{B}$ (advanced composition heuristic); returns percentile intervals. Most conservative but computationally heavy.

Value

Numeric matrix of class c("dp_confint", "matrix") with columns estimate, lower, upper.

Examples

set.seed(11)
d <- data.frame(x = rnorm(300))
d$y <- 1 + 2 * d$x + rnorm(300)
fit <- dp_lm(y ~ x, d, epsilon = 2.0, delta = 1e-6,
             bounds = list(y = c(-20, 20)))
dp_confint(fit)

Description

Fits a GLM with differentially private stochastic gradient descent: per-sample gradients are clipped to max_grad_norm, averaged, and Gaussian noise is added at each iteration. Privacy is accounted with the advanced-composition heuristic over n_iter iterations.

Usage

dp_glm(
  formula,
  data,
  family = stats::gaussian(),
  epsilon,
  delta,
  max_grad_norm = 1,
  n_iter = 1000,
  lr = 0.01,
  batch_size = NULL,
  bounds = NULL
)

Arguments

Value

A list of class "dp_glm" with coefficients, epsilon, delta, and convergence details.

Examples

set.seed(12)
d <- data.frame(x = rnorm(400))
d$y <- rbinom(400, 1, plogis(0.5 * d$x))
fit <- dp_glm(y ~ x, d, binomial(), epsilon = 2.0, delta = 1e-6,
              bounds = list(y = c(0, 1)))
fit$coefficients

Description

Releases bin counts of a bounded variable using Laplace noise with sensitivity 1 per bin, followed by non-negativity post-processing and optional normalization to probabilities.

Usage

dp_histogram(x, epsilon, breaks = NULL, normalize = FALSE)

Arguments

Value

An object of class dp_estimate with element estimate (named numeric vector of privatized bin counts/proportions).

Examples

set.seed(4)
fit <- dp_histogram(rnorm(500), 1.0, breaks = seq(-3, 3, by = 1))
fit$estimate

Description

Releases the ECDFs of two bounded samples on a common grid under DP (ECDF sensitivity $1/n$ per sample; budget split evenly between the two samples) and computes the KS statistic from the privatized ECDFs.

Usage

dp_ks_test(
  x,
  y,
  epsilon,
  bounds = c(min(c(x, y), na.rm = TRUE), max(c(x, y), na.rm = TRUE)),
  n_grid = 100
)

Arguments

Value

An object of class c("dp_htest", "htest").

Examples

set.seed(8)
dp_ks_test(rnorm(150), rnorm(150, 1), 1.0, bounds = c(-6, 6))

Description

Fits OLS on clipped data and releases the coefficient vector under the Gaussian mechanism, calibrated to the L2 sensitivity of $\hat\beta = (X^\top X)^{-1} X^\top y$ given response bounds bounds$y (and optionally a bound $C$ on row norms of X; see dp_lm_sensitivity).

Usage

dp_lm(
  formula,
  data,
  epsilon,
  delta,
  bounds = NULL,
  assume_public_design = TRUE
)

Arguments

Value

An object of class c("dp_lm", "lm") with privatized coefficients, residuals and fitted values computed from the private fit, plus elements epsilon, delta, noise_variance (privacy noise variance per coefficient), and sampling_vcov (the non-private sampling covariance estimate used by dp_confint).

Examples

set.seed(11)
d <- data.frame(x = rnorm(300), z = rnorm(300))
d$y <- 1 + 2 * d$x - d$z + rnorm(300)
fit <- dp_lm(y ~ x + z, d, epsilon = 2.0, delta = 1e-6,
             bounds = list(y = c(-30, 30)))
coef(fit)

Description

Under the assumption that the design matrix $X$ is public/fixed and the response is bounded ($y_i \in [L_y, U_y]$), neighbouring datasets differ in one response value only. With $C = \max_i \|x_i\|_2$ and $D = U_y - L_y$,

$\Delta_2(\hat\beta) = C \cdot D / \lambda_{\min}(X^\top X).$

Usage

dp_lm_sensitivity(
  X,
  y_bounds,
  x_norm_bound = NULL,
  assume_public_design = TRUE
)

Arguments

Details

If the design matrix itself is bounded per-row by x_norm_bound and treated as private, a conservative multiplicative factor of 3 is applied to account for simultaneous changes in $X'X$ and $X'y$ (documented heuristic; see vignette "regression-guide" for discussion).

Value

Scalar L2 sensitivity of the OLS coefficient vector.

Examples

X <- cbind(1, 1:10)
dp_lm_sensitivity(X, y_bounds = c(0, 10))

Description

Differentially private sample mean of a bounded variable. Data are clipped to bounds before the statistic is computed.

Usage

dp_mean(
  x,
  epsilon,
  bounds = range(x, na.rm = TRUE),
  mechanism = c("laplace", "gaussian", "analytic_gaussian"),
  delta = NULL
)

Arguments

Value

An object of class dp_estimate.

Examples

set.seed(1)
dp_mean(rnorm(500), 1.0, bounds = c(-5, 5))$estimate

Description

Releases a differentially private estimate of the median using the exponential mechanism over a grid of candidate values, with score $s(t; x) = -|\#\{i : x_i \le t\}| - n/2|$ which has L1 sensitivity 1.

Usage

dp_median(x, epsilon, bounds, n_bins = 1000)

Arguments

Value

A list of class dp_estimate with element estimate.

Examples

set.seed(42)
fit <- dp_median(rnorm(200), 1.0, bounds = c(-5, 5))
fit$estimate

Description

Releases arbitrary quantiles probs of a bounded variable using the exponential mechanism with score based on distance from the target order statistic. Each quantile receives budget $\epsilon / |\text{probs}|$.

Usage

dp_quantile(x, epsilon, bounds, probs = 0.5, n_bins = 1000)

Arguments

Value

An object of class dp_estimate; estimate is a named vector with one entry per probability in probs.

Examples

set.seed(3)
dp_quantile(rnorm(200), 1.0, bounds = c(-5, 5), probs = c(.25, .5, .75))

Description

Differentially private two-sample t-test. The privacy budget is split evenly across the DP group counts, means and variances; the test statistic is computed entirely by post-processing of privatized quantities.

Usage

dp_t_test(
  x,
  y,
  epsilon,
  bounds = c(min(c(x, y), na.rm = TRUE), max(c(x, y), na.rm = TRUE)),
  alternative = c("two.sided", "less", "greater"),
  delta = NULL
)

Arguments

Value

An object of class c("dp_htest", "htest") with elements statistic, estimate, std.error, p.value, alternative, and epsilon.

Examples

set.seed(7)
dp_t_test(rnorm(200), rnorm(200, 0.5), 1.0, bounds = c(-5, 5))

Description

Computes bias, mean squared error, RMSE, and (optionally) CI coverage of a DP estimator relative to its non-private counterpart or a known truth, across Monte Carlo replicates.

Usage

dp_utility_diagnostics(estimates, truth, ci_matrix = NULL)

Arguments

Value

List with bias, mse, rmse and optional coverage.

Examples

ests <- replicate(100, dp_mean(rnorm(200), 1.0, c(-5, 5))$estimate)
dp_utility_diagnostics(ests, 0)

Description

Differentially private variance of a bounded variable, released as the DP second moment minus the square of the DP mean under a split budget ($\epsilon/2$ each), with post-processing to ensure non-negativity.

Usage

dp_variance(
  x,
  epsilon,
  bounds = range(x, na.rm = TRUE),
  mechanism = c("laplace", "gaussian"),
  delta = NULL
)

Arguments

Value

An object of class dp_estimate.

Examples

set.seed(2)
dp_variance(runif(300), 1.0, bounds = c(0, 1))$estimate

Description

Estimates the delta needed so that $P(L > \epsilon) \le \delta$ given a sample of simulated losses.

Usage

empirical_delta_from_losses(losses, epsilon)

Arguments

Value

Empirical tail probability.

Examples

empirical_delta_from_losses(simulate_gaussian_losses(1000, 5), 2.0)

Description

An (epsilon, 0)-DP mechanism satisfies (epsilon^2 / 2)-zCDP (Bun & Steinke, 2016).

Usage

epsilon_to_rdp(epsilon)

Arguments

Value

zCDP rho parameter.

Description

A synthetic census-style microdata set of 2000 individuals generated for use in examples and vignettes. Income is a linear function of education, age, hours worked, region, plus noise; it is not real personal data.

Usage

example_microdata

Format

A data frame with 2000 rows and 5 variables:

education

Years of education (integer, 0-20).

age

Age in years (integer, 18-80).

hours

Weekly working hours (numeric, 0-80).

region

Factor with levels North, South, East, West.

income

Annual income (numeric, non-negative).

Source

Simulated; see data-raw/generate_data.R.

Description

Samples a candidate from candidates with probability proportional to $\exp(\epsilon \, s(c) / (2 \Delta s))$, where $\Delta s$ is the sensitivity of the score function.

Usage

exponential_mechanism(candidates, scores, epsilon, score_sensitivity = 1)

Arguments

Value

One sampled candidate.

Examples

exponential_mechanism(1:10, -(1:10 - 5)^2, 1.0, 1)

Description

Releases f(x) plus Gaussian noise using the classic $\sigma = \Delta_2 \sqrt{2 \log(1.25/\delta)} / \epsilon$ calibration for (epsilon, delta)-DP.

Usage

gaussian_mechanism(f, x, epsilon, delta, l2_sensitivity)

Arguments

Value

The privatized value of f(x) (scalar or vector).

Examples

gaussian_mechanism(sum, c(1:100), 1.0, 1e-6, l2_sensitivity = 100)

Description

Computes the standard deviation used by the classic Gaussian mechanism.

Usage

gaussian_sigma(epsilon, delta, l2_sensitivity)

Arguments

Value

Scalar noise standard deviation.

Description

Releases f(x) plus Laplace noise calibrated to the L1 sensitivity, providing pure epsilon-DP.

Usage

laplace_mechanism(f, x, epsilon, l1_sensitivity)

Arguments

Value

The privatized value of f(x) (scalar or vector).

Examples

laplace_mechanism(mean, c(1:100), 1.0, l1_sensitivity = 100 / 99)

Description

The privacy loss of one Laplace release with scale $s$ is $L = |d|/s$ with $d \sim \mathrm{Laplace}(0, s)$, i.e. $L \sim \mathrm{Exp}(\epsilon)$ when $s = \Delta_1/\epsilon$. These helpers expose its tail probabilities and quantiles for PLRV-based accounting and simulation studies.

Usage

laplace_plr_tail(t, epsilon)

laplace_plr_quantile(p, epsilon)

Arguments

Value

Tail probabilities $P(L > t)$ (laplace_plr_tail) or quantiles at probabilities p (laplace_plr_quantile).

Examples

laplace_plr_tail(3, 1.0) # exp(-3)

Description

An S3 object tracking cumulative privacy loss across multiple DP releases under basic, advanced, or Renyi DP (RDP) composition.

Usage

new_privacy_budget(
  epsilon,
  delta = 1e-06,
  composition = c("basic", "advanced", "rdp")
)

Arguments

Value

An object of class "privacy_budget".

Examples

b <- new_privacy_budget(3.0, 1e-6)
b <- spend(b, 1.0, description = "DP mean")
b$epsilon_spent

Description

Print method for dp_confint objects

Usage

## S3 method for class 'dp_confint'
print(x, digits = 4, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for dp_estimate objects

Usage

## S3 method for class 'dp_estimate'
print(x, digits = 4, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for dp_glm objects

Usage

## S3 method for class 'dp_glm'
print(x, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for dp_htest objects

Usage

## S3 method for class 'dp_htest'
print(x, digits = 4, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for dp_lm objects

Usage

## S3 method for class 'dp_lm'
print(x, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for privacy_budget objects

Usage

## S3 method for class 'privacy_budget'
print(x, ...)

Arguments

Value

The object x, invisibly.

Description

Print method for summary.dp_lm objects

Usage

## S3 method for class 'summary.dp_lm'
print(x, digits = 4, ...)

Arguments

Value

The object x, invisibly.

Description

Composes a sequence of pure-DP releases via the zCDP/RDP accumulator and converts the result back to (epsilon, delta)-DP. Typically much tighter than basic composition for many small releases.

Usage

rdp_composition(epsilons, delta = 1e-06)

Arguments

Value

List with elements rho and epsilon.

Examples

rdp_composition(rep(0.1, 20), 1e-6)$epsilon
basic_composition(rep(0.1, 20))$epsilon

Description

Uses $\varepsilon = \rho + \sqrt{2 \rho \log(1/\delta)}$.

Usage

rdp_to_epsilon(rho, delta)

Arguments

Value

Equivalent epsilon.

Description

Draws n independent Laplace(0, scale) deviates using inverse-CDF sampling with base R's uniform generator.

Usage

rlaplace(n, location = 0, scale = 1)

Arguments

Value

Numeric vector of length n.

Examples

rlaplace(5, 0, 1)

Description

Generates a census-like dataset with correlated predictors used in examples and vignettes: income as a function of education, age, and hours worked.

Usage

simulate_data(n = 1000)

Arguments

Value

A data frame with columns education (years, 0-20), age (18-80), hours (weekly hours, 0-80), income (annual income, >= 0), and region (factor).

Examples

head(simulate_data(5))

Description

Draws the realized privacy loss $L = z^2/(2\sigma^2) + ...$ approximated by $L = |z|/\sigma + 1/(2\sigma^2)$ for two neighbouring datasets under the Gaussian mechanism, useful for empirical delta estimation.

Usage

simulate_gaussian_losses(n, sigma)

Arguments

Value

Numeric vector of simulated losses.

Examples

l <- simulate_gaussian_losses(1000, 5); mean(l)

Description

Records one DP release against the budget and updates the cumulative privacy loss under the configured composition rule.

Usage

spend(budget, epsilon, delta = 0, description = "")

Arguments

Value

The updated "privacy_budget" object (invisibly also sets remaining_epsilon).

See Also

new_privacy_budget

Description

Computes the L1/L2 sensitivities under bounded-DP (neighbouring datasets differ in one record, same size n) for a record $x_i \in [L, U]$.

Usage

stat_sensitivities(bounds, n)

Arguments

Value

A list with elements l1 and l2, each a named numeric vector of sensitivities for "mean", "sum", "count", "variance" and "ecdf".

Examples

sens <- stat_sensitivities(c(0, 500000), 1000)
sens$l1["mean"]

Description

Prints privatized coefficients with analytical privacy-aware standard errors and confidence intervals.

Usage

## S3 method for class 'dp_lm'
summary(object, level = 0.95, ...)

Arguments

Value

Invisibly, the list with coefficients table.

Description

Repeatedly simulates data, fits dp_lm, builds privacy-aware CIs with dp_confint, and reports empirical coverage and mean interval width against the true generating coefficients.

Usage

validate_coverage(
  formula,
  true_betas,
  sigma = 1,
  data_gen = NULL,
  n = 500,
  n_sims = 200,
  epsilon = 1,
  delta = 1e-06,
  y_bounds = c(-50, 50),
  confint_method = "analytical",
  level = 0.95
)

Arguments

Value

List with coverage_rate, mean_ci_width, target_coverage, n_sims.

Examples

set.seed(1)
validate_coverage(y ~ x, c(`(Intercept)` = 1, x = 2), sigma = 1,
                  n = 200, n_sims = 30, epsilon = 3, delta = 1e-6,
                  y_bounds = c(-15, 15))