# tff.learning.metrics.secure_sum_then_finalize

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/federated/blob/v0.87.0 Version 2.0, January 2004 Licensed under the Apache License, Version 2.0 (the) |

Creates a TFF computation that aggregates metrics using secure summation.

    tff.learning.metrics.secure_sum_then_finalize(
        metric_finalizers: Union[https://www.tensorflow.org/federated/api_docs/python/tff/learning/metrics/MetricFinalizersType, https://www.tensorflow.org/federated/api_docs/python/tff/learning/metrics/FunctionalMetricFinalizersType],
        local_unfinalized_metrics_type: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType] = None,
        metric_value_ranges: Optional[sum_aggregation_factory.UserMetricValueRangeDict] = None
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/Computation

The returned federated TFF computation is a polymorphic computation that
accepts unfinalized client metrics, and returns finalized, summed metrics
placed at the server. Invoking the polymorphic computation will initiate
tracing on the argument and will raise a `ValueError` if the keys (i.e.,
metric names) in `metric_finalizers` are not the same as those of the argument
the polymorphic method is invoked on.

> [!NOTE]
> **Note:** invoking this computation outside of a federated context (a method decorated with [`tff.federated_computation`](https://www.tensorflow.org/federated/api_docs/python/tff/federated_computation)) will require first wrapping it in a concrete, non-polymorphic [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) with appropriate federated types.

The computation is intended to be invoked on the output of
[`tff.learning.models.VariableModel.report_local_unfinalized_metrics()`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#report_local_unfinalized_metrics) when
placed at `CLIENTS`, and the
first output (`aggregated_metrics`) is computed by first securely summing the
unfinalized metrics from `CLIENTS`, followed by applying the finalizers at
`SERVER`. The second output (`secure_sum_measurements`) is an `OrderedDict`
that maps from `factory_key`s to the secure summation measurements (e.g. the
number of clients gets clipped. See [`tff.aggregators.SecureSumFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/SecureSumFactory) for
details). A `factory_key` is uniquely defined by three scalars: lower bound,
upper bound, and tensor dtype (denoted as datatype enum). Metric values of the
same `factory_key` are grouped and aggegrated together (and hence, the
`secure_sum_measurements` are also computed at a group level).

Since secure summation works in fixed-point arithmetic space, floating point
numbers must be encoding using integer quantization. By default, each tensor
in from the clients unfinalized metrics will be clipped to `[0, 2**20 - 1]`
and encoded to integers inside [`tff.aggregators.SecureSumFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/SecureSumFactory). Callers can
change this range by setting `metric_value_ranges`, which may be a partial
tree matching the structure of the argument to `metrics_finalizers`.

Example partial value range specification:

    finalizers = ...
    value_ranges = collections.OrderedDict(
        b=(0.0, 1.0),
        c=[None, (0.0, 1.0)])
    aggregator = tff.learning.metrics.secure_sum_then_finalize(
        finalizers, value_ranges)

This sets the range of the *second* tensor of `b` in the dictionary, using the
range for the first tensor, and the `a` tensor.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `metric_finalizers` | Either the result of [`tff.learning.models.VariableModel.metric_finalizers`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#metric_finalizers) (an `OrderedDict` of callables) or the [`tff.learning.models.FunctionalModel.finalize_metrics`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/FunctionalModel#finalize_metrics) method (a callable that takes an `OrderedDict` argument). If the former, the keys must be the same as the `OrderedDict` returned by [`tff.learning.models.VariableModel.report_local_unfinalized_metrics`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#report_local_unfinalized_metrics). If the later, the callable must compute over the same keyspace of the result returned by [`tff.learning.models.FunctionalModel.update_metrics_state`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/FunctionalModel#update_metrics_state). |
| `local_unfinalized_metrics_type` | Unused, will be removed from the API in the future. |
| `metric_value_ranges` | A `collections.OrderedDict` that matches the structure of the input arguments of `metric_finalizers`. Each leaf in the tree should have a 2-tuple that defines the range of expected values for that variable in the metric. If the entire structure is `None`, a default range of `[0.0, 2.0**20 - 1]` will be applied to all variables. Each leaf may also be `None`, which will also get the default range; allowing partial user sepcialization. At runtime, values that fall outside the ranges specified at the leaves, those values will be clipped to within the range. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| A federated TFF computation that securely sums the unfinalized metrics from `CLIENTS`, and applies the correponding finalizers at `SERVER`. ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If the inputs are of the wrong types. |

<br />