.. _measurement-constructors:
Measurement Constructors
========================
This section gives a high-level overview of the measurements that are available in the library.
Refer to the :ref:`measurement` section for an explanation of what a measurement is.
As covered in the :ref:`chaining` section, 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 `.
In the following table, the scalar-valued and vector-valued versions of each measurement are listed separately.
You can choose whether to construct scalar or vector-valued versions by setting the ``D`` type argument when calling the constructor.
:Scalar: ``D=AllDomain[T]`` (default)
:Vector: ``D=VectorDomain[AllDomain[T]]``
.. list-table::
:header-rows: 1
* - Measurement
- Input Domain
- Output Metric
- Output Measure
* - :func:`opendp.meas.make_base_geometric`
- ``AllDomain``
- ``AbsoluteDistance``
- ``MaxDivergence``
* - :func:`opendp.meas.make_base_geometric`
- ``VectorDomain>``
- ``L1Distance``
- ``MaxDivergence``
* - :func:`opendp.meas.make_base_laplace`
- ``AllDomain``
- ``AbsoluteDistance``
- ``MaxDivergence``
* - :func:`opendp.meas.make_base_laplace`
- ``VectorDomain>``
- ``L1Distance``
- ``MaxDivergence``
* - :func:`opendp.meas.make_base_gaussian`
- ``AllDomain``
- ``AbsoluteDistance``
- ``SmoothedMaxDivergence``
* - :func:`opendp.meas.make_base_gaussian`
- ``VectorDomain>``
- ``L2Distance``
- ``SmoothedMaxDivergence``
* - :func:`opendp.meas.make_base_analytic_gaussian`
- ``AllDomain``
- ``AbsoluteDistance``
- ``SmoothedMaxDivergence``
* - :func:`opendp.meas.make_base_analytic_gaussian`
- ``VectorDomain>``
- ``L2Distance``
- ``SmoothedMaxDivergence``
* - :func:`opendp.meas.make_base_ptr`
- ``MapDomain, AllDomain>``
- ``L1Distance``
- ``SmoothedMaxDivergence``
* - :func:`opendp.meas.make_randomized_response_bool`
- ``AllDomain``
- ``SymmetricDistance``
- ``MaxDivergence``
* - :func:`opendp.meas.make_randomized_response`
- ``AllDomain``
- ``SymmetricDistance``
- ``MaxDivergence``
.. _floating-point:
Floating-Point
--------------
Given the context of measurements, this section goes into greater detail than :ref:`limitations` on floating-point issues.
Be warned that :func:`opendp.meas.make_base_laplace`, :func:`opendp.meas.make_base_gaussian` and :func:`opendp.meas.make_base_ptr`
depend on continuous distributions that are poorly approximated by finite computers.
At this time these mechanisms are present in the library, but require explicit opt-in:
.. doctest::
>>> from opendp.mod import enable_features
>>> enable_features("floating-point")
The canonical paper on this and introduction of the snapping mechanism is here:
`On Significance of the Least Significant Bits For Differential Privacy `_.
Precautions have been made to sample noise using the GNU MPFR library in a way
that provides cryptographically secure, non-porous noise at standard scale.
Noise at arbitrary scale is achieved through a combination of preprocessing and postprocessing
that preserves the properties of differential privacy.
Precautions have also been made to explicitly specify floating-point rounding modes
in such a way that the privacy budget is always slightly overestimated.
We acknowledge the snapping mechanism and have an implementation of it `in PR #84 `_.
We are also working towards adding support for fixed-point data types `in PR #184 `_.