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
andDPTransformer
, providing and specifying basic functionality.
deepcopy
()[source]¶ Produces a deep copy of the class.
 Returns
self – Returns the deep copy.
 Return type
class

set_epsilon
(epsilon)[source]¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

abstract
set_epsilon_delta
(epsilon, delta)[source]¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class


class
diffprivlib.mechanisms.
DPMechanism
[source]¶ Base class for all mechanisms. Instantiated from
DPMachine
.Notes
Each DPMechanism must define a randomise method, to handle the application of differential privacy
Mechanisms that only operate in a limited window of \(\epsilon\) or \(\delta\) must define a set_epsilon_delta method. Errorchecking, for example for nonzero \(\delta\) should be done in set_epsilon_delta; set_epsilon should be left unchanged.
When new methods are added, __repr__ should be updated accordingly in the mechanism.
Each mechanism’s

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

copy
()¶ Produces a copy of the class.
 Returns
self – Returns the copy.
 Return type
class

deepcopy
()¶ Produces a deep copy of the class.
 Returns
self – Returns the deep copy.
 Return type
class

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)[source]¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.

class
diffprivlib.mechanisms.
TruncationAndFoldingMixin
[source]¶ Mixin for truncating or folding the outputs of a mechanism. Must be instantiated with a
DPMechanism
.
Binary mechanism¶

