MEDfl 2.0.10.dev2__py3-none-any.whl → 2.0.10.dev4__py3-none-any.whl

MEDfl/LearningManager/federated_dataset.py

@@ -1,6 +1,8 @@
 from MEDfl.NetManager.net_helper import *
 from MEDfl.NetManager.net_manager_queries import *
 from MEDfl.NetManager.database_connector import DatabaseManager
+from typing import List, Optional
+
 
 class FederatedDataset:
     def __init__(
@@ -11,6 +13,7 @@ class FederatedDataset:
         trainloaders: list,
         valloaders: list,
         testloaders: list,
+        feature_names: Optional[List[str]] = None,
     ):
         """
         Represents a Federated Dataset.
@@ -30,6 +33,25 @@ class FederatedDataset:
         self.testloaders = testloaders
         self.size = len(self.trainloaders[0].dataset[0][0])
 
+        if feature_names is None:
+            feature_names = [
+                f"feature_{index}"
+                for index in range(self.size)
+            ]
+
+        if len(feature_names) != self.size:
+            raise ValueError(
+                "feature_names length must match the "
+                f"federated dataset size. Expected {self.size}, "
+                f"received {len(feature_names)}."
+            )
+
+        self.feature_names = list(
+            feature_names
+        )
+
+
+
         db_manager = DatabaseManager()
         db_manager.connect()
         self.eng = db_manager.get_connection()

MEDfl/LearningManager/server.py

@@ -15,6 +15,12 @@ from .federated_dataset import FederatedDataset
 from .model import Model
 from .strategy import Strategy
 
+from .shap import (
+    SHAPConfig,
+    LocalPyTorchSHAPExplainer,
+    aggregate_federated_shap,
+)
+
 
 # ---------------------------------------------------------------------------
 # Logging setup — call this ONCE before starting the simulation.
@@ -64,7 +70,10 @@ class FlowerServer:
         num_clients: int,
         fed_dataset: FederatedDataset,
         diff_privacy: bool = False,
-        client_resources: Optional[Dict[str, float]] = {'num_cpus': 1, 'num_gpus': 0.0}
+        client_resources: Optional[Dict[str, float]] = {'num_cpus': 1, 'num_gpus': 0.0} , 
+        shap_config: Optional[
+        SHAPConfig
+    ] = None,
     ) -> None:
 
         self.device = torch.device("cpu")
@@ -77,6 +86,19 @@ class FlowerServer:
         self.strategy = strategy
         self.client_resources = client_resources
 
+        self.shap_config = (
+            shap_config
+            if shap_config is not None
+            else SHAPConfig(enabled=False)
+        )
+
+        self.shap_config.validate(
+            input_size=self.fed_dataset.size
+        )
+
+        self.federated_shap_result = None
+        self.local_shap_results = []
+
         setattr(self.strategy.strategy_object, "min_available_clients", self.num_clients)
         setattr(self.strategy.strategy_object, "initial_parameters", fl.common.ndarrays_to_parameters(self.params))
         setattr(self.strategy.strategy_object, "evaluate_fn", self.evaluate)
@@ -117,6 +139,319 @@ class FlowerServer:
         if hasattr(self.global_model.criterion, "pos_weight") and self.global_model.criterion.pos_weight is not None:
             self.global_model.criterion.pos_weight = self.global_model.criterion.pos_weight.detach().cpu()
         self.validate()
+    
+    def synchronize_final_global_model(
+        self,
+    ) -> None:
+        """
+        Copy the last Flower-aggregated parameters into
+        the MEDfl global model wrapper.
+        """
+
+        strategy_object = (
+            self.strategy.strategy_object
+        )
+
+        if strategy_object is None:
+            raise RuntimeError(
+                "The Flower strategy has not been created"
+            )
+
+        final_parameters = getattr(
+            strategy_object,
+            "latest_aggregated_parameters",
+            None,
+        )
+
+        if final_parameters is None:
+            # Your evaluate() method already records the latest
+            # centralized-evaluation parameter arrays.
+            final_arrays = getattr(
+                self,
+                "last_parameters",
+                None,
+            )
+
+            if final_arrays is None:
+                raise RuntimeError(
+                    "The final global model parameters "
+                    "could not be found"
+                )
+        else:
+            final_arrays = (
+                fl.common.parameters_to_ndarrays(
+                    final_parameters
+                )
+            )
+
+        self.global_model.set_parameters(
+            final_arrays
+        )
+
+        self.global_model.model.to(
+            self.device
+        )
+        self.global_model.model.eval()
+
+        logging.getLogger(
+            "MEDfl.server"
+        ).info(
+            "Final global parameters synchronized "
+            "for post-training operations"
+        )
+    
+    def _get_shap_loaders(
+        self,
+    ) -> list[DataLoader]:
+        """
+        Return one loader per client according to SHAPConfig.
+        """
+
+        split = self.shap_config.data_split
+
+        if split == "train":
+            return self.fed_dataset.trainloaders
+
+        if split == "validation":
+            return self.fed_dataset.valloaders
+
+        if split == "test":
+            return self.fed_dataset.testloaders
+
+        raise ValueError(
+            f"Unsupported SHAP data split: {split}"
+        )
+    
+    def calculate_local_shap_results(
+        self,
+    ) -> list[dict]:
+        """
+        Calculate local SHAP summaries for every client partition.
+
+        This method runs only after federated training has finished.
+        """
+
+        if not self.shap_config.enabled:
+            return []
+
+        shap_logger = logging.getLogger(
+            "MEDfl.shap"
+        )
+
+        loaders = self._get_shap_loaders()
+
+        feature_names = (
+            self.shap_config.feature_names
+            if self.shap_config.feature_names
+            is not None
+            else self.fed_dataset.feature_names
+        )
+
+        if len(feature_names) != self.fed_dataset.size:
+            raise ValueError(
+                "SHAP feature names do not match the "
+                "federated dataset input size"
+            )
+
+        local_explainer = (
+            LocalPyTorchSHAPExplainer(
+                explainer_type=(
+                    self.shap_config.explainer
+                ),
+                background_size=(
+                    self.shap_config.background_size
+                ),
+                explanation_size=(
+                    self.shap_config.explanation_size
+                ),
+                random_seed=(
+                    self.shap_config.random_seed
+                ),
+                clipping_value=(
+                    self.shap_config.clipping_value
+                ),
+            )
+        )
+
+        local_results: list[dict] = []
+
+        for client_index, loader in enumerate(
+            loaders
+        ):
+            client_id = str(client_index)
+
+            if loader is None:
+                shap_logger.warning(
+                    "Skipping SHAP client %s: loader is None",
+                    client_id,
+                )
+                continue
+
+            available_samples = len(
+                loader.dataset
+            )
+
+            if available_samples == 0:
+                shap_logger.warning(
+                    "Skipping SHAP client %s: empty dataset",
+                    client_id,
+                )
+                continue
+
+            shap_logger.info(
+                "Starting local SHAP | client=%s | "
+                "available_samples=%d",
+                client_id,
+                available_samples,
+            )
+
+            try:
+                # The model is used for inference only.
+                # No optimizer or training method is called.
+                local_result = (
+                    local_explainer.calculate(
+                        model=self.global_model.model,
+                        loader=loader,
+                        device=self.device,
+                    )
+                )
+
+                explained_samples = int(
+                    local_result["sample_count"]
+                )
+
+                if (
+                    explained_samples
+                    < self.shap_config.minimum_samples
+                ):
+                    shap_logger.warning(
+                        "Skipping client %s because only %d "
+                        "samples were explained; minimum=%d",
+                        client_id,
+                        explained_samples,
+                        self.shap_config.minimum_samples,
+                    )
+                    continue
+
+                local_result[
+                    "client_id"
+                ] = client_id
+
+                local_result[
+                    "feature_names"
+                ] = list(feature_names)
+
+                local_result[
+                    "available_samples"
+                ] = available_samples
+
+                local_results.append(
+                    local_result
+                )
+
+                shap_logger.info(
+                    "Local SHAP completed | client=%s | "
+                    "explained_samples=%d",
+                    client_id,
+                    explained_samples,
+                )
+
+            except Exception as exc:
+                shap_logger.exception(
+                    "Local SHAP failed for client %s: %s",
+                    client_id,
+                    exc,
+                )
+
+        if not local_results:
+            raise RuntimeError(
+                "SHAP was enabled, but no client produced "
+                "a valid explanation result"
+            )
+
+        self.local_shap_results = (
+            local_results
+        )
+
+        return local_results
+    
+    def calculate_federated_shap(
+        self,
+    ) -> dict:
+        """
+        Run the complete post-training SHAP phase.
+        """
+
+        shap_logger = logging.getLogger(
+            "MEDfl.shap"
+        )
+
+        if not self.shap_config.enabled:
+            return {
+                "status": "disabled",
+            }
+
+        shap_logger.info(
+            "========================================"
+        )
+        shap_logger.info(
+            "Starting post-training federated SHAP"
+        )
+        shap_logger.info(
+            "Explainer: %s",
+            self.shap_config.explainer,
+        )
+        shap_logger.info(
+            "Data split: %s",
+            self.shap_config.data_split,
+        )
+        shap_logger.info(
+            "========================================"
+        )
+
+        local_results = (
+            self.calculate_local_shap_results()
+        )
+
+        federated_result = (
+            aggregate_federated_shap(
+                client_results=local_results,
+                include_client_results=(
+                    self.shap_config
+                    .include_client_results
+                ),
+            )
+        )
+
+        federated_result["explainer"] = (
+            self.shap_config.explainer
+        )
+        federated_result["data_split"] = (
+            self.shap_config.data_split
+        )
+        federated_result["background_size"] = (
+            self.shap_config.background_size
+        )
+        federated_result["requested_explanation_size"] = (
+            self.shap_config.explanation_size
+        )
+
+        self.federated_shap_result = (
+            federated_result
+        )
+
+        shap_logger.info(
+            "Federated SHAP completed | clients=%d | "
+            "samples=%d",
+            federated_result[
+                "participating_clients"
+            ],
+            federated_result[
+                "explained_samples"
+            ],
+        )
+
+        return federated_result
 
     def validate(self) -> None:
         if not isinstance(self.global_model, Model):
@@ -249,4 +584,32 @@ class FlowerServer:
             ray_init_args=ray_init_args,
             client_resources=self.client_resources
         )
+    # Training has now completely finished.
+        self.synchronize_final_global_model()
+
+        if self.shap_config.enabled:
+            try:
+                self.federated_shap_result = (
+                    self.calculate_federated_shap()
+                )
+
+            except Exception as exc:
+                logging.getLogger(
+                    "MEDfl.shap"
+                ).exception(
+                    "Post-training federated SHAP failed: %s",
+                    exc,
+                )
+
+                # Important: a SHAP failure does not mean
+                # federated training failed.
+                self.federated_shap_result = {
+                    "status": "failed",
+                    "error": str(exc),
+                }
+        else:
+            self.federated_shap_result = {
+                "status": "disabled",
+            }
+
         return history

MEDfl/LearningManager/shap/__init__.py

@@ -0,0 +1,9 @@
+from .config import SHAPConfig
+from .explainer import LocalPyTorchSHAPExplainer
+from .aggregation import aggregate_federated_shap
+
+__all__ = [
+    "SHAPConfig",
+    "LocalPyTorchSHAPExplainer",
+    "aggregate_federated_shap",
+]

MEDfl/LearningManager/shap/aggregation.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def _validate_client_results(
+    client_results: list[dict],
+) -> tuple[list[str], int]:
+    if not client_results:
+        raise ValueError(
+            "No client SHAP results were provided"
+        )
+
+    reference_features = client_results[0][
+        "feature_names"
+    ]
+
+    feature_count = len(reference_features)
+
+    required_array_keys = {
+        "abs_sum",
+        "signed_sum",
+        "square_sum",
+        "positive_count",
+        "negative_count",
+        "zero_count",
+    }
+
+    for result in client_results:
+        if result["feature_names"] != reference_features:
+            raise ValueError(
+                "Clients used different feature names or orders"
+            )
+
+        if int(result["sample_count"]) <= 0:
+            raise ValueError(
+                f"Client {result.get('client_id')} returned an "
+                "invalid SHAP sample count"
+            )
+
+        for key in required_array_keys:
+            if key not in result:
+                raise ValueError(
+                    f"Client result is missing '{key}'"
+                )
+
+            values = np.asarray(result[key])
+
+            if values.shape != (feature_count,):
+                raise ValueError(
+                    f"Client {result.get('client_id')} returned "
+                    f"invalid shape {values.shape} for {key}. "
+                    f"Expected ({feature_count},)."
+                )
+
+    return reference_features, feature_count
+
+
+def aggregate_federated_shap(
+    client_results: list[dict],
+    include_client_results: bool = True,
+) -> dict[str, Any]:
+    """
+    Aggregate additive local SHAP statistics.
+
+    The global mean absolute SHAP is equivalent to calculating:
+
+        sum of all |SHAP values| / number of all explained samples
+    """
+
+    feature_names, feature_count = (
+        _validate_client_results(client_results)
+    )
+
+    total_samples = sum(
+        int(result["sample_count"])
+        for result in client_results
+    )
+
+    abs_sum = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+    signed_sum = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+    square_sum = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+    positive_count = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+    negative_count = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+    zero_count = np.zeros(
+        feature_count,
+        dtype=np.float64,
+    )
+
+    for result in client_results:
+        abs_sum += np.asarray(
+            result["abs_sum"],
+            dtype=np.float64,
+        )
+        signed_sum += np.asarray(
+            result["signed_sum"],
+            dtype=np.float64,
+        )
+        square_sum += np.asarray(
+            result["square_sum"],
+            dtype=np.float64,
+        )
+        positive_count += np.asarray(
+            result["positive_count"],
+            dtype=np.float64,
+        )
+        negative_count += np.asarray(
+            result["negative_count"],
+            dtype=np.float64,
+        )
+        zero_count += np.asarray(
+            result["zero_count"],
+            dtype=np.float64,
+        )
+
+    mean_abs = abs_sum / total_samples
+    mean_signed = signed_sum / total_samples
+    mean_square = square_sum / total_samples
+
+    # Var(X) = E(X²) - E(X)²
+    variance = np.maximum(
+        mean_square - np.square(mean_signed),
+        0.0,
+    )
+
+    standard_deviation = np.sqrt(variance)
+
+    features = []
+
+    for index, feature_name in enumerate(
+        feature_names
+    ):
+        features.append(
+            {
+                "feature": feature_name,
+                "feature_index": index,
+                "mean_abs_shap": float(
+                    mean_abs[index]
+                ),
+                "mean_signed_shap": float(
+                    mean_signed[index]
+                ),
+                "shap_std": float(
+                    standard_deviation[index]
+                ),
+                "positive_rate": float(
+                    positive_count[index]
+                    / total_samples
+                ),
+                "negative_rate": float(
+                    negative_count[index]
+                    / total_samples
+                ),
+                "zero_rate": float(
+                    zero_count[index]
+                    / total_samples
+                ),
+            }
+        )
+
+    # Highest global importance first.
+    features.sort(
+        key=lambda item: item["mean_abs_shap"],
+        reverse=True,
+    )
+
+    final_result: dict[str, Any] = {
+        "status": "completed",
+        "participating_clients": len(
+            client_results
+        ),
+        "explained_samples": int(
+            total_samples
+        ),
+        "feature_importance": features,
+    }
+
+    if include_client_results:
+        client_summaries = []
+
+        for result in client_results:
+            sample_count = int(
+                result["sample_count"]
+            )
+
+            client_mean_abs = (
+                np.asarray(
+                    result["abs_sum"],
+                    dtype=np.float64,
+                )
+                / sample_count
+            )
+
+            local_features = [
+                {
+                    "feature": feature_name,
+                    "feature_index": index,
+                    "mean_abs_shap": float(
+                        client_mean_abs[index]
+                    ),
+                }
+                for index, feature_name in enumerate(
+                    feature_names
+                )
+            ]
+
+            local_features.sort(
+                key=lambda item: item[
+                    "mean_abs_shap"
+                ],
+                reverse=True,
+            )
+
+            client_summaries.append(
+                {
+                    "client_id": result[
+                        "client_id"
+                    ],
+                    "explained_samples": (
+                        sample_count
+                    ),
+                    "feature_importance": (
+                        local_features
+                    ),
+                }
+            )
+
+        final_result["client_results"] = (
+            client_summaries
+        )
+
+    return final_result

MEDfl/LearningManager/shap/config.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+
+@dataclass
+class SHAPConfig:
+    """
+    Configuration for the optional post-training federated SHAP phase.
+    """
+
+    enabled: bool = False
+
+    explainer: Literal[
+        "gradient",
+        "deep",
+    ] = "gradient"
+
+    data_split: Literal[
+        "train",
+        "validation",
+        "test",
+    ] = "validation"
+
+    background_size: int = 100
+    explanation_size: int = 500
+    random_seed: int = 42
+
+    feature_names: Optional[list[str]] = None
+
+    minimum_samples: int = 10
+    clipping_value: Optional[float] = None
+
+    # Whether individual client summaries should appear
+    # in the final result.
+    include_client_results: bool = True
+
+    def validate(self, input_size: int) -> None:
+        if not isinstance(self.enabled, bool):
+            raise TypeError("SHAP enabled must be a boolean")
+
+        if self.explainer not in {"gradient", "deep"}:
+            raise ValueError(
+                "SHAP explainer must be 'gradient' or 'deep'"
+            )
+
+        if self.data_split not in {
+            "train",
+            "validation",
+            "test",
+        }:
+            raise ValueError(
+                "SHAP data_split must be train, validation, or test"
+            )
+
+        if self.background_size <= 0:
+            raise ValueError(
+                "SHAP background_size must be greater than zero"
+            )
+
+        if self.explanation_size <= 0:
+            raise ValueError(
+                "SHAP explanation_size must be greater than zero"
+            )
+
+        if self.minimum_samples <= 0:
+            raise ValueError(
+                "SHAP minimum_samples must be greater than zero"
+            )
+
+        if self.clipping_value is not None:
+            if self.clipping_value <= 0:
+                raise ValueError(
+                    "SHAP clipping_value must be greater than zero"
+                )
+
+        if self.feature_names is not None:
+            if len(self.feature_names) != input_size:
+                raise ValueError(
+                    "The number of SHAP feature names must match "
+                    f"the model input size. Expected {input_size}, "
+                    f"received {len(self.feature_names)}."
+                )
+
+            if len(set(self.feature_names)) != len(
+                self.feature_names
+            ):
+                raise ValueError(
+                    "SHAP feature names must be unique"
+                )
+
+    def resolved_feature_names(
+        self,
+        input_size: int,
+    ) -> list[str]:
+        if self.feature_names is not None:
+            return list(self.feature_names)
+
+        return [
+            f"feature_{index}"
+            for index in range(input_size)
+        ]

MEDfl/LearningManager/shap/explainer.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader
+
+
+logger = logging.getLogger("MEDfl.shap")
+
+
+class LocalPyTorchSHAPExplainer:
+    """
+    Calculate SHAP values for one client partition.
+
+    Raw samples and per-sample SHAP values are not returned.
+    Only additive summary statistics are returned.
+    """
+
+    def __init__(
+        self,
+        explainer_type: str = "gradient",
+        background_size: int = 100,
+        explanation_size: int = 500,
+        random_seed: int = 42,
+        clipping_value: float | None = None,
+    ) -> None:
+        self.explainer_type = explainer_type
+        self.background_size = background_size
+        self.explanation_size = explanation_size
+        self.random_seed = random_seed
+        self.clipping_value = clipping_value
+
+    @staticmethod
+    def _collect_features(
+        loader: DataLoader,
+    ) -> torch.Tensor:
+        """
+        Collect only X values from the selected client loader.
+        Labels are not required to calculate SHAP values.
+        """
+        feature_batches: list[torch.Tensor] = []
+
+        for batch_index, batch in enumerate(loader):
+            if not isinstance(batch, (tuple, list)):
+                raise TypeError(
+                    "Each DataLoader batch must be a tuple or list"
+                )
+
+            if len(batch) == 0:
+                raise ValueError(
+                    f"Empty batch received at index {batch_index}"
+                )
+
+            X = batch[0]
+
+            if not isinstance(X, torch.Tensor):
+                X = torch.as_tensor(X)
+
+            X = X.detach().cpu().float()
+
+            if torch.isnan(X).any():
+                raise ValueError(
+                    f"SHAP input contains NaN values in batch "
+                    f"{batch_index}"
+                )
+
+            if torch.isinf(X).any():
+                raise ValueError(
+                    f"SHAP input contains infinite values in batch "
+                    f"{batch_index}"
+                )
+
+            feature_batches.append(X)
+
+        if not feature_batches:
+            raise ValueError(
+                "Cannot calculate SHAP using an empty DataLoader"
+            )
+
+        features = torch.cat(
+            feature_batches,
+            dim=0,
+        )
+
+        # First implementation: tabular data.
+        if features.ndim != 2:
+            raise ValueError(
+                "The current SHAP implementation supports tabular "
+                "input with shape (samples, features). "
+                f"Received shape {tuple(features.shape)}."
+            )
+
+        return features
+
+    @staticmethod
+    def _sample_rows(
+        data: torch.Tensor,
+        requested_size: int,
+        generator: torch.Generator,
+    ) -> torch.Tensor:
+        selected_size = min(
+            requested_size,
+            len(data),
+        )
+
+        indices = torch.randperm(
+            len(data),
+            generator=generator,
+        )[:selected_size]
+
+        return data[indices]
+
+    @staticmethod
+    def _normalize_shap_values(
+        raw_values: Any,
+        sample_count: int,
+        feature_count: int,
+    ) -> np.ndarray:
+        """
+        Normalize the different shapes returned by SHAP versions.
+
+        Expected final shape:
+            (number_of_samples, number_of_features)
+        """
+
+        if hasattr(raw_values, "values"):
+            raw_values = raw_values.values
+
+        if isinstance(raw_values, list):
+            if len(raw_values) != 1:
+                raise ValueError(
+                    "The current implementation supports binary or "
+                    "single-output models only. Multiclass SHAP "
+                    "requires class-specific aggregation."
+                )
+
+            raw_values = raw_values[0]
+
+        values = np.asarray(raw_values)
+
+        # Possible shape: (samples, features, 1)
+        if (
+            values.ndim == 3
+            and values.shape[-1] == 1
+        ):
+            values = values[..., 0]
+
+        # Possible shape: (1, samples, features)
+        if (
+            values.ndim == 3
+            and values.shape[0] == 1
+        ):
+            values = values[0]
+
+        expected_shape = (
+            sample_count,
+            feature_count,
+        )
+
+        if values.shape != expected_shape:
+            raise ValueError(
+                "Unexpected SHAP output shape. "
+                f"Expected {expected_shape}, received {values.shape}."
+            )
+
+        values = values.astype(
+            np.float64,
+            copy=False,
+        )
+
+        if np.isnan(values).any():
+            raise ValueError(
+                "Calculated SHAP values contain NaN values"
+            )
+
+        if np.isinf(values).any():
+            raise ValueError(
+                "Calculated SHAP values contain infinite values"
+            )
+
+        return values
+
+    def _create_explainer(
+        self,
+        model: torch.nn.Module,
+        background: torch.Tensor,
+    ):
+        try:
+            import shap
+        except ImportError as exc:
+            raise ImportError(
+                "SHAP is not installed. Install it with: "
+                "pip install shap"
+            ) from exc
+
+        if self.explainer_type == "gradient":
+            return shap.GradientExplainer(
+                model,
+                background,
+            )
+
+        if self.explainer_type == "deep":
+            return shap.DeepExplainer(
+                model,
+                background,
+            )
+
+        raise ValueError(
+            f"Unsupported SHAP explainer: {self.explainer_type}"
+        )
+
+    def calculate(
+        self,
+        model: torch.nn.Module,
+        loader: DataLoader,
+        device: torch.device,
+    ) -> dict:
+        """
+        Calculate SHAP for one client partition.
+
+        The returned values are additive summaries. They can be
+        combined across clients without transmitting raw SHAP rows.
+        """
+
+        features = self._collect_features(loader)
+
+        if len(features) < 2:
+            raise ValueError(
+                "At least two samples are required for SHAP"
+            )
+
+        generator = torch.Generator()
+        generator.manual_seed(self.random_seed)
+
+        background = self._sample_rows(
+            data=features,
+            requested_size=self.background_size,
+            generator=generator,
+        )
+
+        explanation_data = self._sample_rows(
+            data=features,
+            requested_size=self.explanation_size,
+            generator=generator,
+        )
+
+        background = background.to(device)
+        explanation_data = explanation_data.to(device)
+
+        model = model.to(device)
+        model.eval()
+
+        logger.info(
+            "Calculating local SHAP | "
+            "explainer=%s | available=%d | background=%d | "
+            "explained=%d",
+            self.explainer_type,
+            len(features),
+            len(background),
+            len(explanation_data),
+        )
+
+        explainer = self._create_explainer(
+            model=model,
+            background=background,
+        )
+
+        raw_values = explainer.shap_values(
+            explanation_data
+        )
+
+        shap_values = self._normalize_shap_values(
+            raw_values=raw_values,
+            sample_count=len(explanation_data),
+            feature_count=explanation_data.shape[1],
+        )
+
+        if self.clipping_value is not None:
+            shap_values = np.clip(
+                shap_values,
+                -self.clipping_value,
+                self.clipping_value,
+            )
+
+        # Additive summaries are preferable because they can later
+        # be used with distributed or secure aggregation.
+        result = {
+            "sample_count": int(shap_values.shape[0]),
+
+            "abs_sum": np.sum(
+                np.abs(shap_values),
+                axis=0,
+            ),
+
+            "signed_sum": np.sum(
+                shap_values,
+                axis=0,
+            ),
+
+            "square_sum": np.sum(
+                np.square(shap_values),
+                axis=0,
+            ),
+
+            "positive_count": np.sum(
+                shap_values > 0,
+                axis=0,
+            ).astype(np.int64),
+
+            "negative_count": np.sum(
+                shap_values < 0,
+                axis=0,
+            ).astype(np.int64),
+
+            "zero_count": np.sum(
+                shap_values == 0,
+                axis=0,
+            ).astype(np.int64),
+        }
+
+        return result

MEDfl/LearningManager/strategy.py

@@ -152,6 +152,8 @@ class Strategy:
                 # previous global model (flattened) for delta/cos sim
                 self._prev_global_flat: Optional[np.ndarray] = None
 
+                self.latest_aggregated_parameters = None
+
                 # logger (Flower config will handle output)
                 self._log = logging.getLogger("flwr")
                 self._debug_print = debug_print
@@ -225,10 +227,12 @@ class Strategy:
 
                 # Call base aggregation
                 agg = super().aggregate_fit(server_round, results, failures)
+        
 
                 # Round summary + global fingerprint (only if aggregation produced parameters)
                 if agg is not None:
                     parameters_agg, metrics_agg = agg  # type: ignore[misc]
+                    self.latest_aggregated_parameters = (parameters_agg)
                     flat = self._params_to_flat(parameters_agg)
                     fp = self._fingerprint(flat)
                     self._prev_global_flat = flat

MEDfl/LearningManager/xgboost/strategy.py

@@ -336,7 +336,7 @@ class XGBoostSimulationStrategy:
             return
 
         should_save = (
-            server_round % self.saveOnRounds == 0
+            server_round % self.save_on_rounds == 0
             or server_round == self.total_rounds
         )
 

{medfl-2.0.10.dev2.dist-info → medfl-2.0.10.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: medfl
-Version: 2.0.10.dev2
+Version: 2.0.10.dev4
 Summary: Python Open-source package for simulating federated learning and differential privacy
 Home-page: https://github.com/MEDomics-UdeS/MEDfl
 Author: MEDomics consortium
@@ -34,6 +34,7 @@ Requires-Dist: Sphinx<6.0,>=5.3
 Requires-Dist: sphinx-jsonschema==1.19.1
 Requires-Dist: sphinx-rtd-dark-mode==1.2.4
 Requires-Dist: xgboost
+Requires-Dist: shap
 
 # MEDfl: A Collaborative Framework for Federated Learning in Medicine
 

{medfl-2.0.10.dev2.dist-info → medfl-2.0.10.dev4.dist-info}/RECORD

@@ -2,15 +2,19 @@ MEDfl/__init__.py,sha256=70DmtU4C3A-1XYoaYm0moXBe-YGJ2FhEe3ga5SQVTts,97
 MEDfl/LearningManager/__init__.py,sha256=IMHJVeyx5ew0U_90LNMNCd4QISzWv3XCCri7fQRvcsM,341
 MEDfl/LearningManager/client.py,sha256=DQqptRl9Yff3G-THpYz7XOYzUePHKCkPKHBGg3tw88Q,6427
 MEDfl/LearningManager/dynamicModal.py,sha256=q8u7xPpj_TdZnSr8kYj0Xx7Sdz-diXsKBAfVce8-qSU,10534
-MEDfl/LearningManager/federated_dataset.py,sha256=InsZ5Rys2dgqaPxVyP5G3TrJMwiCNHOoTd3tCpUwUVM,2081
+MEDfl/LearningManager/federated_dataset.py,sha256=9U1yBE_rsHiTe8AgqyYmr5semqvsPlxvefzhHxTWsik,2661
 MEDfl/LearningManager/flpipeline.py,sha256=5lT2uod5EqnkRQ04cgm0gYyZz0djumfIYipCrzX1fdo,7111
 MEDfl/LearningManager/model.py,sha256=f6_S0pGtal9d314YHQh8EDkBnpCnlAS_Ak-dly4w-B8,10718
 MEDfl/LearningManager/params.yaml,sha256=joS329zAmYwKzfMVaZt12vx53FL9G3KWTPfYQZck1WI,434
 MEDfl/LearningManager/params_optimiser.py,sha256=8e0gCt4imwQHlNSJ3A2EAuc3wSr6yfSI6JDghohfmZQ,17618
 MEDfl/LearningManager/plot.py,sha256=h9k5KuPN4xncK-M4X4llUWug1gziGtzq4WeoJ4UQ8qI,10704
-MEDfl/LearningManager/server.py,sha256=cM-q1W2hV2Tp4K_3geVEc_4clW30Kuqq9VXHDFv-mWw,9921
-MEDfl/LearningManager/strategy.py,sha256=3wZC1a8-dwg1fSJrY6sVZPihw-fI0Hzj6jam7QpfCfA,13931
+MEDfl/LearningManager/server.py,sha256=zx2yc70TfDVwuJ31SD0SdaHk31cThspTlCdxDI5FCSM,19737
+MEDfl/LearningManager/strategy.py,sha256=YsQ1tFCuFjoRemNBjoygnrNzo59UdYvggbIT8zP2YCE,14071
 MEDfl/LearningManager/utils.py,sha256=90J-d2JiHbaQT2MdlfdW_YnpCUcjX16uE_vyW9MdFMY,9600
+MEDfl/LearningManager/shap/__init__.py,sha256=TKc24eg88e89vfoOgLfyKuImkLgGU4Bsl9Kcf-XRHuk,227
+MEDfl/LearningManager/shap/aggregation.py,sha256=Kg8LbxBXDMGqQ4s2-uy5f2vxa44K6Wj15e0QGxgX67E,6330
+MEDfl/LearningManager/shap/config.py,sha256=vSKHHO7x34-CeEc7lvcrj7CsAnBKvE3yv9f-4mF4fiM,2813
+MEDfl/LearningManager/shap/explainer.py,sha256=p4Ri3xmjJpk4cfq2F4ewaNxLSw68rM4Rl7T_S0DnJpU,8598
 MEDfl/LearningManager/xgboost/__init__.py,sha256=rc8fJMNPc8U3crWaEA2yZ0-Uw2Nn-3HiEqCGoG_eZN0,362
 MEDfl/LearningManager/xgboost/client.py,sha256=czrk90vNZwRpiIRrOtYZZUfYVIZu18NRgcdDCBvnjZo,8363
 MEDfl/LearningManager/xgboost/config.py,sha256=TAS4evXe1DmhTWEduKbeG_Dg4D_oTQCQn96LmQvlIHM,1911
@@ -18,7 +22,7 @@ MEDfl/LearningManager/xgboost/data.py,sha256=UTFx3SOQuKZP94kBeExB1r4MBFKQXx2z4Kq
 MEDfl/LearningManager/xgboost/metrics.py,sha256=lkIChQH6wh6PUT5chIn85jKMpC4IjcERra2cI-SX8o4,3999
 MEDfl/LearningManager/xgboost/serialization.py,sha256=ymoywErp3a8MvitypXYhtQ6feviFsOUsJbPD57VEKBQ,1005
 MEDfl/LearningManager/xgboost/server.py,sha256=JPkWOoHD6TKkLlsvtFlCFws-exZDHDVEdPYUHlfknAM,7913
-MEDfl/LearningManager/xgboost/strategy.py,sha256=GeiZRebgHQbsYyr2b5_kJft2Rcb_uNUlsexumui_Uic,18651
+MEDfl/LearningManager/xgboost/strategy.py,sha256=tEsXYrAVy6zYO1E-0VV9RvIwcWUBmlwhs4V8UOYzL8U,18653
 MEDfl/NetManager/__init__.py,sha256=OpgsIiBg7UA6Bfnu_kqGfEPxU8JfpPxSFU98TOeDTP0,273
 MEDfl/NetManager/database_connector.py,sha256=PZEAesMR-k9jSuthx4wOTkMzUWB3INODOrhQgpMO0kY,1554
 MEDfl/NetManager/dataset.py,sha256=OxUGlUDyjpD9Q0JhyVq7GMvzh42wcqYUArX-YXfouB4,2795
@@ -44,8 +48,8 @@ MEDfl/scripts/base.py,sha256=QrmG7gkiPYkAy-5tXxJgJmOSLGAKeIVH6i0jq7G9xnA,752
 MEDfl/scripts/create_db.py,sha256=MnFtZkTueRZ-3qXPNX4JsXjOKj-4mlkxoRhSFdRcvJw,3817
 alembic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 alembic/env.py,sha256=-aSZ6SlJeK1ZeqHgM-54hOi9LhJRFP0SZGjut-JnY-4,1588
-medfl-2.0.10.dev2.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-medfl-2.0.10.dev2.dist-info/METADATA,sha256=FeWXwOneIWGjq0LETpHsLPQd0YcxINH_stRjqBkS8j8,6632
-medfl-2.0.10.dev2.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-medfl-2.0.10.dev2.dist-info/top_level.txt,sha256=dIL9X8HOFuaVSzpg40DVveDPrymWRoShHtspH7kkjdI,14
-medfl-2.0.10.dev2.dist-info/RECORD,,
+medfl-2.0.10.dev4.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+medfl-2.0.10.dev4.dist-info/METADATA,sha256=aoOACHdZ5B8gMyBBLvuDSNezoLVt3MgzXeJs1NcsVss,6652
+medfl-2.0.10.dev4.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+medfl-2.0.10.dev4.dist-info/top_level.txt,sha256=dIL9X8HOFuaVSzpg40DVveDPrymWRoShHtspH7kkjdI,14
+medfl-2.0.10.dev4.dist-info/RECORD,,