Single Parameter Estimation — API Reference
Auto-generated from the source docstrings. For the problem formulation and a usage example, see the Single Parameter Estimation task page.
Types
dp_testing_platform.tasks.single_parameter_estimation.types
SingleParameterEstimationMetadata
dataclass
Metadata for the single-regression-parameter task.
The task estimates one headline coefficient of a linear regression — the coefficient an applied study reports a conclusion about — so the index of that coefficient is part of the problem specification.
Attributes:
| Name | Type | Description |
|---|---|---|
dim |
int
|
Dimension of the feature vectors (the full regression). |
n_samples |
int
|
Number of samples in the dataset. |
coefficient_of_interest_index |
int
|
Index of the coordinate of the regression coefficient vector that this task targets. Required: it defines the estimand. |
covariate_domain |
Domain | None
|
Domain constraint for covariates X. If None, unbounded. Mirrors linear_regression so lifted algorithms see the same domains. |
response_domain |
Domain | None
|
Domain constraint for response y. If None, unbounded. |
SingleParameterEstimationInput
dataclass
Input for the single-regression-parameter task.
Attributes:
| Name | Type | Description |
|---|---|---|
X |
Array2D
|
Feature matrix, shape (n_samples, dim). |
y |
Array1D
|
Response vector, shape (n_samples,). |
SingleParameterEstimationOutput
dataclass
Output for the single-regression-parameter task.
Attributes:
| Name | Type | Description |
|---|---|---|
coefficient |
float
|
The estimated coefficient of interest (a scalar beta_j). |
se |
float | None
|
DP standard error of the coefficient. None when the algorithm reports a point estimate only (no inferential output). |
p_value |
float | None
|
DP p-value for the coefficient, for inference algorithms. None when the algorithm reports a point estimate only. |
Algorithms
dp_testing_platform.tasks.single_parameter_estimation.algorithms.barrientos_significance
BarrientosSignificanceTest
Bases: BaseAlgorithm
Pure-eps-DP significance test for one regression coefficient.
This is a SIGNIFICANCE TEST, not a point estimator: it releases a
differentially private verdict about whether the coefficient of interest is
nonzero, not its magnitude. The released coefficient field carries only
the DP SIGN (+1 / -1) of the test statistic — no magnitude is released;
se is always None. The headline outputs are (sign, p_value).
Mechanics (subsample-and-aggregate of a scale-free statistic, so no clipping and no domain bounds are needed):
- Assign each record an i.i.d. uniform subset tag (
Mdisjoint subsets). - Per subset, compute the OLS t-statistic for the coefficient of interest
and truncate it to
[-a, a](giving a bounded scorez_l). - Form the sqrt(M)-rescaled mean
T_bar = M^{-1/2} * sum_l z_l(this matches the scale of the full-data t-statistic). - Release
t_1 = T_bar + Laplace(0, 2a / (sqrt(M) * eps)). - Obtain a two-tailed p-value from a Monte-Carlo null reference: draw
N(0, 1)per subset, truncate, sqrt(M)-sum, and ADD the same Laplace term (so the reference accounts for the DP noise); the p-value is the fraction of null draws whose magnitude exceeds|t_1|. The sign issign(t_1). p-value and sign are post-processing oft_1and public random draws, so they cost no additional privacy budget.
Privacy (pure eps-DP; delta is unused):
The paper proves eps-DP under the REPLACE-ONE relation with a balanced
random partition. This library standardizes on the ADD/REMOVE-ONE
relation, under which a balanced partition does NOT transfer (removing a
record changes n and re-randomizes the whole assignment, so up to all
M subsets change). This implementation instead assigns each record an
i.i.d. uniform subset tag, so the same 2a / sqrt(M_eff) sensitivity
holds under add/remove-one: each record sits in exactly one subset, and
removing (or adding) it changes only that subset's membership, moving its
truncated score z_l in [-a, a] by at most 2a and hence T_bar
(the sqrt(M)-rescaled score sum) by at most 2a / sqrt(M_eff). The tags
are consequently unbalanced; degenerate subsets (including empty ones)
score 0 within [-a, a], a privacy-safe constant. The Laplace scale is
sensitivity / eps = 2a / (sqrt(M_eff) * eps), giving eps-DP for
t_1; the p-value and sign are post-processing.
m_eff — and hence the released statistic's form and the Laplace scale —
is a deterministic function of PUBLIC metadata (n_samples, dim) alone:
an n-aware floor caps the effective M so each subset retains enough
residual degrees of freedom for its t-statistic to approximate N(0, 1)
(the basis of the Monte-Carlo null). Conditioning on public metadata, never a
private array's shape, keeps that form and scale public per instance, so the
pure-eps guarantee holds under add/remove-one at fixed declared metadata.
Input arrays are assumed consistent with the declared metadata.
The defaults are deliberately data-independent, fixed public choices. Do
NOT route M or a through a DP private-selection tuner: the test is
meant to run at fixed, public hyperparameters, and tuning it via a DP
selector would double-count the privacy budget (hence tunable: False).
Reference
Barrientos, Reiter, Machanavajjhala & Chen, "Differentially Private Significance Tests for Regression Coefficients", 2017. https://arxiv.org/abs/1705.09561
Hyperparameters
M: Number of disjoint subsets (subsample-and-aggregate). Default: 25. a: Truncation bound on each per-subset t-statistic. Default: 2.0. n_mc: Number of Monte-Carlo null draws for the p-value (public; not tunable). Default: 10000.
Lifted algorithms
Linear-regression algorithms presented as native single-parameter algorithms: each estimates the full coefficient vector, and the output is projected down to the single coefficient of interest.
dp_testing_platform.tasks.single_parameter_estimation.algorithms.lifted
Linear-regression algorithms lifted onto the single-parameter task.
Each class presents a linear_regression algorithm as a native
single_parameter_estimation algorithm. A single-coefficient estimand is
lifted to the full linear_regression task (same X, y, dim, domains); any
linear_regression algorithm therefore runs here, estimating the full coefficient
vector. The push direction projects the lifted full-beta output down to the
single coordinate of interest, so the child surfaces only the scalar the task is
about; the projection reads the index from the child metadata.
Both natively-linear_regression algorithms and algorithms already lifted
onto linear_regression (the M-estimation donors) are wrapped: wrapping an
already-lifted class gives a transparent depth-2 lift (its run performs its
own inner lift). lift_input is per-row (row i maps to row i), so the
inner algorithm's (eps, delta)-DP guarantee transfers verbatim.
Instance generators
dp_testing_platform.tasks.single_parameter_estimation.instance_generators.gaussian_instance_generator
GaussianCovariatesAndNoise
Bases: InstanceGenerator
Gaussian instance generator for the single-regression-parameter task.
Generates y = X @ beta_true + noise with X ~ N(0, I) and a random
unit beta_true, designating one coordinate as the coefficient of
interest. Used for tests and a runnable demo; corpus converters are the
real conclusion-replication instances (a follow-on).
Statistics
dp_testing_platform.tasks.single_parameter_estimation.statistics
Pure statistical primitives for single-coefficient conclusion replication.
These functions are the single source of truth for the conclusion-replication statistic family: given a DP mechanism's per-seed coefficient estimates and a non-private reference, they quantify whether the mechanism reproduces the qualitative conclusion (sign and significance) an analyst would draw about the target coefficient.
Everything here is a pure function over plain numbers (a sequence of per-seed scalars where a spread is needed) — no fitting, no I/O, no task or instance objects. The regression fit that produces the estimates and the reference lives elsewhere; this module only combines the resulting scalars.
SE-source contract: the se fed to :func:t_dp is the published sampling
standard error of the coefficient, taken from the study's published_fit — it
is NEVER recomputed by the library. The coefficient is canonical (recomputing it
cross-checks against the reference fit), but the standard error is not:
classical, robust (heteroskedasticity-consistent), and clustered SEs differ, so
only the paper's own reported SE reproduces the analyst's significance verdict.
These functions do not fit or recompute anything; callers are responsible for
sourcing se from published_fit.
sample_variance
Unbiased (ddof=1) variance of the per-seed estimates.
Returns 0.0 for fewer than two estimates (no spread is estimable from a
single point), matching the v term used by :func:t_dp.
decompose
Decompose per-seed estimates against a reference into (m, b, v).
The three scalars feed :func:t_dp:
m = sign(reference) * mean— the mean estimate oriented so the reference points in the positive direction (mis large and positive when the mechanism agrees with the reference in sign and magnitude).b = mean - reference— the estimation bias (signed shift from the reference).v— the across-seed sampling variance (:func:sample_variance).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
estimates
|
Sequence[float]
|
Per-seed coefficient estimates from the DP mechanism. |
required |
reference
|
float
|
Non-private reference coefficient (e.g. the OLS fit). |
required |
Returns:
| Type | Description |
|---|---|
tuple[float, float, float]
|
The tuple |
t_dp
t-statistic of the DP release under combined sampling + DP-error uncertainty.
Computes max(0, m / sqrt(se**2 + v + b**2)) — equivalently
|beta_DP| / sqrt(se**2 + rmse**2) with rmse**2 = v + b**2: the honest
t-statistic of the DP release under combined published-sampling + DP-error
uncertainty. The bias b enters only the denominator (in quadrature); the
oriented magnitude m enters the numerator directly. The max(0, .) sign
gate sends a flipped oriented mean (m <= 0) to 0. Bias contributes to
total uncertainty in the denominator and is deliberately not subtracted
from the released estimate in the numerator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m
|
float
|
Oriented mean magnitude ( |
required |
b
|
float
|
Estimation bias ( |
required |
v
|
float
|
Across-seed sampling variance (non-negative). |
required |
se
|
float
|
Published sampling standard error of the coefficient — the sampling
uncertainty of the analyst's ORIGINAL (non-private) estimate. It is
supplied externally, NOT derived from the per-seed estimates (those
give |
required |
Returns:
| Type | Description |
|---|---|
float
|
The statistic, |
float
|
spread and no bias). Propagates NaN if any argument is NaN. |
relative_bias
Bias relative to the reference magnitude, oriented by the reference sign.
Computes sign(reference) * b / |reference|: positive when the mechanism
overshoots the reference in its own direction, negative when it undershoots.
Metrics
dp_testing_platform.tasks.single_parameter_estimation.metrics
Metric registry for the single_parameter_estimation task.
These conclusion-replication metrics ask whether a DP fit reproduces the
qualitative conclusion an analyst would draw about the single target coefficient
(its sign, its verdict) rather than its numerical accuracy. They read the
released scalar output.coefficient and obtain the OLS reference at the
coefficient of interest by running the non-private OLS baseline on the
instance's own (X, y), never a re-implemented least-squares solve. They therefore
need the metadata (for the index), and the caller must supply it at evaluation
time (e.g. an instance generator binding it via create_metric).
sign_agreement
sign_agreement(output: SingleParameterEstimationOutput, evaluation_metadata: SingleParameterEstimationMetadata, evaluation_input: SingleParameterEstimationInput) -> float
Whether the released coefficient and the OLS fit agree on its sign.
Returns 1.0 if the released estimate and the instance's OLS coefficient of
interest share a sign, 0.0 otherwise. The OLS reference comes from the OLS
baseline algorithm, projected to the coefficient of interest.
verdict_agreement
verdict_agreement(output: SingleParameterEstimationOutput, evaluation_metadata: SingleParameterEstimationMetadata, evaluation_input: SingleParameterEstimationInput) -> float
Whether the released verdict matches the OLS verdict on the coefficient.
For an inference algorithm that releases a p-value, returns 1.0 iff the
released estimate and the OLS baseline agree on BOTH the sign of the
coefficient AND the significance verdict at the 5% level — i.e. the released
output.p_value < 0.05 matches whether the classical OLS t-test rejects at
0.05. Returns 0.0 when either agreement fails. Returns NaN for a
point-estimate algorithm (output.p_value is None), so it is additive over
the algorithm set: only p-value-releasing algorithms are scored.
The baseline verdict uses the classical (homoskedastic) OLS standard error; the published-standard-error channel is handled scorer-side.