class
diffprivlib.mechanisms.
Binary
[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
Notes
The binary attributes, known as labels, must be specified as strings. If nonstring labels are required (e.g. integervalued labels), a
DPTransformer
can be used (e.g.IntToString
).

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.

set_labels
(value0, value1)[source]¶ Sets the binary labels of the mechanism.
Labels must be unique, nonempty strings. If nonstring labels are required, consider using a
DPTransformer
.
Exponential mechanisms¶

class
diffprivlib.mechanisms.
Exponential
[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

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

get_utility_list
()[source]¶ Gets the utility list of the mechanism, in the same form as accepted by .set_utility_list.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_utility
(utility_list)[source]¶ Sets the utility function of the mechanism. The utility function is used to determine the probability of selecting an output for a given input.
The utility function is set by utility_list, which is a list of pairwise ‘distances’ between values in the mechanism’s domain. As the mechanisms’s domain is set by the values in utility_list, all possible pairs in utility_list must be accounted for. The utility function is symmetric, meaning the distance from a to b is the same as the distance from b to a. Setting the second distance will overwrite the first.
 Parameters
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.
 Returns
self
 Return type
class
 Raises
TypeError – If the value components of each tuple are not strings of if the utility component is not a float.
ValueError – If the utility component is zero or negative.


class
diffprivlib.mechanisms.
ExponentialHierarchical
[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.

check_inputs
(value)¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

get_utility_list
()¶ Gets the utility list of the mechanism, in the same form as accepted by .set_utility_list.

randomise
(value)¶ Randomise value with the mechanism.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_hierarchy
(list_hierarchy)[source]¶ Sets the hierarchy of the hierarchical exponential mechanism.
The hierarchy is specified as a list of lists, where each leaf node is a string, and lies at the same depth as each other leaf node. The utility between each leaf node is then calculated as
 Parameters
list_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.
 Returns
self
 Return type
class

Gaussian mechanisms¶

class
diffprivlib.mechanisms.
Gaussian
[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/TCS042

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

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


class
diffprivlib.mechanisms.
GaussianAnalytic
[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

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

get_bias
(value)¶ Returns the bias of the mechanism at a given value.

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

get_variance
(value)¶ Returns the variance of the mechanism at a given value.

randomise
(value)¶ Randomise value with the mechanism.


class
diffprivlib.mechanisms.
GaussianDiscrete
[source]¶ The Discrete Gaussian mechanism in differential privacy.
As proposed by Canonne, Kamath and Steinke, repurposed for approximate differential privacy.
Paper link: https://arxiv.org/pdf/2004.00010.pdf

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

Geometric mechanisms¶

class
diffprivlib.mechanisms.
Geometric
[source]¶ The classic geometric mechanism for differential privacy, as first proposed by Ghosh, Roughgarden and Sundararajan. Extended to allow for nonunity sensitivity.
Paper link: https://arxiv.org/pdf/0811.2841.pdf

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

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


class
diffprivlib.mechanisms.
GeometricTruncated
[source]¶ The truncated geometric mechanism, where values that fall outside a predescribed range are mapped back to the closest point within the range.

check_inputs
(value)¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_bounds
(lower, upper)[source]¶ Sets the lower and upper bounds of the mechanism.
For the truncated geometric mechanism, lower and upper must be integervalued. Must have lower <= upper.


class
diffprivlib.mechanisms.
GeometricFolded
[source]¶ The folded geometric mechanism, where values outside a predescribed range are folded back toward the domain around the closest point within the domain. Halfinteger bounds are permitted.

check_inputs
(value)¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_bounds
(lower, upper)[source]¶ Sets the lower and upper bounds of the mechanism.
For the folded geometric mechanism, lower and upper must be integer or halfinteger valued. Must have lower <= upper.

Laplace mechanisms¶

class
diffprivlib.mechanisms.
Laplace
[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

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

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

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.


class
diffprivlib.mechanisms.
LaplaceTruncated
[source]¶ The truncated Laplace mechanism, where values outside a predescribed domain are mapped to the closest point within the domain.

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

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

set_bounds
(lower, upper)¶ Sets the lower and upper bounds of the mechanism.
Must have lower <= upper.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.


class
diffprivlib.mechanisms.
LaplaceBoundedDomain
[source]¶ The bounded Laplace mechanism on a bounded domain. The mechanism draws values directly from the domain, without any postprocessing.

check_inputs
(value)¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

get_effective_epsilon
()[source]¶ Gets the effective epsilon of the mechanism, only for strict \(\epsilon\)differential privacy. Returns
None
if \(\delta\) is nonzero. Returns
The effective \(\epsilon\) parameter of the mechanism. Returns
None
if delta is nonzero. Return type

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

set_bounds
(lower, upper)¶ Sets the lower and upper bounds of the mechanism.
Must have lower <= upper.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.


class
diffprivlib.mechanisms.
LaplaceBoundedNoise
[source]¶ The Laplace mechanism with bounded noise, only applicable for approximate differential privacy (delta > 0).

check_inputs
(value)¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.


class
diffprivlib.mechanisms.
LaplaceFolded
[source]¶ The folded Laplace mechanism, where values outside a predescribed domain are folded around the domain until they fall within.

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_bounds
(lower, upper)¶ Sets the lower and upper bounds of the mechanism.
Must have lower <= upper.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_epsilon_delta
(epsilon, delta)¶ Sets the value of epsilon and delta to be used by the mechanism.
epsilon and delta cannot both be zero.
 Parameters
epsilon (float) – The value of epsilon for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have epsilon >= 0.
delta (float) –
The value of delta for achieving \((\epsilon,\delta)\)differential privacy with the mechanism. Must have 0 <= delta <= 1.
delta=0 gives strict (pure) differential privacy (\(\epsilon\)differential privacy). delta > 0 gives relaxed (approximate) differential privacy.
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is negative, or if delta falls outside [0,1], or if epsilon and delta are both zero.

Staircase mechanism¶

class
diffprivlib.mechanisms.
Staircase
[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
check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_gamma
(gamma)[source]¶ Sets the tuning parameter \(\gamma\) for the mechanism.
Must satisfy 0 <= gamma <= 1. If not set, gamma defaults to minimise the expectation of the amplitude of noise, .. math:: gamma = frac{1}{1 + e^{epsilon / 2}}
 Parameters
gamma (float) – Value of the tuning parameter gamma for the mechanism.
 Returns
self
 Return type
class
 Raises
TypeError – If gamma is not a float.
ValueError – If gamma is does not satisfy 0 <= gamma <= 1.

Uniform mechanism¶

class
diffprivlib.mechanisms.
Uniform
[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
check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

set_epsilon_delta
(epsilon, delta)[source]¶ Set privacy parameters \(\epsilon\) and \(\delta\) for the mechanism.
For the uniform mechanism, epsilon must be strictly zero and delta must satisfy 0 < delta <= 0.5.
 Parameters
 Returns
self
 Return type
class
 Raises
ValueError – If epsilon is nonzero or if delta does not satisfy 0 < delta <= 0.5.
TypeError – If epsilon or delta cannot be cast as floats.

Vector mechanism¶

class
diffprivlib.mechanisms.
Vector
[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

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.
 Parameters
value (method) – The value to be checked.
 Returns
 Return type
True if the mechanism is ready to be used.
 Raises
Exception – If parameters have not been set correctly, or if value falls outside the domain of the mechanism.

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

set_alpha
(alpha)[source]¶ Set the regularisation parameter \(\alpha\) for the mechanism.
alpha must be strictly positive. Default is 0.01.
 Parameters
alpha (float) – Regularisation parameter.
 Returns
self
 Return type
class

set_dimension
(vector_dim)[source]¶ Sets the dimension vector_dim of the domain of the mechanism.
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.
 Parameters
vector_dim (int) – Function input dimension.
 Returns
self
 Return type
class

set_epsilon
(epsilon)¶ Sets the value of epsilon to be used by the mechanism.
 Parameters
epsilon (float) – The value of epsilon for achieving \(\epsilon\)differential privacy with the mechanism. Must have epsilon > 0.
 Returns
self
 Return type
class

set_sensitivity
(function_sensitivity, data_sensitivity=1)[source]¶ Sets the sensitivity of the function and data being processed by the mechanism.
The sensitivity of the function relates to the max of its second derivative. Must be strictly positive.
The sensitivity of the data relates to the max 2norm of each row. Must be strictly positive.

Wishart mechanism¶

class
diffprivlib.mechanisms.
Wishart
[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/

check_inputs
(value)[source]¶ Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.
 Parameters
value (method) – The value to be checked.
 Returns
 Return type
True if the mechanism is ready to be used.
 Raises
Exception – If parameters have not been set correctly, or if value falls outside the domain of the mechanism.

randomise
(value)[source]¶ Randomise value with the mechanism.
 Parameters
value (numpy array) – The data to be randomised.
 Returns
The randomised array.
 Return type
numpy array
