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
Metadata
1 maintainer
Release files for medfl 2.0.10.dev8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| medfl-2.0.10.dev8.tar.gz | 113.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| medfl-2.0.10.dev8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 241.7 kB
Release files / medfl-2.0.10.dev8.tar.gz
| Download URL | medfl-2.0.10.dev8.tar.gz |
|---|---|
| Size | 113.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a6c2f44b451e564c52e79d79ad7a7ccffd6316ee37c74b996178b1643d5acade
|
|
BLAKE2b-256 checksum How to use checksums |
9d6ab26f12ed3d33fab5626ad44d0d2fbce864b47c0458644107dccda3d88c5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Release files / medfl-2.0.10.dev8-py3-none-any.whl
| Download URL | medfl-2.0.10.dev8-py3-none-any.whl |
|---|---|
| Size | 127.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ecfd74596ca5f02ce4d749741a36b0030dd290460663c256f587c79f6f35e1c
|
|
BLAKE2b-256 checksum How to use checksums |
4d943cbeea2403339b7a7feb475dff17228f30fd99200d341dc7e83ab159d0a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.2
|
Security for medfl 2.0.10.dev8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
