# tff.analytics.HierarchicalHistogramDecoder

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/federated/blob/v0.87.0 Version 2.0, January 2004 Licensed under the Apache License, Version 2.0 (the) |

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`](https://www.tensorflow.org/api_docs/python/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.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `hierarchical_histogram` | A [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/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. |

<br />

## Methods

### `enforce_consistency`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    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](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

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

Queries the value of a bin in the hierarchical histogram.

<br />

<br />

<br />

| 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). |

<br />

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

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

<br />

### `quantile_query`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

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

Queries the q-quantile in a hierarchical historgram.

<br />

<br />

<br />

| Args ||
|---|---|
| `q` | A `float` specifying the wanted q-quantile. |

<br />

<br />

<br />

<br />

| 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. ||

<br />

<br />

<br />

<br />

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

<br />

### `range_query`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

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

Returns a range query of a hierarchical historgram.

<br />

<br />

<br />

| 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. |

<br />

<br />

<br />

<br />

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

<br />