neuronview 0.1.0__tar.gz

neuronview-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: neuronview
+Version: 0.1.0
+Summary: A lightweight PyTorch activation heatmap visualizer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Turtle-dev3/neuronview
+Project-URL: Issues, https://github.com/Turtle-dev3/neuronview/issues
+Keywords: pytorch,deep-learning,visualization,activations,heatmap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=1.9.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: torchvision>=0.10.0; extra == "dev"
+
+# neuronview
+
+A lightweight PyTorch library for visualizing neural network activations as heatmaps. Hook into any layer of your model and see what it "sees" — with one line of code.
+
+## Installation
+
+```bash
+# From source (recommended during development)
+git clone https://github.com/yourusername/neuronview.git
+cd neuronview
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import torch
+import torchvision.models as models
+from neuronview import Inspector
+
+# 1. Load any PyTorch model
+model = models.resnet18(pretrained=True)
+
+# 2. Create an Inspector and pick a layer to watch
+inspector = Inspector(model)
+inspector.watch("layer2.0.conv1")
+
+# 3. Run a forward pass with your input
+image = torch.randn(1, 3, 224, 224)  # replace with a real image
+inspector.run(image)
+
+# 4. Visualize!
+inspector.heatmap()
+```
+
+## Features
+
+### Discover layers
+
+Not sure which layers your model has? List them all:
+
+```python
+from neuronview import list_layers
+import torchvision.models as models
+
+model = models.resnet18()
+for name in list_layers(model):
+    print(name)
+# conv1
+# bn1
+# relu
+# maxpool
+# layer1.0.conv1
+# layer1.0.bn1
+# ...
+```
+
+### Watch multiple layers
+
+You can hook into several layers at once using method chaining:
+
+```python
+inspector = Inspector(model)
+inspector.watch("layer1.0.conv1").watch("layer3.0.conv1")
+inspector.run(image)
+
+# Specify which layer to visualize
+inspector.heatmap(layer_name="layer1.0.conv1")
+inspector.heatmap(layer_name="layer3.0.conv1")
+```
+
+### View a specific channel
+
+Each convolutional layer has multiple channels (filters). See what an individual channel detects:
+
+```python
+inspector.heatmap(channel=5)            # show channel 5
+inspector.heatmap(channel=0, cmap="hot") # different colormap
+```
+
+### Overlay on the original image
+
+See which part of your input image activated the layer most:
+
+```python
+inspector.heatmap_overlay(
+    original_image=image,
+    alpha=0.6,
+    cmap="jet",
+)
+```
+
+### Save figures
+
+```python
+inspector.heatmap(save_path="activation_map.png")
+```
+
+### Clean up
+
+```python
+inspector.clear()          # clear stored activations (keep hooks)
+inspector.unwatch("conv1") # remove a specific hook
+inspector.unwatch()        # remove all hooks
+```
+
+## API Reference
+
+### `Inspector(model)`
+
+The main class. Wraps a PyTorch model and manages forward hooks.
+
+| Method | Description |
+|--------|-------------|
+| `.watch(layer_name)` | Hook into a layer by its dot-path name. Returns `self` for chaining. |
+| `.run(x)` | Run a forward pass and capture activations. Returns model output. |
+| `.get_activations(layer_name=None)` | Get the raw activation tensor. If only one layer is watched, `layer_name` can be omitted. |
+| `.heatmap(layer_name=None, channel=None, **kwargs)` | Render a heatmap. Pass `cmap`, `figsize`, `title`, `save_path`. |
+| `.heatmap_overlay(original_image, layer_name=None, channel=None, alpha=0.5)` | Overlay heatmap on the input image. |
+| `.layers()` | List all hookable layer names in the model. |
+| `.unwatch(layer_name=None)` | Remove hooks (all if no name given). |
+| `.clear()` | Clear stored activations without removing hooks. |
+
+### `list_layers(model, include_containers=False)`
+
+Standalone function to list all hookable layers in a model.
+
+### `heatmap(activation, channel=None, cmap="viridis", ...)`
+
+Standalone function — render any activation tensor as a heatmap.
+
+### `heatmap_overlay(activation, original_image, channel=None, alpha=0.5, ...)`
+
+Standalone function — overlay an activation heatmap on an image.
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Project Structure
+
+```
+neuronview/
+├── neuronview/
+│   ├── __init__.py      # Public API exports
+│   ├── inspector.py     # Inspector class (hooks + activation capture)
+│   ├── visualize.py     # Heatmap rendering with matplotlib
+│   └── utils.py         # Layer listing + lookup helpers
+├── tests/
+│   ├── test_inspector.py
+│   └── test_visualize.py
+├── pyproject.toml       # Package metadata + dependencies
+└── README.md
+```
+
+## How It Works
+
+The core mechanism is **PyTorch forward hooks**. When you call `inspector.watch("layer2.0.conv1")`, neuronview:
+
+1. Walks the model's module tree to find that layer
+2. Registers a callback (`register_forward_hook`) on it
+3. When `inspector.run(x)` triggers a forward pass, the callback fires and captures the layer's output tensor
+4. The captured tensor is detached from the autograd graph and moved to CPU
+5. `heatmap()` averages across channels (or picks one) and renders with matplotlib
+
+## License
+
+MIT

