opendp.combinators module#

The combinators module provides functions for combining transformations and measurements. For more context, see combinators in the User Guide.

For convenience, all the functions of this module are also available from opendp.prelude. We suggest importing under the conventional name dp:

>>> import opendp.prelude as dp

The methods of this module will then be accessible at dp.c.

opendp.combinators.make_approximate(measurement)[source]#

Constructs a new output measurement where the output measure is δ-approximate, where δ=0.

Required features: contrib

make_approximate in Rust documentation.

Parameters:

measurement (Measurement) – a measurement with a privacy measure to be casted

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_basic_composition(measurements)[source]#

Construct the DP composition [measurement0, measurement1, …]. Returns a Measurement that when invoked, computes [measurement0(x), measurement1(x), ...]

All metrics and domains must be equivalent.

Composition Properties

  • sequential: all measurements are applied to the same dataset

  • basic: the composition is the linear sum of the privacy usage of each query

  • noninteractive: all mechanisms specified up-front (but each can be interactive)

  • compositor: all privacy parameters specified up-front (via the map)

Required features: contrib

make_basic_composition in Rust documentation.

Parameters:

measurements – A vector of Measurements to compose.

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_chain_mt(measurement1, transformation0)[source]#

Construct the functional composition (measurement1 ○ transformation0). Returns a Measurement that when invoked, computes measurement1(transformation0(x)).

Required features: contrib

make_chain_mt in Rust documentation.

Parameters:
Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_chain_pm(postprocess1, measurement0)[source]#

Construct the functional composition (postprocess1 ○ measurement0). Returns a Measurement that when invoked, computes postprocess1(measurement0(x)). Used to represent non-interactive postprocessing.

Required features: contrib

make_chain_pm in Rust documentation.

Parameters:

  • postprocess1 (Function) – outer postprocessor

  • measurement0 (Measurement) – inner measurement/mechanism

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_chain_tt(transformation1, transformation0)[source]#

Construct the functional composition (transformation1 ○ transformation0). Returns a Transformation that when invoked, computes transformation1(transformation0(x)).

Required features: contrib

make_chain_tt in Rust documentation.

Parameters:
Return type:

Transformation

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_fix_delta(measurement, delta)[source]#

Fix the delta parameter in the privacy map of a measurement with a SmoothedMaxDivergence output measure.

Required features: contrib

make_fix_delta in Rust documentation.

Parameters:

  • measurement (Measurement) – a measurement with a privacy curve to be fixed

  • delta (float) – parameter to fix the privacy curve with

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_population_amplification(measurement, population_size)[source]#

Construct an amplified measurement from a measurement with privacy amplification by subsampling. This measurement does not perform any sampling. It is useful when you have a dataset on-hand that is a simple random sample from a larger population.

The DIA, DO, MI and MO between the input measurement and amplified output measurement all match.

Required features: contrib, honest-but-curious

make_population_amplification in Rust documentation.

Why honest-but-curious?:

The privacy guarantees are only valid if the input dataset is a simple sample from a population with population_size records.

Parameters:

  • measurement (Measurement) – the computation to amplify

  • population_size (int) – the size of the population from which the input dataset is a simple sample

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_pureDP_to_zCDP(measurement)[source]#

Constructs a new output measurement where the output measure is casted from MaxDivergence to ZeroConcentratedDivergence.

Required features: contrib

make_pureDP_to_zCDP in Rust documentation.

Citations:

Parameters:

measurement (Measurement) – a measurement with a privacy measure to be casted

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_select_private_candidate(measurement, stop_probability, threshold)[source]#

Select a private candidate whose score is above a threshold.

Given measurement that satisfies ε-DP, returns new measurement M’ that satisfies 2ε-DP. M’ releases the first invocation of measurement whose score is above threshold.

Each time a score is below threshold the algorithm may terminate with probability stop_probability and return nothing.

