Utilities and general functions

Basic functions and other utilities for the differential privacy library

Exceptions and warnings

exception diffprivlib.utils.PrivacyLeakWarning[source]

Custom warning to capture privacy leaks resulting from incorrect parameter setting.

For example, this warning may occur when the user:

  • fails to specify the bounds or range of data to a model where required (e.g., bounds=None to GaussianNB).

  • inputs data to a model that falls outside the bounds or range originally specified.

exception diffprivlib.utils.DiffprivlibCompatibilityWarning[source]

Custom warning to capture inherited class arguments that are not compatible with diffprivlib.

The purpose of the warning is to alert the user of the incompatibility, but to continue execution having fixed the incompatibility at runtime.

For example, this warning may occur when the user:

  • passes a parameter value that is not compatible with diffprivlib (e.g., solver=’liblinear’ to LogisticRegression)

  • specifies a non-default value for a parameter that is ignored by diffprivlib (e.g., intercept_scaling=0.5 to LogisticRegression.

exception diffprivlib.utils.BudgetError[source]

Custom exception to capture the privacy budget being exceeded, typically controlled by a BudgetAccountant.

For example, this exception may be raised when the user:

  • Attempts to execute a query which would exceed the privacy budget of the accountant.

  • Attempts to change the slack of the accountant in such a way that the existing budget spends would exceed the accountant’s budget.

General classes

class diffprivlib.utils.Budget(epsilon, delta)[source]

Custom tuple subclass for privacy budgets of the form (epsilon, delta).

The Budget class allows for correct comparison/ordering of privacy budget, ensuring that both epsilon and delta satisfy the comparison (tuples are compared lexicographically). Additionally, tuples are represented with added verbosity, labelling epsilon and delta appropriately.

Examples

>>> from diffprivlib.utils import Budget
>>> Budget(1, 0.5)
(epsilon=1, delta=0.5)
>>> Budget(2, 0) >= Budget(1, 0.5)
False
>>> (2, 0) >= (1, 0.5) # Tuples are compared with lexicographic ordering
True

General functions

diffprivlib.utils.check_random_state(seed, secure=False)[source]

Turn seed into a np.random.RandomState or secrets.SystemRandom instance.

If secure=True, and seed is None (or was generated from a previous None seed), then secrets is used. Otherwise a np.random.RandomState is used.

Parameters:
  • seed (None, int or instance of RandomState) – If seed is None and secure is False, return the RandomState singleton used by np.random. If seed is None and secure is True, return a SystemRandom instance from secrets. If seed is an int, return a new RandomState instance seeded with seed. If seed is already a RandomState or SystemRandom instance, return it. Otherwise raise ValueError.

  • secure (bool, default: False) – Specifies if a secure random number generator from secrets can be used.

diffprivlib.utils.copy_docstring(source)[source]

Decorator function to copy a docstring from a source function to a target function.

The docstring is only copied if a docstring is present in source, and if none is present in target. Takes inspiration from similar in matplotlib.

Parameters:

source (method) – Source function from which to copy the docstring. If source.__doc__ is empty, do nothing.

Returns:

target – Target function with new docstring.

Return type:

method

diffprivlib.utils.warn_unused_args(args)[source]

Warn the user about supplying unused args to a diffprivlib model.

Arguments can be supplied as a string, a list of strings, or a dictionary as supplied to kwargs.

Parameters:

args (str or list or dict) – Arguments for which warnings should be thrown.

Return type:

None