File size: 6,069 Bytes
282b60c 4f0a769 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c 02e7dc5 282b60c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | # Visualization helpers for ALOE ``explain`` (B-cos 6-channel RGB + inverse).
# Vendored from ``src/models/mixins/bcos_model.py``; kept here for Hub self-containment.
#
# No ``beartype`` / ``jaxtyping`` here: this file is loaded on the Hub via
# ``trust_remote_code`` and must stay transformers-only at runtime.
from __future__ import annotations
from typing import Literal, Optional, Union
import numpy as np
import torch
import torchvision.transforms.functional as TF
from matplotlib.axes import Axes
from matplotlib.image import AxesImage
TensorLike = Union[torch.Tensor, np.ndarray]
def _check_non_neg_int(name: str, n: int) -> None:
if not isinstance(n, int) or n < 0:
raise TypeError(f"{name} must be a non-negative int, got {n!r}")
def _check_closed_percent(name: str, x: float) -> None:
if not isinstance(x, (int, float)):
raise TypeError(f"{name} must be a number, got {type(x).__name__}")
v = float(x)
if not 0.0 <= v <= 100.0:
raise ValueError(f"{name} must be in [0, 100], got {v}")
def _check_open_percent(name: str, x: float) -> None:
if not isinstance(x, (int, float)):
raise TypeError(f"{name} must be a number, got {type(x).__name__}")
v = float(x)
if not 0.0 < v <= 100.0:
raise ValueError(f"{name} must be in (0, 100], got {v}")
def _check_pos_float(name: str, x: float) -> None:
if not isinstance(x, (int, float)):
raise TypeError(f"{name} must be a number, got {type(x).__name__}")
if float(x) <= 0.0:
raise ValueError(f"{name} must be > 0, got {x}")
def _check_non_empty_str(name: str, s: str) -> None:
if not isinstance(s, str) or len(s) == 0:
raise TypeError(f"{name} must be a non-empty str, got {s!r}")
def gradient_to_image(
image: torch.Tensor,
linear_mapping: torch.Tensor,
smooth: int = 15,
alpha_percentile: float = 99.5,
to_numpy: bool = True,
smooth_sigma: Optional[float] = None,
) -> torch.Tensor | np.ndarray:
"""
Build an RGBA explanation tensor (or NumPy array if ``to_numpy``).
Expects ``image`` and ``linear_mapping`` of shape ``(N, C, H, W)`` with ``C >= 3``
(typically ``C == 6`` for B-cos).
"""
_check_non_neg_int("smooth", smooth)
_check_closed_percent("alpha_percentile", alpha_percentile)
if smooth_sigma is not None:
_check_pos_float("smooth_sigma", smooth_sigma)
if linear_mapping.ndim != 4 or image.ndim != 4:
raise ValueError(
f"Expected 4-D tensors; got image.ndim={image.ndim}, linear_mapping.ndim={linear_mapping.ndim}"
)
if image.shape != linear_mapping.shape:
raise ValueError(
f"image shape {tuple(image.shape)} != linear_mapping shape {tuple(linear_mapping.shape)}"
)
contribs = (image * linear_mapping).sum(1, keepdim=True)
denominator = linear_mapping.abs().max(1, keepdim=True).values + 1e-12
rgb_grad = linear_mapping * torch.reciprocal(denominator)
rgb_grad = rgb_grad.clamp(min=0)
if rgb_grad.shape[1] >= 6:
denominator2 = rgb_grad[:, :3] + rgb_grad[:, 3:6] + 1e-12
rgb_grad = rgb_grad[:, :3] * torch.reciprocal(denominator2)
alpha = linear_mapping.norm(p=2, dim=1, keepdim=True)
# Zero alpha where the per-pixel contribution is negative (no positive evidence).
alpha = torch.where(contribs < 0, 0.0, alpha)
if smooth:
sigma_vals = None
if smooth_sigma is not None:
sigma_vals = [float(smooth_sigma), float(smooth_sigma)]
alpha = TF.gaussian_blur(alpha, kernel_size=[smooth, smooth], sigma=sigma_vals)
if alpha.numel() > 0:
B = alpha.shape[0]
alpha_reshaped = alpha.view(B, -1)
# One scalar per batch row: shape (B, 1). ``alpha`` is (B, 1, H, W) — not RGB.
quantiles_per_image = torch.quantile(
alpha_reshaped,
q=float(alpha_percentile) / 100.0,
dim=1,
keepdim=True,
)
# (B,1,1,1) so the per-image divisor broadcasts over H×W (same value every spatial location).
quantiles_for_division = quantiles_per_image.view(B, 1, 1, 1)
alpha = alpha * torch.reciprocal(quantiles_for_division + 1e-12)
alpha = alpha.clip(0, 1)
else:
raise ValueError("Alpha tensor is empty; cannot compute quantiles.")
rgb_grad = torch.concatenate([rgb_grad, alpha], dim=1)
grad_image = rgb_grad.permute(0, 2, 3, 1)
if to_numpy:
return grad_image.cpu().numpy()
return grad_image
def plot_contribution_map(
contribution_map: TensorLike,
ax: Optional[Axes] = None,
vrange: Optional[Union[float, Literal["auto"]]] = None,
vmin: Optional[float] = None,
vmax: Optional[float] = None,
hide_ticks: bool = True,
cmap: str = "bwr",
percentile: float = 99.5,
) -> tuple[Axes, AxesImage]:
"""Plot a 2-D contribution map; returns ``(axes, image_artist)``."""
_check_non_empty_str("cmap", cmap)
_check_open_percent("percentile", percentile)
if isinstance(contribution_map, torch.Tensor):
if contribution_map.ndim != 2:
raise ValueError(f"Contribution map must be 2-D (H, W); got ndim={contribution_map.ndim}")
contribution_map = contribution_map.detach().cpu().numpy()
else:
if contribution_map.ndim != 2:
raise ValueError(f"Contribution map must be 2-D (H, W); got ndim={contribution_map.ndim}")
cutoff = np.percentile(np.abs(contribution_map), percentile)
contribution_map = np.clip(contribution_map, -cutoff, cutoff)
if ax is None:
import matplotlib.pyplot as plt
_, ax = plt.subplots(1)
if vrange is None or vrange == "auto":
vrange_f = float(np.max(np.abs(contribution_map.flatten())))
else:
vrange_f = float(vrange)
im = ax.imshow(
contribution_map,
cmap=cmap,
vmin=-vrange_f if vmin is None else vmin,
vmax=vrange_f if vmax is None else vmax,
)
if hide_ticks:
ax.set_xticks([])
ax.set_yticks([])
return ax, im
|