FL-Contributions-Incentives-Project

This repository implements a federated learning pipeline for brain tumour segmentation on the FeTS/BraTS dataset together with post-hoc client contribution evaluation using cooperative game theory.

The project uses MONAI and PyTorch for segmentation and computes client contribution scores using:

• Shapley Value
• Least Core (LC)

---

Main Notebooks

_01_BRATS-OR-01.ipynb

This notebook implements the complete federated learning training pipeline.

Its responsibilities include:

• Loading and preprocessing the FeTS/BraTS dataset.
• Splitting the dataset into simulated federated clients (training centres).
• Training a global SegResNet model using FedAvg.
• Saving the latest local model for every client.
• Saving the best-performing global model.
• Evaluating every coalition of clients by averaging their local models.
• Computing Shapley Value and Least Core allocations from the coalition utilities.

During training, the notebook automatically generates the model checkpoints required for later contribution analysis.

Outputs

submodels/
├── best_metric_model.pth
├── global_model.pth
├── submodel_<client>.pth

---

_02_run_shapley.ipynb

This notebook performs post-hoc contribution evaluation using the models generated by _01_BRATS-OR-01.ipynb.

Instead of retraining the federated model, it:

1. Reconstructs the validation dataset.
2. Loads the saved global model and client models.
3. Evaluates coalition utilities.
4. Computes Shapley Value and Least Core allocations.
5. Saves the results to CSV files.

The notebook supports resumable evaluation. If coalition utilities have already been computed, previously evaluated coalitions are skipped automatically.

Coalition Evaluation Methods

The notebook supports three coalition evaluation strategies:

Method	Description
snapshot	Default method. Coalitions are formed by averaging the final local client models.
or	One-Round approximation using stored singleton trajectories.
mr	Multi-Round approximation using stored round artifacts.

To select a method, modify:

METHOD = "snapshot"

---

Typical Workflow

Step 1 — Train the federated model

Run

_01_BRATS-OR-01.ipynb

This notebook will:

• train the federated segmentation model,
• save the best global model,
• save each client's final local model,
• generate the artifacts required for contribution evaluation.

---

Step 2 — Run contribution evaluation

After training has completed, run

_02_run_shapley.ipynb

This notebook loads the saved models and computes contribution scores without retraining.

The outputs include:

logs/
├── coalition_utilities.csv
└── allocation_summary.csv

where

• coalition_utilities.csv contains the validation Dice score for every evaluated coalition.
• allocation_summary.csv contains the final Shapley Value and Least Core allocation assigned to every client.

---

Required Files

Before running _02_run_shapley.ipynb, the following files must exist:

submodels/
├── best_metric_model.pth
├── submodel_<client>.pth

These files are generated automatically by _01_BRATS-OR-01.ipynb.

---

Repository Workflow

                 _01_BRATS-OR-01.ipynb
                          │
                          │
          Train Federated Segmentation Model
                          │
                          ▼
          Save Global & Local Client Models
                          │
                          ▼
                 submodels/*.pth
                          │
                          ▼
                 _02_run_shapley.ipynb
                          │
                          ▼
         Evaluate Coalition Utilities
                          │
                          ▼
      Compute Shapley & Least Core Scores
                          │
                          ▼
                 logs/*.csv

---

Notes

• The project assumes access to the MICCAI FeTS/BraTS dataset.
• Data partitioning follows the provided partitioning_*.csv files.
• Validation Dice score is used as the coalition utility throughout the contribution evaluation pipeline.