Creates an IterativeProcess for hierarchical histogram aggregation.
tff.analytics.build_hierarchical_histogram_process(
lower_bound: float,
upper_bound: float,
num_bins: int,
arity: int = 2,
clip_mechanism: str = 'sub-sampling',
max_records_per_user: int = 10,
dp_mechanism: str = 'no-noise',
noise_multiplier: float = 0.0,
expected_clients_per_round: int = 10,
bits: int = 22,
enable_secure_sum: bool = True
) -> tff.templates.IterativeProcess
This function wraps the tff.computation
created by the
build_hierarchical_histogram_computation
in an IterativeProcess
that
is compatible with tff.backends.mapreduce.MapReduceForm
.
Args |
lower_bound
|
A float specifying the lower bound of the data range.
|
upper_bound
|
A float specifying the upper bound of the data range.
|
num_bins
|
The integer number of bins to compute.
|
arity
|
The branching factor of the tree. Defaults to 2.
|
clip_mechanism
|
A str representing the clipping mechanism. Currently
supported mechanisms are - 'sub-sampling': (Default) Uniformly sample up
to max_records_per_user records without replacement from the client
dataset. - 'distinct': Uniquify client dataset and uniformly sample up to
max_records_per_user records without replacement from it.
|
max_records_per_user
|
An int representing the maximum of records each user
can include in their local histogram. Defaults to 10.
|
dp_mechanism
|
A str representing the differentially private mechanism to
use. Currently supported mechanisms are - 'no-noise': (Default) Tree
aggregation mechanism without noise. - 'central-gaussian': Tree
aggregation with central Gaussian mechanism. -
'distributed-discrete-gaussian': Tree aggregation mechanism with the
distributed discrete Gaussian mechanism in "The Distributed Discrete
Gaussian Mechanism for Federated Learning with Secure Aggregation. Peter
Kairouz, Ziyu Liu, Thomas Steinke".
noise_multiplier: A float specifying the noise multiplier (central noise
stddev / L2 clip norm) for model updates. Defaults to 0.0.
|
expected_clients_per_round
|
An int specifying the lower bound on the
expected number of clients. Only needed when dp_mechanism is
'distributed-discrete-gaussian'. Defaults to 10.
|
bits
|
A positive integer specifying the communication bit-width B (where
2**B will be the field size for SecAgg operations). Only needed when
dp_mechanism is 'distributed-discrete-gaussian'. Please read the below
precautions carefully and set bits accordingly. Otherwise, unexpected
overflow or accuracy degradation might happen. (1) Should be in the
inclusive range [1, 22] to avoid overflow inside secure aggregation; (2)
Should be at least as large as log2(4 * sqrt(expected_clients_per_round)*
noise_multiplier * l2_norm_bound + expected_clients_per_round *
max_records_per_user) + 1 to avoid accuracy degradation caused by
frequent modular clipping; (3) If the number of clients exceed
expected_clients_per_round , overflow might happen.
|
enable_secure_sum
|
Whether to aggregate client's update by secure sum or
not. Defaults to True . When dp_mechanism is set to
'distributed-discrete-gaussian' , enable_secure_sum must be True .
|
Returns |
A federated computation that performs hierarchical histogram aggregation.
|