# tf_privacy.TreeCumulativeSumQuery

<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_aggregation_query.py#L48-L261) |

Returns private cumulative sums by clipping and adding correlated noise.

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.TreeCumulativeSumQuery(
        record_specs, noise_generator, clip_fn, clip_value, use_efficient=True
    )

Consider calling `get_noised_result` T times, and each (x_i, i=0,2,...,T-1) is
the private value returned by `accumulate_record`, i.e. x*i = sum* {j=0}\^{n-1}
x*{i,j} where each x* {i,j} is a private record in the database. This class is
intended to make multiple queries, which release privatized values of the
cumulative sums s*i = sum* {k=0}\^{i} x_k, for i=0,...,T-1.
Each call to `get_noised_result` releases the next cumulative sum s_i, which
is in contrast to the GaussianSumQuery that releases x_i. Noise for the
cumulative sums is accomplished using the tree aggregation logic in
`tree_aggregation`, which is proportional to log(T).

<br />

<br />

<br />

| ## Example usage ||
|---|---|
| query = TreeCumulativeSumQuery(...) global_state = query.initial_global_state() params = query.derive_sample_params(global_state) for i, samples in enumerate(streaming_samples): sample_state = query.initial_sample_state(samples\[0\]) # Compute x*i = sum*{j=0}\^{n-1} x_{i,j} for j,sample in enumerate(samples): sample_state = query.accumulate_record(params, sample_state, sample) # noised_cumsum is privatized estimate of s_i noised_cumsum, global_state, event = query.get_noised_result( sample_state, global_state) ||

<br />

<br />

<br />

<br />

| ## Args ||
|---|---|
| `record_specs` | A nested structure of [`tf.TensorSpec`](https://www.tensorflow.org/api_docs/python/tf/TensorSpec)s specifying structure and shapes of records. |
| `noise_generator` | [`tree_aggregation.ValueGenerator`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/tree_aggregation/ValueGenerator) to generate the noise value for a tree node. Should be coupled with clipping norm to guarantee privacy. |
| `clip_fn` | Callable that specifies clipping function. Input to clip is a flat list of vars in a record. |
| `clip_value` | Float indicating the value at which to clip the record. |
| `use_efficient` | Boolean indicating the usage of the efficient tree aggregation algorithm based on the paper "Efficient Use of Differentially Private Binary Trees". |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `clip_fn` | Callable that specifies clipping function. `clip_fn` receives two arguments: a flat list of vars in a record and a `clip_value` to clip the corresponding record, e.g. clip_fn(flat_record, clip_value). |
| `clip_value` | float indicating the value at which to clip the record. |
| `record_specs` | `Collection[tf.TensorSpec]` specifying shapes of records. |
| `tree_aggregator` | [`tree_aggregation.TreeAggregator`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/tree_aggregation/TreeAggregator) initialized with user defined `noise_generator`. `noise_generator` is a [`tree_aggregation.ValueGenerator`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/tree_aggregation/ValueGenerator) to generate the noise value for a tree node. Noise stdandard deviation is specified outside the `dp_query` by the user when defining `noise_fn` and should have order O(clip_norm\*log(T)/eps) to guarantee eps-DP. |

<br />

## Child Classes

[`class GlobalState`](https://www.tensorflow.org/responsible_ai/privacy/api_docs/python/tf_privacy/TreeCumulativeSumQuery/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_l2_gaussian_query`

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

    @classmethod
    build_l2_gaussian_query(
        clip_norm,
        noise_multiplier,
        record_specs,
        noise_seed=None,
        use_efficient=True
    )

Returns a query instance with L2 norm clipping and Gaussian noise.

<br />

<br />

<br />

| Args ||
|---|---|
| `clip_norm` | Each record will be clipped so that it has L2 norm at most `clip_norm`. |
| `noise_multiplier` | The effective noise multiplier for the sum of records. Noise standard deviation is `clip_norm*noise_multiplier`. The value can be used as the input of the privacy accounting functions in `analysis.tree_aggregation_accountant`. |
| `record_specs` | A nested structure of [`tf.TensorSpec`](https://www.tensorflow.org/api_docs/python/tf/TensorSpec)s specifying structure and shapes of records. |
| `noise_seed` | Integer seed for the Gaussian noise generator. If `None`, a nondeterministic seed based on system time will be generated. |
| `use_efficient` | Boolean indicating the usage of the efficient tree aggregation algorithm based on the paper "Efficient Use of Differentially Private Binary Trees". |

<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_aggregation_query.py#L144-L146)

    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_aggregation_query.py#L163-L191)

    get_noised_result(
        sample_state, global_state
    )

Implements `tensorflow_privacy.DPQuery.get_noised_result`.

Updates tree state, and returns noised cumulative sum and updated state.

Computes new cumulative sum, and returns its noised value. Grows tree state
by one new leaf, and returns the new state.

<br />

<br />

<br />

| Args ||
|---|---|
| `sample_state` | Sum of clipped records for this round. |
| `global_state` | Global state with current sample's cumulative sum and tree state. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A tuple of (noised_cumulative_sum, new_global_state). ||

<br />

### `initial_global_state`

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

    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/dp_query.py#L288-L290)

    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_aggregation_query.py#L148-L161)

    preprocess_record(
        params, record
    )

Implements `tensorflow_privacy.DPQuery.preprocess_record`.

<br />

<br />

<br />

| Args ||
|---|---|
| `params` | `clip_value` for the record. |
| `record` | The record to be processed. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| Structure of clipped tensors. ||

<br />

### `reset_state`

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

    reset_state(
        noised_results, global_state
    )

Returns state after resetting the tree.

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.

<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 has current sample's cumulative sum and tree state for the next cumulative sum. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| New global state with current noised cumulative sum and restarted tree state for the next cumulative sum. ||

<br />