interactive_measurements#

Measurements that allow interactively submitting queries to a private dataset.

Functions#

create_adaptive_composition()

Returns a measurement to launch a DecoratedQueryable.

create_adaptive_composition(input_domain, input_metric, d_in, privacy_budget, output_measure)#

Returns a measurement to launch a DecoratedQueryable.

Returned DecoratedQueryable allows transforming the private data and answering non-interactive MeasurementQuerys as long as the cumulative privacy budget spent does not exceed privacy_budget.

Parameters

input_domain (tmlt.core.domains.base.Domain) – Domain of input datasets.
input_metric (tmlt.core.metrics.Metric) – Distance metric for input datasets.
d_in (Any) – Input metric value for inputs.
privacy_budget (tmlt.core.measures.PrivacyBudgetInput) – Total privacy budget across all measurements.
output_measure (Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]) – Distance measure for measurement’s output.

Return type

DecorateQueryable

Classes#

`Queryable`	Base class for Queryables.
`MeasurementQuery`	Contains a Measurement and the d_out it satisfies.
`TransformationQuery`	Contains a Transformation and the d_out it satisfies.
`IndexQuery`	Contains the index of measurement to be answered.
`RetireQuery`	Query for retiring a RetirableQueryable.
`RetirableQueryable`	Wraps another Queryable and allows retiring all descendant Queryables.
`SequentialQueryable`	Answers interactive measurement queries sequentially.
`ParallelQueryable`	Answers index queries on partitions.
`GetAnswerQueryable`	Returns answer obtained from a non-interactive measurement.
`DecoratedQueryable`	Allows modifying the query to and the answer from a Queryable.
`DecorateQueryable`	Creates a `DecoratedQueryable`.
`SequentialComposition`	Creates a `SequentialQueryable`.
`ParallelComposition`	Creates a `ParallelQueryable`.
`MakeInteractive`	Creates a `GetAnswerQueryable`.
`PrivacyAccountantState`	All possible states for a `PrivacyAccountant`.
`PrivacyAccountant`	An interface for adaptively composing measurements across transformed datasets.

class Queryable#

Bases: abc.ABC

Base class for Queryables.

Note

All subclasses of Queryable should have exactly one public method: __call__.

abstract __call__(query)#

Returns answer to given query.

Parameters: query (Any) –
Return type: Any

class MeasurementQuery#

Contains a Measurement and the d_out it satisfies.

Note

The d_in is known by the Queryable.

Used by

SequentialQueryable

measurement :tmlt.core.measurements.base.Measurement#: The measurement to answer.

d_out :Optional[Any]#

The output measure value satisfied by measurement.

It is only required if the measurement’s privacy_function() raises NotImplementedError.

class TransformationQuery#

Contains a Transformation and the d_out it satisfies.

Note

The d_in is known by the Queryable.

Used by

SequentialQueryable

transformation :tmlt.core.transformations.base.Transformation#: The transformation to apply.

d_out :Optional[Any]#

The output metric value satisfied by the transformation.

It is only required if the transformations’s Transformation.stability_function() raises NotImplementedError.

class IndexQuery#

Contains the index of measurement to be answered.

Used by

ParallelQueryable

class RetireQuery#

Query for retiring a RetirableQueryable.

Used by

RetirableQueryable

class RetirableQueryable(queryable)#

Bases: Queryable

Wraps another Queryable and allows retiring all descendant Queryables.

A RetirableQueryable can be initialized with any instance of Queryable and can be in one of two internal states: “active” or “retired”.

All descendant Queryables of a RetirableQueryable are instances of RetirableQueryable. The __call__ method on RetirableQueryable accepts a special RetireQuery query that retires itself and all descendant Queryables.

Submitting a query q to a RetirableQueryable RQ has the following behavior:

If q is a RetireQuery, RQ submits a RetireQuery to

each child RetirableQueryable, changes its state to “retired”

and returns None.

If q is not a RetireQuery and RQ is “active”, it obtains

an answer A by submitting q to its inner Queryable.

If A is not a Queryable, RQ returns A.

Otherwise, RQ constructs and returns a new RetirableQueryable with

Queryable A.

If q is not a RetireQuery and RQ is “retired”, an error is

raised.

Parameters: queryable (Queryable) –

__init__(queryable)#

Constructor.

Arg:: queryable: Queryable to be wrapped.

