# tf_privacy.QAdaClipTreeResSumQuery

<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/quantile_adaptive_clip_tree_query.py#L25-L196) |

`DPQuery` for tree aggregation queries with adaptive clipping.

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.QAdaClipTreeResSumQuery(
        initial_l2_norm_clip,
        noise_multiplier,
        record_specs,
        target_unclipped_quantile,
        learning_rate,
        clipped_count_stddev,
        expected_num_records,
        geometric_update=True,
        noise_seed=None
    )

The implementation is based on tree aggregation noise for cumulative sum in
"Practical and Private (Deep) Learning without Sampling or Shuffling"
(<https://arxiv.org/abs/2103.00039>) and quantile-based adaptive clipping in
"Differentially Private Learning with Adaptive Clipping"
(<https://arxiv.org/abs/1905.03871>).

The quantile value will be continuously estimated, but the clip norm is only
updated when `reset_state` is called, and the tree state will be reset. This
will force the clip norm (and corresponding stddev) in a tree unchanged.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `initial_l2_norm_clip` | The initial value of clipping norm. |
| `noise_multiplier` | The stddev of the noise added to the output will be this times the current value of the clipping norm. |
| `record_specs` | A nested structure of [`tf.TensorSpec`](https://www.tensorflow.org/api_docs/python/tf/TensorSpec)s specifying structure and shapes of records. |
| `target_unclipped_quantile` | The desired quantile of updates which should be unclipped. I.e., a value of 0.8 means a value of l2_norm_clip should be found for which approximately 20% of updates are clipped each round. Andrew et al. recommends that this be set to 0.5 to clip to the median. |
| `learning_rate` | The learning rate for the clipping norm adaptation. With geometric updating, a rate of r means that the clipping norm will change by a maximum factor of exp(r) at each round. This maximum is attained when \|actual_unclipped_fraction - target_unclipped_quantile\| is 1.0. Andrew et al. recommends that this be set to 0.2 for geometric updating. |
| `clipped_count_stddev` | The stddev of the noise added to the clipped_count. Andrew et al. recommends that this be set to `expected_num_records / 20` for reasonably fast adaptation and high privacy. |
| `expected_num_records` | The expected number of records per round, used to estimate the clipped count quantile. |
| `geometric_update` | If `True`, use geometric updating of clip (recommended). |
| `noise_seed` | Integer seed for the Gaussian noise generator of `TreeResidualSumQuery`. If `None`, a nondeterministic seed based on system time will be generated. |

<br />

## 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 />

### `derive_metrics`

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

    derive_metrics(
        global_state
    )

Returns the clipping norm and estimated quantile value as a metric.

### `derive_sample_params`

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

    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/quantile_adaptive_clip_tree_query.py#L146-L159)

    get_noised_result(
        sample_state, global_state
    )

Implements `tensorflow_privacy.DPQuery.get_noised_result`.

### `initial_global_state`

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

    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/quantile_adaptive_clip_tree_query.py#L130-L134)

    initial_sample_state(
        template
    )

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/quantile_adaptive_clip_tree_query.py#L136-L144)

    preprocess_record(
        params, record
    )

Implements `tensorflow_privacy.DPQuery.preprocess_record`.

### `reset_state`

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

    reset_state(
        noised_results, global_state
    )

Returns state after resetting the tree and updating the clip norm.

This function will be used in [`restart_query.RestartQuery`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/restart_query/RestartQuery) after calling
`get_noised_result` when the restarting condition is met. The clip norm (
and corresponding noise stddev) for the tree aggregated sum query is only
updated from the quantile-based estimation when `reset_state` is called.

<br />

<br />

<br />

| Args ||
|---|---|
| `noised_results` | Noised cumulative sum returned by `get_noised_result`. |
| `global_state` | Updated global state returned by `get_noised_result`, which records noise for the conceptual cumulative sum of the current leaf node, and tree state for the next conceptual cumulative sum. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| New global state with restarted tree state, and new clip norm. ||

<br />