Package com.google.privacy.differentialprivacy

Class BoundedQuantiles

  • public class BoundedQuantiles
extends java.lang.Object
    Calculates differentially private quantiles for a collection of values using a quantile tree mechanism.

    Note: the class is not thread-safe.

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

      • computeResult

        public double computeResult​(double rank)
        Calculates and returns a differentially private quantile of the values added via addEntry(double) and addEntries(java.util.Collection<java.lang.Double>). The specified rank must be between 0.0 and 1.0.

        This method can be called multiple times to compute different quantiles. Privacy budget is paid only once, on its first invocation. Calling this method repeatedly for the same rank will return the same result. The results of repeated calls are guaranteed to be monotonically increasing in the sense that r_1 < r_2 implies that computeResult(r_1) <= computeResult(r_2).

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

        Throws:
        java.lang.IllegalStateException - if this instance of BoundedQuantiles has already been serialized.

      • getSerializableSummary

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

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

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

      • mergeWith

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