This documentation is for a development version of OpenDP.

The current release of OpenDP is v0.11.1.

Source code for opendp.combinators

# Auto-generated. Do not edit!
'''
The ``combinators`` module provides functions for combining transformations and measurements.
For more context, see :ref:`combinators in the User Guide <combinators-user-guide>`.

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

.. code:: python

    >>> import opendp.prelude as dp

The methods of this module will then be accessible at ``dp.c``.
'''
from deprecated.sphinx import deprecated # noqa: F401 (Not every file actually has deprecated functions.)

from opendp._convert import *
from opendp._lib import *
from opendp.mod import *
from opendp.typing import *
from opendp.core import *
from opendp.domains import *
from opendp.metrics import *
from opendp.measures import *
__all__ = [
    "make_approximate",
    "make_basic_composition",
    "make_chain_mt",
    "make_chain_pm",
    "make_chain_tt",
    "make_fix_delta",
    "make_population_amplification",
    "make_pureDP_to_zCDP",
    "make_sequential_composition",
    "make_zCDP_to_approxDP",
    "then_sequential_composition"
]


[docs] def make_approximate( measurement: Measurement ) -> Measurement: r"""Constructs a new output measurement where the output measure is δ-approximate, where δ=0. Required features: `contrib` [make_approximate in Rust documentation.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_approximate.html) :param measurement: a measurement with a privacy measure to be casted :type measurement: Measurement :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurement = py_to_c(measurement, c_type=Measurement, type_name=AnyMeasurement) # Call library function. lib_function = lib.opendp_combinators__make_approximate lib_function.argtypes = [Measurement] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement), Measurement)) return output
[docs] def make_basic_composition( measurements ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_basic_composition.html) :param measurements: A vector of Measurements to compose. :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurements = py_to_c(measurements, c_type=AnyObjectPtr, type_name=RuntimeType(origin='Vec', args=[AnyMeasurementPtr])) # Call library function. lib_function = lib.opendp_combinators__make_basic_composition lib_function.argtypes = [AnyObjectPtr] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurements), Measurement)) output._depends_on(get_dependencies_iterable(measurements)) return output
[docs] def make_chain_mt( measurement1: Measurement, transformation0: Transformation ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_chain_mt.html) :param measurement1: outer mechanism :type measurement1: Measurement :param transformation0: inner transformation :type transformation0: Transformation :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurement1 = py_to_c(measurement1, c_type=Measurement, type_name=None) c_transformation0 = py_to_c(transformation0, c_type=Transformation, type_name=None) # Call library function. lib_function = lib.opendp_combinators__make_chain_mt lib_function.argtypes = [Measurement, Transformation] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement1, c_transformation0), Measurement)) output._depends_on(get_dependencies(measurement1), get_dependencies(transformation0)) return output
[docs] def make_chain_pm( postprocess1: Function, measurement0: Measurement ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_chain_pm.html) :param postprocess1: outer postprocessor :type postprocess1: Function :param measurement0: inner measurement/mechanism :type measurement0: Measurement :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_postprocess1 = py_to_c(postprocess1, c_type=Function, type_name=None) c_measurement0 = py_to_c(measurement0, c_type=Measurement, type_name=None) # Call library function. lib_function = lib.opendp_combinators__make_chain_pm lib_function.argtypes = [Function, Measurement] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_postprocess1, c_measurement0), Measurement)) output._depends_on(get_dependencies(postprocess1), get_dependencies(measurement0)) return output
[docs] def make_chain_tt( transformation1: Transformation, transformation0: Transformation ) -> Transformation: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_chain_tt.html) :param transformation1: outer transformation :type transformation1: Transformation :param transformation0: inner transformation :type transformation0: Transformation :rtype: Transformation :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_transformation1 = py_to_c(transformation1, c_type=Transformation, type_name=None) c_transformation0 = py_to_c(transformation0, c_type=Transformation, type_name=None) # Call library function. lib_function = lib.opendp_combinators__make_chain_tt lib_function.argtypes = [Transformation, Transformation] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_transformation1, c_transformation0), Transformation)) output._depends_on(get_dependencies(transformation1), get_dependencies(transformation0)) return output
[docs] def make_fix_delta( measurement: Measurement, delta: float ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_fix_delta.html) :param measurement: a measurement with a privacy curve to be fixed :type measurement: Measurement :param delta: parameter to fix the privacy curve with :type delta: float :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurement = py_to_c(measurement, c_type=Measurement, type_name=None) c_delta = py_to_c(delta, c_type=ctypes.c_double, type_name=f64) # Call library function. lib_function = lib.opendp_combinators__make_fix_delta lib_function.argtypes = [Measurement, ctypes.c_double] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement, c_delta), Measurement)) output._depends_on(get_dependencies(measurement)) return output
[docs] def make_population_amplification( measurement: Measurement, population_size: int ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_population_amplification.html) **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. :param measurement: the computation to amplify :type measurement: Measurement :param population_size: the size of the population from which the input dataset is a simple sample :type population_size: int :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib", "honest-but-curious") # No type arguments to standardize. # Convert arguments to c types. c_measurement = py_to_c(measurement, c_type=Measurement, type_name=AnyMeasurement) c_population_size = py_to_c(population_size, c_type=ctypes.c_size_t, type_name=usize) # Call library function. lib_function = lib.opendp_combinators__make_population_amplification lib_function.argtypes = [Measurement, ctypes.c_size_t] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement, c_population_size), Measurement)) output._depends_on(get_dependencies(measurement)) return output
[docs] def make_pureDP_to_zCDP( measurement: Measurement ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_pureDP_to_zCDP.html) **Citations:** - [BS16 Concentrated Differential Privacy: Simplifications, Extensions, and Lower Bounds](https://arxiv.org/pdf/1605.02065.pdf#subsection.3.1) :param measurement: a measurement with a privacy measure to be casted :type measurement: Measurement :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurement = py_to_c(measurement, c_type=Measurement, type_name=AnyMeasurement) # Call library function. lib_function = lib.opendp_combinators__make_pureDP_to_zCDP lib_function.argtypes = [Measurement] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement), Measurement)) return output
[docs] def make_sequential_composition( input_domain: Domain, input_metric: Metric, output_measure: Measure, d_in, d_mids ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_sequential_composition.html) **Supporting Elements:** * Input Domain: `DI` * Output Type: `Queryable<Measurement<DI, TO, MI, MO>, TO>` * Input Metric: `MI` * Output Measure: `MO` :param input_domain: indicates the space of valid input datasets :type input_domain: Domain :param input_metric: how distances are measured between members of the input domain :type input_metric: Metric :param output_measure: how privacy is measured :type output_measure: Measure :param d_in: maximum distance between adjacent input datasets :param d_mids: maximum privacy expenditure of each query :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # Standardize type arguments. QO = get_distance_type(output_measure) # type: ignore # Convert arguments to c types. c_input_domain = py_to_c(input_domain, c_type=Domain, type_name=None) c_input_metric = py_to_c(input_metric, c_type=Metric, type_name=None) c_output_measure = py_to_c(output_measure, c_type=Measure, type_name=None) c_d_in = py_to_c(d_in, c_type=AnyObjectPtr, type_name=get_distance_type(input_metric)) c_d_mids = py_to_c(d_mids, c_type=AnyObjectPtr, type_name=RuntimeType(origin='Vec', args=[QO])) # Call library function. lib_function = lib.opendp_combinators__make_sequential_composition lib_function.argtypes = [Domain, Metric, Measure, AnyObjectPtr, AnyObjectPtr] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_input_domain, c_input_metric, c_output_measure, c_d_in, c_d_mids), Measurement)) return output
[docs] def then_sequential_composition( output_measure: Measure, d_in, d_mids ): r"""partial constructor of make_sequential_composition .. seealso:: Delays application of `input_domain` and `input_metric` in :py:func:`opendp.combinators.make_sequential_composition` :param output_measure: how privacy is measured :type output_measure: Measure :param d_in: maximum distance between adjacent input datasets :param d_mids: maximum privacy expenditure of each query """ return PartialConstructor(lambda input_domain, input_metric: make_sequential_composition( input_domain=input_domain, input_metric=input_metric, output_measure=output_measure, d_in=d_in, d_mids=d_mids))
[docs] def make_zCDP_to_approxDP( measurement: Measurement ) -> Measurement: r"""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.](https://docs.rs/opendp/0.11.1-nightly.20241016.1/opendp/combinators/fn.make_zCDP_to_approxDP.html) :param measurement: a measurement with a privacy measure to be casted :type measurement: Measurement :rtype: Measurement :raises TypeError: if an argument's type differs from the expected type :raises UnknownTypeException: if a type argument fails to parse :raises OpenDPException: packaged error from the core OpenDP library """ assert_features("contrib") # No type arguments to standardize. # Convert arguments to c types. c_measurement = py_to_c(measurement, c_type=Measurement, type_name=AnyMeasurement) # Call library function. lib_function = lib.opendp_combinators__make_zCDP_to_approxDP lib_function.argtypes = [Measurement] lib_function.restype = FfiResult output = c_to_py(unwrap(lib_function(c_measurement), Measurement)) output._depends_on(get_dependencies(measurement)) return output