examples

NVIDIA FLARE Examples

NVIDIA FLARE provides several examples to help you get started using federated learning for your own applications.

The provided examples cover different aspects of NVIDIA FLARE, such as using the provided Controllers for "scatter and gather" or "cyclic weight transfer" workflows and different Executors to implement your own training and validation pipelines. Some examples use the provided "task data" and "task result" Filters for homomorphic encryption and decryption or differential privacy. Furthermore, we show how to use different components for FL algorithms such as FedAvg, FedProx, and FedOpt. We also provide domain-specific examples for deep learning and medical image analysis.

Getting started

To get started with NVIDIA FLARE, please follow the Getting Started Guide in the documentation. This walks you through installation, creating a POC workspace, and deploying your first NVIDIA FLARE Application. The following examples will detail any additional requirements in their requirements.txt.

Set up a virtual environment

We recommend setting up a virtual environment before installing the dependencies of the examples. You need to set up the virtual environment and install nvflare and set additional PYTHONPATH before launch the jupyter lab.

Install dependencies for a virtual environment with:

python3 -m pip install --user --upgrade pip
python3 -m pip install --user virtualenv

(If needed) make all shell scripts executable using:

find . -name ".sh" -exec chmod +x {} \;

Create and activate your virtual environment with the set_env.sh script:

source ./set_env.sh

Install nvflare

(nvflare_example)$ pip install nvflare

In each example folder, install required packages for training:

(nvflare_example)$ pip install --upgrade pip
(nvflare_example)$ pip install -r requirements.txt

(optional) some examples contains script for plotting the TensorBoard event files, if needed, please also install:

(nvflare_example)$ pip install -r plot-requirements.txt

Set up JupyterLab for notebooks

To run examples including notebooks, we recommend using JupyterLab. You need to set up the virtual environment and install nvflare and set additional PYTHONPATH before launch the jupyter lab.

After activating your virtual environment, install JupyterLab:

(nvflare_example)$ pip install jupyterlab

You can register the virtual environment you created, so it is usable in JupyterLab:

(nvflare_example)$ python3 -m ipykernel install --user --name="nvflare_example"

Start a Jupyter Lab:

(nvflare_example)$ jupyter lab .

When you open a notebook, select the kernel nvflare_example using the dropdown menu at the top right.

1. Hello World Examples

Models	Framework	Notebooks	Notes	Summary
Hello Scatter and Gather	Numpy	Yes	Workflow example	Example using ScatterAndGather controller workflow.
Hello Cross-Site Validation	Numpy	Yes	Workflow example	Example using CrossSiteModelEval controller workflow.
Hello Cyclic Weight Transfer	PyTorch	Yes	Workflow example	Example using CyclicController controller workflow to implement Cyclic Weight Transfer.
Hello PyTorch	PyTorch	Yes	Deep Learning	Example using an image classifier using FedAvg and PyTorch as the deep learning training framework.
Hello TensorFlow	TensorFlow2	Yes	Deep Learning	Example of using an image classifier using FedAvg and TensorFlow as the deep learning training framework.

2. Tutorial notebooks

Notebook	Framework	Notebooks	Notes	Summary
Intro to the FL Simulator	-	Yes	-	Shows how to use the FLARE Simulator to run a local simulation.
Hello FLARE API	-	Yes	-	Goes through the different commnads of the FLARE API.
NVFLARE in POC Mode	-	Yes	-	Shows how to use POC mode.

3. FL algorithms

Example	Subsection	Notebooks	Summary
Federated Learning with CIFAR-10	Simulated Federated Learning with CIFAR-10	-	This example includes instructions on running FedAvg, FedProx, FedOpt, and SCAFFOLD algorithms using NVFlare's FL simulator.
Federated Learning with CIFAR-10	Real-world Federated Learning with CIFAR-10	-	Includes instructions on running FedAvg with streaming of TensorBoard metrics to the server during training and homomorphic encryption.
Federated XGBoost	-	Federated Learning for XGBoost - Data and Job Configs	Includes examples of histogram-based and tree-based algorithms, with details below.
Federated XGBoost	Histogram-based FL for XGBoost	Histogram-based FL for XGBoost on HIGGS Dataset	Histogram-based algorithm
Federated XGBoost	Tree-based Federated Learning for XGBoost	Tree-based FL for XGBoost on HIGGS Dataset	Tree-based algorithms includes bagging and cyclic approaches.

4. Traditional ML examples

Example	Framework	Notebooks	Notes	Summary
Federated Linear Model with Scikit-learn	scikit-learn	FL Model with Scikit-learn on HIGGS Dataset	-	Shows how to use the NVIDIA FLARE with scikit-learn, a widely used open-source machine learning library.
Federated K-Means Clustering with Scikit-learn	scikit-learn	Federated K-Means Clustering with Scikit-learn on Iris Dataset	-	NVIDIA FLARE with scikit-learn and k-Means.
Federated SVM with Scikit-learn	scikit-learn	Federated SVM with Scikit-learn on Breast Cancer Dataset	-	NVIDIA FLARE with scikit-learn and SVM.
Federated Learning for Random Forest based on XGBoost	XGBoost	Federated Random Forest on HIGGS Dataset	-	Example of using NVIDIA FLARE with scikit-learn and Random Forest.

5. Medical Image Analysis

Example	Framework	Notebooks	Notes	Summary
NVFlare + MONAI integration	MONAI	-	-	For an example of using NVIDIA FLARE to train a 3D medical image analysis model using federated averaging (FedAvg) and MONAI Bundle, see here.
Federated Learning with Differential Privacy for BraTS18 segmentation	MONAI	-	see requirements.txt	Illustrates the use of differential privacy for training brain tumor segmentation models using federated learning.
Federated Learning for Prostate Segmentation from Multi-source Data	MONAI	-	see requirements.txt	Example of training a multi-institutional prostate segmentation model using FedAvg, FedProx, and Ditto.

6. Federated Statistics

Example	Framework	Notebooks	Notes	Summary
Federated Statistics Overview	-	-	-	Discuss the overall federated statistics features.
Federated Statistics for Medical Imaging	-	Image Histograms	see requirements.txt	Example of gathering local image histogram to compute the global dataset histograms.
Federated Statistics for DataFrame	-	Data Frame Federated Statistics, Visualization	see requirements.txt	Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics.

7. Federated Policies

Example	Framework	Notebooks	Notes	Summary
Federated Policies	-	-	-	Discuss the federated site policies for authorization, resource and data privacy management.

8. Experiment tracking

Example	Framework	Notebooks	Notes	Summary
Hello PyTorch with TensorBoard Streaming	PyTorch	-	Also requires tensorboard	Example building upon Hello PyTorch showcasing the TensorBoard streaming capability from the clients to the server.

9. NLP

Example	Framework	Notebooks	Notes	Summary
NLP-NER	see details	-	-	Illustrates both BERT and GPT-2 models from Hugging Face (BERT-base-uncased, GPT-2) on a Named Entity Recognition (NER) task using the NCBI disease dataset.