Package {ldpdist}

Local Differential Privacy Tools for Distributional Inference

Description

Estimation of cumulative distribution functions and quantiles under local differential privacy, with binary and categorical randomization mechanisms and methods for statistical inference.

Details

For distribution functions, ldp_mechanism() and ldp_design() specify the randomization mechanism and threshold design. ldp_randomize() generates privatized reports, which are passed to ldp_estimate_cdf() or ldp_estimate_category_cdf().

The quantile functions ldp_estimate_quantile(), ldp_estimate_quantiles(), and ldp_estimate_quantile_cs() are simulation interfaces: they receive a numeric data vector and carry out the sequential local randomization internally. They do not implement a distributed client-server service.

Randomization uses a secure byte source by default. On Windows this requires the suggested openssl package. Seeded pseudo-random generation is available for reproducible simulations through rng = "pseudo".

References

Liu, Y., Hu, Q., Ding, L. and Kong, L. (2023). Online Local Differential Private Quantile Inference via Self-normalization. Proceedings of Machine Learning Research, 202, 21698–21714. https://proceedings.mlr.press/v202/liu23q.html

Liu, Y., Hu, Q. and Kong, L. (2024). Tuning-free Estimation and Inference of Cumulative Distribution Function under Local Differential Privacy. Proceedings of Machine Learning Research, 235, 31147–31164. https://proceedings.mlr.press/v235/liu24z.html

Aggregate CDF estimates from heterogeneous surveys

Description

Aggregates independent survey-level CDF estimates. The theory-motivated rule uses weights proportional to n_s^(2/3) g_s(x0)^(2/3), where n_s is the survey size and g_s(x0) is the threshold design density at the target point.

Usage

ldp_aggregate_surveys(
  fits,
  x0,
  weights = c("equal", "theory", "sample_size", "custom"),
  design_density = NULL,
  custom_weights = NULL
)

Arguments

Value

An object of class ldp_survey_aggregate.

Examples

set.seed(1)
mech <- ldp_mechanism("binary_rr", epsilon = 2)
d <- ldp_design("cdf", grid = seq(0, 1, length.out = 11))
r1 <- ldp_randomize(stats::runif(100), mech, d, rng = "pseudo", seed = 1)
r2 <- ldp_randomize(stats::runif(100), mech, d, rng = "pseudo", seed = 2)
f1 <- ldp_estimate_cdf(r1)
f2 <- ldp_estimate_cdf(r2)
ldp_aggregate_surveys(list(f1, f2), x0 = 0.5)

Estimate category probabilities over a value range

Description

Computes category-specific probability mass over (lower, upper] from fitted category sub-CDFs. With conditional = TRUE, the output estimates category probabilities conditional on the value falling in the requested range. An error is returned when the fitted range mass is zero.

Usage

ldp_category_range_probability(object, lower = NULL, upper = NULL, conditional = TRUE)

Arguments

Value

A data frame with category probabilities. Attributes include range_total and conditional.

Examples

set.seed(1)
x <- stats::runif(100)
y <- sample(c("A", "B"), 100, replace = TRUE)
design <- ldp_design("category_cdf", grid = seq(0, 1, length.out = 11),
                     categories = c("A", "B"), y = y)
mech <- ldp_mechanism("uldp_censor", epsilon = 2, domain_size = 2)
reports <- ldp_randomize(x, mech, design, rng = "pseudo", seed = 1)
fit <- ldp_estimate_category_cdf(reports)
ldp_category_range_probability(fit, lower = 0.25, upper = 0.75)

Finite-grid variance for LDP CDF estimates

Description

Computes the finite-grid pointwise variance induced by binary randomized response and the public threshold design. For isotonic CDF fits, the formula uses the affine randomized-response inverse and aggregates either observed or planned threshold sample sizes over active PAVA pools. Planned allocation is unavailable when report thresholds override the design. For divide-and-conquer fits, it returns the block-studentized variance used by confint().

Usage

ldp_cdf_variance(
  object,
  newdata = NULL,
  source = c("observed", "planned"),
  as_matrix = FALSE
)

Arguments

Value

A named numeric vector, or a covariance matrix when as_matrix = TRUE.

Examples

x <- stats::runif(200)
mech <- ldp_mechanism("binary_rr", epsilon = 2)
design <- ldp_design("cdf", grid = seq(0, 1, length.out = 11))
reports <- ldp_randomize(x, mech, design, rng = "pseudo", seed = 3)
fit <- ldp_estimate_cdf(reports)
ldp_cdf_variance(fit, newdata = c(0.25, 0.75))

