opendp.accuracy module

The accuracy module provides functions for converting between accuracy and scale parameters. For more context, see accuracy in the User Guide.

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

>>> import opendp.prelude as dp

opendp.accuracy.accuracy_to_discrete_gaussian_scale(accuracy, alpha, T=None)

Convert a desired accuracy (tolerance) into a discrete gaussian noise scale at a statistical significance level alpha.

accuracy_to_discrete_gaussian_scale in Rust documentation.

Proof Definition:

(Proof Document)

Parameters:

• accuracy – Desired accuracy. A tolerance for how far values may diverge from the input to the mechanism.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of accuracy and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.accuracy_to_discrete_laplacian_scale(accuracy, alpha, T=None)

Convert a desired accuracy (tolerance) into a discrete Laplacian noise scale at a statistical significance level alpha.

accuracy_to_discrete_laplacian_scale in Rust documentation.

Proof Definition:

(Proof Document)

Parameters:

• accuracy – Desired accuracy. A tolerance for how far values may diverge from the input to the mechanism.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of accuracy and alpha

Returns:

Discrete laplacian noise scale that meets the accuracy requirement at a given level-alpha.

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.accuracy_to_gaussian_scale(accuracy, alpha, T=None)

Convert a desired accuracy (tolerance) into a gaussian noise scale at a statistical significance level alpha.

accuracy_to_gaussian_scale in Rust documentation.

Parameters:

• accuracy – Desired accuracy. A tolerance for how far values may diverge from the input to the mechanism.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of accuracy and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.accuracy_to_laplacian_scale(accuracy, alpha, T=None)

Convert a desired accuracy (tolerance) into a Laplacian noise scale at a statistical significance level alpha.

accuracy_to_laplacian_scale in Rust documentation.

Parameters:

• accuracy – Desired accuracy. A tolerance for how far values may diverge from the input to the mechanism.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of accuracy and alpha

Returns:

Laplacian noise scale that meets the accuracy requirement at a given level-alpha.

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.discrete_gaussian_scale_to_accuracy(scale, alpha, T=None)

Convert a discrete gaussian scale into an accuracy estimate (tolerance) at a statistical significance level alpha.

discrete_gaussian_scale_to_accuracy in Rust documentation.

Proof Definition:

(Proof Document)

Parameters:

• scale – Gaussian noise scale.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of scale and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.discrete_laplacian_scale_to_accuracy(scale, alpha, T=None)

Convert a discrete Laplacian scale into an accuracy estimate (tolerance) at a statistical significance level alpha.

\(\alpha = P[Y \ge accuracy]\), where \(Y = | X - z |\), and \(X \sim \mathcal{L}_{Z}(0, scale)\). That is, \(X\) is a discrete Laplace random variable and \(Y\) is the distribution of the errors.

This function returns a float accuracy. You can take the floor without affecting the coverage probability.

discrete_laplacian_scale_to_accuracy in Rust documentation.

Proof Definition:

(Proof Document)

Parameters:

• scale – Discrete Laplacian noise scale.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of scale and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.gaussian_scale_to_accuracy(scale, alpha, T=None)

Convert a gaussian scale into an accuracy estimate (tolerance) at a statistical significance level alpha.

gaussian_scale_to_accuracy in Rust documentation.

Parameters:

• scale – Gaussian noise scale.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of scale and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.laplacian_scale_to_accuracy(scale, alpha, T=None)

Convert a Laplacian scale into an accuracy estimate (tolerance) at a statistical significance level alpha.

laplacian_scale_to_accuracy in Rust documentation.

Parameters:

• scale – Laplacian noise scale.

• alpha – Statistical significance, level-alpha, or (1. - alpha)100% confidence. Must be within (0, 1].

• T (Type Argument) – Data type of scale and alpha

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

opendp.accuracy.summarize_polars_measurement(measurement, alpha=None)

Summarize the statistics to be released from a measurement that returns a OnceFrame.

If a threshold is configured for censoring small/sensitive partitions, a threshold column will be included, containing the cutoff for the respective count query being thresholded.

Required features: contrib

Parameters:

• measurement (Measurement) – computation from which you want to read noise scale parameters from

• alpha – optional statistical significance to use to compute accuracy estimates

Raises:

• TypeError – if an argument’s type differs from the expected type

• UnknownTypeException – if a type argument fails to parse

• OpenDPException – packaged error from the core OpenDP library

Example:

First, create a measurement with the Polars API: >>> import opendp.prelude as dp >>> import polars as pl >>> dp.enable_features(“contrib”) … >>> lf = pl.LazyFrame(schema={“A”: pl.Int32, “B”: pl.String}) >>> lf_domain = dp.lazyframe_domain([ … dp.series_domain(“A”, dp.atom_domain(T=”i32”)), … dp.series_domain(“B”, dp.atom_domain(T=str)) … ]) >>> lf_domain = dp.with_margin(lf_domain, by=[], max_partition_length=1000) >>> meas = dp.m.make_private_lazyframe( … lf_domain, … dp.symmetric_distance(), … dp.max_divergence(), … lf.select([pl.len().dp.noise(), pl.col(“A”).dp.sum((0, 1))]), … global_scale=1.0 … )

This function extracts utility information about each aggregate in the resulting data frame: >>> dp.summarize_polars_measurement(meas) shape: (2, 4) ┌────────┬───────────┬─────────────────┬───────┐ │ column ┆ aggregate ┆ distribution ┆ scale │ │ — ┆ — ┆ — ┆ — │ │ str ┆ str ┆ str ┆ f64 │ ╞════════╪═══════════╪═════════════════╪═══════╡ │ len ┆ Len ┆ Integer Laplace ┆ 1.0 │ │ A ┆ Sum ┆ Integer Laplace ┆ 1.0 │ └────────┴───────────┴─────────────────┴───────┘

If you pass an alpha argument, then you also get accuracy estimates: >>> dp.summarize_polars_measurement(meas, alpha=.05) shape: (2, 5) ┌────────┬───────────┬─────────────────┬───────┬──────────┐ │ column ┆ aggregate ┆ distribution ┆ scale ┆ accuracy │ │ — ┆ — ┆ — ┆ — ┆ — │ │ str ┆ str ┆ str ┆ f64 ┆ f64 │ ╞════════╪═══════════╪═════════════════╪═══════╪══════════╡ │ len ┆ Len ┆ Integer Laplace ┆ 1.0 ┆ 3.375618 │ │ A ┆ Sum ┆ Integer Laplace ┆ 1.0 ┆ 3.375618 │ └────────┴───────────┴─────────────────┴───────┴──────────┘