Parameters: queryable (tmlt.core.measurements.interactive_measurements.Queryable) –

__call__(query)#

Answers query.

If query is RetireQuery, this queryable and all descendant queryables are retired. Otherwise, the query is routed to the wrapped queryable.

Parameters: query (Any) –
Return type: Any

class SequentialQueryable(input_domain, input_metric, d_in, output_measure, privacy_budget, data)#

Bases: Queryable

Answers interactive measurement queries sequentially.

All interactions with a Queryable obtained from answering an interactive measurement must be completed before a second interactive measurement can be answered.

Parameters

input_domain (tmlt.core.domains.base.Domain) –
input_metric (tmlt.core.metrics.Metric) –
d_in (Any) –
output_measure (Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]) –
privacy_budget (tmlt.core.measures.PrivacyBudgetInput) –
data (Any) –

__init__(input_domain, input_metric, d_in, output_measure, privacy_budget, data)#

Constructor.

Parameters

input_domain (DomainDomain) – Domain of data being queried.
input_metric (MetricMetric) – Distance metric for input_domain.
d_in (AnyAny) – Input metric value for inputs.
output_measure (PureDP | ApproxDP | RhoZCDPUnion[PureDP, ApproxDP, RhoZCDP]) – Distance measure on output.
privacy_budget (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]]]) – Total privacy budget across all queries.
data (AnyAny) – Data to be queried.

__call__(query)#

Answers the query.

Parameters: query (Union[MeasurementQuery, TransformationQuery]) –
Return type: Optional[RetirableQueryable]

class ParallelQueryable(data, measurements)#

Bases: Queryable

Answers index queries on partitions.

Parameters

data (List) –
measurements (List[tmlt.core.measurements.base.Measurement]) –

__init__(data, measurements)#

Constructor.

Parameters

data (ListList) – Data being queried.
measurements (List[Measurement]List[Measurement]) – List of measurements to be answered on each list element.

__call__(query)#

Answers IndexQuerys.

Parameters: query (IndexQuery) –
Return type: Any

class GetAnswerQueryable(measurement, data)#

Bases: Queryable

Returns answer obtained from a non-interactive measurement.

Parameters

measurement (tmlt.core.measurements.base.Measurement) –
data (Any) –

__init__(measurement, data)#

Constructor.

Parameters

measurement (tmlt.core.measurements.base.Measurement) –
data (Any) –

__call__(query)#

Returns answer.

Parameters: query (None) –
Return type: Any

class DecoratedQueryable(queryable, preprocess_query, postprocess_answer)#

Bases: Queryable

Allows modifying the query to and the answer from a Queryable.

The privacy guarantee for DecoratedQueryable depends on the passed function postprocess_answer satisfying certain properties. In particular, postprocess_answer should not use distinguishing pseudo-side channel information, and should be well-defined on its abstract domain. See Postprocessing udfs and pseudo-side channel information.

Parameters

queryable (Queryable) –
preprocess_query (Callable[[Any], Any]) –
postprocess_answer (Callable[[Any], Any]) –

__init__(queryable, preprocess_query, postprocess_answer)#

Constructor.

Parameters

queryable (QueryableQueryable) – Queryable to decorate.
preprocess_query ((Any) → AnyCallable[[Any], Any]) – Function to preprocess queries to this DecoratedQueryable.
postprocess_answer ((Any) → AnyCallable[[Any], Any]) – Function to postprocess answers from this DecoratedQueryable.

__call__(query)#

Answers query.

Parameters: query (Any) –
Return type: Any

class DecorateQueryable(measurement, preprocess_query, postprocess_answer)#

Bases: tmlt.core.measurements.base.Measurement

Creates a DecoratedQueryable.

This class allows preprocessing queries to a Queryable launched by another interactive measurement as well as post-processing answers produced by the Queryable.

Parameters

measurement (tmlt.core.measurements.base.Measurement) –
preprocess_query (Callable[[Any], Any]) –
postprocess_answer (Callable[[Any], Any]) –

__init__(measurement, preprocess_query, postprocess_answer)#

Constructor.

Parameters

measurement (MeasurementMeasurement) – Interactive measurement to decorate.
preprocess_query ((Any) → AnyCallable[[Any], Any]) – Function to preprocess queries submitted to the Queryable obtained by running this measurement.
postprocess_answer ((Any) → AnyCallable[[Any], Any]) – Function to process answers produced by the Queryable returned by this measurement.

