tff.analytics.HierarchicalHistogramDecoder

Hierarchical histogram decoder.

tff.analytics.HierarchicalHistogramDecoder(
    hierarchical_histogram: tf.RaggedTensor,
    lower_bound: float,
    upper_bound: float,
    use_efficient: bool = False
)

Decodes the output hierarchical histogram of the function returned by build_central_hierarchical_histogram_computation to answer node queries / range queries / other statistics. A hierarchical histogram is a tf.RaggedTensor, tree, in which the jth node in the ith layer can be accessed via directly indexing tree[i][j]. When the hierarchical histogram is differentially private, provides optional optimization tricks to improve query accuracy.

hierarchical_histogram A tf.RaggedTensor for the hierarchical histogram.
lower_bound A float representing the lower bound of the hierarchical histogram data.
upper_bound A float representing the upper bound of the hierarchical histogram data.
use_efficient A boolean indicating the usage of the efficient tree aggregation algorithm.

Methods

enforce_consistency

View source

enforce_consistency()

Make the tree consistent by solving a least square optimization problem.

See 'Answering Range Queries Under Local Differential Privacy. Graham Cormode, Tejas Kulkarni, Divesh Srivastava' for details. Improve the accuracy of range queries. When this function is invoked, use_efficient will be automatically set to False because using both optimizations does not further improve the accuracy.

node_query

View source

node_query(
    layer: int, index: int
) -> float

Queries the value of a bin in the hierarchical histogram.

Args
layer An int for the cross-layer index of a node (i.e. which layer the node is in).
index An int for the inne-layer index of a node (i.e. index^th node in the layer).

Returns
A float representing the estimation of the value of the bin indexed by (layer, index).

Raises
ValueError if (layer, index) does not point to an existing node.

quantile_query

View source

quantile_query(
    q
) -> tuple[float, float]

Queries the q-quantile in a hierarchical historgram.

Args
q A float specifying the wanted q-quantile.

Returns
A tuple representing the range of values within the bin such that the sum of bins before it accounts for at least q proportion of the total sum.

Raises
ValueError if the hierarchical histogram is not consistent (e.g. with DP noise) or q is not within [0, 1].

range_query

View source

range_query(
    left: int, right: int
) -> float

Returns a range query of a hierarchical historgram.

Args
left An int representing the inclusive left end of the range query.
right An int representing the inclusive right end of the range query.

Returns
An float representing the sum of the bins within the range of [left, right].