neural-feature-importance 0.5.0__tar.gz

neural_feature_importance-0.5.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

neural_feature_importance-0.5.0/AGENTS.md

@@ -0,0 +1,24 @@
+# Repository Guidelines
+
+This repository contains a minimal Python package named `neural-feature-importance` which provides utilities to compute variance-based feature importances. It exposes `VarianceImportanceCallback` for `tf.keras` models, `VarianceImportanceTorch` for PyTorch, and an `AccuracyMonitor` helper. The method is described in the article [CR de Sá, *Variance-based Feature Importance in Neural Networks*](https://doi.org/10.1007/978-3-030-33778-0_24).
+
+## Style
+- Follow PEP8 and PEP257 standards.
+- Use `tf.keras` APIs instead of the standalone `keras` package.
+- Use Python `logging` for all user-facing messages. Do not add print statements or verbose flags.
+- Provide type hints where practical and keep docstrings concise and descriptive.
+
+## Package layout
+- The public API lives in `neural_feature_importance/callbacks.py` and is re-exported from `neural_feature_importance/__init__.py`.
+- `VarianceImportanceCallback` exposes the attribute `var_scores` and property `feature_importances_`. The module also provides `AccuracyMonitor` and `VarianceImportanceTorch`.
+
+## Testing
+Run these commands after making changes:
+
+```bash
+python -m py_compile neural_feature_importance/callbacks.py
+python -m py_compile "variance-based feature importance in artificial neural networks.ipynb" 2>&1 | head
+# Optionally check notebook conversion if `jupyter` is available
+jupyter nbconvert --to script "variance-based feature importance in artificial neural networks.ipynb" --stdout | head
+```
+

neural_feature_importance-0.5.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,95 @@
+# Variance-based Feature Importance in Neural Networks / Deep Learning
+
+This file provides a working example of how to measure the importance of features (inputs) in neural networks. 
+
+This method is a new method to measure the relative importance of features in Artificial Neural Networks (ANN) models. Its underlying principle assumes that the more important a feature is, the more the weights, connected to the respective input neuron, will change during the training of the model. To capture this behavior, a running variance of every weight connected to the input layer is measured during training. For that, an adaptation of Welford's online algorithm for computing the online variance is proposed.
+
+When the training is finished, for each input, the variances of the weights are combined with the final weights to obtain the measure of relative importance for each feature.
+
+The file **variance-based feature importance in artificial neural networks.ipynb** includes the code to fully replicate the results obtained in the paper:
+
+CR de Sá [**Variance-based Feature Importance in Neural Networks**](https://doi.org/10.1007/978-3-030-33778-0_24)  
+22st International Conference on Discovery Science (DS 2019) Split, Croatia, October 28-30, 2019
+
+
+## VIANN
+#### Variance-based Feature Importance of Artificial Neural Networks
+
+This repository exposes the feature importance callback as a small Python package named `neural-feature-importance`.
+It will automatically track the first layer that contains trainable weights so you can use it with models that start with an `InputLayer` or other preprocessing layers.
+There is also a helper for PyTorch models that follows the same API.
+
+Install with pip and select the extras that match your framework:
+
+```bash
+pip install "neural-feature-importance[tensorflow]"  # for Keras
+pip install "neural-feature-importance[torch]"       # for PyTorch
+```
+
+The package uses `setuptools_scm` to derive its version from Git tags. Access it
+via:
+
+```python
+from neural_feature_importance import __version__
+
+print(__version__)
+```
+
+```python
+from neural_feature_importance import VarianceImportanceCallback, AccuracyMonitor
+
+import logging
+
+logging.basicConfig(level=logging.INFO)
+
+VIANN = VarianceImportanceCallback()
+monitor = AccuracyMonitor(baseline=0.95)
+```
+
+For a PyTorch model, use ``VarianceImportanceTorch`` and call its
+``on_train_begin``, ``on_epoch_end`` and ``on_train_end`` methods inside your
+training loop:
+
+```python
+from neural_feature_importance import VarianceImportanceTorch
+
+tracker = VarianceImportanceTorch(model)
+tracker.on_train_begin()
+for epoch in range(num_epochs):
+    train_one_epoch(model, optimizer, data_loader)
+    tracker.on_epoch_end()
+tracker.on_train_end()
+print(tracker.var_scores)
+```
+
+Use this callback during model training:
+
+```python
+model = Sequential()
+model.add(Dense(50, input_dim=input_dim, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))
+model.add(Dense(100, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))
+model.add(Dense(50, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))
+model.add(Dense(5, activation='softmax', kernel_initializer='normal'))
+
+model.compile(loss='categorical_crossentropy', optimizer='sgd', metrics=['accuracy'])
+model.fit(X, Y, validation_split=0.05, epochs=30, batch_size=64, shuffle=True,
+          verbose=1, callbacks=[VIANN, monitor])
+
+print(VIANN.var_scores)
+```
+
+## Comparing with Random Forest
+
+To verify the variance-based scores, run `compare_feature_importance.py`. The
+script trains a small neural network on the Iris dataset and compares the scores
+with those from a `RandomForestClassifier`.
+
+```bash
+python compare_feature_importance.py
+```
+
+For a larger experiment across several datasets, run `full_experiment.py`. The script builds a simple network for each dataset, applies the `AccuracyMonitor` for early stopping, and prints the correlation between neural network importances and a random forest baseline.
+
+```bash
+python full_experiment.py
+```

neural_feature_importance-0.5.0/compare_feature_importance.py

@@ -0,0 +1,112 @@
+"""Compare feature importance methods using the Iris dataset."""
+
+from __future__ import annotations
+
+import logging
+import numpy as np
+from sklearn.datasets import load_iris
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.model_selection import train_test_split
+from tensorflow.keras.models import Sequential
+from tensorflow.keras.layers import Dense
+from tensorflow.keras.utils import to_categorical
+import torch
+from torch import nn
+from torch.utils.data import DataLoader, TensorDataset
+
+from neural_feature_importance import (
+    VarianceImportanceKeras,
+    VarianceImportanceTorch,
+)
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def build_model(input_dim: int, num_classes: int) -> Sequential:
+    """Return a simple feed-forward neural network."""
+    model = Sequential(
+        [
+            Dense(16, input_dim=input_dim, activation="relu"),
+            Dense(num_classes, activation="softmax"),
+        ]
+    )
+    model.compile(
+        optimizer="adam", loss="categorical_crossentropy", metrics=["accuracy"]
+    )
+    return model
+
+
+def build_torch_model(input_dim: int, num_classes: int) -> nn.Module:
+    """Return a simple feed-forward PyTorch network."""
+    return nn.Sequential(
+        nn.Linear(input_dim, 16),
+        nn.ReLU(),
+        nn.Linear(16, num_classes),
+    )
+
+
+def main() -> None:
+    """Train models and compare feature importances."""
+    data = load_iris()
+    X_train, X_test, y_train, y_test = train_test_split(
+        data.data, data.target, test_size=0.2, random_state=42
+    )
+
+    num_classes = len(np.unique(data.target))
+    y_train_cat = to_categorical(y_train, num_classes)
+
+    model = build_model(data.data.shape[1], num_classes)
+    callback = VarianceImportanceKeras()
+    model.fit(
+        X_train,
+        y_train_cat,
+        epochs=50,
+        batch_size=16,
+        verbose=0,
+        callbacks=[callback],
+    )
+
+    nn_scores = callback.var_scores
+    logger.info("NN feature importances: %s", nn_scores)
+
+    # Train a PyTorch model using the same data
+    torch_model = build_torch_model(data.data.shape[1], num_classes)
+    optimizer = torch.optim.Adam(torch_model.parameters())
+    loss_fn = nn.CrossEntropyLoss()
+    dataset = TensorDataset(
+        torch.tensor(X_train, dtype=torch.float32),
+        torch.tensor(y_train, dtype=torch.long),
+    )
+    loader = DataLoader(dataset, batch_size=16, shuffle=True)
+    tracker = VarianceImportanceTorch(torch_model)
+    tracker.on_train_begin()
+    for _ in range(50):
+        torch_model.train()
+        for xb, yb in loader:
+            optimizer.zero_grad()
+            out = torch_model(xb)
+            loss = loss_fn(out, yb)
+            loss.backward()
+            optimizer.step()
+        tracker.on_epoch_end()
+    tracker.on_train_end()
+    torch_scores = tracker.var_scores
+    logger.info("PyTorch feature importances: %s", torch_scores)
+
+    rf = RandomForestClassifier(random_state=42)
+    rf.fit(X_train, y_train)
+    rf_scores = rf.feature_importances_
+    logger.info("Random forest importances: %s", rf_scores)
+
+    if nn_scores is not None:
+        corr = np.corrcoef(nn_scores, rf_scores)[0, 1]
+        logger.info("Correlation between Keras and RF: %.3f", corr)
+
+    if torch_scores is not None:
+        corr_torch = np.corrcoef(torch_scores, rf_scores)[0, 1]
+        logger.info("Correlation between PyTorch and RF: %.3f", corr_torch)
+
+
+if __name__ == "__main__":
+    main()

neural_feature_importance-0.5.0/full_experiment.py

@@ -0,0 +1,93 @@
+"""Replicate the notebook experiment using the reusable callbacks."""
+from __future__ import annotations
+
+import logging
+from typing import List
+
+import numpy as np
+from sklearn import datasets
+from sklearn.preprocessing import LabelEncoder, scale
+from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
+from tensorflow.keras.models import Sequential
+from tensorflow.keras.layers import Dense
+from tensorflow.keras.utils import to_categorical
+from tensorflow.keras.regularizers import l2
+
+from neural_feature_importance import VarianceImportanceKeras
+from neural_feature_importance.utils import MetricThreshold
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def nn2(input_dim: int, output_dim: int, classification: bool) -> Sequential:
+    """Return a small feed-forward network."""
+    model = Sequential(
+        [
+            Dense(50, input_dim=input_dim, activation="relu", kernel_regularizer=l2(0.01)),
+            Dense(100, activation="relu", kernel_regularizer=l2(0.01)),
+            Dense(50, activation="relu", kernel_regularizer=l2(0.01)),
+        ]
+    )
+    if classification:
+        model.add(Dense(output_dim, activation="softmax"))
+        model.compile(optimizer="sgd", loss="categorical_crossentropy", metrics=["accuracy"])
+    else:
+        model.add(Dense(1))
+        model.compile(optimizer="sgd", loss="mean_squared_error")
+    return model
+
+
+def run_experiment() -> None:
+    """Train on several datasets and compare with random forest importances."""
+    datasets_cfg: List[dict] = [
+        {"name": "breastcancer", "classification": True, "data": datasets.load_breast_cancer()},
+        {"name": "digits", "classification": True, "data": datasets.load_digits()},
+        {"name": "iris", "classification": True, "data": datasets.load_iris()},
+        {"name": "wine", "classification": True, "data": datasets.load_wine()},
+        {"name": "boston", "classification": False, "data": datasets.load_boston()},
+        {"name": "diabetes", "classification": False, "data": datasets.load_diabetes()},
+    ]
+
+    for cfg in datasets_cfg:
+        ds = cfg["data"]
+        X = scale(ds.data)
+        if cfg["classification"]:
+            enc = LabelEncoder()
+            y_enc = enc.fit_transform(ds.target)
+            Y = to_categorical(y_enc)
+            output_size = Y.shape[1]
+            rf = RandomForestClassifier(n_estimators=100)
+            rf.fit(X, ds.target)
+            monitor = MetricThreshold(monitor="val_accuracy", threshold=0.95)
+        else:
+            Y = scale(ds.target)
+            output_size = 1
+            rf = RandomForestRegressor(n_estimators=100)
+            rf.fit(X, ds.target)
+            monitor = None
+
+        model = nn2(X.shape[1], output_size, cfg["classification"])
+        viann = VarianceImportanceKeras()
+        callbacks = [viann]
+        if monitor:
+            callbacks.append(monitor)
+
+        model.fit(
+            X,
+            Y,
+            validation_split=0.05,
+            epochs=100,
+            batch_size=max(1, int(round(X.shape[0] / 7))),
+            verbose=0,
+            callbacks=callbacks,
+        )
+
+        nn_scores = viann.var_scores
+        rf_scores = rf.feature_importances_
+        corr = np.corrcoef(nn_scores, rf_scores)[0, 1]
+        logger.info("%s correlation with RF: %.2f", cfg["name"], corr)
+
+
+if __name__ == "__main__":
+    run_experiment()

neural_feature_importance-0.5.0/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-0.5.0/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-0.5.0/neural_feature_importance/utils/__init__.py

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

neural_feature_importance-0.5.0/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/neural_feature_importance.egg-info/PKG-INFO

@@ -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/neural_feature_importance.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+AGENTS.md
+README.md
+compare_feature_importance.py
+full_experiment.py
+pyproject.toml
+variance-based feature importance in artificial neural networks.ipynb
+.github/workflows/python-publish.yml
+neural_feature_importance/__init__.py
+neural_feature_importance/callbacks.py
+neural_feature_importance.egg-info/PKG-INFO
+neural_feature_importance.egg-info/SOURCES.txt
+neural_feature_importance.egg-info/dependency_links.txt
+neural_feature_importance.egg-info/requires.txt
+neural_feature_importance.egg-info/top_level.txt
+neural_feature_importance/utils/__init__.py
+neural_feature_importance/utils/monitors.py

neural_feature_importance-0.5.0/neural_feature_importance.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

neural_feature_importance-0.5.0/neural_feature_importance.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy
+
+[tensorflow]
+tensorflow
+
+[torch]
+torch

neural_feature_importance-0.5.0/neural_feature_importance.egg-info/top_level.txt

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

neural_feature_importance-0.5.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools", "wheel", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neural-feature-importance"
+description = "Variance-based feature importance for Neural Networks using callbacks for Keras and PyTorch"
+authors = [{name = "CR de Sá"}]
+dependencies = ["numpy"]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+tensorflow = ["tensorflow"]
+torch = ["torch"]
+[tool.setuptools_scm]

neural_feature_importance-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neural_feature_importance-0.5.0/variance-based feature importance in artificial neural networks.ipynb

@@ -0,0 +1,520 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "os.environ[\"CUDA_DEVICE_ORDER\"]=\"PCI_BUS_ID\"\n",
+    "os.environ[\"CUDA_VISIBLE_DEVICES\"]=\"0\"\n",
+    "\n",
+    "import tensorflow\n",
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "\n",
+    "from sklearn.model_selection import train_test_split\n",
+    "from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor\n",
+    "from tensorflow.keras.models import Sequential\n",
+    "from tensorflow.keras.layers import Dense, Dropout\n",
+    "from tensorflow.keras.utils import np_utils, to_categorical\n",
+    "from tensorflow.keras import optimizers\n",
+    "from tensorflow.keras.layers.advanced_activations import PReLU\n",
+    "from tensorflow.keras.layers.normalization import BatchNormalization\n",
+    "from tensorflow.keras.regularizers import l2\n",
+    "from sklearn import datasets\n",
+    "from sklearn import metrics\n",
+    "from sklearn.preprocessing import LabelEncoder, scale\n",
+    "from tensorflow.keras.utils import np_utils\n",
+    "import tensorflow.keras as keras"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Models"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def NN1(input_dim, output_dim, isClassification = True):\n",
+    "    print(\"Starting NN1\")\n",
+    "    \n",
+    "    model = Sequential()\n",
+    "    model.add(Dense(50, input_dim=input_dim, activation='linear', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "    model.add(Dense(100, activation='linear', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "    model.add(Dense(50, activation='linear', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "\n",
+    "    if (isClassification == False):\n",
+    "        model.add(Dense(1, kernel_initializer='normal'))\n",
+    "        model.compile(loss='mean_squared_error', optimizer='sgd')\n",
+    "    elif (isClassification == True):\n",
+    "        model.add(Dense(output_dim, activation='softmax', kernel_initializer='normal'))\n",
+    "        model.compile(loss='categorical_crossentropy', optimizer='sgd', metrics=['accuracy'])\n",
+    "        \n",
+    "    return model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def NN2(input_dim, output_dim, isClassification = True):\n",
+    "    print(\"Starting NN2\")\n",
+    "    \n",
+    "    model = Sequential()\n",
+    "    model.add(Dense(50, input_dim=input_dim, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "    model.add(Dense(100, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "    model.add(Dense(50, activation='relu', kernel_initializer='normal', kernel_regularizer=l2(0.01)))\n",
+    "        \n",
+    "    if (isClassification == False):\n",
+    "        model.add(Dense(1, kernel_initializer='normal'))\n",
+    "        model.compile(loss='mean_squared_error', optimizer='sgd')\n",
+    "    elif (isClassification == True):\n",
+    "        model.add(Dense(output_dim, activation='softmax', kernel_initializer='normal'))\n",
+    "        model.compile(loss='categorical_crossentropy', optimizer='sgd', metrics=['accuracy'])\n",
+    "        \n",
+    "    return model"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Deep Model\n",
+    "def DeepNN(input_dim, output_dim, isClassification = True):\n",
+    "    print(\"Starting DeepNN\")\n",
+    "    \n",
+    "    model = Sequential()\n",
+    "    model.add(Dense(500, input_dim=input_dim, activation='relu', kernel_initializer='normal'))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(1024, kernel_initializer='normal'))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(2048, kernel_initializer='normal', kernel_regularizer=l2(0.1)))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(4096, kernel_initializer='random_uniform', kernel_regularizer=l2(0.1)))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(2048, kernel_initializer='random_uniform', kernel_regularizer=l2(0.1)))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(1024, kernel_initializer='normal', kernel_regularizer=l2(0.1)))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.5))\n",
+    "    model.add(Dense(500, kernel_initializer='normal'))\n",
+    "    model.add(BatchNormalization())\n",
+    "    model.add(Dropout(0.2))\n",
+    "    model.add(PReLU())\n",
+    "\n",
+    "    if (isClassification == False):\n",
+    "        model.add(Dense(1, kernel_initializer='normal'))\n",
+    "        model.compile(loss='mean_squared_error', optimizer='adam')\n",
+    "    elif (isClassification == True):\n",
+    "        model.add(Dense(output_dim, activation='softmax', kernel_initializer='normal'))\n",
+    "        model.compile(loss='categorical_crossentropy', optimizer='adam', metrics=['accuracy'])\n",
+    "        \n",
+    "    return model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Variance Importance methods"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from neural_importance import VarianceImportanceCallback\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Taken from https://csiu.github.io/blog/update/2017/03/29/day33.html\n",
+    "def garson(A, B):\n",
+    "    \"\"\"\n",
+    "    Computes Garson's algorithm\n",
+    "    A = matrix of weights of input-hidden layer (rows=input & cols=hidden)\n",
+    "    B = vector of weights of hidden-output layer\n",
+    "    \"\"\"\n",
+    "    B = np.diag(B)\n",
+    "\n",
+    "    # connection weight through the different hidden node\n",
+    "    cw = np.dot(A, B)\n",
+    "\n",
+    "    # weight through node (axis=0 is column; sum per input feature)\n",
+    "    cw_h = abs(cw).sum(axis=0)\n",
+    "\n",
+    "    # relative contribution of input neuron to outgoing signal of each hidden neuron\n",
+    "    # sum to find relative contribution of input neuron\n",
+    "    rc = np.divide(abs(cw), abs(cw_h))\n",
+    "    rc = rc.sum(axis=1)\n",
+    "\n",
+    "    # normalize to 100% for relative importance\n",
+    "    ri = rc / rc.sum()\n",
+    "    return(ri)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Adapted from https://csiu.github.io/blog/update/2017/03/29/day33.html\n",
+    "class VarImpGarson(tensorflow.keras.callbacks.Callback):\n",
+    "    def __init__(self, verbose=0):\n",
+    "        self.verbose = verbose\n",
+    "        \n",
+    "    def on_train_end(self, batch, logs={}):\n",
+    "        if self.verbose:\n",
+    "            print(\"VarImp Garson\")\n",
+    "        \"\"\"\n",
+    "        Computes Garson's algorithm\n",
+    "        A = matrix of weights of input-hidden layer (rows=input & cols=hidden)\n",
+    "        B = vector of weights of hidden-output layer\n",
+    "        \"\"\"\n",
+    "        A = self.model.layers[0].get_weights()[0]\n",
+    "        B = self.model.layers[len(self.model.layers)-1].get_weights()[0]\n",
+    "        \n",
+    "        self.var_scores = 0\n",
+    "        for i in range(B.shape[1]):\n",
+    "            self.var_scores += garson(A, np.transpose(B)[i])\n",
+    "        if self.verbose:\n",
+    "            print(\"Most important variables: \",\n",
+    "                np.array(self.var_scores).argsort()[-10:][::-1])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Leave-One-Feature-Out LOFO\n",
+    "def LeaveOneFeatureOut(model, X, Y):\n",
+    "    OneOutScore = []\n",
+    "    n = X.shape[0]\n",
+    "    for i in range(0,X.shape[1]):\n",
+    "        newX = X.copy()\n",
+    "        newX[:,i] = 0 #np.random.normal(0,1,n)\n",
+    "        OneOutScore.append(model.evaluate(newX, Y, batch_size=2048, verbose=0))\n",
+    "    OneOutScore = pd.DataFrame(OneOutScore[:])\n",
+    "    ordered = np.argsort(-OneOutScore.iloc[:,0])\n",
+    "    return(OneOutScore, ordered)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Testing variable importance"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Settings obtained for each dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = list()\n",
+    "data.append({\"name\": 'breastcancer', \"classification\": True, \"data\": datasets.load_breast_cancer()})\n",
+    "data.append({\"name\": 'digits', \"classification\": True, \"data\": datasets.load_digits()})\n",
+    "data.append({\"name\": 'iris', \"classification\": True, \"data\": datasets.load_iris()})\n",
+    "data.append({\"name\": 'wine', \"classification\": True, \"data\": datasets.load_wine()})\n",
+    "data.append({\"name\": 'boston', \"classification\": False, \"data\": datasets.load_boston()})\n",
+    "data.append({\"name\": 'diabetes', \"classification\": False, \"data\": datasets.load_diabetes()})"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tensorflow.keras.callbacks import Callback\n",
+    "import numpy as np\n",
+    "\n",
+    "class AccuracyMonitor(Callback):\n",
+    "    def __init__(self,\n",
+    "                 monitor='val_acc',\n",
+    "                 verbose=0,\n",
+    "                 min_epochs=5,\n",
+    "                 baseline=None):\n",
+    "        super(AccuracyMonitor, self).__init__()\n",
+    "\n",
+    "        self.monitor = monitor\n",
+    "        self.baseline = baseline\n",
+    "        self.verbose = verbose\n",
+    "        self.min_epochs = min_epochs\n",
+    "        self.stopped_epoch = 0\n",
+    "\n",
+    "    def on_epoch_end(self, epoch, logs=None):\n",
+    "        if logs.get(self.monitor) > self.baseline and epoch > self.min_epochs:\n",
+    "            self.stopped_epoch = epoch\n",
+    "            self.model.stop_training = True\n",
+    "            print('\\n Stopped at epoch {epoch}. Accuracy of {accuracy} reached.'.format(epoch=(self.stopped_epoch + 1), accuracy=logs.get(self.monitor)), \"\\n\")\n",
+    "\n",
+    "    def on_train_end(self, logs=None):\n",
+    "        if self.stopped_epoch > 0 and self.verbose > 0:\n",
+    "            print('Epoch %05d: early stopping' % (self.stopped_epoch + 1))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "from numpy.random import seed\n",
+    "from tensorflow.keras.callbacks import EarlyStopping\n",
+    "\n",
+    "def runExp(data, mdl = \"NN1\", xseed = 42, epochs = 1000, verbose = 0):\n",
+    "\n",
+    "    res = list()\n",
+    "    VIANN_list = []\n",
+    "    Garson_list = []\n",
+    "    LOFO_list = []\n",
+    "    RF_list = []\n",
+    "    for i in range(len(data)):\n",
+    "        seed(xseed)\n",
+    "        \n",
+    "        dataset = data[i]['data']\n",
+    "        isClassification = data[i]['classification']\n",
+    "        datname = data[i]['name']\n",
+    "        \n",
+    "        print(\"============\")\n",
+    "        print( data[i]['name'])\n",
+    "        print(\"============\\n\")\n",
+    "\n",
+    "        if isClassification == True:\n",
+    "            #Classification\n",
+    "\n",
+    "            labels_encoded = []\n",
+    "            for labels in [dataset.target]:\n",
+    "                encoder = LabelEncoder()\n",
+    "                encoder.fit(labels)\n",
+    "                encoded_Y = encoder.transform(labels)\n",
+    "                # convert integers to dummy variables (i.e. one hot encoded)\n",
+    "                labels_encoded.append(np_utils.to_categorical(encoded_Y))\n",
+    "            dataset.targetLabels = labels_encoded[0]\n",
+    "\n",
+    "            # fit a Random Forest model to the data\n",
+    "            RFmodel = RandomForestClassifier(n_estimators=100)\n",
+    "\n",
+    "            output_size = dataset.targetLabels.shape[1]\n",
+    "\n",
+    "        else:\n",
+    "            dataset.targetLabels = scale(dataset.target)\n",
+    "            output_size = 1\n",
+    "\n",
+    "            # fit a Random Forest model to the data\n",
+    "            RFmodel = RandomForestRegressor(n_estimators=100)\n",
+    "\n",
+    "        X = scale(dataset.data)\n",
+    "        Y = dataset.targetLabels\n",
+    "\n",
+    "        RFmodel.fit(X, Y)\n",
+    "        \n",
+    "        VIANN = VarianceImportanceCallback()\n",
+    "        Garson = VarImpGarson(verbose=verbose)\n",
+    "\n",
+    "        if (mdl == \"NN1\"):\n",
+    "            model = NN1(X.shape[1], output_size, isClassification)\n",
+    "        elif (mdl == \"NN2\"):\n",
+    "            model = NN2(X.shape[1], output_size, isClassification)\n",
+    "        elif (mdl == \"DeepNN\"):\n",
+    "            model = DeepNN(X.shape[1], output_size, isClassification)\n",
+    "        \n",
+    "        clbs = [VIANN,Garson]\n",
+    "        if isClassification == True:\n",
+    "            clbs.append(AccuracyMonitor(monitor='val_acc', baseline=0.95, min_epochs = 5))\n",
+    "        else:\n",
+    "            epochs = 100\n",
+    "        \n",
+    "        model.fit(X, Y, validation_split=0.05, epochs=epochs, batch_size=np.round(X.shape[0]/7).astype(int), shuffle=True, \n",
+    "                  verbose=verbose, callbacks = clbs)\n",
+    "\n",
+    "        LOFO, LOFO_Ordered = LeaveOneFeatureOut(model, X, Y)\n",
+    "\n",
+    "        print('VIANN vs LOFO:  ', round(np.corrcoef([VIANN.var_scores,LOFO[0]])[0,1], 2))\n",
+    "        print('VIANN vs RF:    ', round(np.corrcoef([VIANN.var_scores,RFmodel.feature_importances_])[0,1], 2))\n",
+    "        print('Garson vs LOFO: ', round(np.corrcoef([Garson.var_scores,LOFO[0]])[0,1], 2))\n",
+    "        print('Garson vs VIANN:', round(np.corrcoef([Garson.var_scores,VIANN.var_scores])[0,1], 2))\n",
+    "        \n",
+    "        res.append([data[i]['name'],\n",
+    "                    round(np.corrcoef([VIANN.var_scores,LOFO[0]])[0,1], 2), \n",
+    "                    round(np.corrcoef([VIANN.var_scores,RFmodel.feature_importances_])[0,1], 2),\n",
+    "                    round(np.corrcoef([Garson.var_scores,LOFO[0]])[0,1], 2),\n",
+    "                    round(np.corrcoef([Garson.var_scores,VIANN.var_scores])[0,1], 2)\n",
+    "                          ])\n",
+    "        \n",
+    "        VIANN_list.append([data[i]['name'], VIANN.var_scores])\n",
+    "        Garson_list.append([data[i]['name'], Garson.var_scores])\n",
+    "        LOFO_list.append([data[i]['name'], LOFO])\n",
+    "        RF_list.append([data[i]['name'], RFmodel.feature_importances_])\n",
+    "        \n",
+    "    df = pd.DataFrame(res)\n",
+    "    df.columns = (\"Dataset\", \"VIANN vs LOFO\", \"VIANN vs RF\", \"Garson vs LOFO\", \"Garson vs VIANN\")\n",
+    "    \n",
+    "    return df, VIANN_list, Garson_list, LOFO_list, RF_list"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rsNN1, VIANN_NN1, Garson_NN1, LOFO_NN1, RF = runExp(data, mdl = \"NN1\", verbose = 0)\n",
+    "rsNN1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "rsNN2, VIANN_NN2, Garson_NN2, LOFO_NN2, RF = runExp(data, mdl = \"NN2\", verbose = 0)\n",
+    "rsNN2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rsDeepNN, VIANN_DeepNN, Garson_DeepNN, LOFO_DeepNN, RF = runExp(data, mdl = \"DeepNN\", verbose = 0)\n",
+    "rsDeepNN"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Results published in Discovery Science 2019"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rsNN1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rsNN2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rsDeepNN"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "modelname = \"NN2\"\n",
+    "datname = VIANN_NN2[1][0]\n",
+    "xx = VIANN_NN2[1][1]\n",
+    "yy = LOFO_NN2[1][1][0]\n",
+    "\n",
+    "f = plt.figure()\n",
+    "plt.scatter(xx, yy)\n",
+    "plt.xlabel('VIANN')\n",
+    "plt.ylabel('LOFO')\n",
+    "plt.title('VIANN vs LOFO' + \" (\" + datname + \" dataset)\")\n",
+    "plt.show()\n",
+    "f.savefig(\"VIANNvsLOFO_\" + datname + \"_\" + modelname +\".pdf\")\n",
+    "\n",
+    "print(np.corrcoef([xx,yy])[0,1])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "modelname = \"DeepNN\"\n",
+    "datname = VIANN_DeepNN[1][0]\n",
+    "xx = VIANN_DeepNN[1][1]\n",
+    "yy = RF[1][1]\n",
+    "\n",
+    "f = plt.figure()\n",
+    "plt.scatter(xx, yy)\n",
+    "plt.xlabel('VIANN')\n",
+    "plt.ylabel('RF feature importance')\n",
+    "plt.title('VIANN vs RF' + \" (\" + datname + \" dataset)\")\n",
+    "plt.show()\n",
+    "f.savefig(\"VIANNvsRF_\" + datname + \"_\" + modelname +\".pdf\")\n",
+    "\n",
+    "print(np.corrcoef([xx,yy])[0,1])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "nbformat": 4,
+  "nbformat_minor": 2
+}