Explanations¶
Why was this object classified differently from that one? (contrastive, per feature)
For a pair (i, j) and each feature f, x_i^(f) is x_i with feature f replaced by
its value in x_j, and
Delta d_f = d(i, j) - d(i^(f), j)
in the representation space of each layer (positive: the swap brings i closer to j).
Only the F + 2 rows x_j, x_i, x_i^(1..F) go through the model, so the cost is linear in
the number of features. The ranking is validated outside the geometry by the swap test: copy
the top-k features of j into i and check whether the model's prediction becomes the
prediction of j (the procedure of nearest-instance counterfactuals such as NICE).
Delta d is first order: features that only matter jointly with others get no credit.
ErrorExplanation aggregates the same scores over the model's errors: each misclassified
object is paired with the nearest object the model gets right in its true class, so the shares
say which features keep the errors away from where they belong.
PairExplanation
dataclass
¶
PairExplanation(
i: int | None,
j: int | None,
xi: ndarray,
xj: ndarray,
scores: dict[str, ndarray],
pred_i: int | None = None,
pred_j: int | None = None,
feature_names: list[str] | None = None,
meta: dict = dict(),
)
Per-layer feature scores for one pair.
ranking
¶
shares
¶
Positive part of the scores, normalised to sum 1 (share of the gain in proximity).
top
¶
[(feature, value_i, value_j, share), ...] for the top k features.
Source code in src\fannar\pairs.py
to_frame
¶
Source code in src\fannar\pairs.py
ErrorExplanation
dataclass
¶
ErrorExplanation(
errors: ndarray,
partners: ndarray,
true: ndarray,
pred: ndarray,
shares: dict[str, ndarray],
xi: ndarray,
xj: ndarray,
reference: dict[str, ndarray] = dict(),
support: dict[int, int] = dict(),
feature_names: list[str] | None = None,
class_names: list[str] | None = None,
)
Per-layer feature shares over the model's errors, one row per error.
partners[e] is the object error e was contrasted with (by default, the nearest object
correctly predicted as its true class); shares[layer][e, f] is the share of feature f
in bringing error e closer to it in the representation space. xi and xj hold the
feature values of the errors and of their partners. reference holds the same shares over
correctly predicted objects (each against its nearest unlike object), i.e. how much each
feature matters to the model in general; support counts the objects of each true class.
reference
class-attribute
instance-attribute
¶
pairs
property
¶
(error, partner) pairs, e.g. for Interpreter.swap_test.
mean_shares
¶
Mean share of each feature over the errors (or over the mask of them).
reference_shares
¶
Mean share of each feature over the correctly predicted objects, if computed.
Source code in src\fannar\pairs.py
direction
¶
Share-weighted mean of sign(x_j - x_i) per feature, in [-1, 1]: +1 when the
errors have lower values than their partners (raising the feature moves them towards
their true class), -1 when they have higher values.
Source code in src\fannar\pairs.py
top_fraction
¶
Fraction of the errors in which each feature is the most distinguishing one.
Source code in src\fannar\pairs.py
ranking
¶
top
¶
[(feature, mean share, top fraction), ...] for the top k features.
Source code in src\fannar\pairs.py
confusions
¶
(true, predicted, count) among the errors, most frequent first.
Source code in src\fannar\pairs.py
by_class
¶
by_confusion
¶
Mean shares per (true, predicted) confusion.
to_frame
¶
Source code in src\fannar\pairs.py
Building blocks¶
pair_scores
¶
Delta d_f per layer, from the F + 2 swap rows.
Source code in src\fannar\pairs.py
swap_rows
¶
[x_j, x_i, x_i^(1), ..., x_i^(F)].
Source code in src\fannar\pairs.py
swap_curve
¶
For k = 0..F: 1 if x_i with the first k features of order taken from
x_j is predicted as target. predict(X) -> labels.
Source code in src\fannar\pairs.py
curve_area
¶
Area under a swap curve on [0, 1] (fraction of features swapped).
nearest_unlike
¶
The nearest object (Euclidean, in the given feature space) with another prediction.
Source code in src\fannar\pairs.py
nearest_correct
¶
The nearest object (Euclidean, in the given feature space) correctly predicted as the
true class of i, or None if there is none.