Self-normalized confidence region for many quantiles

Description

Builds a self-normalized ellipsoidal confidence region from a many-quantile fit. The returned object contains the center, shape matrix, critical value, and helper functions for evaluating the statistic and checking membership.

Usage

ldp_confidence_region(
  object,
  level = 0.95,
  critical = NULL,
  n_sim = 5000L,
  n_grid = 400L,
  seed = 1L
)

Arguments

Value

An object of class ldp_confidence_region.

Examples

set.seed(1)
x <- stats::rnorm(300)
fit <- ldp_estimate_quantiles(x, c(0.25, 0.5, 0.75),
                              epsilon = 2, bounds = c(-4, 4),
                              rng = "pseudo", seed = 2)
region <- ldp_confidence_region(fit, level = 0.8, n_sim = 200, n_grid = 50)
region$contains(coef(fit))

Finite-block critical values for D&C CDF inference

Description

Returns finite-block critical values used by the divide-and-conquer CDF studentized interval. Values are interpolated on the log block-count scale from the 2026 D&C CDF supplementary implementation.

Usage

ldp_dc_critical(blocks, level = 0.95)

Arguments

Value

A numeric vector of critical values.

Examples

ldp_dc_critical(c(8, 32, 128))

Create an LDP data-collection design

Description

Creates a design object describing the public queries used during local data collection. The design is separate from the privacy mechanism so that the same estimator can be paired with different randomizers or threshold schemes.

Usage

ldp_design(
  task = c("cdf", "quantile", "quantiles", "category_cdf"),
  grid = NULL,
  tau = NULL,
  bounds = NULL,
  categories = NULL,
  assignment = c("random", "cyclic"),
  weights = NULL,
  ...
)

Arguments

Value

An object of class ldp_design.

Examples

design <- ldp_design("cdf", grid = seq(0, 1, length.out = 11))
design

Estimate category-specific CDFs from censored ULDP reports

Description

Recovers category-specific sub-CDFs from asymmetrically censored randomized response reports. The default implementation uses componentwise marginal isotonic regression. The optional projected procedure uses Dykstra projection onto the shared feasible set and is not presented as an exact ICM likelihood maximizer.

Usage

ldp_estimate_category_cdf(
  reports,
  method = c("marginal", "projected", "global_icm"),
  cap_total = TRUE,
  max_iter = 100L,
  tol = 1e-07
)
## S3 method for class 'ldp_category_cdf_fit'
predict(object, newdata = NULL, ...)

Arguments

Value

An object of class ldp_category_cdf_fit; predict() returns a data frame containing the total CDF and one sub-CDF column per category. Prediction is restricted to the fitted threshold range. Projected fits also store convergence diagnostics in diagnostics.

Examples

set.seed(1)
x <- stats::runif(100)
y <- sample(c("A", "B"), 100, replace = TRUE)
design <- ldp_design("category_cdf", grid = seq(0, 1, length.out = 11),
                     categories = c("A", "B"), y = y)
mech <- ldp_mechanism("uldp_censor", epsilon = 2, domain_size = 2)
reports <- ldp_randomize(x, mech, design, rng = "pseudo", seed = 1)
fit <- ldp_estimate_category_cdf(reports)
predict(fit, c(0.25, 0.5))
projected <- ldp_estimate_category_cdf(reports, method = "projected")

Estimate a CDF from local threshold reports

Description

Fits the monotone current-status CDF estimator from binary randomized response threshold reports. The implementation applies weighted isotonic regression to the privatized threshold means, then maps the fitted curve back to the original CDF scale and clips it to [0, 1]. The divide-and-conquer method fits the same estimator independently over blocks and averages the fitted values. vcov(), ldp_cdf_variance(), and confint() use finite-grid covariance formulas that account for randomized-response inflation, active PAVA pools, and public threshold allocation. The normal limits use the realized active pools as fixed and do not adjust for active-set selection or simultaneous coverage.

Usage

ldp_estimate_cdf(reports, grid = NULL, method = c("isotonic", "dc"), blocks = NULL)
## S3 method for class 'ldp_cdf_fit'
confint(
  object,
  parm,
  level = 0.95,
  critical = c("normal", "dc_finite_block"),
  newdata = NULL,
  variance = c("observed", "planned"),
  ...
)
## S3 method for class 'ldp_cdf_fit'
predict(object, newdata = NULL, ...)
## S3 method for class 'ldp_cdf_fit'
summary(object, ...)
## S3 method for class 'ldp_cdf_fit'
vcov(object, ...)