property measurement#

Returns wrapped Measurement.

Return type: tmlt.core.measurements.base.Measurement

property preprocess_query#

Returns function to preprocess queries.

Return type: Callable[[Any], Any]

property postprocess_answer#

Returns function to postprocess answers.

Return type: Callable[[Any], Any]

privacy_function(d_in)#

Returns the smallest d_out satisfied by the measurement.

Parameters: d_in (Any) –
Return type: Any

__call__(data)#

Returns a DecoratedQueryable.

Parameters: data (Any) –
Return type: DecoratedQueryable

property input_domain#

Return input domain for the measurement.

Return type: tmlt.core.domains.base.Domain

property input_metric#

Distance metric on input domain.

Return type: tmlt.core.metrics.Metric

property output_measure#

Distance measure on output.

Return type: tmlt.core.measures.Measure

property is_interactive#

Returns true iff the measurement is interactive.

Return type: bool

privacy_relation(d_in, d_out)#

Return True if close inputs produce close outputs.

See the privacy and stability tutorial (add link?) for more information.

Parameters

d_in (Any) – Distance between inputs under input_metric.
d_out (Any) – Distance between outputs under output_measure.

Return type

bool

class SequentialComposition(input_domain, input_metric, output_measure, d_in, privacy_budget)#

Bases: tmlt.core.measurements.base.Measurement

Creates a SequentialQueryable.

This class allows for measurements to be answered interactively using a cumulative privacy budget.

The main restriction, which is enforced by the returned SequentialQueryable, is that interactive measurements cannot be freely interleaved.

Parameters

input_domain (tmlt.core.domains.base.Domain) –
input_metric (tmlt.core.metrics.Metric) –
output_measure (Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]) –
d_in (Any) –
privacy_budget (tmlt.core.measures.PrivacyBudgetInput) –

__init__(input_domain, input_metric, output_measure, d_in, privacy_budget)#

Constructor.

Parameters

input_domain (DomainDomain) – Domain of input datasets.
input_metric (MetricMetric) – Distance metric for input datasets.
output_measure (PureDP | ApproxDP | RhoZCDPUnion[PureDP, ApproxDP, RhoZCDP]) – Distance measure for measurement’s output.
d_in (AnyAny) – Input metric value for inputs.
privacy_budget (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]]]) – Total privacy budget across all measurements.

property d_in#

Returns the distance between input datasets.

Return type: Any

property privacy_budget#

Total privacy budget across all measurements.

Return type: tmlt.core.measures.PrivacyBudgetValue

property output_measure#

Return output measure for the measurement.

Return type: Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]

privacy_function(d_in)#

Returns the smallest d_out satisfied by the measurement.

The returned d_out is the privacy_budget.

Parameters: d_in (Any) – Distance between inputs under input_metric. Must be less than or equal to the d_in the measurement was created with.
Return type: tmlt.core.measures.PrivacyBudgetValue

__call__(data)#

Returns a Queryable object on input data.

Parameters: data (Any) –
Return type: SequentialQueryable

property input_domain#

Return input domain for the measurement.

Return type: tmlt.core.domains.base.Domain

property input_metric#

Distance metric on input domain.

Return type: tmlt.core.metrics.Metric

property is_interactive#

Returns true iff the measurement is interactive.

Return type: bool

privacy_relation(d_in, d_out)#

Return True if close inputs produce close outputs.

See the privacy and stability tutorial (add link?) for more information.

Parameters

d_in (Any) – Distance between inputs under input_metric.
d_out (Any) – Distance between outputs under output_measure.

Return type

bool

class ParallelComposition(input_domain, input_metric, output_measure, measurements)#

Bases: tmlt.core.measurements.base.Measurement

Creates a ParallelQueryable.

This class allows for answering measurements on objects in some ListDomain which have a SumOf or RootSumOfSquared input metric, such as after a partition.

The main restriction, which is enforced by the returned ParallelQueryable, is that partitions can only be accessed in the sequence that they appear in the list.

Parameters

input_domain (tmlt.core.domains.collections.ListDomain) –
input_metric (Union[tmlt.core.metrics.SumOf, tmlt.core.metrics.RootSumOfSquared]) –
output_measure (Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]) –
measurements (List[tmlt.core.measurements.base.Measurement]) –

