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)[source]¶
Abstract base class for all mechanisms. Instantiated from
DPMachine.- Parameters
- 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)[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
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)[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
Exponential mechanisms¶
- class diffprivlib.mechanisms.Exponential(*, epsilon, sensitivity, utility, candidates=None, measure=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.
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.
- class diffprivlib.mechanisms.ExponentialCategorical(*, epsilon, utility_list)[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.
- class diffprivlib.mechanisms.ExponentialHierarchical(*, epsilon, hierarchy)[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.
Examples
Example hierarchies:
>>> flat_hierarchy = ["A", "B", "C", "D", "E"] >>> nested_hierarchy = [["A"], ["B"], ["C"], ["D", "E"]]
- class diffprivlib.mechanisms.PermuteAndFlip(*, epsilon, sensitivity, utility, candidates=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.
candidates (list, optional) – An optional list of candidate labels. If omitted, the zero-indexed list [0, 1, …, n] is used.
Gaussian mechanisms¶
- class diffprivlib.mechanisms.Gaussian(*, epsilon, delta, sensitivity)[source]¶
The Gaussian mechanism in differential privacy.
As first proposed by Dwork and Roth in “The algorithmic foundations of differential privacy”.
Paper link: https://www.nowpublishers.com/article/DownloadSummary/TCS-042
- 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, ∞).
- mse(value)¶
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.GaussianAnalytic(*, epsilon, delta, sensitivity)[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
- 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)[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
Geometric mechanisms¶
- class diffprivlib.mechanisms.Geometric(*, epsilon, sensitivity=1)[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
- mse(value)¶
Returns the mean squared error (MSE) of the mechanism at a given value.
- class diffprivlib.mechanisms.GeometricTruncated(*, epsilon, sensitivity=1, lower, upper)[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
- class diffprivlib.mechanisms.GeometricFolded(*, epsilon, sensitivity=1, lower, upper)[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.
Laplace mechanisms¶
- class diffprivlib.mechanisms.Laplace(*, epsilon, delta=0.0, sensitivity)[source]¶
The classic Laplace mechanism in differential privacy, as first proposed by Dwork, McSherry, Nissim and Smith.
Paper link: https://link.springer.com/content/pdf/10.1007/11681878_14.pdf
Includes extension to (relaxed) \((\epsilon,\delta)\)-differential privacy, as proposed by Holohan et al.
Paper link: https://arxiv.org/pdf/1402.6124.pdf
- 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, ∞).
- 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)[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.
- 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)[source]¶
The bounded Laplace mechanism on a bounded domain. The mechanism draws values directly from the domain, without any post-processing.
- 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.
- 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)[source]¶
The Laplace mechanism with bounded noise, only applicable for approximate differential privacy (delta > 0).
- Epsilon must be strictly positive, epsilon > 0. delta must be strictly in the interval (0, 0.5).
Paper link: https://arxiv.org/pdf/1810.00877v1.pdf
- Parameters
- class diffprivlib.mechanisms.LaplaceFolded(*, epsilon, delta=0.0, sensitivity, lower, upper)[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.
Staircase mechanism¶
- class diffprivlib.mechanisms.Staircase(*, epsilon, sensitivity, gamma=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
Uniform mechanism¶
- class diffprivlib.mechanisms.Uniform(*, delta, sensitivity)[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
Vector mechanism¶
- class diffprivlib.mechanisms.Vector(*, epsilon, function_sensitivity, data_sensitivity=1.0, dimension, alpha=0.01)[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, ∞).
Wishart mechanism¶
- class diffprivlib.mechanisms.Wishart(epsilon, sensitivity)[source]¶
The Wishart mechanism in differential privacy.
Used to achieve differential privacy on 2nd moment matrices.
Paper link: https://ieeexplore.ieee.org/abstract/document/7472095/
Deprecated since version 0.4: Wishart is deprecated and will be removed in version 0.5. The Wishart mechanism has been shown not to satisfy differential privacy, and its continued use is not recommended.
- Parameters