# tf_privacy.DistributedSkellamSumQuery

<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/distributed_skellam_query.py#L24-L130) |

Implements DPQuery interface for discrete distributed sum queries.

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.DistributedSkellamSumQuery(
        l1_norm_bound, l2_norm_bound, local_stddev
    )

This implementation is for the distributed queries where the Skellam noise
is applied locally to a discrete vector that matches the norm bound.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `l1_norm_bound` | The l1 norm bound to verify for each record. |
| `l2_norm_bound` | The l2 norm bound to verify for each record. |
| `local_stddev` | The standard deviation of the Skellam distribution. |

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

### `add_noise_to_sample`

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

    add_noise_to_sample(
        local_stddev, record
    )

Adds Skellam noise to the sample.

We use difference of two Poisson random variable with lambda hyperparameter
that equals 'local_stddev\*\*2/2' that results in a standard deviation
'local_stddev' for the Skellam noise to be added locally.

<br />

<br />

<br />

| Args ||
|---|---|
| `local_stddev` | The standard deviation of the local Skellam noise. |
| `record` | The record to be processed. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A record with added noise. ||

<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/distributed_skellam_query.py#L58-L61)

    derive_sample_params(
        global_state
    )

Given the global state, derives parameters to use for the next sample.

For example, if the mechanism needs to clip records to bound the norm,
the clipping norm should be part of the sample params. In a distributed
context, this is the part of the state that would be sent to the workers
so they can process records.

<br />

<br />

<br />

| Args ||
|---|---|
| `global_state` | The current global state. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| Parameters to use to process records in the next sample. ||

<br />

### `get_noised_result`

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

    get_noised_result(
        sample_state, global_state
    )

The noise was already added locally, therefore just continue.

### `initial_global_state`

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

    initial_global_state()

Since we operate on discrete values, use int for L1 bound and float for L2 bound.

### `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/distributed_skellam_query.py#L91-L125)

    preprocess_record(
        params, record
    )

Check record norm and add noise to the record.

For both L1 and L2 norms we compute a global norm of the provided record.
Since the record contains int32 tensors we cast them into float32 to
compute L2 norm. In the end we run three asserts: type, l1, and l2 norms.

<br />

<br />

<br />

| Args ||
|---|---|
| `params` | The parameters for the particular sample. |
| `record` | The record to be processed. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A tuple (preprocessed_records, params) where `preprocessed_records` is the structure of preprocessed tensors, and params contains sample params. ||

<br />