Package com.google.privacy.differentialprivacy

Class Count

  • public class Count
extends java.lang.Object
    Calculates a differentially private count 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), it doesn't do clamping. For datasets with multiple contributions from the same user to a single partition BoundedSum should be used instead.

    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 count meaning that the expected value of the differentially private count is equal to the raw count.

    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

      • increment

        public void increment()
        Increments count by one.
        Throws:
        java.lang.IllegalStateException - if this this instance of Count has already been queried or serialized.

      • incrementBy

        public void incrementBy​(long count)
        Increments count by the given value. Note, that this shouldn't be used to count multiple contributions to a partition from the same user.
        Throws:
        java.lang.IllegalStateException - if this this instance of Count has already been queried or serialized.

      • computeResult

        public long computeResult()
        Calculates and returns a differentially private count of elements added using increment() and incrementBy(long). 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 count.

        The returned value may sometimes be negative. This can be corrected by setting negative results to 0. Note that such post processing introduces bias to the result.

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

      • computeConfidenceInterval

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

        Refer to this doc for more information.

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

      • computeThresholdedResult

        public java.util.Optional<java.lang.Long> computeThresholdedResult​(double thresholdDelta)
        Returns either of computeResult() or Optional.empty(). The result is (epsilon, noiseDelta + thresholdDelta)-differentially private assuming that empty counts are not published. The method can be called only once for a given collection of elements. All subsequent calls will throw an exception.

        To ensure that the boolean signal of a count's publication satisfies (0, thresholdDelta)-differential privacy, noised counts smaller than an appropriately set threshold k > 0 are returned as Optional.empty(). It is the responsibility of the caller of this method to ensure that a count that returned empty is not published.

        Parameters:
        thresholdDelta - the privacy budget spent on publishing non-empty counts.

      • getSerializableSummary

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

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

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

      • mergeWith

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