neural-feature-importance 0.5.0__py3-none-any.whl

neural_feature_importance/__init__.py

@@ -0,0 +1,22 @@
+"""Utilities for variance-based feature importance in neural networks."""
+
+from importlib import metadata
+
+from .callbacks import (
+    VarianceImportanceBase,
+    VarianceImportanceKeras,
+    VarianceImportanceTorch,
+)
+from .utils import MetricThreshold
+
+try:
+    __version__ = metadata.version("neural-feature-importance")
+except metadata.PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "0.0.dev0"
+
+__all__ = [
+    "VarianceImportanceBase",
+    "VarianceImportanceKeras",
+    "VarianceImportanceTorch",
+    "MetricThreshold",
+]

neural_feature_importance/callbacks.py

@@ -0,0 +1,142 @@
+"""Variance-based feature importance utilities."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+from tensorflow.keras.callbacks import Callback
+from tensorflow.keras.layers import Layer
+
+logger = logging.getLogger(__name__)
+
+
+class VarianceImportanceBase:
+    """Compute feature importance using Welford's algorithm."""
+
+    def __init__(self) -> None:
+        self._n = 0
+        self._mean: np.ndarray | None = None
+        self._m2: np.ndarray | None = None
+        self._last_weights: np.ndarray | None = None
+        self.var_scores: np.ndarray | None = None
+
+    def start(self, weights: np.ndarray) -> None:
+        """Initialize statistics for the given weight matrix."""
+        self._mean = weights.astype(np.float64)
+        self._m2 = np.zeros_like(self._mean)
+        self._n = 0
+
+    def update(self, weights: np.ndarray) -> None:
+        """Update running statistics with new weights."""
+        if self._mean is None or self._m2 is None:
+            return
+        self._n += 1
+        delta = weights - self._mean
+        self._mean += delta / self._n
+        delta2 = weights - self._mean
+        self._m2 += delta * delta2
+        self._last_weights = weights
+
+    def finalize(self) -> None:
+        """Finalize statistics and compute normalized scores."""
+        if self._last_weights is None or self._m2 is None:
+            logger.warning(
+                "%s was not fully initialized; no scores computed", self.__class__.__name__
+            )
+            return
+          
+        if self._n < 2:
+            variance = np.full_like(self._m2, np.nan)
+        else:
+            variance = self._m2 / (self._n - 1)
+
+        scores = np.sum(variance * np.abs(self._last_weights), axis=1)
+        min_val = float(np.min(scores))
+        max_val = float(np.max(scores))
+        denom = max_val - min_val if max_val != min_val else 1.0
+        self.var_scores = (scores - min_val) / denom
+
+        top = np.argsort(self.var_scores)[-10:][::-1]
+        logger.info("Most important variables: %s", top)
+
+    @property
+    def feature_importances_(self) -> np.ndarray | None:
+        """Normalized importance scores for each input feature."""
+        return self.var_scores
+
+
+class VarianceImportanceKeras(Callback, VarianceImportanceBase):
+    """Keras callback implementing variance-based feature importance."""
+
+    def __init__(self) -> None:
+        Callback.__init__(self)
+        VarianceImportanceBase.__init__(self)
+        self._layer: Optional[Layer] = None
+
+    def on_train_begin(self, logs: Optional[dict] = None) -> None:  # type: ignore[override]
+        self._layer = None
+        for layer in self.model.layers:
+            if layer.get_weights():
+                self._layer = layer
+                break
+        if self._layer is None:
+            raise ValueError("Model does not contain trainable weights.")
+        weights = self._layer.get_weights()[0]
+        logger.info(
+            "Tracking variance for layer '%s' with %d features",
+            self._layer.name,
+            weights.shape[0],
+        )
+        self.start(weights)
+
+    def on_epoch_end(self, epoch: int, logs: Optional[dict] = None) -> None:  # type: ignore[override]
+        if self._layer is None:
+            return
+        weights = self._layer.get_weights()[0]
+        self.update(weights)
+
+    def on_train_end(self, logs: Optional[dict] = None) -> None:  # type: ignore[override]
+        self.finalize()
+
+    def get_config(self) -> dict[str, int]:
+        """Return configuration for serialization."""
+        return {}
+
+
+class VarianceImportanceTorch(VarianceImportanceBase):
+    """Track variance-based feature importance for PyTorch models."""
+
+    def __init__(self, model: "nn.Module") -> None:
+        from torch import nn  # Local import to avoid hard dependency
+
+        super().__init__()
+        self.model = model
+        self._param: nn.Parameter | None = None
+
+    def on_train_begin(self) -> None:
+        from torch import nn
+
+        for name, param in self.model.named_parameters():
+            if param.requires_grad and param.dim() >= 2:
+                self._param = param
+                weights = param.detach().cpu().numpy()
+                logger.info(
+                    "Tracking variance for parameter '%s' with %d features",
+                    name,
+                    weights.shape[1],
+                )
+                self.start(weights)
+                break
+        if self._param is None:
+            raise ValueError("Model does not contain trainable parameters")
+
+    def on_epoch_end(self) -> None:
+        if self._param is None:
+            return
+        weights = self._param.detach().cpu().numpy()
+        self.update(weights)
+
+    def on_train_end(self) -> None:
+        self.finalize()