Arguments

Value

An object of class ldp_cdf_fit; predict() returns a data frame.

Examples

set.seed(1)
x <- stats::runif(200)
mech <- ldp_mechanism("binary_rr", epsilon = 2)
design <- ldp_design("cdf", grid = seq(0, 1, length.out = 21))
reports <- ldp_randomize(x, mech, design, rng = "pseudo", seed = 2)
fit <- ldp_estimate_cdf(reports)
predict(fit, c(0.25, 0.5, 0.75))

Estimate one quantile with online binary LDP queries

Description

Runs the online binary-response quantile recursion and returns the Polyak-Ruppert averaged estimate. The fit stores the self-normalizer needed for inference without estimating the density at the target quantile. The stored normalizer is not a covariance estimate, so vcov() returns an informative error.

Usage

ldp_estimate_quantile(
  x,
  tau = 0.5,
  mechanism = ldp_mechanism("binary_rr", epsilon),
  epsilon,
  init = 0,
  step_scale = 1,
  step_power = 0.6,
  rng = c("secure", "pseudo"),
  seed = NULL,
  keep_path = FALSE
)
## S3 method for class 'ldp_quantile_fit'
coef(object, ...)
## S3 method for class 'ldp_quantile_fit'
vcov(object, ...)
## S3 method for class 'ldp_quantile_fit'
confint(
  object,
  parm,
  level = 0.95,
  critical = "self_normalized",
  n_sim = 20000L,
  n_grid = 1000L,
  seed = 1L,
  ...
)
## S3 method for class 'ldp_quantile_fit'
summary(object, ...)

Arguments

Details

This function simulates the sequential protocol in one R process. It receives the observation vector and performs local randomization internally.

The self-normalized inference assumes independent observations and local randomization, a unique target quantile with positive continuous density, and the regularity and stability conditions of the online quantile procedure. For a continuous CDF at the target, the quantile solves F(q)=\tau. With discrete data the generalized quantile need not solve this equation; computing a fit does not establish the applicability of the inferential limit.

Value

An object of class ldp_quantile_fit.

Examples

set.seed(1)
x <- stats::rnorm(500)
fit <- ldp_estimate_quantile(x, tau = 0.5, epsilon = 2,
                             init = 0, rng = "pseudo", seed = 10)
coef(fit)
confint(fit)

Asymptotic confidence sequence for one LDP quantile

Description

Runs a dynamic-chain parallel SGD procedure for one LDP quantile and combines the chain-wise variance estimator with a Gaussian confidence-sequence boundary.

Usage

ldp_estimate_quantile_cs(
  x,
  tau = 0.5,
  mechanism = ldp_mechanism("binary_rr", epsilon),
  epsilon,
  init = 0,
  initial_chains = 5L,
  growth = "log",
  log_base = 10,
  step_scale = 1,
  step_power = 0.6,
  alpha = 0.05,
  boundary = c("stitched", "mixture"),
  rho = 0.01,
  rng = c("secure", "pseudo"),
  seed = NULL,
  checkpoints = NULL
)
## S3 method for class 'ldp_quantile_cs'
confint(object, parm, level = 1 - object$alpha, ...)
## S3 method for class 'ldp_quantile_cs'
summary(object, ...)

Arguments

Details

This function simulates the sequential protocol in one R process. It receives the observation vector and performs local randomization internally.

Inference assumes independent observations and local randomization, a unique target quantile with positive continuous density, a bounded density derivative, and the supported step-size and chain-growth schedules. The guarantee is asymptotic, not finite-sample time-uniform coverage.

For chain counts n_j, iterate sums S_j, and the overall averaged estimate \hat q_t, the scale is the weighted variance of (S_j-n_j\hat q_t)/\sqrt{n_j}, with weights n_j/t. Centering before scaling makes the result invariant to a common translation of the data and initialization, including while a new chain catches up.

Value

An object of class ldp_quantile_cs.

Examples

set.seed(1)
x <- stats::rnorm(500)
cs <- ldp_estimate_quantile_cs(x, tau = 0.5, epsilon = 2,
                               rng = "pseudo", seed = 13)
confint(cs)

Jointly estimate multiple quantiles under categorical LDP

Description

