diffprivlib.mechanisms
Basic mechanisms for achieving differential privacy, the basic building blocks of the library.
Base classes
- class diffprivlib.mechanisms.DPMachine[source]
Parent class for
DPMechanismandDPTransformer, providing and specifying basic functionality.
- class diffprivlib.mechanisms.DPMechanism(*, epsilon, delta, random_state=None)[source]
Abstract base class for all mechanisms. Instantiated from
DPMachine.- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in [0, 1]. Cannot be simultaneously zero with
epsilon.random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- copy()
Produces a copy of the class.
- Returns:
self – Returns the copy.
- Return type:
class
- class diffprivlib.mechanisms.TruncationAndFoldingMixin(*, lower, upper)[source]
Mixin for truncating or folding the outputs of a mechanism. Must be instantiated with a
DPMechanism.
Binary mechanism
- class diffprivlib.mechanisms.Binary(*, epsilon, value0, value1, random_state=None)[source]
The classic binary mechanism in differential privacy.
Given a binary input value, the mechanism randomly decides to flip to the other binary value or not, in order to satisfy differential privacy.
Paper link: https://arxiv.org/pdf/1612.05568.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
value0 (str) – 0th binary label.
value1 (str) – 1st binary label. Cannot be the same as
value0.random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Notes
The binary attributes, known as labels, must be specified as strings. If non-string labels are required (e.g. integer-valued labels), a
DPTransformercan be used (e.g.IntToString).
Bingham mechanism
- class diffprivlib.mechanisms.Bingham(*, epsilon, sensitivity=1.0, random_state=None)[source]
The Bingham mechanism in differential privacy.
Used to estimate the first eigenvector (associated with the largest eigenvalue) of a covariance matrix.
Paper link: http://eprints.whiterose.ac.uk/123206/7/simbingham8.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float, default: 1) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Exponential mechanisms
- class diffprivlib.mechanisms.Exponential(*, epsilon, sensitivity, utility, monotonic=False, candidates=None, measure=None, random_state=None)[source]
The exponential mechanism for achieving differential privacy on candidate selection, as first proposed by McSherry and Talwar.
The exponential mechanism achieves differential privacy by randomly choosing a candidate subject to candidate utility scores, with greater probability given to higher-utility candidates.
Paper link: https://www.cs.drexel.edu/~greenie/privacy/mdviadp.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float) – The sensitivity in utility values to a change in a datapoint in the underlying dataset.
utility (list) – A list of non-negative utility values for each candidate.
monotonic (bool, default: False) – Specifies if the utility function is monotonic, i.e. that adding an individual to the underlying dataset can only increase the values in utility.
candidates (list, optional) – An optional list of candidate labels. If omitted, the zero-indexed list [0, 1, …, n] is used.
measure (list, optional) – An optional list of measures for each candidate. If omitted, a uniform measure is used.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- class diffprivlib.mechanisms.ExponentialCategorical(*, epsilon, utility_list, random_state=None)[source]
The exponential mechanism for achieving differential privacy on categorical inputs, as first proposed by McSherry and Talwar.
The exponential mechanism achieves differential privacy by randomly choosing an output value for a given input value, with greater probability given to values ‘closer’ to the input, as measured by a given utility function.
Paper link: https://www.cs.drexel.edu/~greenie/privacy/mdviadp.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
utility_list (list of tuples) – The utility list of the mechanism. Must be specified as a list of tuples, of the form (“value1”, “value2”, utility), where each value is a string and utility is a strictly positive float. A utility must be specified for every pair of values given in the utility_list.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- class diffprivlib.mechanisms.ExponentialHierarchical(*, epsilon, hierarchy, random_state=None)[source]
Adaptation of the exponential mechanism to hierarchical data. Simplifies the process of specifying utility values, as the values can be inferred from the hierarchy.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
hierarchy (nested list of str) – The hierarchy as specified as a nested list of string. Each string must be a leaf node, and each leaf node must lie at the same depth in the hierarchy.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Examples
Example hierarchies:
>>> flat_hierarchy = ["A", "B", "C", "D", "E"] >>> nested_hierarchy = [["A"], ["B"], ["C"], ["D", "E"]]
- class diffprivlib.mechanisms.PermuteAndFlip(*, epsilon, sensitivity, utility, monotonic=False, candidates=None, random_state=None)[source]
The permute and flip mechanism for achieving differential privacy on candidate selection, as first proposed by McKenna and Sheldon.
The permute and flip mechanism is an alternative to the exponential mechanism, and achieves differential privacy by randomly choosing a candidate subject to candidate utility scores, with greater probability given to higher-utility candidates.
Paper link: https://arxiv.org/pdf/2010.12603.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float) – The sensitivity in utility values to a change in a datapoint in the underlying dataset.
utility (list) – A list of non-negative utility values for each candidate.
monotonic (bool, default: False) – Specifies if the utility function is monotonic, i.e. that adding an individual to the underlying dataset can only increase the values in utility.
candidates (list, optional) – An optional list of candidate labels. If omitted, the zero-indexed list [0, 1, …, n] is used.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Gaussian mechanisms
- class diffprivlib.mechanisms.Gaussian(*, epsilon, delta, sensitivity, random_state=None)[source]
The Gaussian mechanism in differential privacy.
First proposed by Dwork and Roth in “The algorithmic foundations of differential privacy” [DR14]. Samples from the Gaussian distribution are generated using two samples from random.normalvariate as detailed in [HB21b], to prevent against reconstruction attacks due to limited floating point precision.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, 1]. For
epsilon > 1, useGaussianAnalytic.delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in (0, 1].
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
References
[DR14]Dwork, Cynthia, and Aaron Roth. “The algorithmic foundations of differential privacy.” Found. Trends Theor. Comput. Sci. 9, no. 3-4 (2014): 211-407.
[HB21b]Holohan, Naoise, and Stefano Braghin. “Secure Random Sampling in Differential Privacy.” arXiv preprint arXiv:2107.10138 (2021).
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.GaussianAnalytic(*, epsilon, delta, sensitivity, random_state=None)[source]
The analytic Gaussian mechanism in differential privacy.
As first proposed by Balle and Wang in “Improving the Gaussian Mechanism for Differential Privacy: Analytical Calibration and Optimal Denoising”.
Paper link: https://arxiv.org/pdf/1805.06530.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in (0, 1].
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- bias(value)
Returns the bias of the mechanism at a given value.
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- randomise(value)
Randomise value with the mechanism.
- class diffprivlib.mechanisms.GaussianDiscrete(*, epsilon, delta, sensitivity=1, random_state=None)[source]
The Discrete Gaussian mechanism in differential privacy.
As proposed by Canonne, Kamath and Steinke, re-purposed for approximate \((\epsilon,\delta)\)-differential privacy.
Paper link: https://arxiv.org/pdf/2004.00010.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in (0, 1].
sensitivity (int, default: 1) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Geometric mechanisms
- class diffprivlib.mechanisms.Geometric(*, epsilon, sensitivity=1, random_state=None)[source]
The classic geometric mechanism for differential privacy, as first proposed by Ghosh, Roughgarden and Sundararajan. Extended to allow for non-unity sensitivity.
Paper link: https://arxiv.org/pdf/0811.2841.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float, default: 1) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.GeometricTruncated(*, epsilon, sensitivity=1, lower, upper, random_state=None)[source]
The truncated geometric mechanism, where values that fall outside a pre-described range are mapped back to the closest point within the range.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float, default: 1) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (int) – The lower bound of the mechanism.
upper (int) – The upper bound of the mechanism.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- class diffprivlib.mechanisms.GeometricFolded(*, epsilon, sensitivity=1, lower, upper, random_state=None)[source]
The folded geometric mechanism, where values outside a pre-described range are folded back toward the domain around the closest point within the domain. Half-integer bounds are permitted.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float, default: 1) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (int or float) – The lower bound of the mechanism. Must be integer or half-integer -valued.
upper (int or float) – The upper bound of the mechanism. Must be integer or half-integer -valued.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Laplace mechanisms
- class diffprivlib.mechanisms.Laplace(*, epsilon, delta=0.0, sensitivity, random_state=None)[source]
The classical Laplace mechanism in differential privacy.
First proposed by Dwork, McSherry, Nissim and Smith [DMNS16], with support for (relaxed) \((\epsilon,\delta)\)-differential privacy [HLM15].
Samples from the Laplace distribution are generated using 4 uniform variates, as detailed in [HB21], to prevent against reconstruction attacks due to limited floating point precision.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
delta (float, default: 0.0) – Privacy parameter \(\delta\) for the mechanism. Must be in [0, 1]. Cannot be simultaneously zero with
epsilon.sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
References
[DMNS16]Dwork, Cynthia, Frank McSherry, Kobbi Nissim, and Adam Smith. “Calibrating noise to sensitivity in private data analysis.” Journal of Privacy and Confidentiality 7, no. 3 (2016): 17-51.
[HLM15]Holohan, Naoise, Douglas J. Leith, and Oliver Mason. “Differential privacy in metric spaces: Numerical, categorical and functional data under the one roof.” Information Sciences 305 (2015): 256-268.
[HB21]Holohan, Naoise, and Stefano Braghin. “Secure Random Sampling in Differential Privacy.” arXiv preprint arXiv:2107.10138 (2021).
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.LaplaceTruncated(*, epsilon, delta=0.0, sensitivity, lower, upper, random_state=None)[source]
The truncated Laplace mechanism, where values outside a pre-described domain are mapped to the closest point within the domain.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
delta (float, default: 0.0) – Privacy parameter \(\delta\) for the mechanism. Must be in [0, 1]. Cannot be simultaneously zero with
epsilon.sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (float) – The lower bound of the mechanism.
upper (float) – The upper bound of the mechanism.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.LaplaceBoundedDomain(*, epsilon, delta=0.0, sensitivity, lower, upper, random_state=None)[source]
The bounded Laplace mechanism on a bounded domain. The mechanism draws values directly from the domain using rejection sampling, without any post-processing [HABM20].
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
delta (float, default: 0.0) – Privacy parameter \(\delta\) for the mechanism. Must be in [0, 1]. Cannot be simultaneously zero with
epsilon.sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (float) – The lower bound of the mechanism.
upper (float) – The upper bound of the mechanism.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
References
[HABM20]Holohan, Naoise, Spiros Antonatos, Stefano Braghin, and Pól Mac Aonghusa. “The Bounded Laplace Mechanism in Differential Privacy.” Journal of Privacy and Confidentiality 10, no. 1 (2020).
- effective_epsilon()[source]
Gets the effective epsilon of the mechanism, only for strict \(\epsilon\)-differential privacy. Returns
Noneif \(\delta\) is non-zero.- Returns:
The effective \(\epsilon\) parameter of the mechanism. Returns
Noneif delta is non-zero.- Return type:
- mse(value)
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.LaplaceBoundedNoise(*, epsilon, delta, sensitivity, random_state=None)[source]
The Laplace mechanism with bounded noise, only applicable for approximate differential privacy (delta > 0) [GDGK18].
- Epsilon must be strictly positive, epsilon > 0. delta must be strictly in the interval (0, 0.5).
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in (0, 0.5).
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
References
[GDGK18]Geng, Quan, Wei Ding, Ruiqi Guo, and Sanjiv Kumar. “Truncated Laplacian Mechanism for Approximate Differential Privacy.” arXiv preprint arXiv:1810.00877v1 (2018).
- class diffprivlib.mechanisms.LaplaceFolded(*, epsilon, delta=0.0, sensitivity, lower, upper, random_state=None)[source]
The folded Laplace mechanism, where values outside a pre-described domain are folded around the domain until they fall within.
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [0, ∞].
delta (float, default: 0.0) – Privacy parameter \(\delta\) for the mechanism. Must be in [0, 1]. Cannot be simultaneously zero with
epsilon.sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (float) – The lower bound of the mechanism.
upper (float) – The upper bound of the mechanism.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Snapping mechanism
- class diffprivlib.mechanisms.Snapping(*, epsilon, sensitivity, lower, upper, random_state=None)[source]
The Snapping mechanism for differential privacy.
First proposed by Ilya Mironov [Mir12].
It eliminates a vulnerability stemming from the representation of reals as floating-point numbers in implementations of the classic Laplace mechanism and its variants which use the inverse CDF of the Laplace distribution to sample it. It causes a high degree of reduction in the granularity of the output.
For the most faithful implementation of the mechanism, the
crlibmpackage should be installed.- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in [\(2 \eta\), ∞], where \(\eta\) is the machine epsilon of the floating point type.
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
lower (float) – The lower bound of the mechanism.
upper (float) – The upper bound of the mechanism.
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
References
Staircase mechanism
- class diffprivlib.mechanisms.Staircase(*, epsilon, sensitivity, gamma=None, random_state=None)[source]
The staircase mechanism in differential privacy.
The staircase mechanism is an optimisation of the classical Laplace Mechanism (
Laplace), described as a “geometric mixture of uniform random variables”. Paper link: https://arxiv.org/pdf/1212.1186.pdf- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
gamma (float, default: 1 / (1 + exp(epsilon/2))) – Value of the tuning parameter gamma for the mechanism. Must be in [0, 1].
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Uniform mechanism
- class diffprivlib.mechanisms.Uniform(*, delta, sensitivity, random_state=None)[source]
The Uniform mechanism in differential privacy.
This emerges as a special case of the
LaplaceBoundedNoisemechanism when epsilon = 0. Paper link: https://arxiv.org/pdf/1810.00877.pdf- Parameters:
delta (float) – Privacy parameter \(\delta\) for the mechanism. Must be in (0, 0.5].
sensitivity (float) – The sensitivity of the mechanism. Must be in [0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.
Vector mechanism
- class diffprivlib.mechanisms.Vector(*, epsilon, function_sensitivity, data_sensitivity=1.0, dimension, alpha=0.01, random_state=None)[source]
The vector mechanism in differential privacy.
The vector mechanism is used when perturbing convex objective functions. Full paper: http://www.jmlr.org/papers/volume12/chaudhuri11a/chaudhuri11a.pdf
- Parameters:
epsilon (float) – Privacy parameter \(\epsilon\) for the mechanism. Must be in (0, ∞].
function_sensitivity (float) – The function sensitivity of the mechanism. Must be in [0, ∞).
data_sensitivity (float, default: 1.0) – The data sensitivityof the mechanism. Must be in [0, ∞).
dimension (int) – Function input dimension. This dimension relates to the size of the input vector of the function being considered by the mechanism. This corresponds to the size of the random vector produced by the mechanism. Must be in [1, ∞).
alpha (float, default: 0.01) – Regularisation parameter. Must be in (0, ∞).
random_state (int or RandomState, optional) – Controls the randomness of the mechanism. To obtain a deterministic behaviour during randomisation,
random_statehas to be fixed to an integer.