nirs4all.pipeline.explain_lineage module

Derive explainability lineage from relation materialization/replay manifests.

Heterogeneous multi-source repetition runs materialise an aligned feature matrix from per-source observations (see nirs4all.data.raw_multisource). When SHAP explanations are computed on such a matrix, the explained columns are derived features (per-source aggregates, cartesian combos, stacked repetitions) rather than a single raw wavelength axis. This module turns a materialization or replay manifest into the provenance metadata carried by nirs4all.api.result.ExplainResult so that the scientific meaning stays visible: an aggregated MIR feature is never presented as if it were one raw observation wavelength.

The single entry point is derive_relation_explain_lineage().

class nirs4all.pipeline.explain_lineage.RelationExplainLineage(explanation_level: str | None = None, feature_lineage: dict[str, dict[str, ~typing.Any]]=<factory>, lineage_warning: str | None = None, feature_names: list[str] | None = None)

Bases: object

Explainability provenance derived from a relation manifest.

Variables:

• explanation_level (str | None) – Human-readable feature level (e.g. source_aggregate, raw_observation, combo, stack) or None when unknown.

• feature_lineage (dict[str, dict[str, Any]]) – Mapping from explained feature name to its provenance payload (representation, source id, fingerprint, lineage stages…).

• lineage_warning (str | None) – Warning emitted when explained features are derived or aggregated rather than raw observation wavelengths, else None.

• feature_names (list[str] | None) – Feature names resolved from the manifest headers when the caller did not supply names, else None.

explanation_level: str | None = None

feature_lineage: dict[str, dict[str, Any]]

feature_names: list[str] | None = None

lineage_warning: str | None = None