Package com.google.privacy.differentialprivacy

Class BoundedMean

  • public class BoundedMean
extends java.lang.Object
    Calculates differentially private average for a collection of values.

    The mean is computed by dividing a noisy sum of the entries by a noisy count of the entries. To improve utility, all entries are normalized by setting them to the difference between their actual value and the middle of the input range before summation. The original mean is recovered by adding the midpoint in a post processing step. This idea is taken from Algorithm 2.4 of "Differential Privacy: From Theory to Practice", by Ninghui Li, Min Lyu, Dong Su and Weining Yang (section 2.5.5, page 28). In contrast to Algorithm 2.4, we do not return the midpoint if the noisy count is less or equal to 1. Instead we set the noisy count to 1. Since this is a mere post processing step, the DP bounds are preserved. Moreover, for small numbers of entries, this approach will return results that are closer to the actual mean in expectation.

    Ninghui Li, Min Lyu, Dong Su and Weining Yang also propose Algorithm 2.3 for computing private means, which according to them yields better accuracy. However, the proof of the Algorithm 2.3 is flawed and it is not actually DP.

    Supports contributions from a single privacy unit to multiple partitions as well as multiple contributions from a single privacy unit to a given partition.

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

    Note: the 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 mean.
        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedMean 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 mean.
        Throws:
        java.lang.IllegalStateException - if this this instance of BoundedMean has already been queried or serialized.

      • computeResult

        public double computeResult()
        Calculates and returns differentially private average of elements added using 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 result in throwing an exception.

        Note that the returned value is not an unbiased estimate of the raw bounded mean.

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

      • computeConfidenceInterval

        public ConfidenceInterval computeConfidenceInterval​(double alpha)
        Computes a confidence interval that contains the true mean with a probability greater or equal to 1 - alpha. The computation is based exclusively on the noised data and the privacy parameters. Thus no privacy budget is consumed by this operation.

        Refer to this doc for more information.

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

      • getSerializableSummary

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

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

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

      • mergeWith

        public void mergeWith​(byte[] otherBoundedMeanSummary)
        Merges the output of getSerializableSummary() from a different instance of BoundedMean 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 BoundedMean has already been queried or serialized.