measures#
Module containing supported variants for differential privacy.
Classes#
Base class for output measures. |
|
The distance between distributions in “pure” differential privacy. |
|
The distance between distributions in approximate differential privacy. |
|
The distance between distributions in ρ-Zero Concentrated Differential Privacy. |
|
An abstract class for representing a privacy budget. |
|
A pure dp budget. |
|
An approximate dp budget. |
|
A zCDP budget. |
- class Measure#
Bases:
abc.ABCBase class for output measures.
Each measure defines a way of measuring “distance” between two distributions that corresponds to a te guarantees of a variant of differential privacy. Note that these “distances” are not metrics.
- abstract validate(value)#
Raises an error if value not a valid distance.
- Parameters
value (Any) – A distance between two probability distributions under this measure.
- Return type
None
- class PureDP#
Bases:
MeasureThe distance between distributions in “pure” differential privacy.
As in Definition 1 of [DMNS06].
In particular, under this measure the distance \(\epsilon\) between two distributions \(X\) and \(Y\) with the same range is:
\[\epsilon = max_{S \subseteq Range(X)}\left(max\left( ln\left(\frac{Pr[X \in S]}{Pr[Y \in S]}\right), ln\left(\frac{Pr[Y \in S]}{Pr[X \in S]}\right)\right)\right)\]- validate(value)#
Raises an error if value not a valid distance.
value must be a nonnegative real or infinity
- Parameters
value (tmlt.core.utils.exact_number.ExactNumberInput) – A distance between two probability distributions under this measure.
- Return type
None
- compare(value1, value2)#
Returns True if value1 is less than or equal to value2.
- Parameters
value1 (tmlt.core.utils.exact_number.ExactNumberInput) –
value2 (tmlt.core.utils.exact_number.ExactNumberInput) –
- Return type
- class ApproxDP#
Bases:
MeasureThe distance between distributions in approximate differential privacy.
As introduced in [DKM+06].
In particular, under this measure valid distances \((\epsilon, \delta)\) between two distributions \(X\) and \(Y\) with the same range are those \((\epsilon, \delta)\) satisfying:
\[\epsilon = max_{S \subseteq Range(X)}\left(max\left( ln\left(\frac{Pr[X \in S] - \delta}{Pr[Y \in S]}\right), ln\left(\frac{Pr[Y \in S] - \delta}{Pr[X \in S]}\right)\right)\right)\]- validate(value)#
Raises an error if value not a valid distance.
value must be a tuple with two values: (epsilon, delta)
epsilon must be a nonnegative real or infinity
delta must be a real between 0 and 1 (inclusive)
- Parameters
value (Tuple[tmlt.core.utils.exact_number.ExactNumberInput, tmlt.core.utils.exact_number.ExactNumberInput]) – A distance between two probability distributions under this measure.
- Return type
None
- compare(value1, value2)#
Returns True if value1 is less than or equal to value2.
- Parameters
value1 (Tuple[tmlt.core.utils.exact_number.ExactNumberInput, tmlt.core.utils.exact_number.ExactNumberInput]) –
value2 (Tuple[tmlt.core.utils.exact_number.ExactNumberInput, tmlt.core.utils.exact_number.ExactNumberInput]) –
- Return type
- class RhoZCDP#
Bases:
MeasureThe distance between distributions in ρ-Zero Concentrated Differential Privacy.
As in Definition 1.1 of [BS16].
In particular, under this measure the distance \(\rho\) between two distributions \(X\) and \(Y\) with the same range is:
\[\rho = max_{\alpha \in (1, \infty)}\left(max\left( \frac{D_{\alpha}(X||Y)}{\alpha}, \frac{D_{\alpha}(Y||X)}{\alpha}\right)\right)\]where \(D_{\alpha}(X||Y)\) is the α-Rényi divergence between X and Y.
- validate(value)#
Raises an error if value not a valid distance.
value must be a nonnegative real or infinity
- Parameters
value (tmlt.core.utils.exact_number.ExactNumberInput) – A distance between two probability distributions under this measure.
- Return type
None
- compare(value1, value2)#
Returns True if value1 is less than or equal to value2.
- Parameters
value1 (tmlt.core.utils.exact_number.ExactNumberInput) –
value2 (tmlt.core.utils.exact_number.ExactNumberInput) –
- Return type
- class PrivacyBudget(value)#
Bases:
abc.ABCAn abstract class for representing a privacy budget.
This class is meant to allow operations on a budget (e.g. subtracting, checking if the budget is infinite) without needing to know the type of the budget.
- Parameters
value (PrivacyBudgetInput) –
- abstract __init__(value)#
Initializes the privacy budget.
- Parameters
value (
ExactNumber|float|int|str|Fraction|Expr|Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]Union[ExactNumber,float,int,str,Fraction,Expr,Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]]) – The value of the privacy budget.- Return type
None
- classmethod cast(measure: RhoZCDP, value: PrivacyBudgetInput) RhoZCDPBudget#
- classmethod cast(measure: PureDP, value: PrivacyBudgetInput) PureDPBudget
- classmethod cast(measure: ApproxDP, value: PrivacyBudgetInput) ApproxDPBudget
Return a privacy budget matching the passed measure.
- Parameters
measure – The measure to return a privacy budget for.
value – The value of the privacy budget.
- property value#
Return the value of the privacy budget.
- Return type
PrivacyBudgetValue
- abstract assert_can_spend_budget(other)#
Return true iff we can spend budget other. Otherwise, raise an error.
- Parameters
other (PrivacyBudgetInput) – The privacy budget we would like to spend.
- Return type
None
- abstract subtract(other)#
Return a new budget after subtracting other.
If the budget represented by this class is infinite, return the current budget.
- Parameters
other (PrivacyBudgetInput) – The privacy budget to subtract.
- Raises
ValueError – If there is not enough privacy budget to subtract other.
- Return type
- class PureDPBudget(value)#
Bases:
PrivacyBudgetA pure dp budget.
- Parameters
value (PrivacyBudgetInput) –
- __init__(value)#
Initialize.
- Parameters
value (
ExactNumber|float|int|str|Fraction|Expr|Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]Union[ExactNumber,float,int,str,Fraction,Expr,Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]]) – The value of the privacy budget.- Return type
None
- property value#
Return the value of the privacy budget.
- Return type
- property epsilon#
The pure dp privacy loss.
- Return type
- assert_can_spend_budget(other)#
Return true iff we can spend budget other. Otherwise, raise an error.
- Parameters
other (PrivacyBudgetInput) – The privacy budget we would like to spend.
- Return type
None
- subtract(other)#
Return a new budget after subtracting other.
If the budget represented by this class is infinite, return the current budget.
- Parameters
other (PrivacyBudgetInput) – The privacy budget to subtract.
- Raises
ValueError – If there is not enough privacy budget to subtract other.
- Return type
- classmethod cast(measure: RhoZCDP, value: PrivacyBudgetInput) RhoZCDPBudget#
- classmethod cast(measure: PureDP, value: PrivacyBudgetInput) PureDPBudget
- classmethod cast(measure: ApproxDP, value: PrivacyBudgetInput) ApproxDPBudget
Return a privacy budget matching the passed measure.
- Parameters
measure – The measure to return a privacy budget for.
value – The value of the privacy budget.
- class ApproxDPBudget(value)#
Bases:
PrivacyBudgetAn approximate dp budget.
- Parameters
value (PrivacyBudgetInput) –
- __init__(value)#
Initialize.
- Parameters
value (
ExactNumber|float|int|str|Fraction|Expr|Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]Union[ExactNumber,float,int,str,Fraction,Expr,Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]]) – The value of the privacy budget.- Return type
None
- property value#
Return the value of the privacy budget.
- Return type
Tuple[tmlt.core.utils.exact_number.ExactNumber, tmlt.core.utils.exact_number.ExactNumber]
- property epsilon#
The first component of the privacy loss.
- Return type
- property delta#
The second component of the privacy loss.
- Return type
- assert_can_spend_budget(other)#
Return true iff we can spend budget other. Otherwise, raise an error.
- Parameters
other (PrivacyBudgetInput) – The privacy budget we would like to spend.
- Return type
None
- subtract(other)#
Return a new budget after subtracting other.
If the budget represented by this class is infinite, return the current budget.
- Parameters
other (PrivacyBudgetInput) – The privacy budget to subtract.
- Raises
ValueError – If there is not enough privacy budget to subtract other.
- Return type
- classmethod cast(measure: RhoZCDP, value: PrivacyBudgetInput) RhoZCDPBudget#
- classmethod cast(measure: PureDP, value: PrivacyBudgetInput) PureDPBudget
- classmethod cast(measure: ApproxDP, value: PrivacyBudgetInput) ApproxDPBudget
Return a privacy budget matching the passed measure.
- Parameters
measure – The measure to return a privacy budget for.
value – The value of the privacy budget.
- class RhoZCDPBudget(value)#
Bases:
PrivacyBudgetA zCDP budget.
- Parameters
value (PrivacyBudgetInput) –
- __init__(value)#
Initialize.
- Parameters
value (
ExactNumber|float|int|str|Fraction|Expr|Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]Union[ExactNumber,float,int,str,Fraction,Expr,Tuple[Union[ExactNumber,float,int,str,Fraction,Expr],Union[ExactNumber,float,int,str,Fraction,Expr]]]) – The value of the privacy budget.- Return type
None
- property value#
Return the value of the privacy budget.
- Return type
- property rho#
The zCDP privacy loss.
- Return type
- assert_can_spend_budget(other)#
Return true iff we can spend budget other. Otherwise, raise an error.
- Parameters
other (PrivacyBudgetInput) – The privacy budget we would like to spend.
- Return type
None
- subtract(other)#
Return a new budget after subtracting other.
If the budget represented by this class is infinite, return the current budget.
- Parameters
other (PrivacyBudgetInput) – The privacy budget to subtract.
- Raises
ValueError – If there is not enough privacy budget to subtract other.
- Return type
- classmethod cast(measure: RhoZCDP, value: PrivacyBudgetInput) RhoZCDPBudget#
- classmethod cast(measure: PureDP, value: PrivacyBudgetInput) PureDPBudget
- classmethod cast(measure: ApproxDP, value: PrivacyBudgetInput) ApproxDPBudget
Return a privacy budget matching the passed measure.
- Parameters
measure – The measure to return a privacy budget for.
value – The value of the privacy budget.
Exceptions#
- exception InsufficientBudgetError(remaining_budget, requested_budget)#
Bases:
ValueErrorException raised when there is not enough budget to perform an operation.
The PrivacyBudget will raise this exception when an operation requests more budget than is remaining.
- Parameters
remaining_budget (PrivacyBudget) –
requested_budget (PrivacyBudget) –