.. _core-structures:
Core Structures
===============
OpenDP is focused on creating computations with specific privacy characteristics.
These computations are modeled with two core structures in OpenDP:
:py:class:`opendp.mod.Transformation` and :py:class:`opendp.mod.Measurement`.
These structures are in all OpenDP programs, regardless of the underlying algorithm or definition of privacy.
By modeling computations in this abstract way, we're able to combine them in flexible arrangements and reason about the privacy properties of the resulting programs.
A unifying perspective towards OpenDP is that OpenDP is a system for `relating`:
#. an upper bound on distance between function inputs
#. an upper bound on distance between respective function outputs (or output distributions)
Each measurement or transformation is a self-contained structure with a map, function, and supporting proof.
.. _measurement:
Measurement
-----------
A :py:class:`Measurement ` is a randomized mapping from datasets to outputs of an arbitrary type.
Say we have an arbitrary instance of a Measurement, called ``meas``, and a code snippet:
.. code-block:: python
d_out = meas.map(d_in)
Outputs of ``meas`` are ``d_out``-DP when inputs are ``d_in``-close,
or equivalently, invocations of ``meas`` are "(``d_in``, ``d_out``)-differentially private".
The code snippet simply evaluates the privacy map that comes bundled inside ``meas``.
In this context, the map captures the privacy of a measurement.
The distances ``d_in`` and ``d_out`` are expressed in the units of the input metric and output measure.
Depending on the context, ``d_in`` could be a distance bound to neighboring datasets or a global sensitivity,
and ``d_out`` may be ``epsilon``, ``(epsilon, delta)``, or some other measure of privacy.
More information on distances is available :ref:`here `.
Each invocation of the measurement's function (via ``meas.invoke(data)`` or ``meas(data)``) is a differentially private release.
A measurement structure contains the following internal fields:
:input_domain: A :ref:`domain ` that describes the set of all possible input values for the function.
:output_domain: A :ref:`domain ` that describes the set of all possible output values of the function.
:function: A :ref:`function ` that computes a differentially private release on private data.
:input_metric: A :ref:`metric ` used to compute distance between two members of the input domain.
:output_measure: A :ref:`measure ` used to measure distance between two distributions in the output domain.
:privacy_map: A :ref:`map ` that encapsulates the privacy characteristics of the function.
The framework quantifies output distance bounds on measurements with a measure, instead of a metric,
because measurements emit samples from a probability distribution,
and measures can be used to quantify differences between probability distributions.
This is the primary differentiating factor between measurements and transformations.
.. _transformation:
Transformation
--------------
A :py:class:`Transformation ` is a (deterministic) mapping from datasets to datasets.
Transformations are used to preprocess and aggregate data before chaining with a measurement.
Similarly to ``meas`` above, say we have an arbitrary instance of a Transformation, called ``trans``,
and a code snippet:
.. code-block:: python
d_out = trans.map(d_in)
Outputs of ``trans`` are ``d_out``-close when inputs are ``d_in``-close,
or equivalently, invocations of ``trans`` are "(``d_in``, ``d_out``)-stable".
The code snippet simply evaluates the stability map that comes bundled inside ``trans``.
In this context, the map captures the stability of a transformation.
The distances ``d_in`` and ``d_out`` are expressed in the units of the input metric and output metric.
Depending on the context, ``d_in`` and ``d_out`` could be a distance bound to neighboring datasets or a global sensitivity.
More information on distances is available :ref:`here `.
Invoking the function (via ``trans.invoke(data)`` or ``trans(data)``) transforms the data, but the output is not differentially private.
Transformations need to be :ref:`chained ` with a measurement before they can be used to create a differentially-private release.
A transformation structure contains the following internal fields:
:input_domain: A :ref:`domain ` that describes the set of all possible input values for the function.
:output_domain: A :ref:`domain ` that describes the set of all possible output values of the function.
:function: A :ref:`function ` that transforms data.
:input_metric: A :ref:`metric ` used to compute distance between two members of the input domain.
:output_metric: A :ref:`metric ` used to measure distance between two members of the output domain.
:stability_map: A :ref:`map ` that encapsulates the stability characteristics of the function.