nvflare.recipe.fedstats module

class FedStatsRecipe(name: str, stats_output_path: str, sites: List[str], statistic_configs: Dict[str, Any], stats_generator: Statistics, min_count: int = 10, min_noise_level: float = 0.1, max_noise_level: float = 0.3, max_bins_percent: float = 10)[source]

Bases: Recipe

A recipe for federated statistics computation.

Recipe parameters become part of the generated job definition and must never contain actual secret values. Read secrets from site environment variables or mounted files; references are supported only where documented in nvflare.recipe.secrets.

FedStatsRecipe is a specialized recipe that facilitates the computation of statistics across multiple federated sites. It creates and configures a StatsJob with the specified parameters and sets up the necessary client connections for distributed statistics computation.

This recipe computes various statistical measures (such as mean, variance, histograms, & quantiles) across data distributed across multiple sites while maintaining data privacy.

Parameters:

  • name (str) – The name of the federated statistics job.

  • stats_output_path (str) – The file path where the computed statistics results will be saved.

  • sites (List[str]) – A list of site names/identifiers that will participate in the federated statistics computation.

  • statistic_configs (Dict[str, Any]) – Configuration dictionary specifying which statistics to compute and their parameters. The structure depends on the specific statistics generator being used.

  • stats_generator (Statistics) – An instance of a Statistics class that implements the actual statistics computation logic. This object must implement the Statistics interface.

  • min_count (int) – The minimum number of samples required to compute a statistic.

  • min_noise_level (float) – The minimum noise level for the statistics.

  • max_noise_level (float) – The maximum noise level for the statistics.

  • max_bins_percent (float) – The maximum percentage of bins for the statistics.

Example

>>> from nvflare.recipe.fedstats import FedStatsRecipe
>>> from my_stats_generator import MyStatsGenerator
>>>
>>> config = {
...     "count": {},
...     "sum": {},
...     "mean": {},
...     "std": {}
... }
>>>
>>> recipe = FedStatsRecipe(
...     name="my_stats_job",
...     stats_output_path="path/to/output",
...     sites=["site1", "site2", "site3"],
...     statistic_configs=config,
...     stats_generator=MyStatsGenerator()
... )

This is base class of a recipe. Recipes are implemented by jobs. A concrete recipe must provide the job for recipe implementation.

Security contract – no secrets in recipe parameters:

Recipe parameters (train_args, task_args, eval_args, per_site_config, config overrides, dicts passed to add_client_config/add_server_config, exec params, etc.) can be written in clear text into generated job configuration. These parameters and their nested values must never contain actual passwords, API keys, tokens, private keys, or other credentials. Instead, read secrets from site environment variables or mounted secret files inside your code, or pass a placeholder created with nvflare.recipe.secrets.secret_ref() or nvflare.recipe.secrets.secret_file_ref() at a supported runtime boundary. See nvflare.recipe.secrets for the supported parameter locations.

Before export or run, recipes scan their parameters with heuristics and emit nvflare.recipe.secrets.PotentialSecretWarning when a value looks like an actual secret. The scan is best-effort: absence of a warning does not prove a parameter is safe to share.

Parameters:

job – the job that implements the recipe.