Fed-BioMed

Introduction

Fed-BioMed is an open source project focused on empowering healthcare using non-centralized approaches for statistical analysis and machine learning.

The project is currently based on Python, PyTorch and Scikit-learn, and enables developing and deploying collaborative learning analysis in real-world machine learning applications, including federated learning and federated analytics.

The code is regularly released and available on the master branch of this repository. The documentation of the releases can be found at https://fedbiomed.org

Curious users may also be interested by the current developments, occurring in the develop branch (https://github.com/fedbiomed/fedbiomed/tree/develop) Develop branch is WIP branch for next release. It may not be fully usable, tested and documented. Support is provided only for releases.

Install and run in development environment

Fed-BioMed is developed under Linux Ubuntu & Fedora (should be easily ported to other Linux distributions) and MacOS X. It is also ported on Windows WSL2.

This README.md file provide a quick start/installation guide for Linux.

Full installation instruction are also available at: https://fedbiomed.org/latest/tutorials/installation/0-basic-software-installation/

An installation guide is also provided for Windows11, which relies on WSL2: https://fedbiomed.org/latest/user-guide/installation/windows-installation/

Prerequisites

• Python: Compatible version (currently 3.10)
• It is recommended to install Python in a local environment, for example, using pyenv.

pyenv install 3.10
pyenv local 3.10

A recommended practice is to use a virtual environment for managing dependencies. For example, if using venv:

python -m venv fb_env
source fb_env/bin/activate

Install

Fed-BioMed can be installed using pip with the following command:

pip install fedbiomed[node, gui, researcher]

If you prefer to use Fed-BioMed in development mode, please refer to the Developer Environment Installation Documentation.

Quick Start: Running Fed-BioMed

Starting a Basic Node

To start a basic Fed-BioMed node, open a new terminal and execute the following command:

$ fedbiomed node start

Uploading New Data to the Node

To upload new data to this node, run:

$ fedbiomed node dataset add

Specifying a Component Directory

If you need to run multiple test nodes on the same host, you can specify a different component directory:

$ fedbiomed node --path ./my-second-node start

Changing the Default IP Address

To specify a different IP address for connecting to the Fed-BioMed researcher component (default: localhost), provide it at launch time:

$ FBM_RESEARCHER_IP=192.168.0.100 fedbiomed node start
$ FBM_SERVER_HOST=192.168.0.100 fedbiomed researcher start

Configuration Persistence

• If this option is provided at the first launch or after a clean configuration, it is saved in the configuration file and becomes the default for future launches.
• If given during a subsequent launch, it only applies to that launch without altering the saved configuration.

Run a Researcher Notebook

1. Open a new terminal and start the researcher component:

   $ fedbiomed researcher start
   

2. This will launch a new Jupyter Notebook environment within the notebooks repository. A good starting point is:

   • 101_getting-started.ipynb: Train a SimpleNet model with federated averaging on the MNIST dataset.

Run a Researcher Script

1. Open a new terminal and activate the environment where Fed-BioMed is installed.

2. Convert the notebook to a Python script:

   jupyter nbconvert --output=101_getting-started --to script ./notebooks/101_getting-started.ipynb
   

3. Execute the researcher script using:

   $ python ./notebooks/101_getting-started.py
   ```### Clean State (restore environments back to new)
   

Cleaning/Removing Fed-BioMed Components

To clean your Fed-BioMed instance:

• Stop the researcher : shutdown the notebook kernel (Quit in on the notebook interface or ctrl-C on the console)
• Stop the nodes : interrupt (ctrl-C) on the nodes console
• Remove all configuration files, dataset sharing configuration, temporary files, caches for all Fed-BioMed components with :

$ rm -rf COMPONENT_DIR

Where COMPONENT_DIR is:

• for a node, the parameter provided as fedbiomed node -p COMPONENT_DIR or by default fbm-node if no parameter was given
• for a researcher, the parameter provided as fedbiomed researcher -p COMPONENT_DIR or by default fbm-researcher if no parameter was given

Fed-BioMed Node GUI

Node GUI provides an interface for Node to manage datasets and deploy new ones. GUI consists of two components, Server and UI. Server is developed on Flask framework and UI is developed using ReactJS. Flask provides API services that use Fed-BioMed's DataManager for deploying and managing dataset. All the source files for GUI has been located on the ${FEDBIOMED_DIR}/gui directory.

Starting GUI

Node GUI can be started using Fed-BioMed CLI.

fedbiomed node [--path [COMPONENT_DIRECTORY]] gui start --data-folder <path-for-data-folder>

Please see possible argument using fedbiomed node gui start --help.

It is also possible to start the GUI on a specific host and port. By default, it starts on localhost as the host and 8484 as the port. To change these settings, you can modify the following command. The GUI is based on HTTPS and will, by default, generate a self-signed certificate. However, you can also start the GUI by specifying the certificate and private key names you want to use for HTTPS support.

fedbiomed node --path <path/to/component/directory> gui start --data-folder <path-for-data-folder> --cert-file <path-to-certificate> --key-file <path-to-private-key>

fedbiomed node -p </path/to/my-node> gui --port 80 --host 0.0.0.0

IMPORTANT: Provide data-folder argument while starting the GUI if not using the default /path/to/my-node/data

fedbiomed node -p </path/to/my-node> gui --data-folder /another/data-dir --port 80 --host 0.0.0.0

Launching Multiple Node GUI

It is possible to start multiple Node GUIs for different nodes as long as the http ports are different.

fedbiomed node -p my-node gui start --port 8181
fedbiomed node -p my-second-node gui start --port 8282
fedbiomed node -p my-second-node gui start --port 8383

Please see docs/developer/development-environment.md to find out how to debug and lunch UI for development purposes.

Troubleshooting

Fedbiomed includes a debug mode, which when enabled prints more outputs with more details, making it easier to troubleshoot. For details on how to use debug mode, refer to troubleshooting.