opendp.measures module

The measures module provides functions that measure the distance between probability distributions. For more context, see measures 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.measures.approximate(measure)

Privacy measure used to define \(\delta\)-approximate PM-differential privacy.

In the following definition, \(d\) corresponds to privacy parameters \((d', \delta)\) when also quantified over all adjacent datasets (\(d'\) is the privacy parameter corresponding to privacy measure PM). That is, \((d', \delta)\) is no smaller than \(d\) (by product ordering), over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

approximate in Rust documentation.

Proof Definition:

For any two distributions \(Y, Y'\) and 2-tuple \(d = (d', \delta)\), where \(d'\) is the distance with respect to privacy measure PM, \(Y, Y'\) are \(d\)-close under the approximate PM measure whenever, for any choice of \(\delta \in [0, 1]\), there exist events \(E\) (depending on \(Y\)) and \(E'\) (depending on \(Y'\)) such that \(\Pr[E] \ge 1 - \delta\), \(\Pr[E'] \ge 1 - \delta\), and

\(D_{\mathrm{PM}}^\delta(Y|_E, Y'|_{E'}) = D_{\mathrm{PM}}(Y|_E, Y'|_{E'})\)

where \(Y|_E\) denotes the distribution of \(Y\) conditioned on the event \(E\).

Note that this \(\delta\) is not privacy parameter \(\delta\) until quantified over all adjacent datasets, as is done in the definition of a measurement.

Parameters:

measure (Measure) – inner privacy measure

Return type:

Measure

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.measures.fixed_smoothed_max_divergence()

Privacy measure used to define \((\epsilon, \delta)\)-approximate differential privacy.

In the following definition, \(d\) corresponds to \((\epsilon, \delta)\) when also quantified over all adjacent datasets. That is, \((\epsilon, \delta)\) is no smaller than \(d\) (by product ordering), over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

Proof Definition:

For any two distributions \(Y, Y'\) and any 2-tuple \(d\) of non-negative numbers \(\epsilon\) and \(\delta\), \(Y, Y'\) are \(d\)-close under the fixed smoothed max divergence measure whenever

\(D_\infty^\delta(Y, Y') = \max_{S \subseteq \textrm{Supp}(Y)} \Big[\ln \dfrac{\Pr[Y \in S] + \delta}{\Pr[Y' \in S]} \Big] \leq \epsilon\).

Note that this \(\epsilon\) and \(\delta\) are not privacy parameters \(\epsilon\) and \(\delta\) until quantified over all adjacent datasets, as is done in the definition of a measurement.

Return type:

Measure

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.measures.max_divergence()

Privacy measure used to define \(\epsilon\)-pure differential privacy.

In the following proof definition, \(d\) corresponds to \(\epsilon\) when also quantified over all adjacent datasets. That is, \(\epsilon\) is the greatest possible \(d\) over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

Proof Definition:

For any two distributions \(Y, Y'\) and any non-negative \(d\), \(Y, Y'\) are \(d\)-close under the max divergence measure whenever

\(D_\infty(Y, Y') = \max_{S \subseteq \textrm{Supp}(Y)} \Big[\ln \dfrac{\Pr[Y \in S]}{\Pr[Y' \in S]} \Big] \leq d\).

Return type:

Measure

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.measures.measure_debug(this)

Debug a measure.

Parameters:

this (Measure) – The measure to debug (stringify).

Return type:

str

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.measures.measure_distance_type(this)

Get the distance type of a measure.

Parameters:

this (Measure) – The measure to retrieve the distance type from.

Return type:

str

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.measures.measure_type(this)

Get the type of a measure.

Parameters:

this (Measure) – The measure to retrieve the type from.

Return type:

str

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.measures.new_privacy_profile(curve)

Construct a PrivacyProfile from a user-defined callback.

Required features: contrib, honest-but-curious

Why honest-but-curious?:

The privacy profile should implement a well-defined \(\delta(\epsilon)\) curve: * monotonically decreasing * rejects epsilon values that are less than zero or nan * returns delta values only within [0, 1]

Parameters:

curve – A privacy curve mapping epsilon to delta

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:

>>> dp.enable_features("contrib", "honest-but-curious")
>>> profile = dp.new_privacy_profile(lambda eps: 1.0 if eps < 0.5 else 1e-8)
...
>>> # epsilon is not enough, so delta saturates to one
>>> profile.delta(epsilon=0.499)
1.0
>>> # invert it, find the suitable epsilon at this delta
>>> profile.epsilon(delta=1e-8)
0.5
>>> # insufficient delta results in infinite epsilon
>>> profile.epsilon(delta=1e-9)
inf