neural_feature_importance/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility callbacks for model training."""
+
+from .monitors import MetricThreshold
+
+__all__ = ["MetricThreshold"]

neural_feature_importance/utils/monitors.py

@@ -0,0 +1,54 @@
+"""Training utilities for keras models."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from tensorflow.keras.callbacks import Callback
+
+logger = logging.getLogger(__name__)
+
+
+class MetricThreshold(Callback):
+    """Stop training when a metric exceeds a given threshold.
+
+    Parameters
+    ----------
+    monitor:
+        Name of the metric to monitor (e.g. ``"val_accuracy"`` or ``"loss"``).
+    threshold:
+        Value that the metric must reach to trigger early stopping.
+    min_epochs:
+        Minimum number of epochs before stopping is allowed.
+    """
+
+    def __init__(self, monitor: str = "val_accuracy", threshold: float | None = None, min_epochs: int = 5) -> None:
+        super().__init__()
+        self.monitor = monitor
+        self.threshold = threshold
+        self.min_epochs = min_epochs
+        self.stopped_epoch = 0
+
+    def on_epoch_end(self, epoch: int, logs: Optional[dict] = None) -> None:  # type: ignore[override]
+        logs = logs or {}
+        metric = logs.get(self.monitor)
+        if (
+            metric is not None
+            and self.threshold is not None
+            and epoch + 1 >= self.min_epochs
+            and metric >= self.threshold
+        ):
+            self.stopped_epoch = epoch + 1
+            self.model.stop_training = True
+            logger.info(
+                "MetricThreshold: stopped at epoch %d with %s=%.4f (threshold %.4f)",
+                self.stopped_epoch,
+                self.monitor,
+                metric,
+                self.threshold,
+            )
+
+    def on_train_end(self, logs: Optional[dict] = None) -> None:  # type: ignore[override]
+        if self.stopped_epoch:
+            logger.info("Training stopped at epoch %d", self.stopped_epoch)

neural_feature_importance-0.5.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: neural-feature-importance
+Version: 0.5.0
+Summary: Variance-based feature importance for Neural Networks using callbacks for Keras and PyTorch
+Author: CR de Sá
+Requires-Dist: numpy
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow; extra == "tensorflow"
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"

neural_feature_importance-0.5.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+neural_feature_importance/__init__.py,sha256=z3Rve0a7QTAhEpCesDhSdbkOwfSsNZgiwDVep1Is_c0,566
+neural_feature_importance/callbacks.py,sha256=HMHsmVaqZOzy5NSbxN-8CWvq82vzgZgZD53zqp2nAz0,4811
+neural_feature_importance/utils/__init__.py,sha256=dMjBUCx8DCoJKAEAnjj_daXfEu9Q5va1k8XupmWdZiE,114
+neural_feature_importance/utils/monitors.py,sha256=LTz7oE0-WgZ50DHyHDnTwfzWSSWMnjWd0xlwt7BWKuU,1763
+neural_feature_importance-0.5.0.dist-info/METADATA,sha256=Uo5R11NK7P-XXpeu3VWIl7I1w5K0l_30y0gp_J5GR-k,346
+neural_feature_importance-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+neural_feature_importance-0.5.0.dist-info/top_level.txt,sha256=yP0Q-BG7hDLLu1H1_x5bGEKwkCso5NxxvScnlmICb-o,26
+neural_feature_importance-0.5.0.dist-info/RECORD,,

neural_feature_importance-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

neural_feature_importance-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+neural_feature_importance