opendp.extras.numpy.canonical module

This module requires extra installs: pip install 'opendp[numpy]'

For convenience, all the members of this module are also available from opendp.prelude. We suggest importing under the conventional name dp:

>>> import opendp.prelude as dp

The members of this module will then be accessible at dp.numpy.canonical.

class opendp.extras.numpy.canonical.BinomialCND(estimate, d_in, d_out, size)

Utilities to conduct statistical inference on the output of the canonical noise mechanism on binomially-distributed data.

Use opendp.measurements.make_canonical_noise() to instantiate the canonical noise mechanism.

The mechanism outputs a sample from X + N, where X ~ Binomial(n=size, p=theta), N ~ CND(0, d_in, d_out).

A counting query is a realization of X ~ Binomial(n=size, p=theta) when, for each row in data with size rows, a counter is incremented with probability theta.

Parameters:

• estimate (float) – the differentially private outcome of the canonical noise mechanism on binomial data

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) total number of records in the sensitive dataset

confidence_interval(alpha, side=None)

Compute a confidence interval for self.estimate.

• side=None: return the two bounds of a confidence interval

• side=”lower”: return a one-sided confidence interval lower bound

• side=”upper”: return a one-sided confidence interval upper bound

Parameters:

• alpha (float) – statistical significance level

• side (Literal['lower', 'upper'] | None) – configure interval type

Returns:

confidence interval bound(s)

Return type:

float | tuple[float, float]

p_value(theta, tail=None)

Computes a p-value based on self.estimate.

• tail=None: null hypothesis states that true proportion is theta

• tail=”left”: null hypothesis states that true proportion is no less than theta

• tail=”right”: null hypothesis states that true proportion is no greater than theta

Parameters:

• theta (float) – success rate

• tail (Literal['left', 'right'] | None) – configure the null hypothesis

Returns:

the probability of observing self.estimate, given the null hypothesis

Return type:

float

opendp.extras.numpy.canonical.one_sided_confidence_interval(Z, d_in, d_out, size, alpha, side)

Compute a one-sided confidence interval for self.estimate.

• tail=”lower”: return a one-sided confidence interval lower bound

• tail=”upper”: return a one-sided confidence interval upper bound

Parameters:

• Z (float) – realization of cnd random variable

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) total number of records in the sensitive dataset

• alpha (float) – statistical significance level

• side (Literal['lower', 'upper']) – configure interval type

Returns:

lower or upper confidence interval bound

Return type:

float

opendp.extras.numpy.canonical.one_sided_pvalue(Z, d_in, d_out, size, theta, tail)

Computes a p-value for a hypothesis test on the probability of success.

• tail=”left”: null hypothesis states that true proportion is no less than theta

• tail=”right”: null hypothesis states that true proportion is no greater than theta

Parameters:

• Z (float) – realization of cnd random variable

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) number of trials

• theta (float) – true probability of binomial distribution

• tail (Literal['left', 'right']) – either “left” or “right”

Returns:

Probability of observing Z when the true success rate is theta

Return type:

float

opendp.extras.numpy.canonical.one_sided_uniformly_most_powerful_tests(d_in, d_out, size, theta, alpha, tail)

Compute one-sided UMP tests for each choice of i in [size].

• When tail=”left”, then the null hypothesis is: the estimate is at most i

• When tail=”right”, then the null hypothesis is: the estimate is at least i

Parameters:

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) number of trials

• theta (float) – true probability of binomial distribution

• alpha (float) – statistical significance level

• tail (Literal['left', 'right']) – either “left” or “right”

Returns:

The probability of accepting the null hypothesis for each choice of i in [size].

Return type:

list[float]

opendp.extras.numpy.canonical.two_sided_confidence_interval(Z, d_in, d_out, size, alpha)

Compute a two-sided confidence interval centered on Z.

Parameters:

• Z (float) – realization of cnd random variable

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) total number of records in the sensitive dataset

• alpha (float) – statistical significance level

Returns:

confidence interval bounds

Return type:

tuple[float, float]

opendp.extras.numpy.canonical.two_sided_pvalue(Z, d_in, d_out, size, theta)

Computes a p-value for a hypothesis test on the probability of success.

Parameters:

• Z (float) – realization of cnd random variable

• d_in (float) – sensitivity of the input to the mechanism

• d_out (tuple[float, float]) – privacy parameters (ε, δ)

• size (int) – (approximate) number of trials

• theta (float) – true probability of binomial distribution

Returns:

Probability of observing Z when the true success rate is theta

Return type:

float