# tff.program.FilteringReleaseManager

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

A [`tff.program.ReleaseManager`](https://www.tensorflow.org/federated/api_docs/python/tff/program/ReleaseManager) that filters values before releasing them.

Inherits From: [`ReleaseManager`](https://www.tensorflow.org/federated/api_docs/python/tff/program/ReleaseManager)

    tff.program.FilteringReleaseManager(
        release_manager: ReleaseManager[ReleasableStructure, Key],
        filter_fn: Callable[[tuple[Union[str, int], ...]], bool]
    )

A [`tff.program.FilteringReleaseManager`](https://www.tensorflow.org/federated/api_docs/python/tff/program/FilteringReleaseManager) is a utility for filtering values
before releasing the values and is used to release values from platform
storage to customer storage in a federated program.

Values are filtered using a `filter_fn` and released to the `release_manager`.

The `filter_fn` is a `Callable` that has a single parameter `path` and returns
a `bool`, and is used to filter values before they are released. A `path` is a
tuple of indices and/or keys which uniquely identifies the position of the
corresponding item in the `value`; `path` matches the expectations of the
`tree` library.

The `filter_fn` is applied to the items in the structure but not the structure
itself. If all the items in a structure are filtered out, then the structure
will be filtered out as well.

#### For example:

    filtering_manager = tff.program.FilteringReleaseManager(
        release_manager=...,
        filter_fn=...,
    )

    value = {
      'loss': 1.0,
      'accuracy': 0.5,
    }
    await filtering_manager.release(value, ...)

If `filter_fn` is:

- `lambda _: True` then the entire structure is released.
- `lambda _: False` then nothing is released.
- `lambda path: path == ('loss',)` then `{'loss': 1.0}` is released.

> [!NOTE]
> **Note:** The path `()` corresponds to the root of the structure; because the `filter_fn` is applied to the items in the structure but not the structure itself, this path can be used to filter individual values from structures of values.

> [!IMPORTANT]
> **Important:** Most [`tff.program.ReleasableStructure`](https://www.tensorflow.org/federated/api_docs/python/tff/program#ReleasableStructure) can be filtered, including individual values, structures, and structures nested in `NamedTuple`s. However, the fields of a `NamedTuple` cannot be filtered.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `release_manager` | A [`tff.program.ReleaseManager`](https://www.tensorflow.org/federated/api_docs/python/tff/program/ReleaseManager) used to release values to. |
| `filter_fn` | A `Callable` used to filter values before they are released, this function has a single parameter `path` and returns a `bool`. |

<br />

## Methods

### `release`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    release(
        value, key
    ) -> Optional[Union[ReleasableStructure, type(_FILTERED_SUBTREE)]]

Releases `value` from a federated program.

<br />

<br />

<br />

| Args ||
|---|---|
| `value` | A [`tff.program.ReleasableStructure`](https://www.tensorflow.org/federated/api_docs/python/tff/program#ReleasableStructure) to release. |
| `key` | A value used to reference the released `value`. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `NotFilterableError` | If the `value` cannot be filtered. |

<br />