Reduces the many-quantile problem to KRR interval-label estimation. At each step the current quantile vector partitions the real line, the user's interval label is privatized by KRR, and the server uses the unbiased one-hot decoder in a projected Robbins-Monro update. The projection enforces noncrossing at every iteration. This function is a simulation wrapper that receives the private numeric vector and performs the local randomization internally. Joint inference is provided by ldp_confidence_region(); confint() returns an informative error rather than unsupported marginal intervals.

Usage

ldp_estimate_quantiles(
  x,
  tau,
  mechanism = ldp_mechanism("krr", epsilon, domain_size = length(tau) + 1L),
  epsilon,
  bounds,
  init = NULL,
  step_scale = NULL,
  step_power = 0.6,
  rng = c("secure", "pseudo"),
  seed = NULL,
  keep_path = FALSE
)
## S3 method for class 'ldp_quantiles_fit'
coef(object, ...)
## S3 method for class 'ldp_quantiles_fit'
confint(object, parm, level = 0.95, simultaneous = TRUE, ...)
## S3 method for class 'ldp_quantiles_fit'
summary(object, ...)

Arguments

Details

Joint self-normalized inference assumes independent observations and local randomization, unique target quantiles with positive continuous densities, and the regularity and stability conditions of the projected recursion. The true quantile vector must be strictly ordered and lie inside the supplied bounds. Numerical positive definiteness of the observed self-normalizer is also required to construct the region.

Value

An object of class ldp_quantiles_fit.

Examples

set.seed(1)
x <- stats::rnorm(300)
mech <- ldp_mechanism("krr", epsilon = 2, domain_size = 4)
fit <- ldp_estimate_quantiles(x, tau = c(0.25, 0.5, 0.75),
                              mechanism = mech, bounds = c(-4, 4),
                              rng = "pseudo", seed = 2)
coef(fit)

Gaussian confidence-sequence boundaries

Description

Computes Gaussian boundaries used by the asymptotic confidence-sequence construction.

Usage

ldp_gaussian_cs_boundary(
  time,
  alpha = 0.05,
  type = c("stitched", "mixture"),
  m = 1,
  rho = 0.01
)

Arguments

Value

A numeric vector of boundary widths on the unit-variance mean scale.

Examples

ldp_gaussian_cs_boundary(c(100, 1000), alpha = 0.05)

Create a local privacy mechanism object

Description

Constructs an ldp_mechanism object with validated privacy and domain parameters.

Usage

ldp_mechanism(
  type = c("binary_rr", "krr", "oue", "olh", "hadamard", "uldp_censor"),
  epsilon,
  domain_size = NULL,
  ...
)

Arguments

Value

An object of class ldp_mechanism.

Examples

mech <- ldp_mechanism("binary_rr", epsilon = 1)
mech

Median efficiency diagnostic under binary randomized response

Description

Computes the median asymptotic variance lower bound for binary randomized-response sequential LDP mechanisms, 1 / (4 * r^2 * n * f(m)^2), where r = tanh(epsilon / 2) and f(m) is the density at the median. The diagnostic reports the privacy variance inflation relative to the non-private median bound and, when an estimator variance is supplied, the ratio of the lower bound to that variance.

Usage

ldp_median_efficiency(
  object = NULL,
  density_at_median,
  epsilon = NULL,
  n = NULL,
  estimator_variance = NULL
)

Arguments

Value

An object of class ldp_median_efficiency.

Examples

ldp_median_efficiency(density_at_median = stats::dnorm(0),
                      epsilon = 2, n = 1000)
x <- stats::rnorm(500)
fit <- ldp_estimate_quantile(x, tau = 0.5, epsilon = 2,
                             rng = "pseudo", seed = 1)
ldp_median_efficiency(fit, density_at_median = stats::dnorm(0))

Multivariate self-normalized Brownian critical values

Description

Approximates the critical value of the multivariate self-normalized Brownian statistic used by the many-quantile confidence region.

Usage

ldp_msn_critical(k, level = 0.95, n_sim = 5000L, n_grid = 400L, seed = 1L)

Arguments

Value

A numeric critical value.

Examples

ldp_msn_critical(2, level = 0.8, n_sim = 200, n_grid = 50)

Weighted pool-adjacent-violators algorithm

Description

Computes the weighted isotonic regression fit using the pool-adjacent-violators algorithm. This is an internal workhorse exposed because many LDP distributional estimators require monotone projections.

Usage

