neural-feature-importance 0.5.0__tar.gz → 0.9.1__tar.gz

neural_feature_importance-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CR de Sá
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neural_feature_importance-0.9.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: neural-feature-importance
+Version: 0.9.1
+Summary: Variance-based feature importance for Neural Networks using callbacks for Keras and PyTorch
+Author: CR de Sá
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow; extra == "tensorflow"
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Dynamic: license-file
+
+# neural-feature-importance
+
+[![PyPI version](https://img.shields.io/pypi/v/neural-feature-importance.svg)](https://pypi.org/project/neural-feature-importance/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Variance-based feature importance for deep learning models.
+
+`neural-feature-importance` implements the method described in
+[CR de Sá, *Variance-based Feature Importance in Neural Networks*](https://doi.org/10.1007/978-3-030-33778-0_24).
+It tracks the variance of the first trainable layer using Welford's algorithm
+and produces normalized importance scores for each feature.
+
+## Features
+
+- `VarianceImportanceKeras` — drop-in callback for TensorFlow/Keras models
+- `VarianceImportanceTorch` — helper class for PyTorch training loops
+- `MetricThreshold` — early-stopping callback based on a monitored metric
+- Example scripts to reproduce the experiments from the paper
+
+## Installation
+
+```bash
+pip install "neural-feature-importance[tensorflow]"  # for Keras
+pip install "neural-feature-importance[torch]"       # for PyTorch
+```
+
+Retrieve the package version via:
+
+```python
+from neural_feature_importance import __version__
+print(__version__)
+```
+
+## Quick start
+
+### Keras
+
+```python
+from neural_feature_importance import VarianceImportanceKeras
+from neural_feature_importance.utils import MetricThreshold
+
+viann = VarianceImportanceKeras()
+monitor = MetricThreshold(monitor="val_accuracy", threshold=0.95)
+model.fit(X, y, validation_split=0.05, epochs=30, callbacks=[viann, monitor])
+print(viann.feature_importances_)
+```
+
+### PyTorch
+
+```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, dataloader)
+    tracker.on_epoch_end()
+tracker.on_train_end()
+print(tracker.feature_importances_)
+```
+
+## Example scripts
+
+Run `scripts/compare_feature_importance.py` to train a small network on the Iris dataset
+and compare the scores with a random forest baseline:
+
+```bash
+python compare_feature_importance.py
+```
+
+Run `scripts/full_experiment.py` to reproduce the experiments from the paper:
+
+```bash
+python full_experiment.py
+```
+
+### Convolutional models
+
+To compute importances for convolutional networks, use
+`ConvVarianceImportanceKeras` from `neural_feature_importance.conv_callbacks`.
+`scripts/conv_visualization_example.py` trains small Conv2D models on the MNIST
+and scikit‑learn digits datasets and displays per-filter heatmaps. An equivalent
+notebook is available in ``notebooks/conv_visualization_example.ipynb``:
+
+```bash
+python scripts/conv_visualization_example.py
+```
+
+### Embedding layers
+
+To compute token importances from embedding weights, use
+`EmbeddingVarianceImportanceKeras` or `EmbeddingVarianceImportanceTorch` from
+`neural_feature_importance.embedding_callbacks`.
+Run `scripts/token_importance_topk_example.py` to train a small text classifier
+on IMDB and display the most important tokens. A matching notebook lives in
+``notebooks/token_importance_topk_example.ipynb``:
+
+```bash
+python scripts/token_importance_topk_example.py
+```
+
+## Development
+
+After making changes, run the following checks:
+
+```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
+jupyter nbconvert --to script "variance-based feature importance in artificial neural networks.ipynb" --stdout | head
+```
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@inproceedings{DBLP:conf/dis/Sa19,
+  author       = {Cl{\'a}udio Rebelo de S{\'a}},
+  editor       = {Petra Kralj Novak and
+                  Tomislav Smuc and
+                  Saso Dzeroski},
+  title        = {Variance-Based Feature Importance in Neural Networks},
+  booktitle    = {Discovery Science - 22nd International Conference, {DS} 2019, Split,
+                  Croatia, October 28-30, 2019, Proceedings},
+  series       = {Lecture Notes in Computer Science},
+  volume       = {11828},
+  pages        = {306--315},
+  publisher    = {Springer},
+  year         = {2019},
+  url          = {https://doi.org/10.1007/978-3-030-33778-0\_24},
+  doi          = {10.1007/978-3-030-33778-0\_24},
+  timestamp    = {Thu, 07 Nov 2019 09:20:36 +0100},
+  biburl       = {https://dblp.org/rec/conf/dis/Sa19.bib},
+  bibsource    = {dblp computer science bibliography, https://dblp.org}
+}
+```
+
+We appreciate citations as they help the community discover this work.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

neural_feature_importance-0.9.1/README.md

@@ -0,0 +1,143 @@
+# neural-feature-importance
+
+[![PyPI version](https://img.shields.io/pypi/v/neural-feature-importance.svg)](https://pypi.org/project/neural-feature-importance/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Variance-based feature importance for deep learning models.
+
+`neural-feature-importance` implements the method described in
+[CR de Sá, *Variance-based Feature Importance in Neural Networks*](https://doi.org/10.1007/978-3-030-33778-0_24).
+It tracks the variance of the first trainable layer using Welford's algorithm
+and produces normalized importance scores for each feature.
+
+## Features
+
+- `VarianceImportanceKeras` — drop-in callback for TensorFlow/Keras models
+- `VarianceImportanceTorch` — helper class for PyTorch training loops
+- `MetricThreshold` — early-stopping callback based on a monitored metric
+- Example scripts to reproduce the experiments from the paper
+
+## Installation
+
+```bash
+pip install "neural-feature-importance[tensorflow]"  # for Keras
+pip install "neural-feature-importance[torch]"       # for PyTorch
+```
+
+Retrieve the package version via:
+
+```python
+from neural_feature_importance import __version__
+print(__version__)
+```
+
+## Quick start
+
+### Keras
+
+```python
+from neural_feature_importance import VarianceImportanceKeras
+from neural_feature_importance.utils import MetricThreshold
+
+viann = VarianceImportanceKeras()
+monitor = MetricThreshold(monitor="val_accuracy", threshold=0.95)
+model.fit(X, y, validation_split=0.05, epochs=30, callbacks=[viann, monitor])
+print(viann.feature_importances_)
+```
+
+### PyTorch
+
+```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, dataloader)
+    tracker.on_epoch_end()
+tracker.on_train_end()
+print(tracker.feature_importances_)
+```
+
+## Example scripts
+
+Run `scripts/compare_feature_importance.py` to train a small network on the Iris dataset
+and compare the scores with a random forest baseline:
+
+```bash
+python compare_feature_importance.py
+```
+
+Run `scripts/full_experiment.py` to reproduce the experiments from the paper:
+
+```bash
+python full_experiment.py
+```
+
+### Convolutional models
+
+To compute importances for convolutional networks, use
+`ConvVarianceImportanceKeras` from `neural_feature_importance.conv_callbacks`.
+`scripts/conv_visualization_example.py` trains small Conv2D models on the MNIST
+and scikit‑learn digits datasets and displays per-filter heatmaps. An equivalent
+notebook is available in ``notebooks/conv_visualization_example.ipynb``:
+
+```bash
+python scripts/conv_visualization_example.py
+```
+
+### Embedding layers
+
+To compute token importances from embedding weights, use
+`EmbeddingVarianceImportanceKeras` or `EmbeddingVarianceImportanceTorch` from
+`neural_feature_importance.embedding_callbacks`.
+Run `scripts/token_importance_topk_example.py` to train a small text classifier
+on IMDB and display the most important tokens. A matching notebook lives in
+``notebooks/token_importance_topk_example.ipynb``:
+
+```bash
+python scripts/token_importance_topk_example.py
+```
+
+## Development
+
+After making changes, run the following checks:
+
+```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
+jupyter nbconvert --to script "variance-based feature importance in artificial neural networks.ipynb" --stdout | head
+```
+
+## Citation
+
+If you use this package in your research, please cite:
+
+```bibtex
+@inproceedings{DBLP:conf/dis/Sa19,
+  author       = {Cl{\'a}udio Rebelo de S{\'a}},
+  editor       = {Petra Kralj Novak and
+                  Tomislav Smuc and
+                  Saso Dzeroski},
+  title        = {Variance-Based Feature Importance in Neural Networks},
+  booktitle    = {Discovery Science - 22nd International Conference, {DS} 2019, Split,
+                  Croatia, October 28-30, 2019, Proceedings},
+  series       = {Lecture Notes in Computer Science},
+  volume       = {11828},
+  pages        = {306--315},
+  publisher    = {Springer},
+  year         = {2019},
+  url          = {https://doi.org/10.1007/978-3-030-33778-0\_24},
+  doi          = {10.1007/978-3-030-33778-0\_24},
+  timestamp    = {Thu, 07 Nov 2019 09:20:36 +0100},
+  biburl       = {https://dblp.org/rec/conf/dis/Sa19.bib},
+  bibsource    = {dblp computer science bibliography, https://dblp.org}
+}
+```
+
+We appreciate citations as they help the community discover this work.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

neural_feature_importance-0.9.1/conv_visualization_example.py

@@ -0,0 +1,60 @@
+"""Example of variance-based importance with a Conv2D model."""
+
+from __future__ import annotations
+
+import logging
+
+import matplotlib.pyplot as plt
+from tensorflow.keras.datasets import mnist
+from tensorflow.keras.layers import Conv2D, Dense, Flatten, MaxPooling2D
+from tensorflow.keras.models import Sequential
+from tensorflow.keras.utils import to_categorical
+
+from neural_feature_importance.conv_callbacks import ConvVarianceImportanceKeras
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def build_model() -> Sequential:
+    """Return a minimal Conv2D model."""
+    model = Sequential(
+        [
+            Conv2D(8, (3, 3), activation="relu", input_shape=(28, 28, 1)),
+            MaxPooling2D((2, 2)),
+            Flatten(),
+            Dense(10, activation="softmax"),
+        ]
+    )
+    model.compile(
+        optimizer="adam", loss="categorical_crossentropy", metrics=["accuracy"]
+    )
+    return model
+
+
+def main() -> None:
+    """Train model on MNIST and display a heatmap of importances."""
+    (x_train, y_train), _ = mnist.load_data()
+    x_train = x_train.astype("float32") / 255.0
+    x_train = x_train[..., None]
+    y_train = to_categorical(y_train, 10)
+
+    model = build_model()
+    callback = ConvVarianceImportanceKeras()
+    model.fit(x_train, y_train, epochs=2, batch_size=128, callbacks=[callback], verbose=0)
+
+    scores = callback.feature_importances_
+    if scores is None:
+        logger.warning("No importance scores computed.")
+        return
+
+    weights = model.layers[0].get_weights()[0]
+    heatmap = scores.reshape(weights.shape[0], weights.shape[1], weights.shape[2]).mean(axis=-1)
+    plt.imshow(heatmap, cmap="hot")
+    plt.colorbar()
+    plt.title("Feature importance heatmap")
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()

neural_feature_importance-0.9.1/conv_viz_utils.py

@@ -0,0 +1,123 @@
+"""Helper utilities for convolutional importance visualizations.
+
+These functions build small convolutional models, compute filter scores using
+variance-based importances, and plot the resulting weight maps and activations.
+They are intended for exploratory analysis and example scripts.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterable
+
+import matplotlib.pyplot as plt
+import matplotlib.colors as mcolors
+import numpy as np
+from tensorflow.keras.layers import Conv2D, Dense, Flatten, MaxPooling2D
+from tensorflow.keras.models import Sequential
+
+logger = logging.getLogger(__name__)
+
+CMAP = mcolors.LinearSegmentedColormap.from_list("white_blue_black", ["white", "blue", "black"])
+WEIGHT_CMAP = plt.cm.seismic
+
+
+def build_model(input_shape: tuple[int, int, int], kernel_size: tuple[int, int]) -> Sequential:
+    """Return a simple Conv2D model for visualization experiments.
+
+    Parameters
+    ----------
+    input_shape:
+        Shape of the input images, e.g. ``(28, 28, 1)``.
+    kernel_size:
+        Size of the convolution kernel.
+    """
+    model = Sequential(
+        [
+            Conv2D(8, kernel_size, activation="relu", input_shape=input_shape),
+            MaxPooling2D((2, 2)),
+            Flatten(),
+            Dense(10, activation="softmax"),
+        ]
+    )
+    model.compile(optimizer="adam", loss="categorical_crossentropy", metrics=["accuracy"])
+    return model
+
+
+def _threshold_filters(weights: np.ndarray, threshold: float) -> np.ndarray:
+    """Binarize filter weights using a threshold."""
+    mask = np.abs(weights) >= threshold
+    return np.where(mask, weights, 0.0)
+
+
+def compute_filter_scores(
+    weights: np.ndarray, heatmap: np.ndarray, threshold: float
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute filter importance scores.
+
+    Filters are thresholded and multiplied by the variance heatmap before
+    summing over all spatial dimensions.
+    """
+    thr_weights = _threshold_filters(weights, threshold)
+    scores = np.sum(np.abs(thr_weights) * heatmap[..., None], axis=(0, 1, 2))
+    return scores.astype(float), thr_weights
+
+
+def rank_filters(weights: np.ndarray, heatmap: np.ndarray, threshold: float) -> np.ndarray:
+    """Return filter indices sorted by descending importance."""
+    scores, _ = compute_filter_scores(weights, heatmap, threshold)
+    order = np.argsort(scores)[::-1]
+    logger.info("Filter scores: %s", scores.tolist())
+    return order
+
+
+def accuracy_with_filters(
+    model: Sequential,
+    x: np.ndarray,
+    y: np.ndarray,
+    indices: Iterable[int],
+) -> float:
+    """Return accuracy when only selected filters are active."""
+    conv = model.layers[0]
+    original = conv.get_weights()
+    weights = original[0].copy()
+    bias = original[1].copy()
+    mask = np.zeros(weights.shape[-1], dtype=bool)
+    mask[list(indices)] = True
+    weights[..., ~mask] = 0.0
+    bias[~mask] = 0.0
+    conv.set_weights([weights, bias])
+    preds = np.argmax(model.predict(x, verbose=0), axis=1)
+    acc = float(np.mean(preds == np.argmax(y, axis=1)))
+    conv.set_weights(original)
+    return acc
+
+
+def plot_filters(
+    weights: np.ndarray,
+    heatmap: np.ndarray,
+    example_out: np.ndarray,
+    order: Iterable[int],
+) -> None:
+    """Display filter weights, importances, and outputs."""
+    n_filters = weights.shape[-1]
+    vmax = float(np.max(np.abs(weights)))
+    fig, axes = plt.subplots(n_filters, 3, figsize=(9, 3 * n_filters))
+    for row, idx in enumerate(order):
+        ax_w = axes[row, 0]
+        ax_i = axes[row, 1]
+        ax_o = axes[row, 2]
+        im_w = ax_w.imshow(weights[:, :, 0, idx], cmap=WEIGHT_CMAP, vmin=-vmax, vmax=vmax)
+        ax_w.set_title(f"Filter {idx} weights")
+        ax_w.axis("off")
+        fig.colorbar(im_w, ax=ax_w)
+        im_i = ax_i.imshow(heatmap[:, :, 0], cmap=CMAP, vmin=0.0, vmax=1.0)
+        ax_i.set_title("Importance")
+        ax_i.axis("off")
+        fig.colorbar(im_i, ax=ax_i)
+        im_o = ax_o.imshow(example_out[:, :, idx], cmap="gray", vmin=0.0, vmax=np.max(example_out))
+        ax_o.set_title("Filter output")
+        ax_o.axis("off")
+        fig.colorbar(im_o, ax=ax_o)
+    plt.tight_layout()
+    plt.show()

{neural_feature_importance-0.5.0 → neural_feature_importance-0.9.1}/neural_feature_importance/__init__.py

@@ -7,6 +7,11 @@ from .callbacks import (
     VarianceImportanceKeras,
     VarianceImportanceTorch,
 )
+from .conv_callbacks import ConvVarianceImportanceKeras, ConvVarianceImportanceTorch
+from .embedding_callbacks import (
+    EmbeddingVarianceImportanceKeras,
+    EmbeddingVarianceImportanceTorch,
+)
 from .utils import MetricThreshold
 
 try:
@@ -19,4 +24,8 @@ __all__ = [
     "VarianceImportanceKeras",
     "VarianceImportanceTorch",
     "MetricThreshold",
+    "ConvVarianceImportanceKeras",
+    "ConvVarianceImportanceTorch",
+    "EmbeddingVarianceImportanceKeras",
+    "EmbeddingVarianceImportanceTorch",
 ]

{neural_feature_importance-0.5.0 → neural_feature_importance-0.9.1}/neural_feature_importance/callbacks.py

@@ -1,4 +1,10 @@
-"""Variance-based feature importance utilities."""
+"""Utilities for computing variance-based feature importances.
+
+These classes track the weights of the first trainable layer during training
+and estimate feature importances by accumulating the variance of each weight
+value. After training, the variances are combined with the last observed
+weights to produce a normalized importance score for every input feature.
+"""
 
 from __future__ import annotations
 
@@ -13,7 +19,13 @@ logger = logging.getLogger(__name__)
 
 
 class VarianceImportanceBase:
-    """Compute feature importance using Welford's algorithm."""
+    """Compute feature importances using running variance statistics.
+
+    The class implements Welford's algorithm to accumulate the variance of
+    weight values over training iterations. Feature importances are derived by
+    combining the final variance estimates with the absolute value of the last
+    observed weights.
+    """
 
     def __init__(self) -> None:
         self._n = 0
@@ -23,13 +35,21 @@ class VarianceImportanceBase:
         self.var_scores: np.ndarray | None = None
 
     def start(self, weights: np.ndarray) -> None:
-        """Initialize statistics for the given weight matrix."""
+        """Initialize running statistics.
+
+        Parameters
+        ----------
+        weights:
+            Initial weight matrix of shape ``(features, outputs)``. The values
+            are converted to ``float64`` for numerical stability and the running
+            mean and variance buffers are reset.
+        """
         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."""
+        """Update running mean and variance using new weights."""
         if self._mean is None or self._m2 is None:
             return
         self._n += 1
@@ -40,7 +60,7 @@ class VarianceImportanceBase:
         self._last_weights = weights
 
     def finalize(self) -> None:
-        """Finalize statistics and compute normalized scores."""
+        """Compute normalized importance scores from accumulated statistics."""
         if self._last_weights is None or self._m2 is None:
             logger.warning(
                 "%s was not fully initialized; no scores computed", self.__class__.__name__
@@ -67,6 +87,7 @@ class VarianceImportanceBase:
         return self.var_scores
 
 
+
 class VarianceImportanceKeras(Callback, VarianceImportanceBase):
     """Keras callback implementing variance-based feature importance."""