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)[source]#
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:
- 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()[source]#
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:
- 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()[source]#
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:
- 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)[source]#
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)[source]#
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)[source]#
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)[source]#
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()[source]#
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:
- 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()[source]#
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:
- 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)[source]#
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 functionf
and any two distributionsY, 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:
- 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()[source]#
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:
- 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