opendp.context module

The context module provides opendp.context.Context and supporting utilities.

class opendp.context.Context(accountant, queryable, d_in, d_mids=None, d_out=None)

A Context coordinates queries to an instance of a privacy accountant.

Parameters:

• accountant (Measurement) –

• queryable (Queryable) –

accountant: Measurement

The accountant is the measurement used to spawn the queryable. It contains information about the queryable, such as the input domain, input metric, and output measure expected of measurement queries sent to the queryable.

static compositor(data, privacy_unit, privacy_loss, split_evenly_over=None, split_by_weights=None, domain=None)

Constructs a new context containing a sequential compositor with the given weights.

If the domain is not specified, it will be inferred from the data. This makes the assumption that the structure of the data is public information.

The weights may be a list of numerics, corresponding to how privacy_loss should be distributed to each query. Alternatively, pass a single integer to distribute the loss evenly.

Parameters:

• data (Any) – The data to be analyzed.

• privacy_unit (Tuple[Metric, float]) – The privacy unit of the compositor.

• privacy_loss (Tuple[Measure, Any]) – The privacy loss of the compositor.

• weights – How to distribute privacy_loss among the queries.

• domain (Domain | None) – The domain of the data.

• split_evenly_over (int | None) –

• split_by_weights (List[float] | None) –

Return type:

Context

query(**kwargs)

Starts a new Query to be executed in this context.

If the context has been constructed with a sequence of privacy losses, the next loss will be used. Otherwise, the loss will be computed from the kwargs.

Parameters:

kwargs – The privacy loss to use for the query. Passed directly into loss_of.

Return type:

Query

queryable: Queryable

The queryable executes the queries and tracks the privacy expenditure.

class opendp.context.PartialChain(f, *args, **kwargs)

A partial chain is a transformation or measurement that is missing one numeric parameter.

The parameter can be solved for by calling the fix method, which returns the closest transformation or measurement that satisfies the given stability or privacy constraint.

fix(d_in, d_out, output_measure=None, T=None)

Returns the closest transformation or measurement that satisfies the given stability or privacy constraint.

The discovered parameter is assigned to the param attribute of the returned transformation or measurement.

partial: Callable[[float], Transformation | Measurement]

The partial transformation or measurement.

classmethod wrap(f)

Wraps a constructor for a transformation or measurement to return a partial chain instead.

class opendp.context.Query(chain, output_measure=None, d_in=None, d_out=None, context=None, _wrap_release=None)

A helper API to build a measurement.

Parameters:

• chain (Tuple[Domain, Metric] | Transformation | Measurement | PartialChain) –

• output_measure (Measure) –

• context (Context) –

• _wrap_release (Callable[[Any], Any] | None) –

compositor(split_evenly_over=None, split_by_weights=None, d_out=None, output_measure=None)

Constructs a new context containing a sequential compositor with the given weights.

Parameters:

• weights – A list of weights corresponding to the privacy budget allocated to a sequence of queries.

• split_evenly_over (int | None) –

• split_by_weights (List[float] | None) –

Return type:

Context

new_with(*, chain, wrap_release=None)

Convenience constructor that creates a new query with a different chain.

Parameters:

chain (Tuple[Domain, Metric] | Transformation | Measurement | PartialChain) –

Return type:

Query

param()

Returns the discovered parameter, if there is one

release()

Release the query. The query must be part of a context.

Return type:

Any

resolve(allow_transformations=False)

Resolve the query into a measurement.”

Parameters:

allow_transformations – If true, allow the response to be a transformation instead of a measurement.

opendp.context.domain_of(T, infer=False)

Constructs an instance of a domain from carrier type T.

Parameters:

• T – carrier type

• infer – if True, T is an example of the sensitive dataset. Passing sensitive data may result in a privacy violation.

Return type:

Domain

opendp.context.loss_of(*, epsilon=None, delta=None, rho=None, U=None)

Constructs a privacy loss, consisting of a privacy measure and a privacy loss parameter.

Parameters:

U – The type of the privacy parameter.

Return type:

Tuple[Measure, float]

>>> from opendp.context import loss_of
>>> measure, distance = loss_of(epsilon=1.0)
>>> measure, distance = loss_of(epsilon=1.0, delta=1e-9)
>>> measure, distance = loss_of(rho=1.0)

opendp.context.metric_of(M)

Constructs an instance of a metric from metric type M.

Return type:

Metric

opendp.context.space_of(T, M=None, infer=False)

A shorthand for building a metric space.

A metric space consists of a domain and a metric.

Example:

Return type:

Tuple[Domain, Metric]

>>> import opendp.prelude as dp
>>> from typing import List # in Python 3.9, can just write list[int] below
...
>>> dp.space_of(List[int])
(VectorDomain(AtomDomain(T=i32)), SymmetricDistance())
>>> # the verbose form allows greater control:
>>> (dp.vector_domain(dp.atom_domain(T=dp.i32)), dp.symmetric_distance())
(VectorDomain(AtomDomain(T=i32)), SymmetricDistance())

Parameters:

• T – carrier type (the type of members in the domain)

• M – metric type

• infer – if True, T is an example of the sensitive dataset. Passing sensitive data may result in a privacy violation.

Return type:

Tuple[Domain, Metric]

opendp.context.unit_of(*, contributions=None, changes=None, absolute=None, l1=None, l2=None, ordered=False, U=None)

Constructs a unit of privacy, consisting of a metric and a dataset distance.

Parameters:

• ordered – Set to true to use InsertDeleteDistance instead of SymmetricDistance, or HammingDistance instead of ChangeOneDistance.

• U – The type of the dataset distance.

Return type:

Tuple[Metric, float]