add README files (#71)

fix spelling

SAG readme

add example readmes

add link to MONAI nvflare tutorial

update root readme

Author: holgerroth

examples/README.md

@@ -0,0 +1,33 @@
+# NVIDIA FLARE Examples
+
+[NVIDIA FLARE](https://nvidia.github.io/NVFlare) provides several examples to help you get started using federated learning for your own applications.
+
+The provided examples cover different aspects of [NVIDIA FLARE](https://nvidia.github.io/NVFlare), such as using the provided [Controllers](https://nvidia.github.io/NVFlare/programming_guide/controllers.html) for "scatter and gather" or "cyclic weight transfer" workflows and example [Executors](https://nvidia.github.io/NVFlare/apidocs/nvflare.apis.html?#module-nvflare.apis.executor) to implement your own training and validation pipelines. Some examples use the provided "task data" and "task result" [Filters](https://nvidia.github.io/NVFlare/apidocs/nvflare.apis.html?#module-nvflare.apis.filter) for homomorphic encryption and decryption or differential privacy. Furthermore, we show how to use different components for FL algorithms such as [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), and [FedOpt](https://arxiv.org/abs/2003.00295). We also provide domain-specific examples for deep learning and medical image analysis.
+
+> **_NOTE:_** To run examples, please follow the instructions for [Installation](https://nvidia.github.io/NVFlare/installation.html) and any additional steps specified in the example readmes.
+
+## 1. Hello World Examples
+### 1.1 Workflows
+* [Hello Scatter and Gather](./hello-numpy-sag/README.md)
+    * Example using "[ScatterAndGather](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html?#module-nvflare.app_common.workflows.scatter_and_gather)" controller workflow.
+* [Hello Cross-Site Validation](./hello-numpy-cross-val/README.md)
+    * Example using [CrossSiteModelEval](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html#nvflare.app_common.workflows.cross_site_model_eval.CrossSiteModelEval) controller workflow.
+* [Hello Cyclic Weight Transfer](./hello-cyclic/README.md)
+    * Example using [CyclicController](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html?#module-nvflare.app_common.workflows.cyclic_ctl) controller workflow to implement [Cyclic Weight Transfer](https://pubmed.ncbi.nlm.nih.gov/29617797/).
+### 1.2 Deep Learning
+* [Hello PyTorch](./hello-pt/README.md)
+  * Example using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) an image classifier using [FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629)) and [PyTorch](https://pytorch.org/) as the deep learning training framework.
+* [Hello TensorFlow](./hello-tf2/README.md)
+  * Example of using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) an image classifier using [FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629)) and [TensorFlow](https://tensorflow.org/) as the deep learning training framework.
+
+## 2. FL algorithms
+* [Federated Learning with CIFAR-10](./cifar10/README.md)
+  * Includes examples of using [FedAvg](https://arxiv.org/abs/1602.05629), [FedProx](https://arxiv.org/abs/1812.06127), [FedOpt](https://arxiv.org/abs/2003.00295), and [homomorphic encryption](https://developer.nvidia.com/blog/federated-learning-with-homomorphic-encryption/).
+
+## 3. Medical Image Analysis
+* [Hello MONAI](./hello-monai/README.md)
+   * Example using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) to train a medical image analysis model using [FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629)) and [MONAI](https://monai.io/)
+* [Federated Learning with Differential Privacy for BraTS18 segmentation](./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](./prostate/README.md)
+   * Example of training a multi-institutional prostate segmentation model using [FedAvg](https://arxiv.org/abs/1602.05629) and [FedProx](https://arxiv.org/abs/1812.06127).

examples/hello-cyclic/README.md

@@ -0,0 +1,41 @@
+# Hello Cyclic Weight Transfer
+
+["Cyclic Weight Transfer"](https://pubmed.ncbi.nlm.nih.gov/29617797/
+) (CWT) is an alternative to the scatter-and-gather approach used in [FedAvg](https://arxiv.org/abs/1602.05629). CWT uses the [CyclicController](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html?#module-nvflare.app_common.workflows.cyclic_ctl) to pass the model weights from one site to the next for repeated fine-tuning.
+
+> **_NOTE:_** This example uses the [MNIST](http://yann.lecun.com/exdb/mnist/) handwritten digits dataset and will load its data within the trainer code.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+Install additional requirements:
+
+```
+pip3 install tensorflow
+```
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-cyclic
+deploy_app hello-cyclic all
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).

examples/hello-monai/README.md

@@ -0,0 +1,40 @@
+# Hello MONAI
+
+Example of using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) to train a medical image analysis model using federated averaging ([FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629))) and [MONAI](https://monai.io/), the "Medical Open Network for Artificial Intelligence", as the deep learning training framework.
+
+See this [Tutorial](https://github.com/Project-MONAI/tutorials/tree/master/federated_learning/nvflare/nvflare_spleen_example) for an example of how to use this trainer for 3D spleen segmentation in computed tomography.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+Install additional requirements:
+
+```
+pip3 install monai
+```
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-monai
+deploy_app hello-monai
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).

examples/hello-numpy-cross-val/README.md

@@ -0,0 +1,35 @@
+# Hello Numpy Cross-Site Validation
+
+The cross-site model evaluation workflow uses the data from clients to run evaluation with the models of other clients. Data is not shared. Rather the collection of models is distributed to each client site to run local validation. The server collects the results of local validation to construct an all-to-all matrix of model performance vs. client dataset. It uses the [CrossSiteModelEval](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html#nvflare.app_common.workflows.cross_site_model_eval.CrossSiteModelEval) controller workflow.
+
+> **_NOTE:_** This example uses a Numpy-based trainer and will generate its data within the code.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-numpy-cross-val
+deploy_app hello-numpy-cross-val
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).

examples/hello-numpy-sag/README.md

@@ -0,0 +1,36 @@
+# Hello Numpy Scatter and Gather
+
+"[Scatter and Gather](https://nvidia.github.io/NVFlare/apidocs/nvflare.app_common.workflows.html?#module-nvflare.app_common.workflows.scatter_and_gather)" is the standard workflow to implement Federated Averaging ([FedAvg](https://arxiv.org/abs/1602.05629)). 
+This workflow follows the hub and spoke model for communicating the global model to each client for local training (i.e., "scattering") and aggregates the result to perform the global model update (i.e., "gathering").  
+
+> **_NOTE:_** This example uses a Numpy-based trainer and will generate its data within the code.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-numpy-sag
+deploy_app hello-numpy-sag all
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).

examples/hello-pt/README.md

@@ -0,0 +1,40 @@
+# Hello PyTorch
+
+Example of using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) to train an image classifier using federated averaging ([FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629))) and [PyTorch](https://pytorch.org/) as the deep learning training framework.
+
+> **_NOTE:_** This example uses the [CIFAR-10](https://www.cs.toronto.edu/~kriz/cifar.html) dataset and will load its data within the trainer code.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+Install additional requirements:
+
+```
+pip3 install torch
+```
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-pt
+deploy_app hello-pt
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).

examples/hello-tf2/README.md

@@ -0,0 +1,40 @@
+# Hello TensorFlow
+
+Example of using [NVIDIA FLARE](https://nvidia.github.io/NVFlare) to train an image classifier using federated averaging ([FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629))) and [TensorFlow](https://tensorflow.org/) as the deep learning training framework.
+
+> **_NOTE:_** This example uses the [CIFAR-10](https://www.cs.toronto.edu/~kriz/cifar.html) dataset and will load its data within the trainer code.
+
+### 1. Install NVIDIA FLARE
+
+Follow the [Installation](https://nvidia.github.io/NVFlare/installation.html) instructions.
+Install additional requirements:
+
+```
+pip3 install torch
+```
+
+### 2. Set up your FL workspace
+
+Follow the [Quickstart](https://nvidia.github.io/NVFlare/quickstart.html) instructions to set up your POC ("proof of concept") workspace.
+
+### 3. Run the experiment
+
+Log into the Admin client by entering `admin` for both the username and password.
+Then, use these Admin commands to run the experiment:
+
+```
+set_run_number 1
+upload_app hello-tf2
+deploy_app hello-tf2
+start_app all
+```
+
+### 4. Shut down the server/clients
+
+To shut down the clients and server, run the following Admin commands:
+```
+shutdown client
+shutdown server
+```
+
+> **_NOTE:_** For more information about the Admin client, see [here](https://nvidia.github.io/NVFlare/user_guide/admin_commands.html).