medfl 2.0.4.dev12

Python Open-source package for simulating federated learning and differential privacy

🧠 MEDfl

MEDfl: A Collaborative Framework for Federated Learning in Medicine

---

📚 Table of Contents

1. Introduction
2. Key Features
3. Installation
4. Modes of Operation
5. Quick Start
6. Documentation
7. Contributing
8. Acknowledgment
9. 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 through Tailscale VPN + WebSockets 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+ and optionally MySQL for local experiment storage.

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 using Tailscale + WebSockets.	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

Or visit the hosted documentation (coming soon):
👉 MEDfl Documentation Portal

---

7. Contributing

We welcome contributions of all kinds — from bug fixes to new modules.

1. Fork the repo and create a feature branch.
2. Run tests and format your code with black and flake8.
3. 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.