tf_privacy.QAdaClipTreeResSumQuery

DPQuery for tree aggregation queries with adaptive clipping.

Inherits From: SumAggregationDPQuery, 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.

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

Methods

accumulate_preprocessed_record

View source

accumulate_preprocessed_record(
    sample_state, preprocessed_record
)

Implements tensorflow_privacy.DPQuery.accumulate_preprocessed_record.

accumulate_record

View source

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.

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

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

derive_metrics

View source

derive_metrics(
    global_state
)

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

derive_sample_params

View source

derive_sample_params(
    global_state
)

Implements tensorflow_privacy.DPQuery.derive_sample_params.

get_noised_result

View source

get_noised_result(
    sample_state, global_state
)

Implements tensorflow_privacy.DPQuery.get_noised_result.

initial_global_state

View source

initial_global_state()

Implements tensorflow_privacy.DPQuery.initial_global_state.

initial_sample_state

View source

initial_sample_state(
    template
)

Implements tensorflow_privacy.DPQuery.initial_sample_state.

merge_sample_states

View source

merge_sample_states(
    sample_state_1, sample_state_2
)

Implements tensorflow_privacy.DPQuery.merge_sample_states.

preprocess_record

View source

preprocess_record(
    params, record
)

Implements tensorflow_privacy.DPQuery.preprocess_record.

reset_state

View source

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

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.

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