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 DPMechanism and DPTransformer, providing and specifying basic functionality.

copy()[source]

Produces a copy of the class.

Returns:

self – Returns the copy.

Return type:

class

abstract randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int or float or str or method) – The value to be randomised.

Returns:

The randomised value, same type as value.

Return type:

int or float or str or method

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value if defined, None otherwise.

Return type:

float or None

copy()

Produces a copy of the class.

Returns:

self – Returns the copy.

Return type:

class

mse(value)[source]

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

abstract randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int or float or str or method) – The value to be randomised.

Returns:

The randomised value, same type as value.

Return type:

int or float or str or method

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value if defined, None otherwise.

Return type:

float or None

class diffprivlib.mechanisms.TruncationAndFoldingMixin(*, lower, upper)[source]

Mixin for truncating or folding the outputs of a mechanism. Must be instantiated with a DPMechanism.

Parameters:
  • lower (float) – The lower bound of the mechanism.

  • upper (float) – The upper bound of the mechanism.

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_state has 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 DPTransformer can be used (e.g. IntToString).

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (str) – The value to be randomised.

Returns:

The randomised value.

Return type:

str

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_state has to be fixed to an integer.

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (numpy array) – The data to be randomised.

Returns:

The randomised eigenvector.

Return type:

numpy array

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_state has to be fixed to an integer.

randomise(value=None)[source]

Select a candidate with differential privacy.

Parameters:

value (None) – Ignored.

Returns:

The randomised candidate.

Return type:

int or other

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_state has to be fixed to an integer.

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (str) – The value to be randomised.

Returns:

The randomised value.

Return type:

str

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_state has to be fixed to an integer.

Examples

Example hierarchies:

>>> flat_hierarchy = ["A", "B", "C", "D", "E"]
>>> nested_hierarchy = [["A"], ["B"], ["C"], ["D", "E"]]
randomise(value)

Randomise value with the mechanism.

Parameters:

value (str) – The value to be randomised.

Returns:

The randomised value.

Return type:

str

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_state has to be fixed to an integer.

randomise(value=None)[source]

Select a candidate with differential privacy.

Parameters:

value (None) – Ignored.

Returns:

The randomised candidate.

Return type:

int or other

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, use GaussianAnalytic.

  • 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_state has 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).

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value.

Return type:

float

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_state has to be fixed to an integer.

bias(value)

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

variance(value)

Returns the variance of the mechanism at a given value.

Parameters:

value (float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value.

Return type:

float

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int) – The value to be randomised.

Returns:

The randomised value.

Return type:

int

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value if defined, None otherwise.

Return type:

float or None

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int) – The value to be randomised.

Returns:

The randomised value.

Return type:

int

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value if defined, None otherwise.

Return type:

float or None

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_state has to be fixed to an integer.

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int) – The value to be randomised.

Returns:

The randomised value.

Return type:

int

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_state has to be fixed to an integer.

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (int) – The value to be randomised.

Returns:

The randomised value.

Return type:

int

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_state has 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).

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value.

Return type:

float

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value.

Return type:

float

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_state has 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).

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

effective_epsilon()[source]

Gets the effective epsilon of the mechanism, only for strict \(\epsilon\)-differential privacy. Returns None if \(\delta\) is non-zero.

Returns:

The effective \(\epsilon\) parameter of the mechanism. Returns None if delta is non-zero.

Return type:

float

mse(value)

Returns the mean squared error (MSE) of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the MSE of the mechanism is sought.

Returns:

bias – The MSE of the mechanism at value if defined, None otherwise.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

variance(value)[source]

Returns the variance of the mechanism at a given value.

Parameters:

value (float) – The value at which the variance of the mechanism is sought.

Returns:

bias – The variance of the mechanism at value.

Return type:

float

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_state has 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).

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

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 crlibm package 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_state has to be fixed to an integer.

References

[Mir12] (1,2)

Mironov, Ilya. “On significance of the least significant bits for differential privacy.” Proceedings of the 2012 ACM conference on Computer and communications security (2012).

effective_epsilon()[source]

Returns the effective value used in the Snapping mechanism to give the required \(\epsilon\)-DP, based on the bounds and the machine epsilon. Based on section 5.2 of [Mir12].

Returns:

The effective value of \(\epsilon\)

Return type:

float

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

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 LaplaceBoundedNoise mechanism 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_state has to be fixed to an integer.

bias(value)[source]

Returns the bias of the mechanism at a given value.

Parameters:

value (int or float) – The value at which the bias of the mechanism is sought.

Returns:

bias – The bias of the mechanism at value.

Return type:

float or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters:

value (float) – The value to be randomised.

Returns:

The randomised value.

Return type:

float

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_state has to be fixed to an integer.

randomise(value)[source]

Randomise value with the mechanism.

If value is a method of two outputs, they are taken as f and fprime (i.e., its gradient), and both are perturbed accordingly.

Parameters:

value (method) – The function to be randomised.

Returns:

The randomised method.

Return type:

method