Package com.google.privacy.differentialprivacy

Class BoundedSum

  • public class BoundedSum
extends java.lang.Object
    Calculates a differentially private sum for a collection of values using the Laplace or Gaussian mechanism.

    This class allows a single privacy unit (e.g., an individual) to contribute data to multiple different partitions. The class does not check whether the number of partitions is within the specified bounds. This is the responsibility of the caller.

    This class assumes that each privacy unit may contribute to a single partition only once (i.e., only one data contribution per privacy unit per partition). Multiple contributions from a single privacy unit should be pre-aggregated before they are passed to this class.

    The user can provide a Noise instance which will be used to generate the noise. If no instance is specified, LaplaceNoise is applied.

    This class provides an unbiased estimator for the raw bounded sum meaning that the expected value of the differentially private bounded sum is equal to the raw bounded sum.

    Note: this class is not thread-safe.

    For more implementation details, see computeResult().

    For general details and key definitions, see this introduction to Differential Privacy.

    • Method Detail

      • addEntry

        public void addEntry​(double e)
        Clamps the input value and adds it to the sum.
        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedSum has already been queried or serialized.

      • addEntries

        public void addEntries​(java.util.Collection<java.lang.Double> e)
        Clamps the input values and adds them to the sum.
        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedSum has already been queried or serialized.

      • computeResult

        public double computeResult()
        Computes and returns a differentially private sum of the elements added via addEntry(double) and addEntries(java.util.Collection<java.lang.Double>). The method can be called only once for a given collection of elements. All subsequent calls will throw an exception.

        The returned value is an unbiased estimate of the raw bounded sum.

        The returned value may sometimes be outside the set of possible raw bounded sums, e.g., the differentially private bounded sum may be positive although neither the lower nor the upper bound are positive. This can be corrected by the caller of this method, e.g., by snapping the result to the closest value representing a bounded sum that is possible. Note that such post processing introduces bias to the result.

        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedSum has already been queried or serialized.

      • computeConfidenceInterval

        public ConfidenceInterval computeConfidenceInterval​(double alpha)
        Computes a confidence interval that contains the true BoundedSum with a probability greater or equal to 1 - alpha using the noised BoundedSum computed by computeResult().

        Refer to this doc for more information.

        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedSum has not been queried yet.

      • getSerializableSummary

        public byte[] getSerializableSummary()
        Returns a serializable summary of the current state of this BoundedSum instance and its parameters. The summary can be used to merge this instance with another instance of BoundedSum.

        This method cannot be invoked if the sum has already been queried, i.e., computeResult() has been called. Moreover, after this instance of BoundedSum has been serialized once, no further modification, queries or serialization is possible anymore.

        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedSum has already been queried or serialized.

      • mergeWith

        public void mergeWith​(byte[] otherBoundedSumSummary)
        Merges the output of getSerializableSummary() from a different instance of BoundedSum with this instance. Intended to be used in the context of distributed computation.
        Throws:
        java.lang.IllegalArgumentException - if the parameters of the two instances (epsilon, delta, contribution bounds, etc.) do not match or if the passed serialized summary is invalid.
        java.lang.IllegalStateException - if this this instance of BoundedSum has already been queried or serialized.