.. _measurement-constructors: Measurements ============ This section gives a high-level overview of the measurements that are available in the library. Refer to the :ref:`section on measurements ` in the discussion of core structures for a defintion of "measurement" in OpenDP. The intermediate domains and metrics need to match when chaining. This means you will need to choose a measurement that chains with your :ref:`aggregator `. .. toctree:: :hidden: additive-noise-mechanisms thresholded-noise-mechanisms canonical-noise-mechanism noisy-max-mechanisms randomized-response Additive Noise Mechanisms ------------------------- See the `Additive Noise Mechanisms notebook `_ for code examples and more exposition. Notice that there is a symmetric structure to the additive noise measurements: .. list-table:: :header-rows: 1 * - Vector Input Metric - Constructor * - ``L1Distance`` - :func:`make_laplace ` * - ``L2Distance`` - :func:`make_gaussian ` ``QI`` can be any numeric type (the data type of the sensitivity can vary independently from the data type of the input). In the following sections, scalar-valued and vector-valued versions of each measurement are listed separately. You can choose whether to construct scalar or vector-valued versions of mechanisms by passing the appropriate input space. See the notebook above for examples. Laplacian Noise *************** These algorithms accept sensitivities in terms of the absolute or L2 metrics and measure privacy in terms of epsilon. Use the :func:`opendp.accuracy.laplacian_scale_to_accuracy` and :func:`opendp.accuracy.accuracy_to_laplacian_scale` functions to convert to/from accuracy estimates. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_laplace` - ``AtomDomain`` - ``AbsoluteDistance`` - ``MaxDivergence`` * - :func:`opendp.measurements.make_laplace` - ``VectorDomain>`` - ``L1Distance`` - ``MaxDivergence`` Gaussian Noise ************** These algorithms accept sensitivities in terms of the absolute or L2 metrics and measure privacy in terms of rho (zero-concentrated differential privacy). Use the :func:`opendp.accuracy.gaussian_scale_to_accuracy` and :func:`opendp.accuracy.accuracy_to_gaussian_scale` functions to convert to/from accuracy estimates. Refer to :ref:`measure-casting` to convert to approximate DP. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_gaussian` - ``AtomDomain`` - ``AbsoluteDistance`` - ``ZeroConcentratedDivergence`` * - :func:`opendp.measurements.make_gaussian` - ``VectorDomain>`` - ``L2Distance`` - ``ZeroConcentratedDivergence`` Geometric Noise *************** The geometric mechanism (:func:`make_geometric `) is an alias for the discrete Laplace (:func:`make_laplace `). If you need constant-time execution to protect against timing side-channels, specify bounds! Canonical Noise *************** The canonical noise mechanism (:func:`opendp.measurements.make_canonical_noise`) is discussed in detail in `these examples `_ Thresholded Noise Mechanisms ---------------------------- Thresholded noise mechanisms are generalizations of the additive noise mechanisms that also release a set of keys, whose values are greater than the ``threshold`` parameter. See the `Thresholded Noise Mechanisms documentation `_ for code examples and more exposition. Just like the additive noise mechanisms, the thresholded noise mechanisms have a symmetric structure: .. list-table:: :header-rows: 1 * - Vector Input Metric - Constructor * - ``L01InfDistance>`` - :func:`make_laplace_threshold ` * - ``L02InfDistance>`` - :func:`make_gaussian_threshold ` Laplacian Noise *************** The algorithm accepts ``L0``, ``L1`` and ``L∞`` sensitivities and measures privacy in terms of epsilon and delta. Use the :func:`opendp.accuracy.laplacian_scale_to_accuracy` and :func:`opendp.accuracy.accuracy_to_laplacian_scale` functions to convert to/from accuracy estimates. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_laplace_threshold` - ``MapDomain, AtomDomain>`` - ``L01InfDistance>`` - ``Approximate`` Gaussian Noise ************** The algorithm accepts ``L0``, ``L2`` and ``L∞`` sensitivities and measures privacy in terms of rho and delta. Use the :func:`opendp.accuracy.gaussian_scale_to_accuracy` and :func:`opendp.accuracy.accuracy_to_gaussian_scale` functions to convert to/from accuracy estimates. Refer to :ref:`measure-casting` to convert to approximate DP. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_gaussian_threshold` - ``MapDomain, AtomDomain>`` - ``L02InfDistance>`` - ``Approximate`` Approximate Laplace Projection ------------------------------ In a similar regime as the thresholded noise mechanism, where keys themselves need to be protected, another approach is to release a differentially private low-dimensional projection of the key-space. See `Approximate Laplace Projection `_ for a demonstration of the approach. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_alp_queryable` - ``MapDomain, AtomDomain>`` - ``L01InfDistance>`` - ``MaxDivergence`` Noisy Max and Noisy Top K ------------------------- See `Noisy Max Mechanisms `_ for code examples and more exposition. The report noisy top-k mechanism is used to privately release the indices of the maximum k values in a vector. This is useful for private selection, and overlaps with the exponential mechanism. Exponential noise is added to scores when the output measure is ``MaxDivergence``, and Gumbel noise is added when the output measure is ``ZeroConcentratedDivergence``. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_noisy_top_k` - ``VectorDomain>`` - ``LInfDistance`` - ``MaxDivergence`` or ``ZeroConcentratedDivergence`` * - :func:`opendp.measurements.make_noisy_max` - ``VectorDomain>`` - ``LInfDistance`` - ``MaxDivergence`` or ``ZeroConcentratedDivergence`` Report noisy max is a special case of noisy top k when k equals one. Randomized Response ------------------- These measurements are used to randomize an individual's response to a query in the local-DP model. See `Randomized Response `_ for code examples and more exposition. .. list-table:: :header-rows: 1 * - Measurement - Input Domain - Input Metric - Output Measure * - :func:`opendp.measurements.make_randomized_response_bool` - ``AtomDomain`` - ``DiscreteDistance`` - ``MaxDivergence`` * - :func:`opendp.measurements.make_randomized_response` - ``AtomDomain`` - ``DiscreteDistance`` - ``MaxDivergence`` * - :func:`opendp.measurements.make_randomized_response_bitvec` - ``AtomDomain`` - ``DiscreteDistance`` - ``MaxDivergence``