Module chain_effect 

Chain-effect analysis contract + per-dataset score normalization.

Turns a corpus of executed linear pipelines (“chains”, e.g. SNV → SavGol → PLS), each with a comparable scalar score, into a stable, serializable ChainEffectAnalysis artifact: every chain projected to a comparable “goodness” (higher is always better) under a normalization ChainEffectLens. The authoritative piece that must live natively here is the per-dataset score normalization (rank / z); downstream consumers such as nirs4all-ui/chains derive the per-node / position / order aggregates descriptively from the emitted points.

Boundary: this operates only on stable identifiers, ordered step tokens/roles and scalar scores — never on feature matrices, tensors or fitted operators, consistent with the dag-ml ownership boundary.

Construction is fail-closed: ChainEffectAnalysis::from_observations rejects empty input, non-finite scores, duplicate ids, mixed evaluation scopes, and (for the rank/z lenses) any observation missing a dataset identity. Repeated ordered tokens are preserved verbatim — position and order are meaningful to downstream consumers.

Deferred (a follow-up slice): building ChainObservations from a crate::plan::GraphPlan + crate::metrics::ScoreSet. ScoreSet carries no dataset/source identity (only plan_id); the dataset key must come from the representation mapping (crate::data::RepresentationSampleObservationMapping) and the per-variant node walk needs its own design, so this slice takes host-supplied observations.

Structs

ChainEffectAnalysis

The serialized chain-effect analysis artifact.

ChainEffectMetric

The metric the scores are expressed in, plus its optimization direction.

ChainEffectPoint

One chain projected to a comparable goodness (higher = better).

ChainEffectStep

One node occurrence inside a chain.

ChainObservation

Host-supplied observation: one executed chain with a comparable score.

Enums

ChainEffectLens

Normalization lens that makes heterogeneous datasets comparable.

ChainStepRole

Coarse role of a chain step; drives color/legend and position/order scoping in downstream consumers.

Constants

CHAIN_EFFECT_SCHEMA_ID

Stable $id of the serialized chain-effect analysis schema.

CHAIN_EFFECT_SCHEMA_VERSION

Current schema version of ChainEffectAnalysis.

Functions

chain_role_for_node_kind

Map a graph NodeKind to its coarse ChainStepRole.

median

Median of the finite values (linear interpolation at the midpoint).

orient

Orient a score so higher is always better.

percentile_ranks

Percentile rank of each value in [0, 1] (1 = largest); average ties.

z_scores

Sample z-scores (mean 0, unit sd, n - 1 divisor); zero variance → all 0.