measurement should make releases in the form of (score, candidate). If you are writing a custom scorer measurement in Python, specify the output type as TO=(float, "ExtrinsicObject"). This ensures that the float value is accessible to the algorithm. The candidate, left as arbitrary Python data, is held behind the ExtrinsicObject.

Algorithm 1 in Private selection from private candidates <https://arxiv.org/pdf/1811.07971.pdf#page=7>_ (Liu and Talwar, STOC 2019).

Required features: contrib

make_select_private_candidate in Rust documentation.

Supporting Elements:

  • Input Domain: DI

  • Output Type: Option<(f64, TO)>

  • Input Metric: MI

  • Output Measure: MaxDivergence

Proof Definition:

(Proof Document)

Parameters:

  • measurement (Measurement) – A measurement that releases a 2-tuple of (score, candidate)

  • stop_probability (float) – The probability of stopping early at any iteration.

  • threshold (float) – The threshold score. Return immediately if the score is above this threshold.

Returns:

A measurement that returns a release from measurement whose score is greater than threshold, or none.

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

Example:

>>> import opendp.prelude as dp
>>> dp.enable_features("contrib")
>>> threshold = 23
>>> space = dp.atom_domain(T=float), dp.absolute_distance(T=float)
...
>>> # For demonstration purposes-- construct a measurement that releases
>>> # a tuple with a differentially private score and value.
>>> # The tuple released must satisfy the privacy guarantee from the map.
>>> m_mock = space >> dp.m.then_user_measurement(
...     dp.max_divergence(),
...     lambda x: (np.random.laplace(loc=x), "arbitrary candidate"),
...     lambda d_in: d_in,
...     TO="(f64, ExtrinsicObject)"
... )
...
>>> m_private_selection = dp.c.make_select_private_candidate(
...     m_mock, threshold=threshold, stop_probability=0
... )
...
>>> score, candidate = m_private_selection(20)
...
>>> assert score >= threshold
>>> assert m_private_selection.map(1) == 2 * m_mock.map(1)
>>> assert isinstance(candidate, str)
opendp.combinators.make_sequential_composition(input_domain, input_metric, output_measure, d_in, d_mids)[source]#

Construct a Measurement that when invoked, returns a queryable that interactively composes measurements.

Composition Properties

  • sequential: all measurements are applied to the same dataset

  • basic: the composition is the linear sum of the privacy usage of each query

  • interactive: mechanisms can be specified based on answers to previous queries

  • compositor: all privacy parameters specified up-front

If the privacy measure supports concurrency, this compositor allows you to spawn multiple interactive mechanisms and interleave your queries amongst them.

Required features: contrib

make_sequential_composition in Rust documentation.

Supporting Elements:

  • Input Domain: DI

  • Output Type: Queryable<Measurement<DI, TO, MI, MO>, TO>

  • Input Metric: MI

  • Output Measure: MO

Parameters:

  • input_domain (Domain) – indicates the space of valid input datasets

  • input_metric (Metric) – how distances are measured between members of the input domain

  • output_measure (Measure) – how privacy is measured

  • d_in – maximum distance between adjacent input datasets

  • d_mids – maximum privacy expenditure of each query

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.make_zCDP_to_approxDP(measurement)[source]#

Constructs a new output measurement where the output measure is casted from ZeroConcentratedDivergence to SmoothedMaxDivergence.

Required features: contrib

make_zCDP_to_approxDP in Rust documentation.

Parameters:

measurement (Measurement) – a measurement with a privacy measure to be casted

Return type:

Measurement

Raises:

  • TypeError – if an argument’s type differs from the expected type

  • UnknownTypeException – if a type argument fails to parse

  • OpenDPException – packaged error from the core OpenDP library

opendp.combinators.then_sequential_composition(output_measure, d_in, d_mids)[source]#

partial constructor of make_sequential_composition

See also

Delays application of input_domain and input_metric in opendp.combinators.make_sequential_composition()

Parameters:

  • output_measure (Measure) – how privacy is measured

  • d_in – maximum distance between adjacent input datasets

  • d_mids – maximum privacy expenditure of each query

On this page
Show Source