__init__(input_domain, input_metric, output_measure, measurements)#

Constructor.

Parameters

input_domain (ListDomainListDomain) – Domain of input lists.
input_metric (SumOf | RootSumOfSquaredUnion[SumOf, RootSumOfSquared]) – Distance metric for input lists.
output_measure (PureDP | ApproxDP | RhoZCDPUnion[PureDP, ApproxDP, RhoZCDP]) – Distance measure for measurement’s output.
measurements (List[Measurement]List[Measurement]) – List of measurements to be applied to the corresponding elements in the input list. The length of this list must match the length of lists in the input_domain.

property measurements#

Returns list of composed measurements.

Return type: List[tmlt.core.measurements.base.Measurement]

privacy_function(d_in)#

Returns the smallest d_out satisfied by the measurement.

Returns the largest d_out from the privacy_function() of all of the composed measurements.

Parameters: d_in (Any) – Distance between inputs under input_metric.
Raises: NotImplementedError – If any of the composed measurements’ privacy_relation() raise NotImplementedError.
Return type: tmlt.core.measures.PrivacyBudgetValue

__call__(data)#

Returns a ParallelQueryable.

Parameters: data (Any) –
Return type: ParallelQueryable

property input_domain#

Return input domain for the measurement.

Return type: tmlt.core.domains.base.Domain

property input_metric#

Distance metric on input domain.

Return type: tmlt.core.metrics.Metric

property output_measure#

Distance measure on output.

Return type: tmlt.core.measures.Measure

property is_interactive#

Returns true iff the measurement is interactive.

Return type: bool

privacy_relation(d_in, d_out)#

Return True if close inputs produce close outputs.

See the privacy and stability tutorial (add link?) for more information.

Parameters

d_in (Any) – Distance between inputs under input_metric.
d_out (Any) – Distance between outputs under output_measure.

Return type

bool

class MakeInteractive(measurement)#

Bases: tmlt.core.measurements.base.Measurement

Creates a GetAnswerQueryable.

This allows submitting non-interactive measurements as interactive measurement queries to SequentialQueryable and ParallelQueryable.

Parameters: measurement (tmlt.core.measurements.base.Measurement) –

__init__(measurement)#

Constructor.

Parameters: measurement (MeasurementMeasurement) – Non-interactive measurement to be wrapped.

privacy_function(d_in)#

Returns the smallest d_out satisfied by the measurement.

Parameters: d_in (Any) –
Return type: Any

privacy_relation(d_in, d_out)#

Returns True only if wrapped measurement’s privacy relation is satisfied.

Parameters

d_in (Any) –
d_out (Any) –

Return type

Any

property measurement#

Returns wrapped non-interactive measurement.

Return type: tmlt.core.measurements.base.Measurement

__call__(data)#

Returns a GetAnswerQueryable.

Parameters: data (Any) –
Return type: GetAnswerQueryable

property input_domain#

Return input domain for the measurement.

Return type: tmlt.core.domains.base.Domain

property input_metric#

Distance metric on input domain.

Return type: tmlt.core.metrics.Metric

property output_measure#

Distance measure on output.

Return type: tmlt.core.measures.Measure

property is_interactive#

Returns true iff the measurement is interactive.

Return type: bool

class PrivacyAccountantState#

Bases: enum.Enum

All possible states for a PrivacyAccountant.

ACTIVE = 1#

The PrivacyAccountant is active and can perform actions.

This is the default state of a PrivacyAccountant constructed by calling launch().

A PrivacyAccountant can only perform actions if it is ACTIVE.

Transitioning to ACTIVE:

A PrivacyAccountant that is WAITING_FOR_SIBLING will become ACTIVE if

the sibling immediately preceding this PrivacyAccountant is
RETIRED.

force_activate() is called.

This will retire all preceding siblings and their descendants

A PrivacyAccountant that is WAITING_FOR_CHILDREN will become ACTIVE if

all of its children are RETIRED

force_activate() is called.

This will retire all of its descendants

WAITING_FOR_SIBLING = 2#

The PrivacyAccountant is waiting for the preceding sibling to retire.

This is the default state of all but the first PrivacyAccountant created by split(). PrivacyAccountants obtained by calling split() must be activated in the same order that they appear in the list.

WAITING_FOR_CHILDREN = 3#

The PrivacyAccountant has children who have not been retired.

