opendp.measurements module#

The measurements module provides functions that apply calibrated noise to data to ensure differential privacy.

opendp.measurements.make_alp_queryable(input_domain, input_metric, scale, total_limit, value_limit=None, size_factor=50, alpha=4, CO=None)[source]#

Measurement to release a queryable containing a DP projection of bounded sparse data.

The size of the projection is O(total * size_factor * scale / alpha). The evaluation time of post-processing is O(beta * scale / alpha).

size_factor is an optional multiplier (defaults to 50) for setting the size of the projection. There is a memory/utility trade-off. The value should be sufficiently large to limit hash collisions.

make_alp_queryable in Rust documentation.

Citations:

ALP21 Differentially Private Sparse Vectors with Low Error, Optimal Space, and Fast Access Algorithm 4

Supporting Elements:

Input Domain: MapDomain<AtomDomain<K>, AtomDomain<CI>>
Output Type: Queryable<K, CO>
Input Metric: L1Distance<CI>
Output Measure: MaxDivergence<CO>

Parameters:

input_domain (Domain) –
input_metric (Metric) –
scale – Privacy loss parameter. This is equal to epsilon/sensitivity.
total_limit – Either the true value or an upper bound estimate of the sum of all values in the input.
value_limit – Upper bound on individual values (referred to as β). Entries above β are clamped.
size_factor – Optional multiplier (default of 50) for setting the size of the projection.
alpha – Optional parameter (default of 4) for scaling and determining p in randomized response step.
CO (Type Argument) –

Return type:

Measurement

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.measurements.make_base_discrete_gaussian(input_domain, input_metric, scale, MO='ZeroConcentratedDivergence<QO>')[source]#

Make a Measurement that adds noise from the discrete_gaussian(scale) distribution to the input.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)`	`T`	`absolute_distance(QI)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l2_distance(QI)`

make_base_discrete_gaussian in Rust documentation.

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MO

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
MO (Type Argument) – Output measure. The only valid measure is ZeroConcentratedDivergence<QO>, but QO can be any float.

Return type:

Measurement

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.measurements.make_base_discrete_laplace(input_domain, input_metric, scale, QO=None)[source]#

Make a Measurement that adds noise from the discrete_laplace(scale) distribution to the input.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l1_distance(T)`

This uses make_base_discrete_laplace_cks20 if scale is greater than 10, otherwise it uses make_base_discrete_laplace_linear.

make_base_discrete_laplace in Rust documentation.

Citations:

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<QO>

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale. f32 or f64.

Return type:

Measurement

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.measurements.make_base_discrete_laplace_cks20(input_domain, input_metric, scale, QO=None)[source]#

Make a Measurement that adds noise from the discrete_laplace(scale) distribution to the input, using an efficient algorithm on rational bignums.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l1_distance(T)`

make_base_discrete_laplace_cks20 in Rust documentation.

Citations:

CKS20 The Discrete Gaussian for Differential Privacy

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<QO>

Parameters:

input_domain (Domain) –
input_metric (Metric) –
scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale.

Return type:

Measurement

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.measurements.make_base_discrete_laplace_linear(input_domain, input_metric, scale, bounds=None, QO=None)[source]#

Make a Measurement that adds noise from the discrete_laplace(scale) distribution to the input, using a linear-time algorithm on finite data types.

This algorithm can be executed in constant time if bounds are passed. Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l1_distance(T)`

make_base_discrete_laplace_linear in Rust documentation.

Citations:

GRS12 Universally Utility-Maximizing Privacy Mechanisms

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<QO>

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the distribution. scale == standard_deviation / sqrt(2).
bounds (Any) – Set bounds on the count to make the algorithm run in constant-time.
QO (Type Argument) – Data type of the scale and output distance.

Return type:

Measurement

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.measurements.make_base_gaussian(input_domain, input_metric, scale, k=-1074, MO='ZeroConcentratedDivergence<T>')[source]#

Make a Measurement that adds noise from the gaussian(scale) distribution to the input.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l2_distance(T)`

This function takes a noise granularity in terms of 2^k. Larger granularities are more computationally efficient, but have a looser privacy map. If k is not set, k defaults to the smallest granularity.

make_base_gaussian in Rust documentation.

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MO

Parameters:

input_domain (Domain) – Domain of the data type to be privatized. Valid values are VectorDomain<AtomDomain<T>> or AtomDomain<T>.
input_metric (Metric) – Metric of the data type to be privatized. Valid values are AbsoluteDistance<T> or L2Distance<T>.
scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
k (int) – The noise granularity in terms of 2^k.
MO (Type Argument) – Output Measure. The only valid measure is ZeroConcentratedDivergence<T>.

Return type:

Measurement

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.measurements.make_base_geometric(input_domain, input_metric, scale, bounds=None, QO=None)[source]#

An alias for make_base_discrete_laplace_linear. If you don’t need timing side-channel protections via bounds, make_base_discrete_laplace is more efficient.

make_base_geometric in Rust documentation.

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<QO>

Parameters:

input_domain (Domain) –
input_metric (Metric) –
scale –
bounds (Any) –
QO (Type Argument) –

Return type:

Measurement

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.measurements.make_base_laplace(input_domain, input_metric, scale, k=-1074)[source]#

Make a Measurement that adds noise from the Laplace(scale) distribution to a scalar value.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l1_distance(T)`

