{ "cells": [ { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "# Additive Noise Mechanisms\n", "\n", "This notebook documents the variations on additive noise mechanisms in OpenDP:\n", "\n", "* Distribution: Laplace vs. Gaussian\n", "* Support: float vs. integer\n", "* Domain: scalar vs. vector\n", "* Bit-depth" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "----\n", "Any constructors that have not completed the proof-writing and vetting process may still be accessed if you opt-in to \"contrib\".\n", "Please contact us if you are interested in proof-writing. Thank you!" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "from opendp.mod import enable_features\n", "enable_features(\"contrib\")" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Distribution: Laplace vs. Gaussian\n", "\n", "The Laplace mechanism is a ubiquitous algorithm in the DP ecosystem that is used to privatize an aggregate, like a sum or mean.\n", "\n", "An instance of the Laplace mechanism is captured by a _measurement_ containing the following five elements:\n", "\n", "
\n", " Elements of a Laplace Measurement\n", "\n", "1. We first define the **function** $f(\\cdot)$, that applies the Laplace mechanism to some argument $x$. This function simply samples from the Laplace distribution centered at $x$, with a fixed noise scale.\n", "\n", "$$f(x) = Laplace(\\mu=x, b=scale)$$\n", "\n", "2. Importantly, $f(\\cdot)$ is only well-defined for any finite float input. This set of permitted inputs is described by the **input domain** (denoted `AtomDomain`).\n", "\n", "3. The Laplace mechanism has a privacy guarantee in terms of epsilon. \n", "This guarantee is represented by a **privacy map**, a function that computes the privacy loss $\\epsilon$ for any choice of sensitivity $\\Delta$.\n", "\n", "$$map(\\Delta) = \\Delta / scale <= \\epsilon$$\n", "\n", "4. This map only promises that the privacy loss will be at most $\\epsilon$ if inputs from any two neighboring datasets may differ by no more than some quantity $\\Delta$ under the absolute distance **input metric** (`AbsoluteDistance`).\n", "\n", "5. We similarly describe units on the output ($\\epsilon$) via the **output measure** (`MaxDivergence`).\n", "
\n", "\n", "\n", "The `make_base_laplace` constructor function returns the equivalent of the Laplace measurement described above." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "noisy aggregate: 1.7764984858902648\n", "epsilon: 0.5\n" ] } ], "source": [ "from opendp.measurements import make_base_laplace\n", "from opendp.domains import atom_domain\n", "from opendp.metrics import absolute_distance\n", "\n", "# call the constructor to produce the measurement `base_lap`\n", "input_space = atom_domain(T=float), absolute_distance(T=float)\n", "base_lap = make_base_laplace(*input_space, scale=2.)\n", "\n", "# invoke the measurement on some aggregate x, to sample Laplace(x, 1.) noise\n", "aggregated = 0.\n", "print(\"noisy aggregate:\", base_lap(aggregated))\n", "\n", "# we must know the sensitivity of `aggregated` to determine epsilon\n", "sensitivity = 1.\n", "print(\"epsilon:\", base_lap.map(d_in=sensitivity))" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The analogous constructor for gaussian noise is `make_gaussian`: " ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "noisy aggregate: 0.2214567907024509\n", "rho: 0.125\n" ] } ], "source": [ "from opendp.measurements import make_gaussian\n", "\n", "# call the constructor to produce the measurement `gauss`\n", "input_space = atom_domain(T=float), absolute_distance(T=float)\n", "gauss = make_gaussian(*input_space, scale=2.)\n", "\n", "# invoke the measurement on some aggregate x, to sample Gaussian(x, 1.) noise\n", "aggregated = 0.\n", "print(\"noisy aggregate:\", gauss(aggregated))\n", "\n", "# we must know the sensitivity of `aggregated` to determine epsilon\n", "sensitivity = 1.\n", "print(\"rho:\", gauss.map(d_in=sensitivity))" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "Notice that `base_lap` measures privacy with epsilon (in the `MaxDivergence` measure), and `base_gauss` measures privacy with rho (in the `ZeroConcentratedDivergence` measure).\n" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Support: Float vs. Integer\n", "\n", "There are also discrete analogues of the continuous Laplace and Gaussian measurements.\n", "The continuous measurements accept and emit floats, while the discrete measurements accept and emit integers.\n", "Measurements with distributions supported on the integers expect integer sensitivities by default.\n", "\n", "`make_base_discrete_laplace` is equivalent to the geometric mechanism:" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "noisy aggregate: 0\n", "epsilon: 1.0\n" ] } ], "source": [ "from opendp.measurements import make_base_discrete_laplace\n", "\n", "# call the constructor to produce the measurement `base_discrete_lap`\n", "input_space = atom_domain(T=int), absolute_distance(T=int)\n", "base_discrete_lap = make_base_discrete_laplace(*input_space, scale=1.)\n", "\n", "# invoke the measurement on some integer aggregate x, to sample DiscreteLaplace(x, 1.) noise\n", "aggregated = 0\n", "print(\"noisy aggregate:\", base_discrete_lap(aggregated))\n", "\n", "# in this case, the sensitivity is integral:\n", "sensitivity = 1\n", "print(\"epsilon:\", base_discrete_lap.map(d_in=sensitivity))" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "`make_base_discrete_gaussian` is the analogous measurement for Gaussian noise:" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "noisy aggregate: 1\n", "rho: 0.5\n" ] } ], "source": [ "from opendp.measurements import make_base_discrete_gaussian\n", "\n", "# call the constructor to produce the measurement `base_discrete_gauss`\n", "input_space = atom_domain(T=int), absolute_distance(T=int)\n", "base_discrete_gauss = make_base_discrete_gaussian(*input_space, scale=1.)\n", "\n", "# invoke the measurement on some aggregate x, to sample DiscreteGaussian(x, 1.) noise\n", "aggregated = 0\n", "print(\"noisy aggregate:\", base_discrete_gauss(aggregated))\n", "\n", "# we must know the sensitivity of `aggregated` to determine epsilon\n", "sensitivity = 1\n", "print(\"rho:\", base_discrete_gauss.map(d_in=sensitivity))" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The continuous mechanisms use these discrete samplers internally.\n", "More information on this can be found at the end of this notebook." ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Domain: Scalar vs. Vector" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "Measurements covered thus far have accepted scalar inputs and emitted scalar outputs, \n", "and sensitivities have been expressed in terms of the absolute distance.\n", "\n", "The noise addition mechanisms can similarly operate over metric spaces consisting of vectors, \n", "and where the distance between any two vectors is computed via the L1 or L2 distance." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "inferred type is f64, expected Vec. See https://github.com/opendp/opendp/discussions/298\n" ] } ], "source": [ "# call again, but this time indicate that the measurement should operate over a vector domain\n", "\n", "from opendp.domains import vector_domain, atom_domain\n", "from opendp.metrics import l1_distance\n", "input_space = vector_domain(atom_domain(T=float)), l1_distance(T=float)\n", "base_lap_vec = make_base_laplace(*input_space, scale=1.)\n", "\n", "aggregated = 1.\n", "# If we try to pass the wrong data type into our vector laplace measurement, \n", "# the error shows that our float argument should be a vector of floats.\n", "try:\n", " print(\"noisy aggregate:\", base_lap_vec(aggregated))\n", "except TypeError as e:\n", " # The error messages will often point to a discussion page with more info.\n", " print(e)" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "noisy aggregate: [-2.600872570181145, 0.056345706343156464, 0.5331502281803662]\n" ] } ], "source": [ "# actually pass a vector-valued input, as expected\n", "aggregated = [0., 2., 2.]\n", "print(\"noisy aggregate:\", base_lap_vec(aggregated))\n" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The resulting measurement expects sensitivity in terms of the appropriate Lp-distance: the vector Laplace measurement expects sensitivity in terms of an `\"l1_distance(T=f64)\"`, while the vector Gaussian measurement expects a sensitivity in terms of an `\"l2_distance(T=f64)\"`. " ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "epsilon: 1.0\n" ] } ], "source": [ "sensitivity = 1.\n", "print(\"epsilon:\", base_lap_vec.map(d_in=sensitivity))" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The documentation for each constructor also reflects the relationship between `D` and the resulting input metric in a table:" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function make_base_laplace in module opendp.measurements:\n", "\n", "make_base_laplace(input_domain, input_metric, scale, k: int = -1074) -> opendp.mod.Measurement\n", " Make a Measurement that adds noise from the Laplace(`scale`) distribution to a scalar value.\n", " \n", " Valid inputs for `input_domain` and `input_metric` are:\n", " \n", " | `input_domain` | input type | `input_metric` |\n", " | ------------------------------- | ------------ | ---------------------- |\n", " | `atom_domain(T)` (default) | `T` | `absolute_distance(T)` |\n", " | `vector_domain(atom_domain(T))` | `Vec` | `l1_distance(T)` |\n", " \n", " This function takes a noise granularity in terms of 2^k.\n", " Larger granularities are more computationally efficient, but have a looser privacy map.\n", " If k is not set, k defaults to the smallest granularity.\n", " \n", " [make_base_laplace in Rust documentation.](https://docs.rs/opendp/latest/opendp/measurements/fn.make_base_laplace.html)\n", " \n", " **Supporting Elements:**\n", " \n", " * Input Domain: `D`\n", " * Output Type: `D::Carrier`\n", " * Input Metric: `D::InputMetric`\n", " * Output Measure: `MaxDivergence`\n", " \n", " :param input_domain: Domain of the data type to be privatized.\n", " :param input_metric: Metric of the data type to be privatized.\n", " :param scale: Noise scale parameter for the laplace distribution. `scale` == standard_deviation / sqrt(2).\n", " :param k: The noise granularity in terms of 2^k.\n", " :type k: int\n", " :rtype: Measurement\n", " :raises TypeError: if an argument's type differs from the expected type\n", " :raises UnknownTypeException: if a type argument fails to parse\n", " :raises OpenDPException: packaged error from the core OpenDP library\n", "\n" ] } ], "source": [ "help(make_base_laplace)" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The discrete Gaussian mechanism allows for the type of the input sensitivity to be a float.\n", "This is because there is often a square root in the sensitivity calculations for vector-valued queries." ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "0.999698" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from opendp.metrics import l2_distance\n", "\n", "# call again, but this time indicate that the measurement should operate over a vector domain\n", "input_space = vector_domain(atom_domain(T=int)), l2_distance(T=float)\n", "base_gauss_vec = make_base_discrete_gaussian(*input_space, scale=1.)\n", "\n", "base_gauss_vec.map(d_in=1.414)\n" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Bit depth\n", "\n", "By default, all floating-point data types default to 64-bit double-precision (denoted `\"f64\"`), and all integral data types default to 32-bit (denoted `\"i32\"`).\n", "The atomic data type expected by the function and privacy units can be further configured to operate over specific bit-depths by explicitly specifying `\"f32\"` instead of `\"float\"`, or `\"i64\"` instead of `\"int\"`. " ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [], "source": [ "# explicitly specify that the...\n", "# * computation should be handled with 32-bit integers, and the\n", "# * privacy analysis be conducted with 64-bit floats\n", "base_discrete_lap_i32 = make_base_discrete_laplace(\n", " atom_domain(T=\"i32\"), absolute_distance(T=\"i32\"),\n", " scale=1., QO=\"f64\"\n", ")" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "More information on acceptable data types can be found in the _Utilities > Typing_ section of the User Guide." ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Desideratum: Floating-Point Granularity\n", "\n", "The \"continuous\" Laplace and Gaussian measurements convert their float arguments to a rational representation, and then add integer noise to the numerator via the respective discrete distribution. \n", "In the OpenDP Library's default configuration, this rational representation of a float is exact.\n", "Therefore the privacy analysis is as tight as if you were to sample truly continuous noise and then postprocess by rounding to the nearest float. \n", "\n", "For most use-cases the sampling algorithm is sufficiently fast when the rational representation is exact.\n", "That is, when noise is sampled with a granularity of $2^{-1074}$, the same granularity as the distance between subnormal 64-bit floats.\n", "However, the granularity can be adjusted to $2^k$, for some choice of k, for a faster runtime.\n", "Adjusting this parameter comes with a small penalty to the sensitivity (to account for rounding to the nearest rational), and subsequently, to the privacy parameters.\n", "\n", "The following plot shows the resulting distribution for some large choices of k:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "image/png": "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fIixY8fi3r176N27N1JSUqo1DoqI6j69jnHSlEwmg62tLVauXAlDQ0N4eHggOzsbCxcurDRxio6ORlRUlPzvwsJCzmZDRETUiERGRiIyMlLpa+np6Qp/Z2VlqWxPIpFg9uzZmD17tg6iI6L6Qm+JkzYDNlu1aoWmTZvC0NBQXtapUyfk5uaipKQERkZGFdbhgEwiIiIiIqouvY1x0mbA5gsvvICLFy9CJpPJy/7880+0atVKadJERERERESkC3qdVU/TAZvjxo3D3bt38f777+PPP//Erl27MG/ePEyYMEFfu0BERERERI2AXsc4aTpg08nJCXv27MGkSZPQvXt3ODo64v3338eUKVP0tQtERERERNQI6H1yCE0GbAJAz549cejQoRqOioiIiIiI6B96vVWPiIiIiIioPmDiREREREREpAITJyIiIiIiIhWYOBEREREREanAxImIiIiIiEgFJk5EREREREQqMHEiIiIiIiJSgYkTERERERGRCkyciIiIiIiIVGDiREREREREpAITJyIiIiIiIhWYOBEREREREanAxImIiIiIiEgFJk5EREREREQqMHEiIiIiIiJSgYkTERERERGRCkyciIiIiIiIVGDiRET13vLly+Hs7AxjY2P4+PjgyJEjldbdunUrPD090bx5c5iZmcHd3R3r1q2rxWiJiIioPmLiRET12qZNmxAVFYXY2FhkZmbCzc0NAQEBuHXrltL61tbW+Pjjj5GRkYHff/8d4eHhCA8Px549e2o5ciIiIqpPmDgRUb22ZMkSREREIDw8HJ07d0ZiYiJMTU2RnJystH6fPn3w6quvolOnTnBxccH777+P7t2748CBA7UcOREREdUnWiVOaWlpuo6DiEhjJSUlOHbsGPz9/eVlBgYG8Pf3R0ZGhsr1hRBITU3F+fPn8eKLL1Zar7i4GIWFhQoLERERNS5aJU6BgYFwcXHB3Llzcf36dV3HRESklvz8fJSWlsLOzk6h3M7ODrm5uZWuV1BQAHNzcxgZGWHQoEFYunQpXnrppUrrx8XFwdLSUr44OTnpbB+IiIioftAqccrOzkZkZCS2bNmC9u3bIyAgAN9++y1KSkp0HR8Rkc41a9YMJ06cwNGjR/HJJ58gKioK6enpldaPjo5GQUGBfOEPRkRERI2PVomTjY0NJk2ahBMnTuDw4cN47rnnMH78eDg4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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import numpy as np\n", "import matplotlib.pyplot as plt\n", "input_domain, input_metric = vector_domain(atom_domain(T=float)), l1_distance(T=float)\n", "\n", "num_samples = 10_000\n", "fig, axes = plt.subplots(nrows=1, ncols=3, figsize=(10, 3))\n", "fig.subplots_adjust(top=0.8)\n", "for axis, k in zip(axes, [1, 0, -1]):\n", " base_lap_vec = make_base_laplace(input_domain, input_metric, scale=1., k=k)\n", " support, counts = np.unique(base_lap_vec([0.] * num_samples), return_counts=True)\n", " axis.bar(support, counts / num_samples)\n", " axis.set_xticks([-2, 0, 2])\n", " axis.set_title(f\"k = {k}; gap = {2**k}\")\n", "axes[0].set_ylabel(\"density\")\n", "fig.suptitle('make_base_laplace for different choices of k', y=0.95);" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "The distribution becomes increasingly smooth as k approaches the default value (`-1074`).\n", "\n", "The privacy map still adds a penalization when the sensitivity is zero. \n", "The following table uses this behavior to show the increase in epsilon for some choices of k:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
ε penaltydetail
k
-10740.000000e+00no penalty
-10734.940656e-324~min float
-1007.888609e-31~2^-100
-15.000000e-01~2^-1
01.000000e+00~2^0
12.000000e+00~2^1
\n", "
" ], "text/plain": [ " ε penalty detail\n", "k \n", "-1074 0.000000e+00 no penalty\n", "-1073 4.940656e-324 ~min float\n", "-100 7.888609e-31 ~2^-100\n", "-1 5.000000e-01 ~2^-1\n", " 0 1.000000e+00 ~2^0\n", " 1 2.000000e+00 ~2^1" ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "k = [-1074, -1073, -100, -1, 0, 1]\n", "input_domain, input_metric = atom_domain(T=float), absolute_distance(T=float)\n", "ε_penalty = [make_base_laplace(input_domain, input_metric, scale=1., k=k_i).map(d_in=0.) for k_i in k]\n", "detail = [\"no penalty\", \"~min float\", \"~2^-100\", \"~2^-1\", \"~2^0\", \"~2^1\"]\n", "\n", "import pandas as pd\n", "pd.DataFrame({\"k\": k, \"ε penalty\": ε_penalty, \"detail\": detail}).set_index(\"k\")" ] } ], "metadata": { "kernelspec": { "display_name": "psi", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.3" }, "orig_nbformat": 4, "vscode": { "interpreter": { "hash": "3220da548452ac41acb293d0d6efded0f046fab635503eb911c05f743e930f34" } } }, "nbformat": 4, "nbformat_minor": 2 }