xai4tsc.evaluation.quantus_groups

What each Quantus metric consumes, and the explanation domains that follow from it.

Quantus metrics do not all need the same inputs. A metric that reads only the attribution measures a property of the attribution itself and is therefore domain-agnostic; one that perturbs the input and re-queries the model needs the explanation in the model-native domain, the domain the model’s inputs live in (Explanation.data_domain), because that is the space it can perturb and predict in. For a model trained on raw series that is the time domain; for one trained on spectra it is the frequency domain, and these metrics apply there instead. Quantus itself draws no such distinction - every metric inherits one __call__ that asserts the attribution and the input correspond - so it is recorded here.

The four groups are disjoint and cover every key of QUANTUS_METRICS:

group	its own code reads	n	explanation domain
ATTRIBUTION_ONLY	a_batch	3	any
MODEL_PERTURBATION	x_batch + model	16	model-native
LOCALISATION	x_batch + s_batch	6	model-native (see below)
RE_EXPLAIN	+ explain_func	12	model-native

Derived by walking each metric’s own evaluate_batch / evaluate_instance / custom_*_preprocess bodies with ast, excluding the inherited Metric.__call__ that every subclass re-declares with the full parameter list. sandbox/fixtures/group_metrics.py re-derives the table from the installed quantus so it can be re-checked after a dependency bump.

LOCALISATION is model-native for the time being because it is blocked on s_batch (ground-truth masks), which nothing supplies yet - not because of the domain. Once masks are derived, those six become domain-agnostic too: TimeFrequencyAUCEvaluator already builds ground-truth masks on the coefficient grid.

Attributes

QUANTUS_GROUPS	Group of every metric in QUANTUS_METRICS, keyed by the same display name.
BLOCKED_BY_BACKEND	Metrics whose Quantus implementation cannot serve a time series correctly.

Classes

QuantusGroup

Which inputs a Quantus metric's own code reads; see the module docstring.

Functions

quantus_requires_native_domain(→ bool)	Return whether the named Quantus metric needs the model-native domain.
quantus_requires_explain_func(→ bool)	Return whether the named Quantus metric re-explains and so needs an explain func.
quantus_requires_s_batch(→ bool)	Return whether the named Quantus metric scores against ground-truth masks.

Module Contents

class xai4tsc.evaluation.quantus_groups.QuantusGroup(*args, **kwds)

Bases: enum.Enum

Which inputs a Quantus metric’s own code reads; see the module docstring.

ATTRIBUTION_ONLY = 'attribution-only'

Reads the attribution alone, so it applies in any explanation domain.

MODEL_PERTURBATION = 'model-perturbation'

Perturbs the input and re-queries the model.

LOCALISATION = 'localisation'

Scores the attribution against a ground-truth mask (s_batch).

RE_EXPLAIN = 're-explain'

Re-explains perturbed or randomised inputs via explain_func.

xai4tsc.evaluation.quantus_groups.QUANTUS_GROUPS: dict[str, QuantusGroup]

Group of every metric in QUANTUS_METRICS, keyed by the same display name.

xai4tsc.evaluation.quantus_groups.quantus_requires_native_domain(name: str) → bool

Return whether the named Quantus metric needs the model-native domain.

Parameters:

name (str) – A key of QUANTUS_METRICS (the metric’s display name).

Returns:

True if the explanation must be in the same domain as the model’s inputs, False if the metric applies in any domain. An unclassified name is treated as needing the native domain, the conservative choice.

Return type:

bool

xai4tsc.evaluation.quantus_groups.quantus_requires_explain_func(name: str) → bool

Return whether the named Quantus metric re-explains and so needs an explain func.

Parameters:

name (str) – A key of QUANTUS_METRICS (the metric’s display name).

Returns:

True for the RE_EXPLAIN group only. An unclassified name is treated as not requiring one: supplying the callable to a metric that ignores it is harmless, whereas demanding one that is never used would refuse a metric that works.

Return type:

bool

xai4tsc.evaluation.quantus_groups.quantus_requires_s_batch(name: str) → bool

Return whether the named Quantus metric scores against ground-truth masks.

Parameters:

name (str) – A key of QUANTUS_METRICS (the metric’s display name).

Returns:

True for the LOCALISATION group only. These metrics compare the attribution against the region a dataset declares as discriminative, so they are unusable without one — unlike the other groups, which need nothing but the model and the attribution.

Return type:

bool

xai4tsc.evaluation.quantus_groups.BLOCKED_BY_BACKEND: dict[str, str]

Metrics whose Quantus implementation cannot serve a time series correctly.

Four of them index a second spatial axis that a (B, C, T) series does not have - super-pixels, quadrants, 2-D padding, pixel neighbourhoods - and raise somewhere inside the library. Refusing them here turns an obscure IndexError or shape assertion into a stated reason, and keeps them out of the error column where they look like something worth fixing.

Smooth MPRT is the dangerous one and the reason this table is not just about shapes: it returns a number. It calls the library’s own explain function instead of the one it is given, so without this entry it would report a plausible score for an explainer it never ran.