fannar 0.3.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fannar/__init__.py +51 -0
- fannar/interpreter.py +354 -0
- fannar/kernels.py +147 -0
- fannar/pairs.py +229 -0
- fannar/pipeline.py +146 -0
- fannar/plots.py +287 -0
- fannar/readings.py +178 -0
- fannar/report.py +92 -0
- fannar/sources/__init__.py +62 -0
- fannar/sources/torch.py +254 -0
- fannar/sources/tree.py +65 -0
- fannar/space.py +225 -0
- fannar/transforms.py +132 -0
- fannar-0.3.1.dist-info/METADATA +252 -0
- fannar-0.3.1.dist-info/RECORD +18 -0
- fannar-0.3.1.dist-info/WHEEL +5 -0
- fannar-0.3.1.dist-info/licenses/LICENCE +813 -0
- fannar-0.3.1.dist-info/top_level.txt +1 -0
fannar/__init__.py
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Fannar -- representation spaces of trained models from Gram matrices of several sources.
|
|
2
|
+
|
|
3
|
+
The method (fixed): one positive-definite kernel per source of information about each object,
|
|
4
|
+
admissible transformations, Hadamard composition, and the geometry and spectral energy of the
|
|
5
|
+
resulting PSD Gram matrix. The instantiation (your choice): which objects, which sources, which
|
|
6
|
+
kernels and transformations.
|
|
7
|
+
|
|
8
|
+
Quick start::
|
|
9
|
+
|
|
10
|
+
import fannar as fa
|
|
11
|
+
interp = fa.Interpreter(model, X_test, y_test, layers=["layer1", "layer2"])
|
|
12
|
+
report = interp.evaluate()
|
|
13
|
+
interp.plot_report(report)
|
|
14
|
+
interp.explain_pair(0).top(5)
|
|
15
|
+
|
|
16
|
+
Building blocks::
|
|
17
|
+
|
|
18
|
+
pipe = fa.KernelPipeline({"A": fa.Component("linear"), "B": fa.Component(my_kernel)})
|
|
19
|
+
space = pipe(sources={"A": feats_a, "B": feats_b}) # or pipe(grams={"A": K_a, "B": K_b})
|
|
20
|
+
space.distances, space.neighbors(0, 5), space.energies(), space.embedding()
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from . import kernels, readings, transforms
|
|
24
|
+
from .interpreter import Interpreter
|
|
25
|
+
from .kernels import RBF, Cosine, FunctionKernel, Kernel, Linear, Polynomial
|
|
26
|
+
from .pairs import ErrorExplanation, PairExplanation
|
|
27
|
+
from .pipeline import (PRESETS, Component, KernelPipeline, paper_pipeline, positions_pipeline,
|
|
28
|
+
single_source)
|
|
29
|
+
from .readings import evaluate
|
|
30
|
+
from .report import Report
|
|
31
|
+
from .sources import FunctionSources, Sources, TorchSources, TreeSources
|
|
32
|
+
from .space import GramSpace
|
|
33
|
+
from .transforms import (Transform, angular, center, frobenius_normalize, identity, max_eig_normalize,
|
|
34
|
+
psd_project, shift, spectral, trace_normalize, whiten)
|
|
35
|
+
|
|
36
|
+
# A versão vem do pyproject.toml (metadados do pacote instalado): um só lugar para mudar.
|
|
37
|
+
try:
|
|
38
|
+
from importlib.metadata import PackageNotFoundError as _NotFound, version as _version
|
|
39
|
+
__version__ = _version("fannar")
|
|
40
|
+
except _NotFound: # rodando do código-fonte sem instalar
|
|
41
|
+
__version__ = "0.3.1"
|
|
42
|
+
|
|
43
|
+
__all__ = [
|
|
44
|
+
"Interpreter", "GramSpace", "KernelPipeline", "Component", "Report", "PairExplanation", "ErrorExplanation",
|
|
45
|
+
"Sources", "TorchSources", "TreeSources", "FunctionSources",
|
|
46
|
+
"Kernel", "Linear", "Cosine", "RBF", "Polynomial", "FunctionKernel",
|
|
47
|
+
"Transform", "identity", "center", "trace_normalize", "frobenius_normalize", "max_eig_normalize",
|
|
48
|
+
"angular", "shift", "whiten", "spectral", "psd_project",
|
|
49
|
+
"paper_pipeline", "single_source", "positions_pipeline", "PRESETS", "evaluate",
|
|
50
|
+
"kernels", "transforms", "readings", "__version__",
|
|
51
|
+
]
|
fannar/interpreter.py
ADDED
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
"""High-level interface: a trained model, the objects to interpret, and everything else.
|
|
2
|
+
|
|
3
|
+
>>> import fannar as fa
|
|
4
|
+
>>> interp = fa.Interpreter(model, X_test, y_test, layers=["stem", "b1", "b2"],
|
|
5
|
+
... reference_model=untrained_copy) # floor (optional)
|
|
6
|
+
>>> report = interp.evaluate() # readings per layer
|
|
7
|
+
>>> report.to_frame(); report.to_markdown(); interp.plot_report(report)
|
|
8
|
+
>>> interp.plot_embedding(); interp.plot_gram("b2"); interp.plot_spectrum("b2")
|
|
9
|
+
>>> expl = interp.explain_pair(0) # nearest object with another prediction
|
|
10
|
+
>>> expl.top(5); expl.plot()
|
|
11
|
+
>>> errs = interp.explain_errors() # features that keep the errors away from their class
|
|
12
|
+
>>> errs.top(5); errs.plot()
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from typing import Callable, Sequence
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
|
|
21
|
+
from .pairs import (ErrorExplanation, PairExplanation, curve_area, nearest_correct, nearest_unlike,
|
|
22
|
+
pair_scores, swap_curve)
|
|
23
|
+
from .pipeline import KernelPipeline, get_pipeline, positions_pipeline
|
|
24
|
+
from .readings import evaluate as evaluate_space
|
|
25
|
+
from .report import Report
|
|
26
|
+
from .sources import FunctionSources, Sources, TreeSources
|
|
27
|
+
from .space import GramSpace
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _is_torch(model) -> bool:
|
|
31
|
+
try:
|
|
32
|
+
import torch.nn as nn
|
|
33
|
+
except ImportError: # pragma: no cover
|
|
34
|
+
return False
|
|
35
|
+
return isinstance(model, nn.Module)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _is_sklearn_tree(model) -> bool:
|
|
39
|
+
return hasattr(model, "tree_") and hasattr(model, "decision_path")
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class Interpreter:
|
|
43
|
+
"""Builds the representation space of a trained model over chosen objects, per layer.
|
|
44
|
+
|
|
45
|
+
Parameters
|
|
46
|
+
----------
|
|
47
|
+
model:
|
|
48
|
+
A trained PyTorch classifier, a fitted scikit-learn decision tree, or anything else when
|
|
49
|
+
``extractor`` is given.
|
|
50
|
+
X:
|
|
51
|
+
The objects to interpret (array, tensor or, for PyTorch, a DataLoader).
|
|
52
|
+
y:
|
|
53
|
+
True labels of ``X`` (needed for the correctness, confusion and containment readings).
|
|
54
|
+
layers:
|
|
55
|
+
Layers to probe (PyTorch module names); ignored for trees and custom extractors.
|
|
56
|
+
pipeline:
|
|
57
|
+
A :class:`KernelPipeline`, or a preset name (``"paper"`` by default). For your own Gram
|
|
58
|
+
construction, pass a pipeline whose components use your kernels, or call
|
|
59
|
+
:meth:`space_from_grams`.
|
|
60
|
+
reference_model:
|
|
61
|
+
Optional model of the same architecture used as the *floor* (typically the same network
|
|
62
|
+
with its initial weights). Its geometry is measured against the trained model's behaviour.
|
|
63
|
+
baselines:
|
|
64
|
+
Other pipelines or preset names evaluated alongside (default: activations alone).
|
|
65
|
+
extractor:
|
|
66
|
+
``callable(X) -> Sources`` (or :class:`FunctionSources`) for models that are neither
|
|
67
|
+
PyTorch nor sklearn trees.
|
|
68
|
+
**source_options:
|
|
69
|
+
Passed to :class:`~fannar.sources.TorchSources` (``target``, ``fixed_class``, ``grid``,
|
|
70
|
+
``weight_modules``, ``device``, ``batch_size``...).
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
def __init__(self, model, X, y=None, *, layers: Sequence[str] | None = None,
|
|
74
|
+
pipeline: KernelPipeline | str = "paper", reference_model=None,
|
|
75
|
+
baselines: Sequence[KernelPipeline | str] | dict = ("activations",),
|
|
76
|
+
extractor: Callable | None = None, feature_names: Sequence[str] | None = None,
|
|
77
|
+
class_names: Sequence[str] | None = None, k: int = 5, **source_options) -> None:
|
|
78
|
+
self.model, self.X, self.k = model, X, k
|
|
79
|
+
self.y = None if y is None else np.asarray(y)
|
|
80
|
+
self.feature_names = list(feature_names) if feature_names is not None else None
|
|
81
|
+
self.class_names = list(class_names) if class_names is not None else None
|
|
82
|
+
self.extractor = self._make_extractor(model, extractor, layers, source_options)
|
|
83
|
+
self.reference_extractor = (None if reference_model is None
|
|
84
|
+
else self._make_extractor(reference_model, None, layers, source_options))
|
|
85
|
+
self.pipeline = get_pipeline(pipeline)
|
|
86
|
+
if _is_sklearn_tree(model) and pipeline == "paper":
|
|
87
|
+
self.pipeline = KernelPipeline(["path", "slack", "classes"])
|
|
88
|
+
if tuple(baselines) == ("activations",):
|
|
89
|
+
baselines = {"path": KernelPipeline(["path"])}
|
|
90
|
+
if isinstance(baselines, dict):
|
|
91
|
+
self.baselines = {k: get_pipeline(v) for k, v in baselines.items()}
|
|
92
|
+
else:
|
|
93
|
+
self.baselines = {(b if isinstance(b, str) else f"baseline{t}"): get_pipeline(b)
|
|
94
|
+
for t, b in enumerate(baselines)}
|
|
95
|
+
self.sources: Sources | None = None
|
|
96
|
+
self.reference_sources: Sources | None = None
|
|
97
|
+
self.spaces: dict[str, GramSpace] = {}
|
|
98
|
+
|
|
99
|
+
# ------------------------------------------------------------------ construction
|
|
100
|
+
@staticmethod
|
|
101
|
+
def _make_extractor(model, extractor, layers, options):
|
|
102
|
+
if extractor is not None:
|
|
103
|
+
known = (FunctionSources, TreeSources)
|
|
104
|
+
try:
|
|
105
|
+
from .sources.torch import TorchSources
|
|
106
|
+
known = known + (TorchSources,)
|
|
107
|
+
except ImportError: # pragma: no cover
|
|
108
|
+
pass
|
|
109
|
+
return extractor if isinstance(extractor, known) else FunctionSources(extractor)
|
|
110
|
+
if _is_torch(model):
|
|
111
|
+
from .sources.torch import TorchSources
|
|
112
|
+
return TorchSources(model, layers, **options)
|
|
113
|
+
if _is_sklearn_tree(model):
|
|
114
|
+
return TreeSources(model, **{k: v for k, v in options.items() if k in ("scale", "depths")})
|
|
115
|
+
raise TypeError("model is neither a torch.nn.Module nor a sklearn tree; pass `extractor=`")
|
|
116
|
+
|
|
117
|
+
def fit(self) -> "Interpreter":
|
|
118
|
+
"""Extracts the sources and builds the representation space of every layer."""
|
|
119
|
+
self.sources = self.extractor(self.X)
|
|
120
|
+
if self.reference_extractor is not None:
|
|
121
|
+
self.reference_sources = self.reference_extractor(self.X)
|
|
122
|
+
self.spaces = {layer: self._build(self.pipeline, self.sources, layer, "joint") for layer in self.layers}
|
|
123
|
+
return self
|
|
124
|
+
|
|
125
|
+
def _ensure(self) -> None:
|
|
126
|
+
if self.sources is None:
|
|
127
|
+
self.fit()
|
|
128
|
+
|
|
129
|
+
def _build(self, pipeline: KernelPipeline, sources: Sources, layer: str, name: str) -> GramSpace:
|
|
130
|
+
available = sources.layers[layer]
|
|
131
|
+
missing = [c for c in pipeline.names if c not in available]
|
|
132
|
+
if missing:
|
|
133
|
+
raise KeyError(f"layer {layer!r} has no source(s) {missing}; available: {list(available)}")
|
|
134
|
+
return pipeline(sources=available, labels=self.y, predictions=self.sources.predictions if self.sources else None,
|
|
135
|
+
name=f"{name} · {layer}")
|
|
136
|
+
|
|
137
|
+
@property
|
|
138
|
+
def layers(self) -> list[str]:
|
|
139
|
+
if self.sources is None:
|
|
140
|
+
self.fit()
|
|
141
|
+
return self.sources.layer_names
|
|
142
|
+
|
|
143
|
+
@property
|
|
144
|
+
def predictions(self) -> np.ndarray:
|
|
145
|
+
self._ensure()
|
|
146
|
+
return self.sources.predictions
|
|
147
|
+
|
|
148
|
+
def space(self, layer: str) -> GramSpace:
|
|
149
|
+
"""The :class:`GramSpace` of one layer."""
|
|
150
|
+
self._ensure()
|
|
151
|
+
return self.spaces[layer]
|
|
152
|
+
|
|
153
|
+
def baseline_space(self, name: str, layer: str) -> GramSpace:
|
|
154
|
+
self._ensure()
|
|
155
|
+
return self._build(self.baselines[name], self.sources, layer, name)
|
|
156
|
+
|
|
157
|
+
def floor_space(self, layer: str) -> GramSpace:
|
|
158
|
+
"""The same pipeline on the reference (e.g. untrained) model."""
|
|
159
|
+
self._ensure()
|
|
160
|
+
if self.reference_sources is None:
|
|
161
|
+
raise ValueError("no reference_model was given")
|
|
162
|
+
return self._build(self.pipeline, self.reference_sources, layer, "floor")
|
|
163
|
+
|
|
164
|
+
def space_from_grams(self, grams: dict[str, np.ndarray], pipeline: KernelPipeline | None = None,
|
|
165
|
+
name: str = "custom") -> GramSpace:
|
|
166
|
+
"""A space from Gram matrices you built yourself (``{component: (n, n)}``), composed by
|
|
167
|
+
``pipeline`` (default: the interpreter's). Components not in ``grams`` must be sources."""
|
|
168
|
+
self._ensure()
|
|
169
|
+
pipe = pipeline or KernelPipeline(list(grams))
|
|
170
|
+
return pipe(grams=grams, labels=self.y, predictions=self.predictions, name=name)
|
|
171
|
+
|
|
172
|
+
# ------------------------------------------------------------------ readings
|
|
173
|
+
def evaluate(self, layers: Sequence[str] | None = None, include_baselines: bool = True,
|
|
174
|
+
include_floor: bool = True) -> Report:
|
|
175
|
+
"""Behaviour readings per layer for the joint space, the baselines and the floor.
|
|
176
|
+
|
|
177
|
+
The floor uses the reference model's *geometry* against the trained model's *behaviour*
|
|
178
|
+
(the "cross" floor), so the only difference between a reading and its floor is training.
|
|
179
|
+
"""
|
|
180
|
+
self._ensure()
|
|
181
|
+
if self.y is None:
|
|
182
|
+
raise ValueError("evaluate() needs the true labels `y`")
|
|
183
|
+
layers = list(layers or self.layers)
|
|
184
|
+
preds, probs = self.sources.predictions, self.sources.probabilities
|
|
185
|
+
run = lambda sp: evaluate_space(sp, self.y, preds, probs, self.k) # noqa: E731
|
|
186
|
+
values = {"joint": {layer: run(self.spaces[layer]) for layer in layers}}
|
|
187
|
+
if include_baselines:
|
|
188
|
+
for name in self.baselines:
|
|
189
|
+
ok = [layer for layer in layers if self._has(self.baselines[name], layer)]
|
|
190
|
+
if ok:
|
|
191
|
+
values[name] = {layer: run(self.baseline_space(name, layer)) for layer in ok}
|
|
192
|
+
if include_floor and self.reference_sources is not None:
|
|
193
|
+
values["floor"] = {layer: run(self.floor_space(layer)) for layer in layers}
|
|
194
|
+
accuracy = float((preds == self.y).mean())
|
|
195
|
+
return Report(layers, values, {"accuracy": accuracy, "n": len(self.y), "pipeline": repr(self.pipeline)})
|
|
196
|
+
|
|
197
|
+
# ------------------------------------------------------------------ pairs
|
|
198
|
+
def explain_pair(self, i: int, j: int | None = None, layers: Sequence[str] | None = None) -> PairExplanation:
|
|
199
|
+
"""Which features distinguish object ``i`` from ``j`` for the model (``j`` defaults to the
|
|
200
|
+
nearest object with a different prediction). Vector inputs only."""
|
|
201
|
+
self._ensure()
|
|
202
|
+
X = self._matrix()
|
|
203
|
+
j = nearest_unlike(X, self.predictions, i) if j is None else j
|
|
204
|
+
scores = pair_scores(self.extractor, self.pipeline, X[i], X[j], layers)
|
|
205
|
+
return PairExplanation(i, j, X[i], X[j], scores, int(self.predictions[i]), int(self.predictions[j]),
|
|
206
|
+
self.feature_names)
|
|
207
|
+
|
|
208
|
+
def explain_errors(self, layers: Sequence[str] | None = None, against: str = "correct",
|
|
209
|
+
max_errors: int | None = None, reference: int = 100, seed: int = 0) -> ErrorExplanation:
|
|
210
|
+
"""Which features drive the model's errors, aggregated over the misclassified objects.
|
|
211
|
+
|
|
212
|
+
Each error ``i`` is explained as a pair against a partner ``j``: with ``against="correct"``
|
|
213
|
+
(default) the nearest object correctly predicted as the true class of ``i`` (falling back
|
|
214
|
+
to the nearest unlike object when that class has none), so the shares say which features
|
|
215
|
+
keep ``i`` away from its class in the representation space; with ``against="unlike"``, the
|
|
216
|
+
nearest object with another prediction, as in :meth:`explain_pair`. ``max_errors`` caps the
|
|
217
|
+
number of errors and ``reference`` the number of correctly predicted objects explained the
|
|
218
|
+
same way as a baseline (both sampled with ``seed``; ``reference=0`` skips it).
|
|
219
|
+
Vector inputs only."""
|
|
220
|
+
if self.y is None:
|
|
221
|
+
raise ValueError("explaining errors needs the true labels `y`")
|
|
222
|
+
if against not in ("correct", "unlike"):
|
|
223
|
+
raise ValueError("against must be 'correct' or 'unlike'")
|
|
224
|
+
self._ensure()
|
|
225
|
+
X, pred, rng = self._matrix(), self.predictions, np.random.default_rng(seed)
|
|
226
|
+
errors = np.flatnonzero(pred != self.y)
|
|
227
|
+
if len(errors) == 0:
|
|
228
|
+
raise ValueError("the model makes no errors on these objects")
|
|
229
|
+
if max_errors is not None and len(errors) > max_errors:
|
|
230
|
+
errors = np.sort(rng.choice(errors, size=max_errors, replace=False))
|
|
231
|
+
partners = []
|
|
232
|
+
for i in errors:
|
|
233
|
+
j = nearest_correct(X, self.y, pred, int(i)) if against == "correct" else None
|
|
234
|
+
partners.append(nearest_unlike(X, pred, int(i)) if j is None else j)
|
|
235
|
+
partners = np.array(partners)
|
|
236
|
+
correct = np.flatnonzero(pred == self.y)
|
|
237
|
+
correct = np.sort(rng.choice(correct, size=min(reference, len(correct)), replace=False))
|
|
238
|
+
return ErrorExplanation(errors, partners, self.y[errors], pred[errors],
|
|
239
|
+
self._pair_shares(X, errors, partners, layers), X[errors], X[partners],
|
|
240
|
+
self._pair_shares(X, correct, [nearest_unlike(X, pred, int(i)) for i in correct], layers),
|
|
241
|
+
{int(c): int((self.y == c).sum()) for c in np.unique(self.y)},
|
|
242
|
+
self.feature_names, self.class_names)
|
|
243
|
+
|
|
244
|
+
def _pair_shares(self, X, rows, partners, layers) -> dict[str, np.ndarray]:
|
|
245
|
+
"""Normalised positive ``Delta d`` of every ``(rows[e], partners[e])`` pair, per layer."""
|
|
246
|
+
out = {}
|
|
247
|
+
for i, j in zip(rows, partners):
|
|
248
|
+
for layer, s in pair_scores(self.extractor, self.pipeline, X[i], X[j], layers).items():
|
|
249
|
+
s = np.maximum(s, 0)
|
|
250
|
+
out.setdefault(layer, []).append(s / s.sum() if s.sum() > 0 else s)
|
|
251
|
+
return {layer: np.stack(v) for layer, v in out.items()}
|
|
252
|
+
|
|
253
|
+
def swap_test(self, pairs: int | Sequence[tuple[int, int]] = 50, layer: str | None = None,
|
|
254
|
+
predict: Callable | None = None, seed: int = 0) -> dict:
|
|
255
|
+
"""Swap-test area per ranking (method, |Delta x|, random among differing features),
|
|
256
|
+
averaged over pairs. ``pairs`` is a number of random correctly-predicted objects (each with
|
|
257
|
+
its nearest unlike neighbour) or explicit ``(i, j)`` pairs."""
|
|
258
|
+
self._ensure()
|
|
259
|
+
X = self._matrix()
|
|
260
|
+
predict = predict or self._predict_fn()
|
|
261
|
+
rng = np.random.default_rng(seed)
|
|
262
|
+
if isinstance(pairs, int):
|
|
263
|
+
pool = np.flatnonzero(self.predictions == self.y) if self.y is not None else np.arange(len(X))
|
|
264
|
+
chosen = rng.choice(pool, size=min(pairs, len(pool)), replace=False)
|
|
265
|
+
pairs = [(int(i), nearest_unlike(X, self.predictions, int(i))) for i in chosen]
|
|
266
|
+
layer = layer or self.layers[-1]
|
|
267
|
+
areas = {"method": [], "absdiff": [], "random": []}
|
|
268
|
+
for i, j in pairs:
|
|
269
|
+
s = pair_scores(self.extractor, self.pipeline, X[i], X[j], [layer])[layer]
|
|
270
|
+
differ = np.flatnonzero(np.abs(X[j] - X[i]) > 1e-12)
|
|
271
|
+
rest = np.setdiff1d(np.arange(X.shape[1]), differ)
|
|
272
|
+
orders = {"method": np.argsort(-s, kind="stable"), "absdiff": np.argsort(-np.abs(X[j] - X[i]), kind="stable"),
|
|
273
|
+
"random": np.concatenate([rng.permutation(differ), rest])}
|
|
274
|
+
for key, order in orders.items():
|
|
275
|
+
areas[key].append(curve_area(swap_curve(predict, X[i], X[j], int(self.predictions[j]), order)))
|
|
276
|
+
return {k: float(np.mean(v)) for k, v in areas.items()} | {"pairs": len(pairs), "layer": layer}
|
|
277
|
+
|
|
278
|
+
# ------------------------------------------------------------------ positions of one input
|
|
279
|
+
def energy_map(self, x, layer: str, max_side: int = 32) -> np.ndarray:
|
|
280
|
+
"""Retained spectral energy of every position of one input (e.g. an image), as a map.
|
|
281
|
+
|
|
282
|
+
Positions are the objects; components use linear kernels without the angular transform
|
|
283
|
+
(which would give every position the same energy)."""
|
|
284
|
+
from .sources.torch import TorchSources
|
|
285
|
+
if not isinstance(self.extractor, TorchSources):
|
|
286
|
+
raise TypeError("energy maps need a PyTorch model")
|
|
287
|
+
src = self.extractor.positions(x, layer, max_side)
|
|
288
|
+
names = [s for s in ("parameters", "activations", "gradients") if s in src]
|
|
289
|
+
space = positions_pipeline(names)(sources=src)
|
|
290
|
+
shape = self.extractor.position_shape(x, layer, max_side)
|
|
291
|
+
return space.energies()["E_par"].reshape(shape)
|
|
292
|
+
|
|
293
|
+
# ------------------------------------------------------------------ plots
|
|
294
|
+
def plot_report(self, report: Report | None = None, readings=None):
|
|
295
|
+
from .plots import plot_report
|
|
296
|
+
return plot_report(report or self.evaluate(), readings)
|
|
297
|
+
|
|
298
|
+
def plot_embedding(self, layers: Sequence[str] | None = None, color_by: str = "prediction",
|
|
299
|
+
include_floor: bool = True, include_baselines: bool = True):
|
|
300
|
+
from .plots import plot_embedding
|
|
301
|
+
self._ensure()
|
|
302
|
+
layers = list(layers or self.layers)
|
|
303
|
+
rows = {"joint": [self.spaces[layer] for layer in layers]}
|
|
304
|
+
if include_baselines:
|
|
305
|
+
for name in self.baselines:
|
|
306
|
+
if all(self._has(self.baselines[name], layer) for layer in layers):
|
|
307
|
+
rows[name] = [self.baseline_space(name, layer) for layer in layers]
|
|
308
|
+
if include_floor and self.reference_sources is not None:
|
|
309
|
+
rows["floor"] = [self.floor_space(layer) for layer in layers]
|
|
310
|
+
colors = self.predictions if color_by == "prediction" else self.y
|
|
311
|
+
return plot_embedding(rows, layers, colors, self.y, self.predictions, self.class_names)
|
|
312
|
+
|
|
313
|
+
def plot_errors(self, k: int | None = None, layer: str | None = None, rows: str = "class", **kw):
|
|
314
|
+
return self.explain_errors(**kw).plot(k, layer, rows)
|
|
315
|
+
|
|
316
|
+
def plot_gram(self, layer: str):
|
|
317
|
+
from .plots import plot_gram
|
|
318
|
+
return plot_gram(self.space(layer), self.y if self.y is not None else self.predictions)
|
|
319
|
+
|
|
320
|
+
def plot_spectrum(self, layer: str):
|
|
321
|
+
from .plots import plot_spectrum
|
|
322
|
+
return plot_spectrum(self.space(layer))
|
|
323
|
+
|
|
324
|
+
def plot_energy_map(self, x, layer: str, max_side: int = 32, image=None):
|
|
325
|
+
from .plots import plot_energy_map
|
|
326
|
+
return plot_energy_map(self.energy_map(x, layer, max_side), image)
|
|
327
|
+
|
|
328
|
+
# ------------------------------------------------------------------ helpers
|
|
329
|
+
def _has(self, pipeline: KernelPipeline, layer: str) -> bool:
|
|
330
|
+
return all(c in self.sources.layers[layer] for c in pipeline.names)
|
|
331
|
+
|
|
332
|
+
def _matrix(self) -> np.ndarray:
|
|
333
|
+
X = self.X
|
|
334
|
+
if hasattr(X, "detach"):
|
|
335
|
+
X = X.detach().cpu().numpy()
|
|
336
|
+
X = np.asarray(X, dtype=np.float64)
|
|
337
|
+
if X.ndim != 2:
|
|
338
|
+
raise ValueError("pair explanations need vector inputs (n, F)")
|
|
339
|
+
return X
|
|
340
|
+
|
|
341
|
+
def _predict_fn(self) -> Callable:
|
|
342
|
+
if _is_sklearn_tree(self.model):
|
|
343
|
+
return self.model.predict
|
|
344
|
+
if _is_torch(self.model):
|
|
345
|
+
import torch
|
|
346
|
+
model = self.model
|
|
347
|
+
device = next(model.parameters()).device
|
|
348
|
+
|
|
349
|
+
def predict(rows):
|
|
350
|
+
model.eval()
|
|
351
|
+
with torch.no_grad():
|
|
352
|
+
return model(torch.as_tensor(rows, device=device)).argmax(1).cpu().numpy()
|
|
353
|
+
return predict
|
|
354
|
+
raise TypeError("pass `predict=` for this model")
|
fannar/kernels.py
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""Positive-definite kernels that turn one source of information into a raw Gram matrix.
|
|
2
|
+
|
|
3
|
+
Every kernel maps a set of objects ``X`` (any array-like whose first axis indexes the
|
|
4
|
+
objects; the remaining axes are flattened) to the raw Gram matrix
|
|
5
|
+
``K[i, j] = kappa(x_i, x_j)``. The method only requires each kernel to be positive
|
|
6
|
+
definite; which kernel to use is part of the *instantiation*, not of the method.
|
|
7
|
+
|
|
8
|
+
A word on composition. The joint Gram is the Hadamard product of the component Grams.
|
|
9
|
+
With linear-type kernels this realises the tensor product of the feature spaces, so the
|
|
10
|
+
joint similarity keeps the *multiplicative interaction* between sources. With Gaussian
|
|
11
|
+
kernels it does not: the product of two Gaussians is the Gaussian of the summed
|
|
12
|
+
exponents, and the composition collapses into an additive combination of the source
|
|
13
|
+
metrics. :class:`RBF` is available, but ``Linear``/``Cosine`` are the default for this
|
|
14
|
+
reason.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from abc import ABC, abstractmethod
|
|
20
|
+
from typing import Callable
|
|
21
|
+
|
|
22
|
+
import numpy as np
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def as_matrix(x) -> np.ndarray:
|
|
26
|
+
"""Objects as rows: ``(n, ...)`` array-like (NumPy, PyTorch, lists) -> ``(n, D)`` float64."""
|
|
27
|
+
if hasattr(x, "detach"): # torch.Tensor without importing torch
|
|
28
|
+
x = x.detach().cpu().numpy()
|
|
29
|
+
x = np.asarray(x, dtype=np.float64)
|
|
30
|
+
if x.ndim == 1:
|
|
31
|
+
x = x[:, None]
|
|
32
|
+
return x.reshape(len(x), -1)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class Kernel(ABC):
|
|
36
|
+
"""Base class. Subclasses implement :meth:`compute` on ``(n, D)`` and ``(m, D)`` arrays."""
|
|
37
|
+
|
|
38
|
+
name = "kernel"
|
|
39
|
+
|
|
40
|
+
def __call__(self, X, Y=None) -> np.ndarray:
|
|
41
|
+
X = as_matrix(X)
|
|
42
|
+
Y = X if Y is None else as_matrix(Y)
|
|
43
|
+
return self.compute(X, Y)
|
|
44
|
+
|
|
45
|
+
@abstractmethod
|
|
46
|
+
def compute(self, X: np.ndarray, Y: np.ndarray) -> np.ndarray:
|
|
47
|
+
"""Raw Gram block ``K[i, j] = kappa(X[i], Y[j])``."""
|
|
48
|
+
|
|
49
|
+
def __repr__(self) -> str:
|
|
50
|
+
params = ", ".join(f"{k}={v!r}" for k, v in vars(self).items() if not k.startswith("_"))
|
|
51
|
+
return f"{type(self).__name__}({params})"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class Linear(Kernel):
|
|
55
|
+
"""``kappa(x, y) = <x, y>``. Combined with the angular transform it becomes the cosine."""
|
|
56
|
+
|
|
57
|
+
name = "linear"
|
|
58
|
+
|
|
59
|
+
def compute(self, X, Y):
|
|
60
|
+
return X @ Y.T
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class Cosine(Kernel):
|
|
64
|
+
"""``kappa(x, y) = <x, y> / (|x| |y|)``; zero vectors get similarity 0 (1 with themselves)."""
|
|
65
|
+
|
|
66
|
+
name = "cosine"
|
|
67
|
+
|
|
68
|
+
def __init__(self, eps: float = 1e-12) -> None:
|
|
69
|
+
self.eps = eps
|
|
70
|
+
|
|
71
|
+
def compute(self, X, Y):
|
|
72
|
+
nx = np.linalg.norm(X, axis=1)
|
|
73
|
+
ny = np.linalg.norm(Y, axis=1)
|
|
74
|
+
k = (X @ Y.T) / np.maximum(np.outer(nx, ny), self.eps)
|
|
75
|
+
if X is Y:
|
|
76
|
+
np.fill_diagonal(k, 1.0)
|
|
77
|
+
return k
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class RBF(Kernel):
|
|
81
|
+
"""Gaussian kernel ``exp(-gamma |x - y|^2)``. ``gamma=None`` uses the median heuristic.
|
|
82
|
+
|
|
83
|
+
See the module docstring: under Hadamard composition, Gaussian components add their
|
|
84
|
+
metrics instead of multiplying the similarities.
|
|
85
|
+
"""
|
|
86
|
+
|
|
87
|
+
name = "rbf"
|
|
88
|
+
|
|
89
|
+
def __init__(self, gamma: float | None = None) -> None:
|
|
90
|
+
self.gamma = gamma
|
|
91
|
+
|
|
92
|
+
def compute(self, X, Y):
|
|
93
|
+
sx = (X**2).sum(1)[:, None]
|
|
94
|
+
sy = (Y**2).sum(1)[None, :]
|
|
95
|
+
d2 = np.maximum(sx + sy - 2 * X @ Y.T, 0.0)
|
|
96
|
+
gamma = self.gamma
|
|
97
|
+
if gamma is None:
|
|
98
|
+
med = np.median(d2[d2 > 0]) if np.any(d2 > 0) else 1.0
|
|
99
|
+
gamma = 1.0 / med
|
|
100
|
+
return np.exp(-gamma * d2)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
class Polynomial(Kernel):
|
|
104
|
+
"""``kappa(x, y) = (gamma <x, y> + coef0) ** degree`` with ``coef0 >= 0``."""
|
|
105
|
+
|
|
106
|
+
name = "polynomial"
|
|
107
|
+
|
|
108
|
+
def __init__(self, degree: int = 2, coef0: float = 1.0, gamma: float | None = None) -> None:
|
|
109
|
+
if coef0 < 0:
|
|
110
|
+
raise ValueError("coef0 must be >= 0 for the kernel to be positive definite")
|
|
111
|
+
self.degree, self.coef0, self.gamma = degree, coef0, gamma
|
|
112
|
+
|
|
113
|
+
def compute(self, X, Y):
|
|
114
|
+
gamma = self.gamma if self.gamma is not None else 1.0 / X.shape[1]
|
|
115
|
+
return (gamma * (X @ Y.T) + self.coef0) ** self.degree
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class FunctionKernel(Kernel):
|
|
119
|
+
"""Wraps a user function ``fn(X, Y) -> (n, m) array``. Positive definiteness is the user's."""
|
|
120
|
+
|
|
121
|
+
name = "function"
|
|
122
|
+
|
|
123
|
+
def __init__(self, fn: Callable[[np.ndarray, np.ndarray], np.ndarray], name: str | None = None) -> None:
|
|
124
|
+
self.fn = fn
|
|
125
|
+
if name:
|
|
126
|
+
self.name = name
|
|
127
|
+
|
|
128
|
+
def compute(self, X, Y):
|
|
129
|
+
return np.asarray(self.fn(X, Y), dtype=np.float64)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
_BY_NAME = {"linear": Linear, "cosine": Cosine, "rbf": RBF, "polynomial": Polynomial}
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def as_kernel(obj) -> Kernel:
|
|
136
|
+
"""Accepts a :class:`Kernel`, a name (``"linear"``, ``"cosine"``, ``"rbf"``, ``"polynomial"``)
|
|
137
|
+
or a callable ``fn(X, Y)``."""
|
|
138
|
+
if isinstance(obj, Kernel):
|
|
139
|
+
return obj
|
|
140
|
+
if isinstance(obj, str):
|
|
141
|
+
try:
|
|
142
|
+
return _BY_NAME[obj.lower()]()
|
|
143
|
+
except KeyError as exc:
|
|
144
|
+
raise ValueError(f"unknown kernel {obj!r}; choose from {sorted(_BY_NAME)}") from exc
|
|
145
|
+
if callable(obj):
|
|
146
|
+
return FunctionKernel(obj)
|
|
147
|
+
raise TypeError(f"cannot interpret {obj!r} as a kernel")
|