Transitioning to WAITING_FOR_CHILDREN:

A PrivacyAccountant that is ACTIVE will become WAITING_FOR_CHILDREN if

split() creates children

RETIRED = 4#

The PrivacyAccountant can no longer perform actions.

Transitioning to RETIRED:

A PrivacyAccountant that is WAITING_FOR_SIBLING or ACTIVE will become RETIRED if

retire() is called on it

retire() is called on one of its ancestors with force = True

force_activate() is called on one of its succeeding siblings.

force_activate() is called on one of its ancestors.

Note

If a PrivacyAccountant is retired while it is WAITING_FOR_SIBLING (before it has performed any actions), a RuntimeWarning is raised.

A PrivacyAccountant that is WAITING_FOR_CHILDREN will become RETIRED when

retire() is called on it with force = True

retire() is called on its ancestor with force = True

force_activate() is called on one of its succeeding siblings.

force_activate() is called on one of its ancestors.

name()#: The name of the Enum member.

value()#: The value of the Enum member.

class PrivacyAccountant(queryable, input_domain, input_metric, output_measure, d_in, privacy_budget, parent=None)#

An interface for adaptively composing measurements across transformed datasets.

PrivacyAccountant supports multiple actions to answer measurements and transform data.

Calling any of the following methods is considered an action:

transform_in_place()
measure()
split()

To preserve privacy, after children are created (using split()), there are restrictions on the order of interactions among the PrivacyAccountant and its descendants. See PrivacyAccountantState for more information.

Methods#
`input_domain()`	Returns the domain of the private data.
`input_metric()`	Returns the distance metric for neighboring datasets.
`output_measure()`	Returns the output measure for measurement outputs.
`d_in()`	Returns the distance for neighboring datasets.
`privacy_budget()`	Returns the remaining privacy budget.
`state()`	Returns this `PrivacyAccountant`’s current state.
`parent()`	Returns the parent of this `PrivacyAccountant`.
`children()`	Returns the children of this `PrivacyAccountant`.
`launch()`	Returns a `PrivacyAccountant` from a measurement and data.
`transform_in_place()`	Transforms the private data inside this `PrivacyAccountant`.
`measure()`	Returns the answer to measurement.
`split()`	Returns new `PrivacyAccountant`s from splitting the private data.
`force_activate()`	Set this `PrivacyAccountant`’s state to ACTIVE.
`retire()`	Set this `PrivacyAccountant`’s state to RETIRED.
`queue_transformation()`	Queue transformation to be executed when this `PrivacyAccountant` becomes ACTIVE.

Parameters

queryable (Optional[Queryable]) –
input_domain (tmlt.core.domains.base.Domain) –
input_metric (tmlt.core.metrics.Metric) –
output_measure (Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]) –
d_in (Any) –
privacy_budget (tmlt.core.measures.PrivacyBudgetInput) –
parent (Optional[PrivacyAccountant]) –

__init__(queryable, input_domain, input_metric, output_measure, d_in, privacy_budget, parent=None)#

Constructor.

Note

A PrivacyAccountant should be constructed using launch(). Do not use the constructor directly.

Parameters

