# tf_privacy.TreeRangeSumQuery

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L93-L268) |

Implements dp_query for accurate range queries using tree aggregation.

Inherits From: [`SumAggregationDPQuery`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/SumAggregationDPQuery), [`DPQuery`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/DPQuery)

    tf_privacy.TreeRangeSumQuery(
        inner_query: https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/SumAggregationDPQuery,
        arity: int = 2
    )

Implements a variant of the tree aggregation protocol from. "Is interaction
necessary for distributed private learning?. Adam Smith, Abhradeep Thakurta,
Jalaj Upadhyay." Builds a tree on top of the input record and adds noise to
the tree for differential privacy. Any range query can be decomposed into the
sum of O(log(n)) nodes in the tree compared to O(n) when using a histogram.
Improves efficiency and reduces noise scale.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `inner_query` | The inner `DPQuery` that adds noise to the tree. |
| `arity` | The branching factor of the tree (i.e. the number of children each internal node has). Defaults to 2. |

<br />

## Child Classes

[`class GlobalState`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/TreeRangeSumQuery/GlobalState)

## Methods

### `accumulate_preprocessed_record`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/dp_query.py#L292-L295)

    accumulate_preprocessed_record(
        sample_state, preprocessed_record
    )

Implements `tensorflow_privacy.DPQuery.accumulate_preprocessed_record`.

### `accumulate_record`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/dp_query.py#L187-L210)

    accumulate_record(
        params, sample_state, record
    )

Accumulates a single record into the sample state.

This is a helper method that simply delegates to `preprocess_record` and
`accumulate_preprocessed_record` for the common case when both of those
functions run on a single device. Typically this will be a simple sum.

<br />

<br />

<br />

| Args ||
|---|---|
| `params` | The parameters for the sample. In standard DP-SGD training, the clipping norm for the sample's microbatch gradients (i.e., a maximum norm magnitude to which each gradient is clipped) |
| `sample_state` | The current sample state. In standard DP-SGD training, the accumulated sum of previous clipped microbatch gradients. |
| `record` | The record to accumulate. In standard DP-SGD training, the gradient computed for the examples in one microbatch, which may be the gradient for just one example (for size 1 microbatches). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The updated sample state. In standard DP-SGD training, the set of previous microbatch gradients with the addition of the record argument. ||

<br />

### `build_central_gaussian_query`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L213-L238)

    @classmethod
    build_central_gaussian_query(
        l2_norm_clip: float, stddev: float, arity: int = 2
    )

Returns `TreeRangeSumQuery` with central Gaussian noise.

<br />

<br />

<br />

| Args ||
|---|---|
| `l2_norm_clip` | Each record should be clipped so that it has L2 norm at most `l2_norm_clip`. |
| `stddev` | Stddev of the central Gaussian noise. |
| `arity` | The branching factor of the tree (i.e. the number of children each internal node has). Defaults to 2. |

<br />

### `build_distributed_discrete_gaussian_query`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L240-L268)

    @classmethod
    build_distributed_discrete_gaussian_query(
        l2_norm_bound: float, local_stddev: float, arity: int = 2
    )

Returns `TreeRangeSumQuery` with central Gaussian noise.

<br />

<br />

<br />

| Args ||
|---|---|
| `l2_norm_bound` | Each record should be clipped so that it has L2 norm at most `l2_norm_bound`. |
| `local_stddev` | Scale/stddev of the local discrete Gaussian noise. |
| `arity` | The branching factor of the tree (i.e. the number of children each internal node has). Defaults to 2. |

<br />

### `derive_metrics`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/dp_query.py#L256-L268)

    derive_metrics(
        global_state
    )

Derives metric information from the current global state.

Any metrics returned should be derived only from privatized quantities.

<br />

<br />

<br />

| Args ||
|---|---|
| `global_state` | The global state from which to derive metrics. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A `collections.OrderedDict` mapping string metric names to tensor values. ||

<br />

### `derive_sample_params`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L143-L147)

    derive_sample_params(
        global_state
    )

Implements `tensorflow_privacy.DPQuery.derive_sample_params`.

### `get_noised_result`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L179-L211)

    get_noised_result(
        sample_state, global_state
    )

Implements `tensorflow_privacy.DPQuery.get_noised_result`.

This function re-constructs the [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor) from the flattened tree
output by `preprocess_records.`

<br />

<br />

<br />

| Args ||
|---|---|
| `sample_state` | A [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) for the flattened tree. |
| `global_state` | The global state of the protocol. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A [`tf.RaggedTensor`](https://www.tensorflow.org/api_docs/python/tf/RaggedTensor) representing the tree. ||

<br />

### `initial_global_state`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L131-L135)

    initial_global_state()

Implements `tensorflow_privacy.DPQuery.initial_global_state`.

### `initial_sample_state`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L137-L141)

    initial_sample_state(
        template=None
    )

Implements `tensorflow_privacy.DPQuery.initial_sample_state`.

### `merge_sample_states`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/dp_query.py#L297-L299)

    merge_sample_states(
        sample_state_1, sample_state_2
    )

Implements `tensorflow_privacy.DPQuery.merge_sample_states`.

### `preprocess_record`

[View source](https://github.com/tensorflow/privacy/blob/v0.9.0/privacy/privacy/dp_query/tree_range_query.py#L149-L177)

    preprocess_record(
        params, record
    )

Implements `tensorflow_privacy.DPQuery.preprocess_record`.

This method builds the tree, flattens it and applies
`inner_query.preprocess_record` to the flattened tree.

<br />

<br />

<br />

| Args ||
|---|---|
| `params` | Hyper-parameters for preprocessing record. |
| `record` | A histogram representing the leaf nodes of the tree. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor) representing the flattened version of the preprocessed tree. ||

<br />