Federated Learning#

Client Base Classes#

class monai.fl.client.BaseClient[source]#

Provide an abstract base class to allow the client to return summary statistics of the data.

To define a new stats script, subclass this class and implement the following abstract methods:

- self.get_data_stats()

initialize(), abort(), and finalize() – inherited from ClientAlgoStats; can be optionally be implemented to help with lifecycle management of the class object.

abort(extra=None)[source]#

Call to abort the ClientAlgo training or evaluation.

Parameters:

extra – Dict with additional information that can be provided by the FL system.

finalize(extra=None)[source]#

Call to finalize the ClientAlgo class.

Parameters:

extra – Dict with additional information that can be provided by the FL system.

initialize(extra=None)[source]#

Call to initialize the ClientAlgo class.

Parameters:

extra – optional extra information, e.g. dict of ExtraItems.CLIENT_NAME and/or ExtraItems.APP_ROOT.

class monai.fl.client.ClientAlgo[source]#

Provide an abstract base class for defining algo to run on any platform. To define a new algo script, subclass this class and implement the following abstract methods:

  • self.train()

  • self.get_weights()

  • self.evaluate()

  • self.get_data_stats() (optional, inherited from ClientAlgoStats)

initialize(), abort(), and finalize() - inherited from ClientAlgoStats - can be optionally be implemented to help with lifecycle management of the class object.

evaluate(data, extra=None)[source]#

Get evaluation metrics on test data.

Parameters:

  • data – ExchangeObject with network weights to use for evaluation.

  • extra – Dict with additional information that can be provided by the FL system.

Returns:

ExchangeObject with evaluation metrics.

Return type:

metrics

get_weights(extra=None)[source]#

Get current local weights or weight differences.

Parameters:

extra – Dict with additional information that can be provided by the FL system.

Returns:

current local weights or weight differences.

Return type:

ExchangeObject

ExchangeObject example:

ExchangeObject(
    weights = self.trainer.network.state_dict(),
    optim = None,  # could be self.optimizer.state_dict()
    weight_type = WeightType.WEIGHTS
)
train(data, extra=None)[source]#

Train network and produce new network from train data.

Parameters:

  • data – ExchangeObject containing current network weights to base training on.

  • extra – Dict with additional information that can be provided by the FL system.

Returns:

None

class monai.fl.client.ClientAlgoStats[source]#
get_data_stats(extra=None)[source]#

Get summary statistics about the local data.

Parameters:

extra – Dict with additional information that can be provided by the FL system. For example, requested statistics.

Returns:

summary statistics.

Return type:

ExchangeObject

Extra dict example:

requested_stats = {
    FlStatistics.STATISTICS: metrics,
    FlStatistics.NUM_OF_BINS: num_of_bins,
    FlStatistics.BIN_RANGES: bin_ranges
}

Returned ExchangeObject example:

ExchangeObject(
    statistics = {...}
)

MONAI Bundle Reference Implementations#

class monai.fl.client.MonaiAlgo(bundle_root, local_epochs=1, send_weight_diff=True, config_train_filename='configs/train.json', train_kwargs=None, config_evaluate_filename='default', eval_kwargs=None, config_filters_filename=None, disable_ckpt_loading=True, best_model_filepath='models/model.pt', final_model_filepath='models/model_final.pt', save_dict_key='model', data_stats_transform_list=None, eval_workflow_name='train', train_workflow=None, eval_workflow=None)[source]#

Implementation of ClientAlgo to allow federated learning with MONAI bundle configurations.

