This release is a pre-release and may not be stable for production use.
MEDfl: A Collaborative Framework for Federated Learning in Medicine
📚 Table of Contents
- Introduction
- Key Features
- Installation
- Modes of Operation
- Quick Start
- Documentation
- Contributing
- Acknowledgment
- Authors
1. Introduction
MEDfl is an open-source Federated Learning (FL) framework designed for both simulation and real-world distributed trainingin the medical and healthcare domains. It integrates Differential Privacy (DP), Transfer Learning (TL), and secure communication to enable privacy-preserving model training across multiple institutions—particularly suited for medical and clinical data.
2. Key Features
-
🧩 Two Operation Modes
- Simulation Mode: Run FL experiments locally for testing and benchmarking.
- Real-World Mode: Connect remote clients for production-grade FL.
-
🔒 Differential Privacy (Opacus Integration)
Ensures client updates are mathematically protected against data leakage. -
🧠 Transfer Learning Integration
Improve convergence and accuracy in small or heterogeneous datasets. -
⚙️ Modular Design
Plug-and-play components for models, optimizers, datasets, and aggregation strategies.
3. Installation
pip install medfl
✅ Requires Python 3.9+.
If you prefer the development version:
git clone https://github.com/MEDomics-UdeS/MEDfl.git
cd MEDfl
pip install -e .
4. Modes of Operation
| Mode | Description | Typical Use Case |
|---|---|---|
| Simulation FL | Runs all clients locally in a controlled environment. | Benchmarking, debugging, or prototyping. |
| Real-World FL | Connects distributed client machines. | Multi-institution collaboration, production deployments. |
5. Quick Start
🌍 Real-World Federated Learning Example
Server Setup
from MEDfl.rw.server import FederatedServer, Strategy
custom_strategy = Strategy(
name="FedAvg",
fraction_fit=1,
min_fit_clients=1,
min_evaluate_clients=1,
min_available_clients=1,
local_epochs=1,
threshold=0.5,
learning_rate=0.01,
optimizer_name="SGD",
saveOnRounds=3,
savingPath="./",
total_rounds=10,
datasetConfig={"isGlobal": True, "globalConfig": {"target": "label", "testFrac": 0.2}},
)
server = FederatedServer(
host="0.0.0.0",
port=8080,
num_rounds=10,
strategy=custom_strategy,
)
server.start()
Client Setup
from MEDfl.rw.client import FlowerClient, DPConfig
# Example: XGBoost client
xgb_params = {
"objective": "binary:logistic",
"eval_metric": "logloss",
"eta": 0.1,
"max_depth": 6,
"subsample": 0.8,
"colsample_bytree": 0.8,
"tree_method": "hist", # GPU: "gpu_hist"
}
client = FlowerClient(
server_address="100.65.215.27:8080",
data_path="../data/client1.csv",
dp_config=None, # DP only applies to neural networks
model_type="xgb",
xgb_params=xgb_params,
xgb_rounds=10,
)
client.start()
💡 Tip:
Use Tailscale to connect clients and server under the same secure VPN for real-world deployments.
6. Documentation
You can generate and host the documentation locally with Sphinx:
cd docs
make clean && make html
cd _build/html
python -m http.server
7. Contributing
We welcome contributions of all kinds — from bug fixes to new modules.
- Fork the repo and create a feature branch.
- Run tests and format your code with
blackandflake8. - Submit a Pull Request with clear details on your changes.
8. Acknowledgment
MEDfl is part of the MEDomicsLab initiative at the Université de Sherbrooke.
It was developed to enable secure, privacy-preserving, and reproducible machine learning across distributed medical datasets.
9. Authors
- 🧑💻 Ouael Nedjem Eddine Sahbi — Master’s Research Student, Université de Sherbrooke
- 👨💻 Haithem Lamri — Research Intern
- 🧬 MEDomics-UdeS
⭐ If you find this project useful, please consider starring it on GitHub to support continued development.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file medfl-2.0.10.dev3.tar.gz.
File metadata
- Download URL: medfl-2.0.10.dev3.tar.gz
- Upload date:
- Size: 94.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
67305eef659993a0500541e8f35cf775aba0ffb729b8ae358eb54e04ba67e351
|
|
| MD5 |
68a66ca808bc71c71cc8c202e75cc8f0
|
|
| BLAKE2b-256 |
ca2ece6833ead208ecae56e1d702cbabd3c636a8b9a96fddbadc1936e1cc93b7
|
File details
Details for the file medfl-2.0.10.dev3-py3-none-any.whl.
File metadata
- Download URL: medfl-2.0.10.dev3-py3-none-any.whl
- Upload date:
- Size: 108.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2775799af1b8974cfa4a437b17c64530ee4078b4b33100cf8d4226dd12218f2f
|
|
| MD5 |
d7b7011af1c1113e3a8b1b1618dd2977
|
|
| BLAKE2b-256 |
e73c4b12d52542663945ff2f3b81a871b452cab517c3554a1d5891f34d65a573
|
