diff --git a/docs/example_applications_algorithms.rst b/docs/example_applications_algorithms.rst index ed48e4575b..8f50be597b 100644 --- a/docs/example_applications_algorithms.rst +++ b/docs/example_applications_algorithms.rst @@ -38,7 +38,6 @@ The following tutorials and quickstart guides walk you through some of these exa * `Intro to the FL Simulator `_ - Shows how to use the :ref:`fl_simulator` to run a local simulation of an NVFLARE deployment to test and debug an application without provisioning a real FL project. * `Hello FLARE API `_ - Goes through the different commands of the :ref:`flare_api` to show the syntax and usage of each. * `NVFLARE in POC Mode `_ - Shows how to use :ref:`POC mode ` to test the features of a full FLARE deployment on a single machine. - * `Provision and Start NVFLARE `_ - Shows how to provision and start a secure FL system. 3. **FL algorithms** @@ -165,44 +164,44 @@ Federated Learning Algorithms ============================= Federated Averaging -^^^^^^^^^^^^^^^^^^^ +------------------- In NVIDIA FLARE, FedAvg is implemented through the :ref:`scatter_and_gather_workflow`. In the federated averaging workflow, a set of initial weights is distributed to client workers who perform local training. After local training, clients return their local weights as a Shareables that are aggregated (averaged). This new set of global average weights is redistributed to clients and the process repeats for the specified number of rounds. FedProx -^^^^^^^ +------- `FedProx `_ implements a :class:`Loss function ` to penalize a client's local weights based on deviation from the global model. An example configuration can be found in cifar10_fedprox of the `CIFAR-10 example `_. FedOpt -^^^^^^ +------ `FedOpt `_ implements a :class:`ShareableGenerator ` that can use a specified Optimizer and Learning Rate Scheduler when updating the global model. An example configuration can be found in cifar10_fedopt of `CIFAR-10 example `_. SCAFFOLD -^^^^^^^^ +-------- `SCAFFOLD `_ uses a slightly modified version of the CIFAR-10 Learner implementation, namely the `CIFAR10ScaffoldLearner`, which adds a correction term during local training following the `implementation `_ as described in `Li et al. `_ Ditto -^^^^^ +----- `Ditto `_ uses a slightly modified version of the prostate Learner implementation, namely the `ProstateDittoLearner`, which decouples local personalized model from global model via an additional model training and a controllable prox term. See the `prostate segmentation example `_ for an example with ditto in addition to FedProx, FedAvg, and centralized training. Federated XGBoost -^^^^^^^^^^^^^^^^^ +----------------- * `Federated XGBoost (GitHub) `_ - Includes examples of histogram-based and tree-based algorithms. Tree-based algorithms also includes bagging and cyclic approaches Federated Analytics -^^^^^^^^^^^^^^^^^^^ +------------------- * `Federated Statistics for medical imaging (Github) `_ - Example of gathering local image histogram to compute the global dataset histograms. * `Federated Statistics for tabular data with DataFrame (Github) `_ - Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics. diff --git a/docs/examples/tutorial_notebooks.rst b/docs/examples/tutorial_notebooks.rst index 0b0cd78b33..b6fb68a997 100644 --- a/docs/examples/tutorial_notebooks.rst +++ b/docs/examples/tutorial_notebooks.rst @@ -7,4 +7,3 @@ Tutorial Notebooks FL Simulator Notebook (GitHub) Hello FLARE API Notbook (GitHub) NVFLARE in POC Mode (GitHub) - Provision and Start NVFLARE (GitHub) diff --git a/docs/programming_guide/high_availability.rst b/docs/programming_guide/high_availability.rst index 7404edec69..6175e37714 100644 --- a/docs/programming_guide/high_availability.rst +++ b/docs/programming_guide/high_availability.rst @@ -138,6 +138,11 @@ If I'm currently hot, and the hot SP has changed to not me, then I transition to I will prepare to stop serving the client requests. If any requests are received during the Hot-to-Cold state, I will tell them I am not in service. This is a transition state to the cold state. +.. note:: + + While trying restart unfinished jobs, users should be aware that some jobs may be in a state that contains incomplete results, i.e. some client + results may not have been received by the server during this transition. As such, users must handle such cases appropriately in the aggregation logic. + Admin Client ------------ Admin Client: No response from Overseer (connection error, etc.) diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 57954e7b2b..c4dd013a79 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -245,6 +245,9 @@ an optional boolean to determine whether or not to allow empty global weights an Some pipelines can have empty global weights at the first round, such that clients start training from scratch without any global info. +7. Updates to the Job Scheduler Configuration +============================================= +See :ref:`job_scheduler_configuration` for information on how the Job Scheduler can be configured with different arguments. ************************** Previous Releases of FLARE diff --git a/examples/README.md b/examples/README.md index 4f2dd6d6e6..3f936e3600 100644 --- a/examples/README.md +++ b/examples/README.md @@ -73,71 +73,58 @@ When you open a notebook, select the kernel `nvflare_example` using the dropdown ![Selecting a JupyterLab kernel](./jupyterlab_kernel.png) ## 1. Hello World Examples -### 1.1 Workflows -* [Hello Scatter and Gather](./hello-world/hello-numpy-sag/README.md) - * Example using "[ScatterAndGather](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.scatter_and_gather.html)" controller workflow. -* [Hello Cross-Site Validation](./hello-world/hello-numpy-cross-val/README.md) - * Example using [CrossSiteModelEval](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cross_site_model_eval.html) controller workflow. -* [Hello Cyclic Weight Transfer](./hello-world/hello-cyclic/README.md) - * Example using [CyclicController](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cyclic_ctl.html) controller workflow to implement [Cyclic Weight Transfer](https://pubmed.ncbi.nlm.nih.gov/29617797/). -### 1.2 Deep Learning -* [Hello PyTorch](./hello-world/hello-pt/README.md) - * Example using [NVIDIA FLARE](https://nvflare.readthedocs.io/en/main/index.html) an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [PyTorch](https://pytorch.org/) as the deep learning training framework. -* [Hello TensorFlow](./hello-world/hello-tf2/README.md) - * Example of using [NVIDIA FLARE](https://nvflare.readthedocs.io/en/main/index.html) an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [TensorFlow](https://tensorflow.org/) as the deep learning training framework. +| Models | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Hello Scatter and Gather](./hello-world/hello-numpy-sag/README.md) | Numpy | [Yes](./hello-world/hello_world.ipynb) | Workflow example | Example using [ScatterAndGather](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.scatter_and_gather.html) controller workflow. | +| [Hello Cross-Site Validation](./hello-world/hello-numpy-cross-val/README.md) | Numpy | [Yes](./hello-world/hello_world.ipynb) | Workflow example | Example using [CrossSiteModelEval](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cross_site_model_eval.html) controller workflow. | +| [Hello Cyclic Weight Transfer](./hello-world/hello-cyclic/README.md) | PyTorch | [Yes](./hello-world/hello_world.ipynb) | Workflow example | Example using [CyclicController](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cyclic_ctl.html) controller workflow to implement [Cyclic Weight Transfer](https://pubmed.ncbi.nlm.nih.gov/29617797/). | +| [Hello PyTorch](./hello-world/hello-pt/README.md) | PyTorch | [Yes](./hello-world/hello_world.ipynb) | Deep Learning | Example using an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [PyTorch](https://pytorch.org/) as the deep learning training framework. | +| [Hello TensorFlow](./hello-world/hello-tf2/README.md) | TensorFlow2 | [Yes](./hello-world/hello_world.ipynb) | Deep Learning | Example of using an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [TensorFlow](https://tensorflow.org/) as the deep learning training framework. | ## 2. Tutorial notebooks -* [Intro to the FL Simulator](./tutorials/flare_simulator.ipynb) - * Shows how to use the FLARE Simulator to run a local simulation. -* [Hello FLARE API](./tutorials/flare_api.ipynb) - * Goes through the different commands of the FLARE API. -* [NVFLARE in POC Mode](./tutorials/setup_poc.ipynb) - * Shows how to use POC mode. +| Notebook | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Intro to the FL Simulator](./tutorials/flare_simulator.ipynb) | - | [Yes](./tutorials/flare_simulator.ipynb) | - | Shows how to use the FLARE Simulator to run a local simulation. | +| [Hello FLARE API](./tutorials/flare_api.ipynb) | - | [Yes](./tutorials/flare_api.ipynb) | - | Goes through the different commnads of the FLARE API. | +| [NVFLARE in POC Mode](./tutorials/setup_poc.ipynb) | - | [Yes](./tutorials/setup_poc.ipynb) | - | Shows how to use POC mode. | ## 3. FL algorithms -* [Federated Learning with CIFAR-10](./advanced/cifar10/README.md) - * [Simulated Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-sim/README.md) - * This example includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629), - [FedProx](https://arxiv.org/abs/1812.06127), [FedOpt](https://arxiv.org/abs/2003.00295), - and [SCAFFOLD](https://arxiv.org/abs/1910.06378) algorithms using NVFlare's FL simulator. - * [Real-world Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-real-world/README.md) - * Includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629) with streaming - of TensorBoard metrics to the server during training - and [homomorphic encryption](https://developer.nvidia.com/blog/federated-learning-with-homomorphic-encryption/). -* [Federated XGBoost](./advanced/xgboost/README.md) - * Includes examples of [histogram-based](./advanced/xgboost/histogram-based/README.md) algorithm, [tree-based](./advanced/xgboost/tree-based/README.md). - Tree-based algorithms also includes [bagging](./advanced/xgboost/tree-based/jobs/bagging_base) and [cyclic](./advanced/xgboost/tree-based/jobs/cyclic_base) approaches. +| Example | Subsection | Notebooks | Summary | +|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Federated Learning with CIFAR-10](./advanced/cifar10/README.md) | [Simulated Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-sim/README.md) | - | This example includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), [FedOpt](https://arxiv.org/abs/2003.00295), and [SCAFFOLD](https://arxiv.org/abs/1910.06378) algorithms using NVFlare's FL simulator. | +| Federated Learning with CIFAR-10 | [Real-world Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-real-world/README.md) | - | Includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629) with streaming of TensorBoard metrics to the server during training and [homomorphic encryption](https://developer.nvidia.com/blog/federated-learning-with-homomorphic-encryption/). | +| [Federated XGBoost](./advanced/xgboost/README.md) | - | [Federated Learning for XGBoost - Data and Job Configs](./advanced/xgboost/data_job_setup.ipynb) | Includes examples of histogram-based and tree-based algorithms, with details below. | +| Federated XGBoost | [Histogram-based FL for XGBoost](./advanced/xgboost/histogram-based/README.md) | [Histogram-based FL for XGBoost on HIGGS Dataset](./advanced/xgboost/histogram-based/xgboost_histogram_higgs.ipynb) | Histogram-based algorithm | +| Federated XGBoost | [Tree-based Federated Learning for XGBoost ](./advanced/xgboost/tree-based/README.md) | [Tree-based FL for XGBoost on HIGGS Dataset](./advanced/xgboost/tree-based/README.md) | Tree-based algorithms includes [bagging](./advanced/xgboost/tree-based/jobs/bagging_base) and [cyclic](./advanced/xgboost/tree-based/jobs/cyclic_base) approaches. | ## 4. Traditional ML examples -* [Federated Linear Model with Scikit-learn](./advanced/sklearn-linear/README.md) - * Shows how to use the NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/), a widely used open-source machine learning library. -* [Federated K-Means Clustering with Scikit-learn](./advanced/sklearn-kmeans/README.md) - * NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and k-Means. -* [Federated SVM with Scikit-learn](./advanced/sklearn-svm/README.md) - * NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and [SVM](https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html). -* [Federated Learning for Random Forest based on XGBoost](./advanced/random_forest/README.md) - * Example of using NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and Random Forest. +| Example | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Federated Linear Model with Scikit-learn](./advanced/sklearn-linear/README.md) | scikit-learn | [FL Model with Scikit-learn on HIGGS Dataset](./advanced/sklearn-linear/sklearn_linear_higgs.ipynb) | - | Shows how to use the NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/), a widely used open-source machine learning library. | +| [Federated K-Means Clustering with Scikit-learn](./advanced/sklearn-kmeans/README.md) | scikit-learn | [Federated K-Means Clustering with Scikit-learn on Iris Dataset](./advanced/sklearn-kmeans/sklearn_kmeans_iris.ipynb) | - | NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and k-Means. | +| [Federated SVM with Scikit-learn](./advanced/sklearn-svm/README.md) | scikit-learn | [Federated SVM with Scikit-learn on Breast Cancer Dataset](./advanced/sklearn-svm/sklearn_svm_cancer.ipynb) | - | NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and [SVM](https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html). | +| [Federated Learning for Random Forest based on XGBoost](./advanced/random_forest/README.md) | XGBoost | [Federated Random Forest on HIGGS Dataset](./advanced/random_forest/random_forest.ipynb) | - | Example of using NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and Random Forest. | ## 5. Medical Image Analysis -* [NVFlare + MONAI integration](../integration/monai/README.md) - * 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](../integration/monai/examples/README.md). -* [Federated Learning with Differential Privacy for BraTS18 segmentation](./advanced/brats18/README.md) - * Illustrates the use of differential privacy for training brain tumor segmentation models using federated learning. -* [Federated Learning for Prostate Segmentation from Multi-source Data](./advanced/prostate/README.md) - * Example of training a multi-institutional prostate segmentation model using [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), and [Ditto](https://arxiv.org/abs/2012.04221). +| Example | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [NVFlare + MONAI integration](../integration/monai/README.md) | 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](../integration/monai/examples/README.md). | +| [Federated Learning with Differential Privacy for BraTS18 segmentation](./advanced/brats18/README.md) | 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](./advanced/prostate/README.md) | MONAI | - | see requirements.txt | Example of training a multi-institutional prostate segmentation model using [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), and [Ditto](https://arxiv.org/abs/2012.04221). | ## 6. Federated Statistics -* [Federated Statistic Overview](./advanced/federated-statistics/README.md) - * Discuss the overall federated statistics features -* [Federated Statistics for Medical Imaging](./advanced/federated-statistics/image_stats/README.md) - * Example of gathering local image histogram to compute the global dataset histograms. -* [Federated Statistics for DataFrame](./advanced/federated-statistics/df_stats/README.md) - * Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics. +| Example | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Federated Statistics Overview](./advanced/federated-statistics/README.md) | - | - | - | Discuss the overall federated statistics features. | +| [Federated Statistics for Medical Imaging](./advanced/federated-statistics/image_stats/README.md) | - | [Image Histograms](./advanced/federated-statistics/image_stats.ipynb) | see requirements.txt | Example of gathering local image histogram to compute the global dataset histograms. | +| [Federated Statistics for DataFrame](./advanced/federated-statistics/df_stats/README.md) | - | [Data Frame Federated Statistics](./advanced/federated-statistics/df_stats.ipynb), [Visualization](./advanced/federated-statistics/df_stats/demo/visualization.ipynb) | see requirements.txt | Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics. | ## 7. Federated Policies -* [Federated Policies](./advanced/federated-policies/README.rst) - * Discuss the federated site policies for authorization, resource and data privacy management +| Example | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Federated Policies](./advanced/federated-policies/README.rst) | - | - | - | Discuss the federated site policies for authorization, resource and data privacy management. | ## 8. Experiment tracking -* [Hello PyTorch with TensorBoard Streaming](./advanced/experiment-tracking/tensorboard-streaming/README.md) - * Example building upon [Hello PyTorch](./hello-world/hello-pt/README.md) showcasing the [TensorBoard](https://tensorflow.org/tensorboard) streaming capability from the clients to the server. +| Example | Framework | Notebooks | Notes | Summary | +|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Hello PyTorch with TensorBoard Streaming](./advanced/experiment-tracking/tensorboard-streaming/README.md) | PyTorch | - | Also requires tensorboard | Example building upon [Hello PyTorch](./hello-world/hello-pt/README.md) showcasing the [TensorBoard](https://tensorflow.org/tensorboard) streaming capability from the clients to the server. | diff --git a/examples/advanced/sklearn-svm/sklearn_svm_cancer.ipynb b/examples/advanced/sklearn-svm/sklearn_svm_cancer.ipynb index 1b1cfc7003..47e0d7245a 100644 --- a/examples/advanced/sklearn-svm/sklearn_svm_cancer.ipynb +++ b/examples/advanced/sklearn-svm/sklearn_svm_cancer.ipynb @@ -7,7 +7,7 @@ "tags": [] }, "source": [ - "# Federated K-Means Clustering with Scikit-learn on Iris Dataset" + "# Federated SVM with Scikit-learn on Breast Cancer Dataset" ] }, { diff --git a/examples/nvflare_getting_started.ipynb b/examples/nvflare_getting_started.ipynb new file mode 100644 index 0000000000..98362a348f --- /dev/null +++ b/examples/nvflare_getting_started.ipynb @@ -0,0 +1,108 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "4fafdd07-51e1-469c-84d8-c57a61daa28c", + "metadata": {}, + "source": [ + "# Getting Started with NVFLARE in JupyterLab" + ] + }, + { + "cell_type": "markdown", + "id": "9aa3fb14", + "metadata": {}, + "source": [ + "## Table of Examples and Tutorials\n", + "We provide a wide array of examples and tutorials to get users hands-on NVFLARE quickly.\n", + "\n", + "### 1. Hello World Examples\n", + "| Models | Framework | Notes | Summary |\n", + "|--------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Hello Scatter and Gather](./hello-world/hello_world.ipynb) | Numpy | Workflow example | Example using [ScatterAndGather](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.scatter_and_gather.html) controller workflow. |\n", + "| [Hello Cross-Site Validation](./hello-world/hello_world.ipynb) | Numpy | Workflow example | Example using [CrossSiteModelEval](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cross_site_model_eval.html) controller workflow. |\n", + "| [Hello Cyclic Weight Transfer](./hello-world/hello_world.ipynb) | PyTorch | Workflow example | Example using [CyclicController](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.app_common.workflows.cyclic_ctl.html) controller workflow to implement [Cyclic Weight Transfer](https://pubmed.ncbi.nlm.nih.gov/29617797/). |\n", + "| [Hello PyTorch](./hello-world/hello_world.ipynb) | PyTorch | Deep Learning | Example using an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [PyTorch](https://pytorch.org/) as the deep learning training framework. |\n", + "| [Hello TensorFlow](./hello-world/hello_world.ipynb) | TensorFlow2 | Deep Learning | Example of using an image classifier using [FedAvg](https://arxiv.org/abs/1602.05629) and [TensorFlow](https://tensorflow.org/) as the deep learning training framework. |\n", + "\n", + "### 2. Tutorial notebooks\n", + "| Notebook | Framework | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Intro to the FL Simulator](./tutorials/flare_simulator.ipynb) | - | - | Shows how to use the FLARE Simulator to run a local simulation. |\n", + "| [Hello FLARE API](./tutorials/flare_api.ipynb) | - | - | Goes through the different commnads of the FLARE API. |\n", + "| [NVFLARE in POC Mode](./tutorials/setup_poc.ipynb) | - | - | Shows how to use POC mode. |\n", + "\n", + "### 3. FL algorithms\n", + "| Example | Subsection | Notebooks | Summary |\n", + "|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| Federated Learning with CIFAR-10 | [Simulated Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-sim/README.md) | - | [This example](./advanced/cifar10/README.md) includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), [FedOpt](https://arxiv.org/abs/2003.00295), and [SCAFFOLD](https://arxiv.org/abs/1910.06378) algorithms using NVFlare's FL simulator. |\n", + "| Federated Learning with CIFAR-10 | [Real-world Federated Learning with CIFAR-10](./advanced/cifar10/cifar10-real-world/README.md) | - | Includes instructions on running [FedAvg](https://arxiv.org/abs/1602.05629) with streaming of TensorBoard metrics to the server during training and [homomorphic encryption](https://developer.nvidia.com/blog/federated-learning-with-homomorphic-encryption/). |\n", + "| Federated XGBoost | - | [Federated Learning for XGBoost - Data and Job Configs](./advanced/xgboost/data_job_setup.ipynb) | Includes examples of histogram-based and tree-based algorithms for [Federated XGBoost](./advanced/xgboost/README.md), with details below. |\n", + "| Federated XGBoost | [Histogram-based FL for XGBoost](./advanced/xgboost/histogram-based/README.md) | [Histogram-based FL for XGBoost on HIGGS Dataset](./advanced/xgboost/histogram-based/xgboost_histogram_higgs.ipynb) | Histogram-based algorithm |\n", + "| Federated XGBoost | [Tree-based Federated Learning for XGBoost ](./advanced/xgboost/tree-based/README.md) | [Tree-based FL for XGBoost on HIGGS Dataset](./advanced/xgboost/tree-based/README.md) | Tree-based algorithms includes [bagging](./advanced/xgboost/tree-based/jobs/bagging_base) and [cyclic](./advanced/xgboost/tree-based/jobs/cyclic_base) approaches. |\n", + "\n", + "### 4. Traditional ML examples\n", + "| Example | Framework | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|-------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Federated Linear Model with Scikit-learn](./advanced/sklearn-linear/sklearn_linear_higgs.ipynb) | scikit-learn | - | Shows how to use the NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/), a widely used open-source machine learning library. |\n", + "| [Federated K-Means Clustering with Scikit-learn](./advanced/sklearn-kmeans/sklearn_kmeans_iris.ipynb) | scikit-learn | - | NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and k-Means. |\n", + "| [Federated SVM with Scikit-learn](./advanced/sklearn-svm/sklearn_svm_cancer.ipynb) | scikit-learn | - | NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and [SVM](https://scikit-learn.org/stable/modules/generated/sklearn.svm.SVC.html). |\n", + "| [Federated Learning for Random Forest based on XGBoost](./advanced/random_forest/random_forest.ipynb | XGBoost | - | Example of using NVIDIA FLARE with [scikit-learn](https://scikit-learn.org/) and Random Forest. |\n", + "\n", + "### 5. Medical Image Analysis\n", + "| Example | Framework | Notebooks | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [NVFlare + MONAI integration](../integration/monai/README.md) | 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](../integration/monai/examples/README.md). |\n", + "| [Federated Learning with Differential Privacy for BraTS18 segmentation](./advanced/brats18/README.md) | MONAI | - | see requirements.txt | Illustrates the use of differential privacy for training brain tumor segmentation models using federated learning. |\n", + "| [Federated Learning for Prostate Segmentation from Multi-source Data](./advanced/prostate/README.md) | MONAI | - | see requirements.txt | Example of training a multi-institutional prostate segmentation model using [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), and [Ditto](https://arxiv.org/abs/2012.04221). |\n", + "\n", + "### 6. Federated Statistics\n", + "| Example | Framework | Notebooks | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Federated Statistics Overview](./advanced/federated-statistics/README.md) | - | - | - | Discuss the overall federated statistics features. |\n", + "| [Federated Statistics for Medical Imaging](./advanced/federated-statistics/image_stats/README.md) | - | [Image Histograms](./advanced/federated-statistics/image_stats.ipynb) | see requirements.txt | Example of gathering local image histogram to compute the global dataset histograms. |\n", + "| [Federated Statistics for DataFrame](./advanced/federated-statistics/df_stats/README.md) | - | [Data Frame Federated Statistics](./advanced/federated-statistics/df_stats.ipynb), [Visualization](./advanced/federated-statistics/df_stats/demo/visualization.ipynb) | see requirements.txt | Example of gathering local statistics summary from Pandas DataFrame to compute the global dataset statistics. |\n", + "\n", + "### 7. Federated Policies\n", + "| Example | Framework | Notebooks | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Federated Policies](./advanced/federated-policies/README.rst) | - | - | - | Discuss the federated site policies for authorization, resource and data privacy management. |\n", + "\n", + "### 8. Experiment tracking\n", + "| Example | Framework | Notebooks | Notes | Summary |\n", + "|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", + "| [Hello PyTorch with TensorBoard Streaming](./advanced/experiment-tracking/tensorboard-streaming/README.md) | PyTorch | - | Also requires tensorboard | Example building upon [Hello PyTorch](./hello-world/hello-pt/README.md) showcasing the [TensorBoard](https://tensorflow.org/tensorboard) streaming capability from the clients to the server. |\n" + ] + }, + { + "cell_type": "markdown", + "id": "4dadb9a7", + "metadata": {}, + "source": [ + "## How to Navigate\n", + "We recommend users to get started with [nvflare_setup.ipynb](nvflare_setup.ipynb) to set up a virtual environment and get NVFLARE installed before going through the Hello World examples to get familiar with NVFLARE. The tutorial notebooks introduce concepts in NVFLARE. Finally, the advanced examples cover more advanced workflows with integration of NVFLARE with other frameworks." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "nvflare_example", + "language": "python", + "name": "nvflare_example" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.10" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}