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

deepcopy()[source]

Produces a deep copy of the class.

Returns

self – Returns the deep 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

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. Error-checking, for example for non-zero \(\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.

Parameters

value (int or float or str or 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.

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

get_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

get_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

get_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

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

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.

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 (float) –

Returns

Return type

True if the mechanism is ready to be used.

set_bounds(lower, upper)[source]

Sets the lower and upper bounds of the mechanism.

Must have lower <= upper.

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

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

Returns

self

Return type

class

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 non-string labels are required (e.g. integer-valued 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.

Parameters

value (str) – 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 (str) – The value to be randomised.

Returns

The randomised value.

Return type

str

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, non-empty strings. If non-string labels are required, consider using a DPTransformer.

Parameters
  • value0 (str) – 0th binary label.

  • value1 (str) – 1st binary label.

Returns

self

Return type

class

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.

Parameters

value (str) – 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.

get_utility_list()[source]

Gets the utility list of the mechanism, in the same form as accepted by .set_utility_list.

Returns

utility_list – Returns a list of tuples of the form (“value1”, “value2”, utility), or None if the utility has not yet been set.

Return type

list of tuples (str, str, float), or None

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (str) – The value to be randomised.

Returns

The randomised value.

Return type

str

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.

Parameters

value (str) – 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.

get_utility_list()

Gets the utility list of the mechanism, in the same form as accepted by .set_utility_list.

Returns

utility_list – Returns a list of tuples of the form (“value1”, “value2”, utility), or None if the utility has not yet been set.

Return type

list of tuples (str, str, float), or None

randomise(value)

Randomise value with the mechanism.

Parameters

value (str) – The value to be randomised.

Returns

The randomised value.

Return type

str

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/TCS-042

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 (float) – 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.

get_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

get_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

get_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

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (float) – The value to be randomised.

Returns

The randomised value.

Return type

float

set_epsilon_delta(epsilon, delta)[source]

Sets the privacy parameters \(\epsilon\) and \(\delta\) for the mechanism.

For the Gaussian mechanism, epsilon cannot be greater than 1, and delta must be non-zero.

Parameters
  • epsilon (float) – Epsilon value of the mechanism. Must satisfy 0 < epsilon <= 1.

  • delta (float) – Delta value of the mechanism. Must satisfy 0 < delta <= 1.

Returns

self

Return type

class

set_sensitivity(sensitivity)[source]

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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.

Parameters

value (float) – 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.

get_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

get_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

get_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

randomise(value)

Randomise value with the mechanism.

Parameters

value (float) – The value to be randomised.

Returns

The randomised value.

Return type

float

set_epsilon_delta(epsilon, delta)[source]

Sets the privacy parameters \(\epsilon\) and \(\delta\) for the mechanism.

For the analytic Gaussian mechanism, epsilon and delta must be non-zero.

Parameters
  • epsilon (float) – Epsilon value of the mechanism. Must satisfy 0 < epsilon.

  • delta (float) – Delta value of the mechanism. Must satisfy 0 < delta < 1.

Returns

self

Return type

class

set_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

class diffprivlib.mechanisms.GaussianDiscrete[source]

The Discrete Gaussian mechanism in differential privacy.

As proposed by Canonne, Kamath and Steinke, re-purposed 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.

Parameters

value (int) – 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.

get_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

set_epsilon_delta(epsilon, delta)[source]

Sets the privacy parameters \(\epsilon\) and \(\delta\) for the mechanism.

For the discrete Gaussian mechanism, epsilon and delta must be non-zero.

Parameters
  • epsilon (float) – Epsilon value of the mechanism. Must satisfy 0 < epsilon.

  • delta (float) – Delta value of the mechanism. Must satisfy 0 < delta < 1.

Returns

self

Return type

class

set_sensitivity(sensitivity)[source]

Sets the sensitivity of the mechanism.

Parameters

sensitivity (int) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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 non-unity 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.

Parameters

value (int) – 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.

get_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

get_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

get_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

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (int) – The value to be randomised.

Returns

The randomised value.

Return type

int

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(sensitivity)[source]

Sets the sensitivity of the mechanism.

Parameters

sensitivity (int) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

class diffprivlib.mechanisms.GeometricTruncated[source]

The truncated geometric mechanism, where values that fall outside a pre-described 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.

Parameters

value (int) – 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 (int) – The value to be randomised.

Returns

The randomised value.

Return type

int

set_bounds(lower, upper)[source]

Sets the lower and upper bounds of the mechanism.

For the truncated geometric mechanism, lower and upper must be integer-valued. Must have lower <= upper.

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

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

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(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (int) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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

check_inputs(value)

Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

Parameters

value (int) – 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 (int) – The value to be randomised.

Returns

The randomised value.

Return type

int

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 half-integer -valued. Must have lower <= upper.

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

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

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(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (int) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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.

Parameters

value (float) – 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.

get_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

get_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

get_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

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (float) – The value to be randomised.

Returns

The randomised value.

Return type

float

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_sensitivity(sensitivity)[source]

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

class diffprivlib.mechanisms.LaplaceTruncated[source]

The truncated Laplace mechanism, where values outside a pre-described 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.

Parameters

value (float) – 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.

get_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

get_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

get_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

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (float) – The value to be randomised.

Returns

The randomised value.

Return type

float

set_bounds(lower, upper)

Sets the lower and upper bounds of the mechanism.

Must have lower <= upper.

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

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

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_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_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

class diffprivlib.mechanisms.LaplaceBoundedDomain[source]

The bounded Laplace mechanism on a bounded domain. The mechanism draws values directly from the domain, without any post-processing.

check_inputs(value)

Checks that all parameters of the mechanism have been initialised correctly, and that the mechanism is ready to be used.

Parameters

value (float) – 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.

get_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

get_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

get_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

get_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

randomise(value)[source]

Randomise value with the mechanism.

Parameters

value (float) – The value to be randomised.

Returns

The randomised value.

Return type

float

set_bounds(lower, upper)

Sets the lower and upper bounds of the mechanism.

Must have lower <= upper.

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

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

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_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_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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.

Parameters

value (float) – 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.

get_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

set_epsilon_delta(epsilon, delta)[source]

Set the privacy parameters \(\epsilon\) and \(\delta\) for the mechanism.

Epsilon must be strictly positive, epsilon > 0. delta must be strictly in the interval (0, 0.5).
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 < 0.5.

Returns

self

Return type

class

set_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

class diffprivlib.mechanisms.LaplaceFolded[source]

The folded Laplace mechanism, where values outside a pre-described 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.

Parameters

value (float) – 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.

get_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

set_bounds(lower, upper)

Sets the lower and upper bounds of the mechanism.

Must have lower <= upper.

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

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

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_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_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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.

Parameters

value (float) – 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.

get_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

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.

set_sensitivity(sensitivity)

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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.

Parameters

value (float) – 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.

get_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

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
  • epsilon (float) – For the uniform mechanism, epsilon must be strictly zero.

  • delta (float) – For the uniform mechanism, delta must satisfy 0 < delta <= 0.5.

Returns

self

Return type

class

Raises
  • ValueError – If epsilon is non-zero or if delta does not satisfy 0 < delta <= 0.5.

  • TypeError – If epsilon or delta cannot be cast as floats.

set_sensitivity(sensitivity)[source]

Sets the sensitivity of the mechanism.

Parameters

sensitivity (float) – The sensitivity of the mechanism. Must satisfy sensitivity > 0.

Returns

self

Return type

class

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 2-norm of each row. Must be strictly positive.

Parameters
  • function_sensitivity (float) – The function sensitivity of the mechanism.

  • data_sensitivity (float, default: 1.0) – The data sensitivity of the mechanism.

Returns

self

Return type

class

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

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(sensitivity)[source]

Sets the l2-norm sensitivity of the data being processed by the mechanism.

Parameters

sensitivity (float) – The maximum l2-norm of the data.

Returns

self

Return type

class