diffprivlib.accountant

Privacy budget accountant for differential privacy

Base class

class diffprivlib.accountant.BudgetAccountant(epsilon=inf, delta=1.0, slack=0.0, spent_budget=None)

Privacy budget accountant for differential privacy.

This class creates a privacy budget accountant to track privacy spend across queries and other data accesses. Once initialised, the BudgetAccountant stores each privacy spend and iteratively updates the total budget spend, raising an error when the budget ceiling (if specified) is exceeded. The accountant can be initialised without any maximum budget, to enable users track the total privacy spend of their actions without hindrance.

Diffprivlib functions can make use of a BudgetAccountant in three different ways (see examples for more details):

• Passed as an accountant parameter to the function (e.g., mean(..., accountant=acc))

• Set as the default using the set_default() method (all subsequent diffprivlib functions will use the accountant by default)

• As a context manager using a with statement (the accountant is used for that block of code)

Implements the accountant rules as given in [KOV17].

Parameters:

• epsilon (float, default: infinity) – Epsilon budget ceiling of the accountant.

• delta (float, default: 1.0) – Delta budget ceiling of the accountant.

• slack (float, default: 0.0) – Slack allowed in delta spend. Greater slack may reduce the overall epsilon spend.

• spent_budget (list of tuples of the form (epsilon, delta), optional) – List of tuples of pre-existing budget spends. Allows for a new accountant to be initialised with spends extracted from a previous instance.

epsilon

Epsilon budget ceiling of the accountant.

Type:

float

delta

Delta budget ceiling of the accountant.

Type:

float

slack

The accountant’s slack. Can be modified at runtime, subject to the privacy budget not being exceeded.

Type:

float

spent_budget

The list of privacy spends recorded by the accountant. Can be used in the initialisation of a new accountant.

Type:

list of tuples of the form (epsilon, delta)

Examples

A BudgetAccountant is typically passed to diffprivlib functions as an accountant parameter. If epsilon and delta are not set, the accountant has an infinite budget by default, allowing you to track privacy spend without imposing a hard limit. By allowing a slack in the budget calculation, the overall epsilon privacy spend can be reduced (at the cost of extra delta spend).

>>> import diffprivlib as dp
>>> from numpy.random import random
>>> X = random(100)
>>> acc = dp.BudgetAccountant(epsilon=1.5, delta=0)
>>> dp.tools.mean(X, bounds=(0, 1), accountant=acc)
0.4547006207923884
>>> acc.total()
(epsilon=1.0, delta=0)
>>> dp.tools.std(X, bounds=(0, 1), epsilon=0.25, accountant=acc)
0.2630216611181259
>>> acc.total()
(epsilon=1.25, delta=0)

>>> acc2 = dp.BudgetAccountant() # infinite budget
>>> first_half = dp.tools.mean(X[:50], epsilon=0.25, bounds=(0, 1), accountant=acc2)
>>> last_half = dp.tools.mean(X[50:], epsilon=0.25, bounds=(0, 1), accountant=acc2)
>>> acc2.total()
(epsilon=0.5, delta=0)
>>> acc2.remaining()
(epsilon=inf, delta=1.0)

>>> acc3 = dp.BudgetAccountant(slack=1e-3)
>>> for i in range(20):
...     dp.tools.mean(X, epsilon=0.05, bounds=(0, 1), accountant=acc3)
>>> acc3.total() # Slack has reduced the epsilon spend by almost 25%
(epsilon=0.7613352285668463, delta=0.001)

Using set_default(), an accountant is used by default in all diffprivlib functions in that script. Accountants also act as context managers, allowing for use in a with statement. Passing an accountant as a parameter overrides all other methods.

>>> acc4 = dp.BudgetAccountant()
>>> acc4.set_default()
BudgetAccountant()
>>> Y = random((100, 2)) - 0.5
>>> clf = dp.models.PCA(1, centered=True, data_norm=1.4)
>>> clf.fit(Y)
PCA(accountant=BudgetAccountant(spent_budget=[(1.0, 0)]), centered=True, copy=True, data_norm=1.4, epsilon=1.0,
n_components=1, random_state=None, bounds=None, whiten=False)
>>> acc4.total()
(epsilon=1.0, delta=0)

>>> with dp.BudgetAccountant() as acc5:
...     dp.tools.mean(Y, bounds=(0, 1), epsilon=1/3)
>>> acc5.total()
(epsilon=0.3333333333333333, delta=0)

References

[KOV17]

Kairouz, Peter, Sewoong Oh, and Pramod Viswanath. “The composition theorem for differential privacy.” IEEE Transactions on Information Theory 63.6 (2017): 4037-4049.

check(epsilon, delta)

Checks if the provided (epsilon,delta) can be spent without exceeding the accountant’s budget ceiling.

Parameters:

• epsilon (float) – Epsilon budget spend to check.

• delta (float) – Delta budget spend to check.

Returns:

True if the budget can be spent, otherwise a BudgetError is raised.

Return type:

bool

Raises:

BudgetError – If the specified budget spend will result in the budget ceiling being exceeded.

static load_default(accountant)

Loads the default privacy budget accountant if none is supplied, otherwise checks that the supplied accountant is a BudgetAccountant class.

An accountant can be set as the default using the set_default() method. If no default has been set, a default is created.

Parameters:

accountant (BudgetAccountant or None) – The supplied budget accountant. If None, the default accountant is returned.

Returns:

default – Returns a working BudgetAccountant, either the supplied accountant or the existing default.

Return type:

BudgetAccountant

static pop_default()

Pops the default BudgetAccountant from the class and returns it to the user.

Returns:

default – Returns the existing default BudgetAccountant.

Return type:

BudgetAccountant

remaining(k=1)

Calculates the budget that remains to be spent.

Calculates the privacy budget that can be spent on k queries. Spending this budget on k queries will match the budget ceiling, assuming no floating point errors.

Parameters:

k (int, default: 1) – The number of queries for which to calculate the remaining budget.

Returns:

• epsilon (float) – Total epsilon spend remaining for k queries.

• delta (float) – Total delta spend remaining for k queries.

set_default()

Sets the current accountant to be the default when running functions and queries with diffprivlib.

Returns:

self

Return type:

BudgetAccountant

spend(epsilon, delta)

Spend the given privacy budget.

Instructs the accountant to spend the given epsilon and delta privacy budget, while ensuring the target budget is not exceeded.

Parameters:

• epsilon (float) – Epsilon privacy budget to spend.

• delta (float) – Delta privacy budget to spend.

Returns:

self

Return type:

BudgetAccountant

total(spent_budget=None, slack=None)

Returns the total current privacy spend.

spent_budget and slack can be specified as parameters, otherwise the class values will be used.

Parameters:

• spent_budget (list of tuples of the form (epsilon, delta), optional) – List of tuples of budget spends. If not provided, the accountant’s spends will be used.

• slack (float, optional) – Slack in delta for composition. If not provided, the accountant’s slack will be used.

Returns:

• epsilon (float) – Total epsilon spend.

• delta (float) – Total delta spend.