make_base_laplace in Rust documentation.

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<D::Atom>

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
k (int) – The noise granularity in terms of 2^k.

Return type:

Measurement

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.measurements.make_base_laplace_threshold(input_domain, input_metric, scale, threshold, k=-1074)[source]#

Make a Measurement that uses propose-test-release to privatize a hashmap of counts.

make_base_laplace_threshold in Rust documentation.

Supporting Elements:

Input Domain: MapDomain<AtomDomain<TK>, AtomDomain<TV>>
Output Type: HashMap<TK, TV>
Input Metric: L1Distance<TV>
Output Measure: FixedSmoothedMaxDivergence<TV>

Parameters:

input_domain (Domain) – Domain of the input.
input_metric (Metric) – Metric for the input domain.
scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
threshold – Exclude counts that are less than this minimum value.
k (int) – The noise granularity in terms of 2^k.

Return type:

Measurement

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.measurements.make_gaussian(input_domain, input_metric, scale, MO='ZeroConcentratedDivergence<QO>')[source]#

Make a Measurement that adds noise from the gaussian(scale) distribution to the input.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)`	`T`	`absolute_distance(QI)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l2_distance(QI)`

make_gaussian in Rust documentation.

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MO

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
MO (Type Argument) – Output Measure. The only valid measure is ZeroConcentratedDivergence<T>.

Return type:

Measurement

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.measurements.make_laplace(input_domain, input_metric, scale, QO='float')[source]#

Make a Measurement that adds noise from the laplace(scale) distribution to the input.

Valid inputs for input_domain and input_metric are:

`input_domain`	input type	`input_metric`
`atom_domain(T)` (default)	`T`	`absolute_distance(T)`
`vector_domain(atom_domain(T))`	`Vec<T>`	`l1_distance(T)`

This uses make_base_laplace if T is float, otherwise it uses make_base_discrete_laplace.

make_laplace in Rust documentation.

Citations:

Supporting Elements:

Input Domain: D
Output Type: D::Carrier
Input Metric: D::InputMetric
Output Measure: MaxDivergence<QO>

Parameters:

input_domain (Domain) – Domain of the data type to be privatized.
input_metric (Metric) – Metric of the data type to be privatized.
scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale. f32 or f64.

Return type:

Measurement

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.measurements.make_randomized_response(categories, prob, constant_time=False, T=None, QO=None)[source]#

Make a Measurement that implements randomized response on a categorical value.

make_randomized_response in Rust documentation.

Supporting Elements:

Input Domain: AtomDomain<T>
Output Type: T
Input Metric: DiscreteDistance
Output Measure: MaxDivergence<QO>

Parameters:

categories (Any) – Set of valid outcomes
prob – Probability of returning the correct answer. Must be in [1/num_categories, 1)
constant_time (bool) – Set to true to enable constant time. Slower.
T (Type Argument) – Data type of a category.
QO (Type Argument) – Data type of probability and output distance.

Return type:

Measurement

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.measurements.make_randomized_response_bool(prob, constant_time=False, QO=None)[source]#

Make a Measurement that implements randomized response on a boolean value.

make_randomized_response_bool in Rust documentation.

Supporting Elements:

Input Domain: AtomDomain<bool>
Output Type: bool
Input Metric: DiscreteDistance
Output Measure: MaxDivergence<QO>

Proof Definition:

(Proof Document)

Parameters:

prob – Probability of returning the correct answer. Must be in [0.5, 1)
constant_time (bool) – Set to true to enable constant time. Slower.
QO (Type Argument) – Data type of probability and output distance.

Return type:

Measurement

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.measurements.make_report_noisy_max_gumbel(input_domain, input_metric, scale, optimize, QO=None)[source]#

Make a Measurement that takes a vector of scores and privately selects the index of the highest score.

make_report_noisy_max_gumbel in Rust documentation.

Supporting Elements:

Input Domain: VectorDomain<AtomDomain<TIA>>
Output Type: usize
Input Metric: LInfDistance<TIA>
Output Measure: MaxDivergence<QO>

Proof Definition:

(Proof Document)

Parameters:

input_domain (Domain) – Domain of the input vector. Must be a non-nullable VectorDomain.
input_metric (Metric) – Metric on the input domain. Must be LInfDistance
scale (Any) – Higher scales are more private.
optimize (str) – Indicate whether to privately return the “Max” or “Min”
QO (Type Argument) – Output Distance Type.

Return type:

Measurement

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.measurements.make_user_measurement(input_domain, input_metric, output_measure, function, privacy_map, TO='ExtrinsicObject')[source]#

Construct a Measurement from user-defined callbacks.

Supporting Elements:

Input Domain: AnyDomain
Output Type: AnyObject
Input Metric: AnyMetric
Output Measure: AnyMeasure

Parameters:

input_domain (Domain) – A domain describing the set of valid inputs for the function.
input_metric (Metric) – The metric from which distances between adjacent inputs are measured.
output_measure (Measure) – The measure from which distances between adjacent output distributions are measured.
function – A function mapping data from input_domain to a release of type TO.
privacy_map – A function mapping distances from input_metric to output_measure.
TO (Type Argument) – The data type of outputs from the function.

Return type:

Measurement

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.measurements.then_alp_queryable(scale, total_limit, value_limit=None, size_factor=50, alpha=4, CO=None)[source]#

partial constructor of make_alp_queryable

See also

Delays application of input_domain and input_metric in opendp.measurements.make_alp_queryable()

Parameters:

scale – Privacy loss parameter. This is equal to epsilon/sensitivity.
total_limit – Either the true value or an upper bound estimate of the sum of all values in the input.
value_limit – Upper bound on individual values (referred to as β). Entries above β are clamped.
size_factor – Optional multiplier (default of 50) for setting the size of the projection.
alpha – Optional parameter (default of 4) for scaling and determining p in randomized response step.
CO (Type Argument) –

opendp.measurements.then_base_discrete_gaussian(scale, MO='ZeroConcentratedDivergence<QO>')[source]#

partial constructor of make_base_discrete_gaussian

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_discrete_gaussian()

Parameters:

scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
MO (Type Argument) – Output measure. The only valid measure is ZeroConcentratedDivergence<QO>, but QO can be any float.

opendp.measurements.then_base_discrete_laplace(scale, QO=None)[source]#

partial constructor of make_base_discrete_laplace

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_discrete_laplace()

Parameters:

scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale. f32 or f64.

opendp.measurements.then_base_discrete_laplace_cks20(scale, QO=None)[source]#

partial constructor of make_base_discrete_laplace_cks20

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_discrete_laplace_cks20()

Parameters:

scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale.

opendp.measurements.then_base_discrete_laplace_linear(scale, bounds=None, QO=None)[source]#

partial constructor of make_base_discrete_laplace_linear

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_discrete_laplace_linear()

Parameters:

scale – Noise scale parameter for the distribution. scale == standard_deviation / sqrt(2).
bounds (Any) – Set bounds on the count to make the algorithm run in constant-time.
QO (Type Argument) – Data type of the scale and output distance.

opendp.measurements.then_base_gaussian(scale, k=-1074, MO='ZeroConcentratedDivergence<T>')[source]#

partial constructor of make_base_gaussian

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_gaussian()

Parameters:

scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
k (int) – The noise granularity in terms of 2^k.
MO (Type Argument) – Output Measure. The only valid measure is ZeroConcentratedDivergence<T>.

opendp.measurements.then_base_geometric(scale, bounds=None, QO=None)[source]#

partial constructor of make_base_geometric

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_geometric()

Parameters:

scale –
bounds (Any) –
QO (Type Argument) –

opendp.measurements.then_base_laplace(scale, k=-1074)[source]#

partial constructor of make_base_laplace

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_laplace()

Parameters:

scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
k (int) – The noise granularity in terms of 2^k.

opendp.measurements.then_base_laplace_threshold(scale, threshold, k=-1074)[source]#

partial constructor of make_base_laplace_threshold

See also

Delays application of input_domain and input_metric in opendp.measurements.make_base_laplace_threshold()

Parameters:

scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
threshold – Exclude counts that are less than this minimum value.
k (int) – The noise granularity in terms of 2^k.

opendp.measurements.then_gaussian(scale, MO='ZeroConcentratedDivergence<QO>')[source]#

partial constructor of make_gaussian

See also

Delays application of input_domain and input_metric in opendp.measurements.make_gaussian()

Parameters:

scale – Noise scale parameter for the gaussian distribution. scale == standard_deviation.
MO (Type Argument) – Output Measure. The only valid measure is ZeroConcentratedDivergence<T>.

opendp.measurements.then_laplace(scale, QO='float')[source]#

partial constructor of make_laplace

See also

Delays application of input_domain and input_metric in opendp.measurements.make_laplace()

Parameters:

scale – Noise scale parameter for the laplace distribution. scale == standard_deviation / sqrt(2).
QO (Type Argument) – Data type of the output distance and scale. f32 or f64.

opendp.measurements.then_report_noisy_max_gumbel(scale, optimize, QO=None)[source]#

partial constructor of make_report_noisy_max_gumbel

See also

Delays application of input_domain and input_metric in opendp.measurements.make_report_noisy_max_gumbel()

Parameters:

scale (Any) – Higher scales are more private.
optimize (str) – Indicate whether to privately return the “Max” or “Min”
QO (Type Argument) – Output Distance Type.

opendp.measurements.then_user_measurement(output_measure, function, privacy_map, TO='ExtrinsicObject')[source]#

partial constructor of make_user_measurement

See also

Delays application of input_domain and input_metric in opendp.measurements.make_user_measurement()

Parameters:

output_measure (Measure) – The measure from which distances between adjacent output distributions are measured.
function – A function mapping data from input_domain to a release of type TO.
privacy_map – A function mapping distances from input_metric to output_measure.
TO (Type Argument) – The data type of outputs from the function.

Branches

Releases

opendp.measurements module#