neuronview-0.1.0/README.md

@@ -0,0 +1,171 @@
+# neuronview
+
+A lightweight PyTorch library for visualizing neural network activations as heatmaps. Hook into any layer of your model and see what it "sees" — with one line of code.
+
+## Installation
+
+```bash
+# From source (recommended during development)
+git clone https://github.com/yourusername/neuronview.git
+cd neuronview
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import torch
+import torchvision.models as models
+from neuronview import Inspector
+
+# 1. Load any PyTorch model
+model = models.resnet18(pretrained=True)
+
+# 2. Create an Inspector and pick a layer to watch
+inspector = Inspector(model)
+inspector.watch("layer2.0.conv1")
+
+# 3. Run a forward pass with your input
+image = torch.randn(1, 3, 224, 224)  # replace with a real image
+inspector.run(image)
+
+# 4. Visualize!
+inspector.heatmap()
+```
+
+## Features
+
+### Discover layers
+
+Not sure which layers your model has? List them all:
+
+```python
+from neuronview import list_layers
+import torchvision.models as models
+
+model = models.resnet18()
+for name in list_layers(model):
+    print(name)
+# conv1
+# bn1
+# relu
+# maxpool
+# layer1.0.conv1
+# layer1.0.bn1
+# ...
+```
+
+### Watch multiple layers
+
+You can hook into several layers at once using method chaining:
+
+```python
+inspector = Inspector(model)
+inspector.watch("layer1.0.conv1").watch("layer3.0.conv1")
+inspector.run(image)
+
+# Specify which layer to visualize
+inspector.heatmap(layer_name="layer1.0.conv1")
+inspector.heatmap(layer_name="layer3.0.conv1")
+```
+
+### View a specific channel
+
+Each convolutional layer has multiple channels (filters). See what an individual channel detects:
+
+```python
+inspector.heatmap(channel=5)            # show channel 5
+inspector.heatmap(channel=0, cmap="hot") # different colormap
+```
+
+### Overlay on the original image
+
+See which part of your input image activated the layer most:
+
+```python
+inspector.heatmap_overlay(
+    original_image=image,
+    alpha=0.6,
+    cmap="jet",
+)
+```
+
+### Save figures
+
+```python
+inspector.heatmap(save_path="activation_map.png")
+```
+
+### Clean up
+
+```python
+inspector.clear()          # clear stored activations (keep hooks)
+inspector.unwatch("conv1") # remove a specific hook
+inspector.unwatch()        # remove all hooks
+```
+
+## API Reference
+
+### `Inspector(model)`
+
+The main class. Wraps a PyTorch model and manages forward hooks.
+
+| Method | Description |
+|--------|-------------|
+| `.watch(layer_name)` | Hook into a layer by its dot-path name. Returns `self` for chaining. |
+| `.run(x)` | Run a forward pass and capture activations. Returns model output. |
+| `.get_activations(layer_name=None)` | Get the raw activation tensor. If only one layer is watched, `layer_name` can be omitted. |
+| `.heatmap(layer_name=None, channel=None, **kwargs)` | Render a heatmap. Pass `cmap`, `figsize`, `title`, `save_path`. |
+| `.heatmap_overlay(original_image, layer_name=None, channel=None, alpha=0.5)` | Overlay heatmap on the input image. |
+| `.layers()` | List all hookable layer names in the model. |
+| `.unwatch(layer_name=None)` | Remove hooks (all if no name given). |
+| `.clear()` | Clear stored activations without removing hooks. |
+
+### `list_layers(model, include_containers=False)`
+
+Standalone function to list all hookable layers in a model.
+
+### `heatmap(activation, channel=None, cmap="viridis", ...)`
+
+Standalone function — render any activation tensor as a heatmap.
+
+### `heatmap_overlay(activation, original_image, channel=None, alpha=0.5, ...)`
+
+Standalone function — overlay an activation heatmap on an image.
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Project Structure
+
+```
+neuronview/
+├── neuronview/
+│   ├── __init__.py      # Public API exports
+│   ├── inspector.py     # Inspector class (hooks + activation capture)
+│   ├── visualize.py     # Heatmap rendering with matplotlib
+│   └── utils.py         # Layer listing + lookup helpers
+├── tests/
+│   ├── test_inspector.py
+│   └── test_visualize.py
+├── pyproject.toml       # Package metadata + dependencies
+└── README.md
+```
+
+## How It Works
+
+The core mechanism is **PyTorch forward hooks**. When you call `inspector.watch("layer2.0.conv1")`, neuronview:
+
+1. Walks the model's module tree to find that layer
+2. Registers a callback (`register_forward_hook`) on it
+3. When `inspector.run(x)` triggers a forward pass, the callback fires and captures the layer's output tensor
+4. The captured tensor is detached from the autograd graph and moved to CPU
+5. `heatmap()` averages across channels (or picks one) and renders with matplotlib
+
+## License
+
+MIT