queryable (Queryable | NoneOptional[Queryable]) – A Queryable to wrap. If initial_state is ACTIVE, this should not be None.
input_domain (DomainDomain) – The input domain for queryable.
input_metric (MetricMetric) – The input metric for queryable.
output_measure (PureDP | ApproxDP | RhoZCDPUnion[PureDP, ApproxDP, RhoZCDP]) – The output measure for queryable.
d_in (AnyAny) – The input metric value for queryable.
privacy_budget (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 privacy budget for the queryable.
parent (PrivacyAccountant | NoneOptional[PrivacyAccountant] (default: None)) – The parent of this PrivacyAccountant.

property input_domain#

Returns the domain of the private data.

Return type: tmlt.core.domains.base.Domain

property input_metric#

Returns the distance metric for neighboring datasets.

Return type: tmlt.core.metrics.Metric

property output_measure#

Returns the output measure for measurement outputs.

Return type: Union[tmlt.core.measures.PureDP, tmlt.core.measures.ApproxDP, tmlt.core.measures.RhoZCDP]

property d_in#

Returns the distance for neighboring datasets.

Return type: Any

property privacy_budget#

Returns the remaining privacy budget.

Return type: tmlt.core.measures.PrivacyBudgetValue

property state#

Returns this PrivacyAccountant’s current state.

See PrivacyAccountantState for more information.

Return type: PrivacyAccountantState

property parent#

Returns the parent of this PrivacyAccountant.

If this is the root PrivacyAccountant, this returns None.

Return type: Optional[PrivacyAccountant]

property children#

Returns the children of this PrivacyAccountant.

Children are created by calling split().

Return type: List[PrivacyAccountant]

static launch(measurement, data)#

Returns a PrivacyAccountant from a measurement and data.

The returned PrivacyAccountant is ACTIVE and has no parent.

Example

>>> measurement = SequentialComposition(
...     input_domain=SparkDataFrameDomain(
...         {
...             "A": SparkIntegerColumnDescriptor(),
...             "B": SparkStringColumnDescriptor(),
...         }
...     ),
...     input_metric=SymmetricDifference(),
...     output_measure=PureDP(),
...     d_in=1,
...     privacy_budget=5,
... )
>>> privacy_accountant = PrivacyAccountant.launch(measurement, dataframe)
>>> privacy_accountant.state
<PrivacyAccountantState.ACTIVE: 1>
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.privacy_budget
5
>>> print(privacy_accountant.parent)
None

Parameters

measurement (SequentialComposition) – A SequentialComposition to apply to the data.
data (Any) – The private data to use.

Return type

PrivacyAccountant

transform_in_place(transformation, d_out=None)#

Transforms the private data inside this PrivacyAccountant.

This method is an action.

Requirements to apply transformation:

this PrivacyAccountant’s state must be ACTIVE
transformation’s input_domain must match this PrivacyAccountant’s input_domain
transformation’s input_metric must match this PrivacyAccountant’s input_metric
if d_out is provided, transformation’s stability_relation() must hold for PrivacyAccountant’s d_in and d_out

After applying transformation:

this PrivacyAccountant’s input_domain will become transformation’s output_domain
this PrivacyAccountant’s input_metric will become transformation’s output_metric
this PrivacyAccountant’s d_in will become transformation’s d_out
- if transformation implements a stability_function(), its d_out is the output of its stability function on this PrivacyAccountant’s d_in
- otherwise it is the argument d_out

Example

>>> privacy_accountant.input_domain
NumpyIntegerDomain(size=64)
>>> privacy_accountant.input_metric
AbsoluteDifference()
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
2
>>> privacy_accountant.privacy_budget
5
>>> transformation = CreateDictFromValue(
...     input_domain=NumpyIntegerDomain(),
...     input_metric=AbsoluteDifference(),
...     key="A",
... )
>>> privacy_accountant.transform_in_place(transformation)
>>> privacy_accountant.input_domain
DictDomain(key_to_domain={'A': NumpyIntegerDomain(size=64)})
>>> privacy_accountant.input_metric
DictMetric(key_to_metric={'A': AbsoluteDifference()})
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
{'A': 2}
>>> privacy_accountant.privacy_budget
5

Parameters

transformation (tmlt.core.transformations.base.Transformation) – The transformation to apply.
d_out (Optional[Any]) – An optional value for the output metric for transformation. It is only used if transformation does not implement a stability_function().

Raises

InactiveAccountantError – If this PrivacyAccountant is not ACTIVE.

Return type

None

measure(measurement, d_out=None)#

Returns the answer to measurement.

This method is an action.

Requirements to answer measurement:

measurement’s input_domain must match this PrivacyAccountant’s input_domain
measurement’s input_metric must match this PrivacyAccountant’s input_metric
measurement’s output_measure must match this PrivacyAccountant’s output_measure
if d_out is provided, measurement’s privacy_relation() must hold for PrivacyAccountant’s d_in and d_out
this PrivacyAccountant’s privacy_budget must be greater than or equal to the measurement’s d_out
- if measurement implements a privacy_function(), its d_out is the output of its privacy function on this PrivacyAccountant’s d_in
- otherwise it is the argument d_out

After answering measurement:

this PrivacyAccountant’s privacy_budget will decrease by measurement’s d_out

Example

>>> privacy_accountant.input_domain
NumpyIntegerDomain(size=64)
>>> privacy_accountant.input_metric
AbsoluteDifference()
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
2
>>> privacy_accountant.privacy_budget
5
>>> noise_scale = calculate_noise_scale(
...     d_in=2,
...     d_out=3,
...     output_measure=PureDP(),
... )
>>> measurement = AddLaplaceNoise(
...     input_domain=NumpyIntegerDomain(),
...     scale=noise_scale,
... )
>>> privacy_accountant.measure(measurement) 

...
>>> privacy_accountant.input_domain
NumpyIntegerDomain(size=64)
>>> privacy_accountant.input_metric
AbsoluteDifference()
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
2
>>> privacy_accountant.privacy_budget
2

Parameters

measurement (tmlt.core.measurements.base.Measurement) – A non-interactive measurement to answer.
d_out (Optional[tmlt.core.measures.PrivacyBudgetInput]) – An optional d_out for measurement. It is only used if measurement does not implement a privacy_function().

Raises

InactiveAccountantError – If this PrivacyAccountant is not ACTIVE.

Return type

Any

split(splitting_transformation, privacy_budget, d_out=None)#

Returns new PrivacyAccountants from splitting the private data.

Uses splitting_transformation to split the private data into a list of new datasets. A new PrivacyAccountant is returned for each element in the list created by splitting_transformation.

Note

Unlike transform_in_place(), this does not transform the private data in this PrivacyAccountant.

This method is an action.

Requirements to split:

splitting_transformation’s input_domain must match this PrivacyAccountant’s input_domain
splitting_transformation’s input_metric must match this PrivacyAccountant’s input_metric
if d_out is provided, splitting_transformation’s stability_relation() must hold for this PrivacyAccountant’s d_in and d_out
splitting_transformation’s output_domain must be a ListDomain with a fixed length.
splitting_transformation’s output_metric must be SumOf if this PrivacyAccountant’s output_measure is PureDP or RootSumOfSquared if this PrivacyAccountant’s output_measure is RhoZCDP

After creating the new PrivacyAccountants:

this PrivacyAccountant’s privacy_budget will decrease by privacy_budget
this PrivacyAccountant’s children will be a list with the new PrivacyAccountants
this PrivacyAccountant’s state will become WAITING_FOR_CHILDREN
the new PrivacyAccountants’ input_domain will be the element domain of splitting_transformation’s ListDomain
the new PrivacyAccountants’ input_metric will be the inner metric of splitting_transformation’s SumOf or RootSumOfSquared metric
the new PrivacyAccountants’ output_measure will be this PrivacyAccountants output_measure
the new PrivacyAccountants’ d_in will be splitting_transformation’s d_out
- if splitting_transformation implements a stability_function(), its d_out is the output of its stability function on this PrivacyAccountant’s d_in
- otherwise it is the argument d_out
the new PrivacyAccountants’ privacy_budget will be privacy_budget
the first child PrivacyAccountant‘s state will be ACTIVE and all other child PrivacyAccountants’ state will be WAITING_FOR_SIBLING.

Note

After creating children, the state will change to WAITING_FOR_CHILDREN, until the children are all RETIRED.

Example

>>> privacy_accountant.input_domain
DictDomain(key_to_domain={'A': ListDomain(element_domain=NumpyIntegerDomain(size=64), length=3)})
>>> privacy_accountant.input_metric
DictMetric(key_to_metric={'A': SumOf(inner_metric=AbsoluteDifference())})
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
{'A': 2}
>>> privacy_accountant.privacy_budget
5
>>> privacy_accountant.state
<PrivacyAccountantState.ACTIVE: 1>
>>> splitting_transformation = GetValue(
...     input_domain=DictDomain(
...         key_to_domain={
...             "A": ListDomain(
...                 element_domain=NumpyIntegerDomain(),
...                 length=3,
...             ),
...         }
...     ),
...     input_metric=DictMetric(
...         key_to_metric={"A": SumOf(inner_metric=AbsoluteDifference())}
...     ),
...     key="A",
... )
>>> children = privacy_accountant.split(
...     splitting_transformation=splitting_transformation,
...     privacy_budget=3,
... )
>>> privacy_accountant.input_domain
DictDomain(key_to_domain={'A': ListDomain(element_domain=NumpyIntegerDomain(size=64), length=3)})
>>> privacy_accountant.input_metric
DictMetric(key_to_metric={'A': SumOf(inner_metric=AbsoluteDifference())})
>>> privacy_accountant.output_measure
PureDP()
>>> privacy_accountant.d_in
{'A': 2}
>>> privacy_accountant.privacy_budget
2
>>> privacy_accountant.state
<PrivacyAccountantState.WAITING_FOR_CHILDREN: 3>
>>> children[0].input_domain
NumpyIntegerDomain(size=64)
>>> children[0].input_metric
AbsoluteDifference()
>>> children[0].output_measure
PureDP()
>>> children[0].d_in
2
>>> children[0].privacy_budget
3
>>> # The first child is ACTIVE
>>> children[0].state
<PrivacyAccountantState.ACTIVE: 1>
>>> # The other children are WAITING_FOR_SIBLING
>>> children[1].state
<PrivacyAccountantState.WAITING_FOR_SIBLING: 2>
>>> children[2].state
<PrivacyAccountantState.WAITING_FOR_SIBLING: 2>
>>> # When the first child is RETIRED, the second child becomes ACTIVE
>>> children[0].retire()
>>> children[0].state
<PrivacyAccountantState.RETIRED: 4>
>>> children[1].state
<PrivacyAccountantState.ACTIVE: 1>
>>> # When all children are RETIRED, the parent transitions from
>>> # WAITING_FOR_CHILDREN to ACTIVE
>>> children[1].retire()
>>> children[2].retire()
>>> privacy_accountant.state
<PrivacyAccountantState.ACTIVE: 1>

Parameters

splitting_transformation (tmlt.core.transformations.base.Transformation) – The transformation to apply.
privacy_budget (tmlt.core.measures.PrivacyBudgetInput) – The privacy budget to allocate to the new PrivacyAccountants.
d_out (Optional[Any]) – An optional value for the :attr:~.Transformation.output_metric` for splitting_transformation. It is only used if splitting_transformation does not implement a stability_function().

Raises

InactiveAccountantError – If this PrivacyAccountant is not ACTIVE.

Return type

List[PrivacyAccountant]

force_activate()#

Set this PrivacyAccountant’s state to ACTIVE.

A PrivacyAccountant must be ACTIVE to perform actions

See PrivacyAccountantState for more information.

If this PrivacyAccountant is WAITING_FOR_SIBLING, it retires all preceding siblings. If this PrivacyAccountant is WAITING_FOR_CHILDREN it retires all of its descendants.

Raises: RuntimeError – If this PrivacyAccountant is RETIRED.
Return type: None

retire(force=False)#

Set this PrivacyAccountant’s state to RETIRED.

If this PrivacyAccountant is WAITING_FOR_SIBLING, it also retires all preceding siblings and their descendants. If this PrivacyAccountant is WAITING_FOR_CHILDREN it also retires all of its descendants.

A RETIRED PrivacyAccountant cannot perform actions, but its properties can still be inspected.

See PrivacyAccountantState for more information.

Parameters

force (bool) – Whether this PrivacyAccountant can retire its descendants if this PrivacyAccountant is WAITING_FOR_CHILDREN.

Raises

RuntimeError – If this PrivacyAccountant cannot be set to RETIRED. If force is False, this PrivacyAccountant cannot be WAITING_FOR_CHILDREN. If force is True, retire() can always be called.
RuntimeWarning – If the PrivacyAccountant is WAITING_FOR_SIBLING.

Return type

None

queue_transformation(transformation, d_out=None)#

Queue transformation to be executed when this PrivacyAccountant becomes ACTIVE.

If this PrivacyAccountant is ACTIVE, this has the same behavior as transform_in_place().

If this PrivacyAccountant is WAITING_FOR_CHILDREN or WAITING_FOR_SIBLING, transformation will be applied to the private data when this PrivacyAccountant becomes ACTIVE, but otherwise it has the same behavior as transform_in_place() (input_domain, input_metric, and d_in are updated immediately).

Note that multiple transformations can be queued.

Parameters

transformation (tmlt.core.transformations.base.Transformation) – The transformation to apply.
d_out (Optional[Any]) – An optional value for the output metric for transformation. It is only used if transformation does not implement a stability_function().

Return type

None

Exceptions#

exception InactiveAccountantError#

Bases: RuntimeError

Raised when trying to perform operations on an accountant that is not ACTIVE.

PrivacyAccountant will raise this exception if you attempt an operation and the accountant is not ACTIVE.

Tumult Core

interactive_measurements#

Functions#

Classes#

Exceptions#