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 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")