neuronview-0.1.0/neuronview/__init__.py

@@ -0,0 +1,20 @@
+"""
+neuronview — A lightweight PyTorch activation heatmap visualizer.
+
+Inspect what your neural network sees by hooking into any layer
+and visualizing its activations as heatmaps.
+
+Basic usage:
+    >>> from neuronview import Inspector
+    >>> inspector = Inspector(model)
+    >>> inspector.watch("layer2.0.conv1")
+    >>> inspector.run(input_tensor)
+    >>> inspector.heatmap()
+"""
+
+from neuronview.inspector import Inspector
+from neuronview.visualize import heatmap, heatmap_overlay
+from neuronview.utils import list_layers
+
+__version__ = "0.1.0"
+__all__ = ["Inspector", "heatmap", "heatmap_overlay", "list_layers"]

neuronview-0.1.0/neuronview/inspector.py

@@ -0,0 +1,253 @@
+"""
+inspector.py — The core of neuronview.
+
+This module contains the Inspector class, which uses PyTorch's forward hook
+mechanism to capture activations from any layer in a model.
+
+HOW FORWARD HOOKS WORK:
+    PyTorch lets you register a callback on any nn.Module. Every time a
+    forward pass runs through that module, your callback receives:
+        - module: the layer itself
+        - input:  the tensor(s) going INTO the layer
+        - output: the tensor(s) coming OUT of the layer (the "activations")
+
+    We grab `output`, detach it from the computation graph (so it doesn't
+    affect gradients), and store it. That's it — that's the whole trick.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import torch
+import torch.nn as nn
+
+from neuronview.visualize import heatmap, heatmap_overlay
+from neuronview.utils import list_layers, _get_layer_by_name
+
+
+class Inspector:
+    """Attach to a PyTorch model and capture activations from watched layers.
+
+    Parameters
+    ----------
+    model : nn.Module
+        The PyTorch model to inspect.
+
+    Example
+    -------
+    >>> import torchvision.models as models
+    >>> model = models.resnet18(pretrained=True)
+    >>> inspector = Inspector(model)
+    >>> inspector.watch("layer2.0.conv1")
+    >>> inspector.run(my_image_tensor)
+    >>> inspector.heatmap()
+    """
+
+    def __init__(self, model: nn.Module) -> None:
+        self.model = model
+        self.model.eval()  # always inspect in eval mode
+
+        # Maps layer name -> captured activation tensor
+        self._activations: dict[str, torch.Tensor] = {}
+
+        # Maps layer name -> hook handle (so we can remove hooks later)
+        self._hooks: dict[str, torch.utils.hooks.RemovableHook] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def watch(self, layer_name: str) -> "Inspector":
+        """Register a forward hook on the named layer.
+
+        Parameters
+        ----------
+        layer_name : str
+            Dot-separated path to the layer, e.g. "layer2.0.conv1".
+            Use ``Inspector.layers()`` to discover valid names.
+
+        Returns
+        -------
+        Inspector
+            Returns self so you can chain calls:
+            ``inspector.watch("layer1").watch("layer2")``
+        """
+        if layer_name in self._hooks:
+            return self  # already watching
+
+        layer = _get_layer_by_name(self.model, layer_name)
+
+        def hook_fn(module, input, output, name=layer_name):
+            """Capture the output tensor when this layer runs."""
+            # .detach() prevents this from being part of the gradient graph
+            # .cpu() moves it off GPU so we don't hold GPU memory
+            if isinstance(output, torch.Tensor):
+                self._activations[name] = output.detach().cpu()
+            elif isinstance(output, tuple):
+                # Some layers return tuples; grab the first tensor
+                self._activations[name] = output[0].detach().cpu()
+
+        handle = layer.register_forward_hook(hook_fn)
+        self._hooks[layer_name] = handle
+        return self
+
+    def run(self, x: torch.Tensor) -> torch.Tensor:
+        """Run a forward pass through the model and capture activations.
+
+        Parameters
+        ----------
+        x : torch.Tensor
+            Input tensor. For image models, typically shape (1, C, H, W).
+
+        Returns
+        -------
+        torch.Tensor
+            The model's output (predictions).
+        """
+        if not self._hooks:
+            raise RuntimeError(
+                "No layers are being watched. "
+                "Call inspector.watch('layer_name') first."
+            )
+
+        with torch.no_grad():
+            output = self.model(x)
+        return output
+
+    def get_activations(self, layer_name: Optional[str] = None) -> torch.Tensor:
+        """Retrieve captured activations.
+
+        Parameters
+        ----------
+        layer_name : str, optional
+            Which layer's activations to return. If None and only one layer
+            is being watched, returns that layer's activations.
+
+        Returns
+        -------
+        torch.Tensor
+            The activation tensor, typically shape (batch, channels, H, W).
+        """
+        if layer_name is None:
+            if len(self._activations) == 1:
+                return next(iter(self._activations.values()))
+            raise ValueError(
+                f"Multiple layers watched: {list(self._activations.keys())}. "
+                "Specify which one with layer_name=."
+            )
+
+        if layer_name not in self._activations:
+            raise KeyError(
+                f"No activations for '{layer_name}'. "
+                "Did you call inspector.run() after inspector.watch()?"
+            )
+        return self._activations[layer_name]
+
+    def heatmap(
+        self,
+        layer_name: Optional[str] = None,
+        channel: Optional[int] = None,
+        **kwargs,
+    ):
+        """Show a heatmap of the captured activations.
+
+        Parameters
+        ----------
+        layer_name : str, optional
+            Which layer to visualize. Can be omitted if only one is watched.
+        channel : int, optional
+            Specific channel to show. If None, averages across all channels.
+        **kwargs
+            Passed to matplotlib (cmap, figsize, etc.)
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+        """
+        act = self.get_activations(layer_name)
+        return heatmap(act, channel=channel, **kwargs)
+
+    def heatmap_overlay(
+        self,
+        original_image: torch.Tensor,
+        layer_name: Optional[str] = None,
+        channel: Optional[int] = None,
+        alpha: float = 0.5,
+        **kwargs,
+    ):
+        """Overlay the activation heatmap on the original image.
+
+        Parameters
+        ----------
+        original_image : torch.Tensor
+            The input image tensor, shape (C, H, W) or (1, C, H, W).
+        layer_name : str, optional
+            Which layer to visualize.
+        channel : int, optional
+            Specific channel. If None, averages across all channels.
+        alpha : float
+            Transparency of the heatmap overlay (0 = invisible, 1 = opaque).
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+        """
+        act = self.get_activations(layer_name)
+        return heatmap_overlay(
+            act, original_image, channel=channel, alpha=alpha, **kwargs
+        )
+
+    def layers(self) -> list[str]:
+        """List all hookable layers in the model.
+
+        Returns
+        -------
+        list[str]
+            Layer names you can pass to ``watch()``.
+        """
+        return list_layers(self.model)
+
+    def unwatch(self, layer_name: Optional[str] = None) -> "Inspector":
+        """Remove hooks and free captured activations.
+
+        Parameters
+        ----------
+        layer_name : str, optional
+            Specific layer to unwatch. If None, removes ALL hooks.
+        """
+        if layer_name is None:
+            for handle in self._hooks.values():
+                handle.remove()
+            self._hooks.clear()
+            self._activations.clear()
+        else:
+            if layer_name in self._hooks:
+                self._hooks[layer_name].remove()
+                del self._hooks[layer_name]
+            self._activations.pop(layer_name, None)
+        return self
+
+    def clear(self) -> "Inspector":
+        """Clear stored activations without removing hooks.
+
+        Useful between forward passes when you want fresh data.
+        """
+        self._activations.clear()
+        return self
+
+    # ------------------------------------------------------------------
+    # Dunder methods
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        watched = list(self._hooks.keys())
+        captured = list(self._activations.keys())
+        return (
+            f"Inspector(model={self.model.__class__.__name__}, "
+            f"watching={watched}, captured={captured})"
+        )
+
+    def __del__(self) -> None:
+        """Clean up hooks when the Inspector is garbage-collected."""
+        self.unwatch()