README.md

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 example 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.

NOTE: To run examples, please follow the instructions for Installation and any additional steps specified in the example readmes.

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.

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 {} \;

activate your virtual environment.

source ./set_env.sh

within each example folder, install required packages for training

pip install --upgrade pip
pip install -r requirements.txt

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

pip install -r plot-requirements.txt

Notebooks

To run examples including notebooks, we recommend using JupyterLab.

After activating your virtual environment, install JupyterLab

pip install jupyterlab

Register the virtual environment kernel

python -m ipykernel install --user --name="nvflare_example"

Start a Jupyter Lab

jupyter lab .

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

1. Hello World Examples

1.1 Workflows

• Hello Scatter and Gather
  • Example using "ScatterAndGather" controller workflow.
• Hello Cross-Site Validation
  • Example using CrossSiteModelEval controller workflow.
• Hello Cyclic Weight Transfer
  • Example using CyclicController controller workflow to implement Cyclic Weight Transfer.

1.2 Deep Learning

• Hello PyTorch
  • Example using NVIDIA FLARE an image classifier using FedAvg and PyTorch as the deep learning training framework.
• Hello TensorFlow
  • Example of using NVIDIA FLARE an image classifier using FedAvg and TensorFlow as the deep learning training framework.

2. Tutorial notebooks

• Intro to the FL Simulator
  • Shows how to use the FLARE Simulator to run a local simulation.
• Hello FLARE API
  • Goes through the different commnads of the FLARE API.
• NVFLARE in POC Mode
  • Shows how to use POC mode.
• Provision and Start NVFLARE
  • Shows how to provision and start a secure FL system.

3. FL algorithms

• 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.
  • 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
  • Includes examples of histogram-based algorithm, tree-based. Tree-based algorithms also includes bagging and cyclic approaches

4. Traditional ML examples

• Federated Linear Model with Scikit-learn
  • 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
  • NVIDIA FLARE with scikit-learn and k-Means.
• Federated SVM with Scikit-learn
  • NVIDIA FLARE with scikit-learn and SVM.
• Federated Learning for Random Forest based on XGBoost
  • Example of using NVIDIA FLARE with scikit-learn and Random Forest.

5. Medical Image Analysis

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

6. Federated Statistics

• Federated Statistic Overview
  • Discuss the overall federated statistics features
• Federated Statistics for Medical Imaging
  • Example of gathering local image histogram to compute the global dataset histograms.
• Federated Statistics for DataFrame
  • Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics.

7. Federated Policies

• Federated Policies
  • Discuss the federated site policies for authorization, resource and data privacy management

8. Experiment tracking

• Hello PyTorch with TensorBoard Streaming
  • Example building upon Hello PyTorch showcasing the TensorBoard streaming capability from the clients to the server.