ldp_pava(y, weights = NULL, decreasing = FALSE, backend = c("auto", "C", "R"))

Arguments

Value

A numeric vector of fitted monotone values.

Examples

ldp_pava(c(0.1, 0.4, 0.3, 0.8))
ldp_pava(c(0.1, 0.4, 0.3, 0.8), backend = "R")

Check analytic likelihood-ratio bounds for LDP mechanisms

Description

Reports the analytic likelihood-ratio bound associated with a mechanism. For ordinary LDP mechanisms this checks the symmetric epsilon-LDP bound. For the censored ULDP mechanism, the report explicitly states that the guarantee is asymmetric and applies to the protected censored output rather than to all original-value pairs.

Usage

ldp_privacy_check(mechanism)

Arguments

Value

An object of class ldp_privacy_check.

Examples

ldp_privacy_check(ldp_mechanism("binary_rr", epsilon = 1))
ldp_privacy_check(ldp_mechanism("uldp_censor", epsilon = 1, domain_size = 2))

Locally randomize private observations

Description

Applies a local randomizer to private data. The current implementation supports threshold CDF reports with binary randomized response and censored category-CDF reports with the ULDP censoring mechanism.

Usage

ldp_randomize(
  x,
  mechanism,
  design,
  rng = c("secure", "pseudo"),
  seed = NULL,
  threshold = NULL
)

Arguments

Value

An object of class ldp_reports.

Examples

x <- c(0.2, 0.6, 0.9)
mech <- ldp_mechanism("binary_rr", epsilon = 2)
design <- ldp_design("cdf", grid = seq(0, 1, by = 0.25), assignment = "cyclic")
ldp_randomize(x, mech, design, rng = "pseudo", seed = 1)

Categorical local randomizers and unbiased decoders

Description

Applies categorical LDP mechanisms and decodes the resulting reports into unbiased one-hot estimates. Implemented mechanisms are direct randomized response ("krr"), optimized unary encoding ("oue"), optimized local hashing ("olh"), and Hadamard response ("hadamard").

Usage

ldp_randomize_category(category, mechanism, rng = c("secure", "pseudo"), seed = NULL)
ldp_decode_category(reports, mechanism = reports$mechanism)

Arguments

Value

ldp_randomize_category() returns an ldp_category_reports object. ldp_decode_category() returns a numeric matrix with one row per report and one column per category.

Examples

cat <- c(0, 1, 2, 1)
mech <- ldp_mechanism("krr", epsilon = 2, domain_size = 3)
reports <- ldp_randomize_category(cat, mech, rng = "pseudo", seed = 1)
ldp_decode_category(reports)

Generate uniform random numbers for LDP workflows

Description

Generates uniforms using either a cryptographically secure byte source or R's pseudo-random generator. Secure generation uses openssl when available and otherwise ‘/dev/urandom’ on Unix-like systems.

Usage

ldp_rng_uniform(n, rng = c("secure", "pseudo"), seed = NULL)

Arguments

Value

A numeric vector in [0, 1).

Examples

ldp_rng_uniform(3, rng = "pseudo", seed = 1)

Simulate a scalar self-normalized Brownian critical value

Description

Approximates the quantile of the scalar self-normalized Brownian statistic used by the online quantile confidence interval.

Usage

ldp_sn_critical(level = 0.95, n_sim = 20000L, n_grid = 1000L, seed = 1L)

Arguments

Value

A numeric critical value.

Examples

ldp_sn_critical(level = 0.8, n_sim = 200, n_grid = 50)

List registered mechanisms, tasks, and estimators

Description

Returns the mechanisms, task families, estimators, and public functions available in ldpdist.

Usage

ldp_supported_methods()

Value

A named list of character vectors.

Examples

ldp_supported_methods()

Plot ldpdist fitted objects

Description

Base graphics plotting methods for CDF fits, category CDF fits, and quantile confidence sequences.

Usage

## S3 method for class 'ldp_cdf_fit'
plot(x, ..., conf.int = FALSE, level = 0.95,
  xlab = "x", ylab = "CDF", main = "LDP CDF estimate")
## S3 method for class 'ldp_category_cdf_fit'
plot(x, ..., xlab = "x", ylab = "Sub-CDF",
  main = "LDP category CDF estimates")
## S3 method for class 'ldp_quantile_cs'
plot(x, ..., xlab = "Time", ylab = "Quantile",
  main = "LDP quantile confidence sequence")

Arguments

Value

The input object, invisibly.