Parameters:

  • bundle_root – directory path of the bundle.

  • local_epochs – number of local epochs to execute during each round of local training; defaults to 1.

  • send_weight_diff – whether to send weight differences rather than full weights; defaults to True.

  • config_train_filename – bundle training config path relative to bundle_root. can be a list of files. defaults to “configs/train.json”. only useful when train_workflow is None.

  • train_kwargs – other args of the ConfigWorkflow of train, except for config_file, meta_file, logging_file, workflow_type. only useful when train_workflow is None.

  • config_evaluate_filename – bundle evaluation config path relative to bundle_root. can be a list of files. if “default”, [“configs/train.json”, “configs/evaluate.json”] will be used. this arg is only useful when eval_workflow is None.

  • eval_kwargs – other args of the ConfigWorkflow of evaluation, except for config_file, meta_file, logging_file, workflow_type. only useful when eval_workflow is None.

  • config_filters_filename – filter configuration file. Can be a list of files; defaults to None.

  • disable_ckpt_loading – do not use any CheckpointLoader if defined in train/evaluate configs; defaults to True.

  • best_model_filepath – location of best model checkpoint; defaults “models/model.pt” relative to bundle_root.

  • final_model_filepath – location of final model checkpoint; defaults “models/model_final.pt” relative to bundle_root.

  • save_dict_key – If a model checkpoint contains several state dicts, the one defined by save_dict_key will be returned by get_weights; defaults to “model”. If all state dicts should be returned, set save_dict_key to None.

  • data_stats_transform_list – transforms to apply for the data stats result.

  • eval_workflow_name – the workflow name corresponding to the “config_evaluate_filename”, default to “train” as the default “config_evaluate_filename” overrides the train workflow config. this arg is only useful when eval_workflow is None.

  • train_workflow – the bundle workflow to execute training, if None, will create a ConfigWorkflow internally based on config_train_filename and train_kwargs.

  • eval_workflow – the bundle workflow to execute evaluation, if None, will create a ConfigWorkflow internally based on config_evaluate_filename, eval_kwargs, eval_workflow_name.

abort(extra=None)[source]#

Abort the training or evaluation. :param extra: Dict with additional information that can be provided by the FL system.

evaluate(data, extra=None)[source]#

Evaluate on client’s local data.

Parameters:

  • data – ExchangeObject containing the current global model weights.

  • extra – Dict with additional information that can be provided by the FL system.

Returns:

ExchangeObject containing evaluation metrics.

Return type:

return_metrics

finalize(extra=None)[source]#

Finalize the training or evaluation. :param extra: Dict with additional information that can be provided by the FL system.

get_weights(extra=None)[source]#

Returns the current weights of the model.

Parameters:

extra – Dict with additional information that can be provided by the FL system.

Returns:

ExchangeObject containing current weights (default)

or load requested model type from disk (ModelType.BEST_MODEL or ModelType.FINAL_MODEL).

Return type:

return_weights

initialize(extra=None)[source]#

Initialize routine to parse configuration files and extract main components such as trainer, evaluator, and filters.

Parameters:

extra – Dict with additional information that should be provided by FL system, i.e., ExtraItems.CLIENT_NAME and ExtraItems.APP_ROOT.

train(data, extra=None)[source]#

Train on client’s local data.

Parameters:

  • data – ExchangeObject containing the current global model weights.

  • extra – Dict with additional information that can be provided by the FL system.

class monai.fl.client.MonaiAlgoStats(bundle_root, config_train_filename='configs/train.json', config_filters_filename=None, data_stats_transform_list=None, histogram_only=False, workflow=None)[source]#

Implementation of ClientAlgoStats to allow federated learning with MONAI bundle configurations.

Parameters:

  • bundle_root – directory path of the bundle.

  • config_train_filename – bundle training config path relative to bundle_root. Can be a list of files; defaults to “configs/train.json”. only useful when workflow is None.

  • config_filters_filename – filter configuration file. Can be a list of files; defaults to None.

  • data_stats_transform_list – transforms to apply for the data stats result.

  • histogram_only – whether to only compute histograms. Defaults to False.

  • workflow – the bundle workflow to execute, usually it’s training, evaluation or inference. if None, will create an ConfigWorkflow internally based on config_train_filename.

get_data_stats(extra=None)[source]#

Returns summary statistics about the local data.

Parameters:

extra – Dict with additional information that can be provided by the FL system. Both FlStatistics.HIST_BINS and FlStatistics.HIST_RANGE must be provided.

Returns:

ExchangeObject with summary statistics.

Return type:

stats

initialize(extra=None)[source]#

Initialize routine to parse configuration files and extract main components such as trainer, evaluator, and filters.

Parameters:

extra – Dict with additional information that should be provided by FL system, i.e., ExtraItems.CLIENT_NAME and ExtraItems.APP_ROOT.