opendp.measures.renyi_divergence()

Privacy measure used to define \(\epsilon(\alpha)\)-Rényi differential privacy.

In the following proof definition, \(d\) corresponds to an RDP curve when also quantified over all adjacent datasets. That is, an RDP curve \(\epsilon(\alpha)\) is no smaller than \(d(\alpha)\) for any possible choices of \(\alpha\), and over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

Proof Definition:

For any two distributions \(Y, Y'\) and any curve \(d\), \(Y, Y'\) are \(d\)-close under the Rényi divergence measure if, for any given \(\alpha \in (1, \infty)\),

\(D_\alpha(Y, Y') = \frac{1}{1 - \alpha} \mathbb{E}_{x \sim Y'} \Big[\ln \left( \dfrac{\Pr[Y = x]}{\Pr[Y' = x]} \right)^\alpha \Big] \leq d(\alpha)\)

Note that this \(\epsilon\) and \(\alpha\) are not privacy parameters \(\epsilon\) and \(\alpha\) until quantified over all adjacent datasets, as is done in the definition of a measurement.

Return type:

Measure

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.measures.smoothed_max_divergence()

Privacy measure used to define \(\epsilon(\delta)\)-approximate differential privacy.

In the following proof definition, \(d\) corresponds to a privacy profile when also quantified over all adjacent datasets. That is, a privacy profile \(\epsilon(\delta)\) is no smaller than \(d(\delta)\) for all possible choices of \(\delta\), and over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

The distance \(d\) is of type PrivacyProfile, so it can be invoked with an \(\epsilon\) to retrieve the corresponding \(\delta\).

Proof Definition:

For any two distributions \(Y, Y'\) and any curve \(d(\cdot)\), \(Y, Y'\) are \(d\)-close under the smoothed max divergence measure whenever, for any choice of non-negative \(\epsilon\), and \(\delta = d(\epsilon)\),

\(D_\infty^\delta(Y, Y') = \max_{S \subseteq \textrm{Supp}(Y)} \Big[\ln \dfrac{\Pr[Y \in S] + \delta}{\Pr[Y' \in S]} \Big] \leq \epsilon\).

Note that \(\epsilon\) and \(\delta\) are not privacy parameters \(\epsilon\) and \(\delta\) until quantified over all adjacent datasets, as is done in the definition of a measurement.

Return type:

Measure

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.measures.user_divergence(descriptor)

Privacy measure with meaning defined by an OpenDP Library user (you).

Any two instances of UserDivergence are equal if their string descriptors are equal.

Required features: honest-but-curious

Why honest-but-curious?:

The essential requirement of a privacy measure is that it is closed under postprocessing. Your privacy measure D must satisfy that, for any pure function f and any two distributions Y, Y', then \(D(Y, Y') \ge D(f(Y), f(Y'))\).

Beyond this, you should also consider whether your privacy measure can be used to provide meaningful privacy guarantees to your privacy units.

Parameters:

descriptor (str) – A string description of the privacy measure.

Return type:

Measure

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.measures.zero_concentrated_divergence()

Privacy measure used to define \(\rho\)-zero concentrated differential privacy.

In the following proof definition, \(d\) corresponds to \(\rho\) when also quantified over all adjacent datasets. That is, \(\rho\) is the greatest possible \(d\) over all pairs of adjacent datasets \(x, x'\) where \(Y \sim M(x)\), \(Y' \sim M(x')\). \(M(\cdot)\) is a measurement (commonly known as a mechanism). The measurement’s input metric defines the notion of adjacency, and the measurement’s input domain defines the set of possible datasets.

Proof Definition:

For any two distributions \(Y, Y'\) and any non-negative \(d\), \(Y, Y'\) are \(d\)-close under the zero-concentrated divergence measure if, for every possible choice of \(\alpha \in (1, \infty)\),

\(D_\alpha(Y, Y') = \frac{1}{1 - \alpha} \mathbb{E}_{x \sim Y'} \Big[\ln \left( \dfrac{\Pr[Y = x]}{\Pr[Y' = x]} \right)^\alpha \Big] \leq d \cdot \alpha\).

Return type:

Measure

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