From bda0145f27eb6b67d940f87ee89b372b206989e9 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 00:04:20 -0800 Subject: [PATCH 01/13] Say why a forecast is the forecast it is Ports Kumo-TS's forecast attribution and the report it draws, which this client said it could not have. That was wrong, and wrong for a reason worth writing down: the attribution reads the model's gradients and walks its latent trajectory, so it cannot cross a wire, but the in-process backend has the model right here. The judgement was made against the served path and applied to both. It arrives as the contract's `explanation` output field, asked for like any other and produced only where the model runs in this process. An explanation walks a window per step of the context, so it costs tens of seconds where a forecast costs a fraction of one, and feature-axis attribution costs minutes. That is why it is asked for rather than always computed. `forecast_report` draws it. The explanation travels as plain JSON because that is what an output field is, and every array the pages read is in it, so the drawing reads them back. A page whose data is absent is not drawn, which is what "this was not computed" looks like on paper. The vendored modules sit together under `_kumo_ts/` and are excluded from ruff and mypy, as the generated parser is: an attribution is a statement about what a model did, and rewriting the arithmetic that makes it would make it a statement about something else. They were checked for the lints that are not style first, which found two module-level names this move had dropped; without them the integrated-gradients page raised NameError. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/adapters/forecast.py | 4 + .../src/sdm_client/explain/__init__.py | 22 + .../src/sdm_client/explain/_explain.py | 114 + .../sdm_client/explain/_kumo_ts/__init__.py | 15 + .../explain/_kumo_ts/channel_flow.py | 536 +++++ .../explain/_kumo_ts/channel_stability.py | 381 ++++ .../explain/_kumo_ts/integrated_gradients.py | 343 +++ .../explain/_kumo_ts/interpretability.py | 1725 +++++++++++++++ .../src/sdm_client/explain/_kumo_ts/pages.py | 1893 +++++++++++++++++ .../src/sdm_client/explain/_model.py | 77 + .../src/sdm_client/in_process/forecast.py | 50 +- .../src/sdm_client/models.py | 6 +- .../src/sdm_client/reporting/__init__.py | 3 +- .../src/sdm_client/reporting/forecast.py | 149 ++ .../test_a_forecast_says_what_it_rested_on.py | 147 ++ pyproject.toml | 10 + 16 files changed, 5469 insertions(+), 6 deletions(-) create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/__init__.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_explain.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py create mode 100644 packages/structured-data-models-client/src/sdm_client/explain/_model.py create mode 100644 packages/structured-data-models-client/src/sdm_client/reporting/forecast.py create mode 100644 packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py index 985b7c969..02b7d1189 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -124,12 +124,16 @@ def answered( f'it cannot be put in order', code='INVALID_RESPONSE', ) + explanation = next( + (item.explanation for item in items if item.explanation), None + ) result = PredictionResult( model=model, request_id=request_id, items=items, metadata=dict(metadata or {}), outputs=outputs, + explanation=explanation, ) result._names_its_rows = False result._names_its_step = True diff --git a/packages/structured-data-models-client/src/sdm_client/explain/__init__.py b/packages/structured-data-models-client/src/sdm_client/explain/__init__.py new file mode 100644 index 000000000..6ba12ca26 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/__init__.py @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Why a forecast is the forecast it is. + +Asked for as an output field, like any other, and produced only where the +model runs in this process: the attribution reads the model's gradients and +its latent trajectory, and neither of those crosses a wire. + +It is expensive. The latent trajectory walks a window per step of the +context, so an explanation costs tens of seconds on a CPU where a forecast +costs a fraction of one, and feature-axis attribution costs minutes. That is +why it is asked for rather than always computed. + +Not public API itself. :func:`sdm_client.reporting.forecast_report` draws +what this produces. +""" + +from sdm_client.explain._explain import explanation_of + +__all__ = ['explanation_of'] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py new file mode 100644 index 000000000..64740b69c --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -0,0 +1,114 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Running the attribution over a history, and saying what it found. + +The ported pipeline wants the context as channels by steps and the model +behind a protocol; the client holds a history as a frame and a loaded +structured-data-models forecaster. This is what stands between them, and the +dict it returns is what travels as the ``explanation`` output field. +""" + +from __future__ import annotations + +from typing import Any + +import numpy as np +import pandas as pd + +from sdm_client.errors import StructuredDataError + +#: How far back the lag attribution looks, and how finely. Upstream's +#: defaults; both cost time roughly in proportion. +_LAGS = 128 + + +def explanation_of( + model: Any, + history: np.ndarray, + *, + channels: list[str], + target: str, + horizon: int, + forecast: np.ndarray, + feature_axis: bool = False, +) -> dict[str, Any]: + r"""Attribute ``forecast`` to the history it was made from. + + Args: + model: The loaded ``sdm.models.KumoForecast``. + history: The context as ``[C, R]``, channels by steps, in the order + ``channels`` names them. + channels: What each channel is called. + target: Which of them was forecast. + horizon: How many steps were asked for. + forecast: What came back, one value per step. + feature_axis: Also attribute across channels rather than only across + lags. It costs several times the rest put together. + + Raises: + StructuredDataError: If the history is shorter than the model reads. + """ + + from sdm_client.explain._kumo_ts.interpretability import explain_forecast + from sdm_client.explain._model import Forecaster + + forecaster = Forecaster(model) + if history.shape[-1] < forecaster.context_size: + raise StructuredDataError( + f'an explanation attributes a forecast to the window the model ' + f'reads, which is {forecaster.context_size} steps, and this ' + f'history is {history.shape[-1]}', + code='UNSUPPORTED_SHAPE', + ) + window = history[..., -forecaster.context_size :] + explanation = explain_forecast( + forecaster, + x_context_ct=np.ascontiguousarray(window, dtype='float32'), + input_mask_l=np.ones(forecaster.context_size, dtype='float32'), + model_horizon=forecaster.prediction_size, + forecast_horizon=horizon, + device=next(model.parameters()).device, + n_lags=min(_LAGS, forecaster.context_size), + surrogate=False, + channel_axis=feature_axis, + channel_target=channels.index(target) if feature_axis else None, + channel_output_aware=feature_axis, + ) + return _as_dict(explanation, channels, target, horizon, forecast) + + +def _as_dict( + explanation: Any, + channels: list[str], + target: str, + horizon: int, + forecast: np.ndarray, +) -> dict[str, Any]: + r"""The explanation as the contract carries one: plain JSON data. + + Rendered by the code that drew it upstream, so a report built from this + and one built there say the same things in the same words. + """ + from sdm_client.explain._kumo_ts.pages import _explanation_to_dict + + frame = pd.DataFrame( + { + 'forecast_step': range(1, horizon + 1), + f'{target}_forecast': np.asarray(forecast, dtype='float32'), + } + ) + rendered = _explanation_to_dict( + frame, + explanation, + target_column=target, + timestamp_column='forecast_step', + channel_labels=list(channels), + ) + # Upstream keeps the labels only where feature-axis attribution ran, and + # they name the channels of every explanation. The client knows them + # either way, and a report that cannot say which channel is which is + # harder to read than one that can. + rendered.setdefault('metadata', {})['channel_labels'] = list(channels) + return rendered diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py new file mode 100644 index 000000000..a6419fbfd --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py @@ -0,0 +1,15 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""Kumo-TS's forecast attribution and its report, as that package wrote them. + +Adapted from NVIDIA/Kumo-TS at af74798bbf7d020d3298f545fb9be383560a18ce. +Kept together and kept as written: an attribution is a statement about what a +model did, and rewriting the arithmetic that makes it would make it a +statement about something else. + +Only the imports are rewired, to reach each other here. These modules are +excluded from type checking for the same reason the generated parser is +excluded from linting: they are not this repository's to edit. +""" diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py new file mode 100644 index 000000000..3bb6afb18 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py @@ -0,0 +1,536 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/channel_flow.py +# at af74798bbf7d020d3298f545fb9be383560a18ce. + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Per-channel Jacobian-flow decomposition for feature-axis interpretability. + +This module extends the temporal-axis framework in :mod:`interpretability` to +multivariate inputs. It decomposes each latent trajectory step into per-channel +contributions with a directional central-secant approximation of the +channel-block Jacobian. + +The resulting per-channel flow feeds :func:`lag_channel_horizon_attribution`, +which produces a joint `[K, C, H]` lag-by-channel-by-horizon attribution +tensor. :func:`channel_horizon_marginal` reduces that tensor to the `[C, H]` +feature-axis attribution used by the SDK report. +""" + +from collections.abc import Callable +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal + +import numpy as np +import torch + +if TYPE_CHECKING: + from collections.abc import Sequence + +from sdm_client.explain._kumo_ts.interpretability import ( + Array, + ForecastModel, + _embed_batch, + _rolling_window_sources, +) + +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class ChannelFlowConfig: + """Configuration for per-channel Jacobian-flow decomposition. + + Args: + jacobian_secant_scale: Multiplicative scale applied to the per-channel + input increment for the central-difference probe. + time_indices: Optional trajectory transition indices to evaluate. By + default every consecutive transition is processed. + batch_size: Number of probe windows evaluated per forward pass. + transition_batch: Number of transitions stacked into one embed call + before the probe windows are chunked by `batch_size`. + """ + + jacobian_secant_scale: float = 0.5 + time_indices: Sequence[int] | None = None + batch_size: int = 32 + transition_batch: int = 1 + + +@dataclass(frozen=True) +class ChannelFlowReport: + """Per-channel Jacobian-flow decomposition outputs.""" + + method: str + per_channel_flow: Array + flow_total: Array + residual_ratio_per_step: Array | None = None + residual_ratio_mean: float | None = None + residual_ratio_p95: float | None = None + n_time_steps: int = 0 + n_channels: int = 0 + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _resolve_step_indices( + *, + time_indices: Sequence[int] | None, + n_windows: int, +) -> np.ndarray: + """Return the array of trajectory transition indices to evaluate. + + A "transition" at index ``tau`` is the pair ``(tau, tau+1)``; valid range + is ``[0, n_windows - 2]``. + """ + if n_windows < 2: + raise ValueError( + f'Need at least 2 rolling windows for flow, got {n_windows}' + ) + if time_indices is None: + return np.arange(n_windows - 1, dtype=np.int64) + arr = np.asarray(time_indices, dtype=np.int64).reshape(-1) + if arr.size == 0: + raise ValueError( + '`time_indices` must contain at least one transition index.' + ) + invalid = (arr < 0) | (arr >= n_windows - 1) + if np.any(invalid): + raise ValueError( + f'`time_indices` contains values outside [0, {n_windows - 2}]: {arr[invalid].tolist()}' + ) + return np.unique(arr) + + +class _ChannelFlowEmbedDP(torch.nn.Module): + """Routes forward() to model.embed() so DataParallel shards the + probe-embedding batches across GPUs in channel-flow Jacobians. + DataParallel only intercepts forward(), not arbitrary named methods. + """ + + def __init__(self, model: ForecastModel) -> None: + super().__init__() + self._m = model + + def forward( + self, x_enc: torch.Tensor, input_mask: torch.Tensor + ) -> torch.Tensor: + out = self._m.embed(x_enc=x_enc, input_mask=input_mask) + return out.embeddings if hasattr(out, 'embeddings') else out + + +def _embed_windows_batched( + model: ForecastModel, + windows: Array, + masks: Array, + *, + device: torch.device, + batch_size: int, +) -> Array: + """Batched embedding of a stack of ``[N, C, L]`` windows. + + NaN/inf in the model's embedding output are replaced with zero, mirroring + the sanitization that ``interpretability.extract_latent_trajectory`` + applies to the v1 path. Without this, non-finite activations from + out-of-distribution forecast-extension windows can propagate + into ``per_channel_flow`` and break the v1 reduction (Prop 1) on real + weights even though the in-context portion is clean. + """ + n = int(windows.shape[0]) + if n == 0: + return np.zeros((0, 0), dtype=np.float32) + out_chunks: list[Array] = [] + _is_dp = isinstance(model, torch.nn.DataParallel) + for i in range(0, n, batch_size): + x = torch.from_numpy( + np.ascontiguousarray(windows[i : i + batch_size]) + ).to(device=device, dtype=torch.float32) + m = torch.from_numpy( + np.ascontiguousarray(masks[i : i + batch_size]) + ).to(device=device, dtype=torch.long) + if _is_dp: + out_chunks.append( + model(x, m).detach().cpu().numpy().astype(np.float32) + ) + else: + out_chunks.append(_embed_batch(model, x, m)) + z = np.concatenate(out_chunks, axis=0) + if np.any(~np.isfinite(z)): + z = np.nan_to_num(z, nan=0.0, posinf=0.0, neginf=0.0).astype( + np.float32, copy=False + ) + return z + + +ValueFn = Callable[..., Array] + + +# --------------------------------------------------------------------------- +# Jacobian-flow +# --------------------------------------------------------------------------- + + +@torch.no_grad() +def compute_per_channel_flow_jacobian( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + cfg: ChannelFlowConfig | None = None, + value_fn: ValueFn | None = None, +) -> ChannelFlowReport: + """First-order per-channel decomposition of latent flow. + + For each transition ``tau -> tau+1`` we approximate + + Delta Z_tau^(c) ~= 0.5 * [ embed(X_tau + s * bump_c) - embed(X_tau - s * bump_c) ] + / s + + where ``bump_c`` is the input-tensor with row ``c`` set to the per-channel + increment ``Delta x_tau^(c) = X_{tau+1}[c] - X_tau[c]`` and zeros elsewhere, + and ``s = cfg.jacobian_secant_scale``. The per-channel flow magnitude is + ``phi_tau(c) = || Delta Z_tau^(c) ||_2``. + + The residual ``r_tau = Delta Z_tau - sum_c Delta Z_tau^(c)`` is used to + populate the trust ratio diagnostic. + + Cost: For each of ``T - 1`` transitions we evaluate ``2C + 1`` embeddings + (``C`` "+s" probes, ``C`` "-s" probes, plus ``Z_{tau+1}`` -- ``Z_tau`` is + re-used from the previous iteration). We batch over channels so this is + one batched forward of size ``2C + 1`` per transition. + """ + cfg = cfg or ChannelFlowConfig() + # When multiple GPUs are available and no custom value_fn is set, + # wrap the model so DataParallel splits the (2+2*C)-probe embedding + # batch across devices, cutting wall-clock roughly in half per + # additional GPU without any change to the transition loop logic. + _n_gpus = torch.cuda.device_count() if torch.cuda.is_available() else 0 + if _n_gpus > 1 and value_fn is None: + import logging as _log + + _log.getLogger(__name__).info( + 'channel flow Jacobian: using %d GPUs via DataParallel', _n_gpus + ) + model = torch.nn.DataParallel(_ChannelFlowEmbedDP(model)) + vf = value_fn if value_fn is not None else _embed_windows_batched + + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T < 2: + raise ValueError( + f'Need at least 2 time steps for flow decomposition, got T={T}' + ) + transitions = _resolve_step_indices( + time_indices=cfg.time_indices, n_windows=T + ) + + C = int(np.asarray(series_ct).shape[0]) + L = int(seq_len) + s = float(cfg.jacobian_secant_scale) + if s <= 0: + raise ValueError(f'jacobian_secant_scale must be > 0, got {s}') + + phi = np.full((T - 1, C), np.nan, dtype=np.float32) + flow_total = np.full((T - 1,), np.nan, dtype=np.float32) + residual = np.full((T - 1,), np.nan, dtype=np.float32) + + # Number of "probe windows" per transition: Z_tau, Z_{tau+1}, +/- bumps. + probes_per_trans = 2 + 2 * C + trans_batch = max(1, int(cfg.transition_batch)) + + for chunk_start in range(0, len(transitions), trans_batch): + chunk = transitions[chunk_start : chunk_start + trans_batch] + m_chunk = len(chunk) + + # Pre-fetch all windows referenced by this chunk in one slice each + # (avoids materialising the rolling-window view C+1 times per + # transition like the per-tau path used to do). + starts = chunk.astype(np.int64) + win_a = np.asarray(xw_view[starts], dtype=np.float32) # [m, C, L] + win_b = np.asarray(xw_view[starts + 1], dtype=np.float32) # [m, C, L] + mask_a = np.asarray(m_view[starts], dtype=np.int64) # [m, L] + mask_b = np.asarray(m_view[starts + 1], dtype=np.int64) # [m, L] + delta_cl = (win_b - win_a).astype(np.float32, copy=False) # [m, C, L] + + # Build the [m * probes_per_trans, C, L] probe stack in one shot. + # Layout per transition is [a, b, +probe_0..+probe_{C-1}, -probe_0..]. + stack = np.empty((m_chunk, probes_per_trans, C, L), dtype=np.float32) + stack[:, 0] = win_a + stack[:, 1] = win_b + + # Bumps share the original window's content except on the bumped + # channel row, which is shifted by +/- s * delta_x. We construct + # them by tiling x_a across C "probes" and then overwriting the + # diagonal (c, c) row with the per-channel shifted value. + plus = np.broadcast_to(win_a[:, None, :, :], (m_chunk, C, C, L)).copy() + minus = plus.copy() + # diag indexing: for each transition m and probe c, row c is + # x_a[m, c] +/- s * delta_cl[m, c]. + diag_idx = np.arange(C) + plus[:, diag_idx, diag_idx, :] = ( + win_a[:, diag_idx, :] + s * delta_cl[:, diag_idx, :] + ) + minus[:, diag_idx, diag_idx, :] = ( + win_a[:, diag_idx, :] - s * delta_cl[:, diag_idx, :] + ) + stack[:, 2 : 2 + C] = plus + stack[:, 2 + C :] = minus + + # Mask discipline: position 1 (Z_{tau+1}) uses window B's mask; + # everything else uses window A's mask. This matches the per-window + # mask discipline used by ``extract_latent_trajectory`` and is what + # makes the v1 reduction (Prop 1) hold exactly when C=1. + masks_full = np.broadcast_to( + mask_a[:, None, :], (m_chunk, probes_per_trans, L) + ).copy() + masks_full[:, 1] = mask_b + + flat_stack = stack.reshape(m_chunk * probes_per_trans, C, L) + flat_masks = masks_full.reshape(m_chunk * probes_per_trans, L) + + z_flat = vf( + model, + flat_stack, + flat_masks, + device=device, + batch_size=int(cfg.batch_size), + ) # [m * probes_per_trans, Dv] + D = int(z_flat.shape[1]) + z = z_flat.reshape(m_chunk, probes_per_trans, D) + + z_tau = z[:, 0, :] # [m, D] + z_tau_plus = z[:, 1, :] # [m, D] + delta_z = z_tau_plus - z_tau # [m, D] + + # Per-channel directional derivative, central-secant form: + # (z_+ - z_-) / (2s). Reshape pulls out [m, C, D]. + delta_z_per_chan = (z[:, 2 : 2 + C, :] - z[:, 2 + C :, :]) / ( + 2.0 * s + ) # [m, C, D] + + # Per-tau scalar norms. We deliberately call ``np.linalg.norm`` once + # per row (instead of an axis-aware norm across the m-batch) to + # match the float32 summation order of the original per-tau loop + # bit-for-bit -- otherwise BLAS picks a slightly different reduction + # tree for [m, D] vs [D] inputs and the scalar flow_total / residual + # drift by ~1 ULP. The scalar work is negligible compared to the + # (already-vectorised) embed pass that produced ``z``. + for k, tau in enumerate(chunk): + dz_k = delta_z[k] # [D] + dzpc_k = delta_z_per_chan[k] # [C, D] + phi[int(tau)] = np.linalg.norm(dzpc_k, ord=2, axis=1).astype( + np.float32 + ) + flow_total[int(tau)] = float(np.linalg.norm(dz_k, ord=2)) + denom_k = float(np.linalg.norm(dz_k, ord=2)) + 1e-12 + r_k = dz_k - dzpc_k.sum(axis=0) + residual[int(tau)] = float(np.linalg.norm(r_k, ord=2)) / denom_k + + finite = np.isfinite(residual) + res_mean = float(np.nanmean(residual[finite])) if np.any(finite) else None + res_p95 = ( + float(np.nanpercentile(residual[finite], 95)) + if np.any(finite) + else None + ) + + return ChannelFlowReport( + method='jacobian', + per_channel_flow=phi, + flow_total=flow_total, + residual_ratio_per_step=residual, + residual_ratio_mean=res_mean, + residual_ratio_p95=res_p95, + n_time_steps=int(T - 1), + n_channels=C, + ) + + +def compute_per_channel_flow( + model: ForecastModel, + series_ct: Array, + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + cfg: ChannelFlowConfig | None = None, + value_fn: ValueFn | None = None, +) -> ChannelFlowReport: + """Compute the configured per-channel Jacobian-flow report.""" + return compute_per_channel_flow_jacobian( + model, + series_ct, + seq_len=seq_len, + input_mask_t=input_mask_t, + device=device, + cfg=cfg, + value_fn=value_fn, + ) + + +# --------------------------------------------------------------------------- +# Lag x Channel x Horizon attribution +# --------------------------------------------------------------------------- + + +def lag_channel_horizon_attribution( + per_channel_flow: Array, # [T-1, C] + *, + t_index: int, + n_lags: int, + horizon: int, + softmax_tau: float = 1.0, + horizon_kernel: Literal['exp', 'none'] = 'exp', + kernel_min_scale: float = 4.0, + kernel_max_scale: float | None = None, + normalize: Literal['joint', 'per_channel', 'none'] = 'joint', +) -> tuple[Array, Array]: + """Joint lag x channel x horizon attribution. + + This is the natural generalisation of :func:`lag_horizon_attribution` to + a per-channel flow input. The lag-horizon kernel ``w_h(a) = exp(-a / s_h)`` + is reused unchanged from v1; the only difference is that the cumulative + kernel-weighted sum is taken per channel, producing a ``[K, C, H]`` + score tensor instead of v1's ``[K, H]``. + + The ``normalize`` flag controls how the softmax over the score tensor is + taken: + + * ``"joint"`` (default): softmax over the *joint* ``(lag, channel)`` axis + for each horizon. Marginalising over channels recovers v1's + lag-horizon attribution as a sanity check; marginalising over lags + gives a per-channel-per-horizon attribution. + * ``"per_channel"``: softmax over the lag axis, separately for each + ``(c, h)`` pair. Useful when the absolute scale of each channel's + contribution is known to vary widely. + * ``"none"``: return raw scores without softmax normalization. + + Returns: + scores: ``[K, C, H]`` + attributions: ``[K, C, H]`` + """ + flow_tc = np.asarray(per_channel_flow, dtype=np.float32) + if flow_tc.ndim != 2: + raise ValueError( + f'Expected per_channel_flow shape [T-1, C], got {flow_tc.shape}' + ) + flow_tc = np.where(np.isfinite(flow_tc), flow_tc, 0.0).astype(np.float32) + + Tm1, C = flow_tc.shape + K = int(n_lags) + H = int(horizon) + if K <= 0 or H <= 0: + raise ValueError('n_lags and horizon must be positive') + if not (1 <= int(t_index) <= Tm1): + raise ValueError(f't_index must be in [1, {Tm1}], got {t_index}') + if int(t_index) < K: + raise ValueError(f'n_lags must be <= t_index={int(t_index)}, got {K}') + + # Most-recent-first slice of history flow per channel. + hist_tail = flow_tc[max(0, int(t_index) - K) : int(t_index), :] # [<=K, C] + hist_rev = hist_tail[::-1, :] # most recent first + L = hist_rev.shape[0] + + # Horizon scales (identical to v1). + min_s = float(kernel_min_scale) + max_s = ( + float(kernel_max_scale) if kernel_max_scale is not None else float(K) + ) + if min_s <= 0 or max_s <= 0: + raise ValueError('kernel scales must be positive') + max_s = max(max_s, min_s) + if H == 1: + scales_h = np.array([min_s], dtype=np.float32) + else: + u_h = np.arange(H, dtype=np.float32) / float(H - 1) + scales_h = (min_s + u_h * (max_s - min_s)).astype(np.float32) + + scores = np.zeros((K, C, H), dtype=np.float32) + if horizon_kernel == 'none': + csum = np.cumsum(hist_rev, axis=0, dtype=np.float32) # [L, C] + scores[:L, :, :] = csum[:, :, None] + elif horizon_kernel == 'exp': + ages_l = np.arange(L, dtype=np.float32)[:, None] # [L, 1] + target_bytes = 64 * 1024 * 1024 + bytes_per_h = max(1, L * C * 4) + chunk = max(1, min(H, target_bytes // bytes_per_h)) + for h0 in range(0, H, chunk): + h1 = min(H, h0 + chunk) + s = np.maximum(scales_h[h0:h1][None, :], np.float32(1e-6)) + w_lh = np.exp(-ages_l / s).astype(np.float32) # [L, chunk] + # hist_rev: [L, C]; w_lh: [L, chunk] -> contribution per (l, c, h) + hw_lhc = hist_rev[:, :, None] * w_lh[:, None, :] # [L, C, chunk] + csum = np.cumsum(hw_lhc, axis=0, dtype=np.float32) # [L, C, chunk] + scores[:L, :, h0:h1] = csum + else: + raise ValueError(f'Unsupported horizon_kernel={horizon_kernel!r}') + + tau = max(float(softmax_tau), 1e-6) + if normalize == 'none': + return scores, scores.copy() + if normalize == 'per_channel': + attrib = np.empty_like(scores) + for c in range(C): + for h in range(H): + col = scores[:, c, h] + if not np.any(col): + attrib[:, c, h] = 1.0 / float(K) + else: + e = np.exp((col - col.max()) / tau) + s = e.sum() + attrib[:, c, h] = e / s if s > 0 else 1.0 / float(K) + return scores, attrib + if normalize != 'joint': + raise ValueError(f'Unsupported normalize={normalize!r}') + + # Joint softmax over (lag, channel) per horizon. + attrib = np.empty_like(scores) + flat = scores.reshape(K * C, H) + for h in range(H): + col = flat[:, h] + if not np.any(col): + attrib[:, :, h] = 1.0 / float(K * C) + continue + e = np.exp((col - col.max()) / tau) + s = e.sum() + if s <= 0: + attrib[:, :, h] = 1.0 / float(K * C) + else: + attrib[:, :, h] = (e / s).reshape(K, C) + return scores, attrib + + +def channel_horizon_marginal(attribution_kch: Array) -> Array: + """Sum a ``[K, C, H]`` attribution tensor over the lag axis.""" + return ( + np.asarray(attribution_kch, dtype=np.float32) + .sum(axis=0) + .astype(np.float32) + ) + + +def lag_horizon_marginal(attribution_kch: Array) -> Array: + """Sum a ``[K, C, H]`` attribution tensor over the channel axis. + + Matches the v1 lag-horizon attribution shape ``[K, H]`` so it can be + plugged directly into :func:`evaluate_lag_faithfulness`. + """ + return ( + np.asarray(attribution_kch, dtype=np.float32) + .sum(axis=1) + .astype(np.float32) + ) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py new file mode 100644 index 000000000..c3394dcec --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py @@ -0,0 +1,381 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/channel_stability.py +# at af74798bbf7d020d3298f545fb9be383560a18ce. + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Per-channel embedding stability (v2 feature-axis stability). + +This module contains the channel-axis analogue of v1's embedding stability +primitive in :mod:`interpretability`: + +* :func:`compute_embedding_stability` (v1) reports a single scalar Lipschitz + ratio per (model, series), aggregating over many input perturbation trials. + Its v2 counterpart :func:`compute_per_channel_embedding_stability` reports + the same ratio *per input channel*, by perturbing only one row of the input + window at a time. Answers: "which input channels does the embedding map + treat in a Lipschitz-safe way?" + +Mathematical definitions +======================== + +**Per-channel embedding stability (Lipschitz-style).** +For an input context ``X_t in R^{C x L}`` and a channel ``c in {0, ..., C-1}``, +define the per-channel-perturbed input + + X_t^(c, eps) = X_t + epsilon e_c x_t^T , epsilon ~ N(0, (alpha sigma_c)^2 I_L), + +i.e. additive Gaussian noise with scale ``alpha * sigma_c`` (where +``sigma_c = std(X_t[c, observed])`` and ``alpha = noise_scale``) restricted to +row ``c`` of the input. Only row ``c`` differs from ``X_t``, so the Frobenius +norm reduces to a row-vector L2 norm: + + || X_t^(c, eps) - X_t ||_F = || epsilon ||_2 = || x_t'[c, :] - x_t[c, :] ||_2 . + +The per-channel Lipschitz-style ratio is + + R_t^(c) = || embed(X_t^(c, eps)) - embed(X_t) ||_2 / ( || X_t^(c, eps) - X_t ||_F + eta ), + +where ``eta = 1e-12`` is a numerical floor on the denominator. We aggregate +over ``n_trials`` perturbation trials per channel and per time index, then +report mean / max / p50 / p95 per channel. + +**Sanity invariance.** If the embedding is channel-independent -- +``embed(X) = sum_c phi_c(x_c)`` for some per-channel maps ``phi_c`` -- then +perturbing only row ``c`` changes ``embed`` by ``phi_c(x_c + n) - phi_c(x_c)`` +alone. The ratio ``R_t^(c)`` therefore probes the local Lipschitz constant of +``phi_c`` in isolation. In the limit of vanishing noise scale, +``R_t^(c) -> ||J_{phi_c}||_op``. For the linear channel-independent mock model +the ratio is *exactly* ``||W^c||_op`` of that channel's projection -- this is +the invariance checked by +``test_channel_independent_model_recovers_jacobian_norm`` in the test suite. + +Cost summary +============ + +* :func:`compute_per_channel_embedding_stability`: + ``n_trials * C`` embed calls per time index, ``+1`` baseline embed call. + All batched into one forward pass per time index via ``_embed_windows_batched``. +""" + +from dataclasses import dataclass + +import numpy as np +import torch + +from sdm_client.explain._kumo_ts.channel_flow import _embed_windows_batched +from sdm_client.explain._kumo_ts.interpretability import ( + Array, + ForecastModel, + _rolling_window_sources, + extract_latent_trajectory, +) + +# --------------------------------------------------------------------------- +# Reports +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class PerChannelEmbeddingStabilityReport: + """Per-channel result of the empirical embedding stability test. + + Shapes (with ``C`` input channels): + + * ``lip_ratio_mean``, ``lip_ratio_max``, ``lip_ratio_p50``, ``lip_ratio_p95``: + ``[C]`` -- aggregates over the ratios collected for that channel. + * ``n_trials_per_channel``: ``[C]`` -- number of perturbation trials that + contributed a finite ratio for that channel (may differ across channels + if some perturbations were skipped, e.g. a fully-zero noise draw on a + constant channel). + * ``n_unique_windows``: ``int`` -- count of distinct time indices that + contributed to at least one channel's ratio set. + * ``step_delta_norm_mean``: ``float`` -- mean ``||Z_{t+1} - Z_t||`` on the + unperturbed trajectory (a v1-style reference scale; identical to the + scalar returned by :func:`compute_embedding_stability`). + """ + + lip_ratio_mean: Array # [C] + lip_ratio_max: Array # [C] + lip_ratio_p50: Array # [C] + lip_ratio_p95: Array # [C] + n_trials_per_channel: Array # [C], int + n_unique_windows: int + step_delta_norm_mean: float + n_channels: int + + +# --------------------------------------------------------------------------- +# Shared helpers +# --------------------------------------------------------------------------- + + +def _select_time_indices( + *, + seq_len: int, + T: int, + n_trials: int, + rng: np.random.Generator, + time_indices: Array | None = None, +) -> np.ndarray: + """Mirror the sampling discipline used in v1 :func:`compute_embedding_stability`. + + Prefers indices ``[seq_len - 1, T)`` (full-window region) and repeats with + a shuffle if the candidate pool is smaller than ``n_trials``. Different + perturbation seeds across the repeats keep the trials statistically + distinct even when the underlying windows are reused. + """ + if time_indices is not None: + return np.asarray(time_indices, dtype=np.int64).reshape(-1) + candidates = np.arange(seq_len - 1, T, dtype=np.int64) + if len(candidates) == 0: + candidates = np.arange(T, dtype=np.int64) + if len(candidates) >= n_trials: + return rng.choice(candidates, size=n_trials, replace=False) + n_repeats = int(np.ceil(n_trials / len(candidates))) + out = np.tile(candidates, n_repeats)[:n_trials] + rng.shuffle(out) + return out + + +def _per_channel_std(window_cl: Array, win_mask: Array) -> Array: + """Per-channel std of ``window_cl[:, observed]``. + + Channels with std ``< 1e-8`` (numerically constant on the observed slice) + fall back to ``1.0`` to match the v1 convention -- they get the *raw* + noise scale and we measure ``embed`` sensitivity to that absolute scale + rather than to a normalised-by-zero scale. + """ + obs = np.asarray(win_mask, dtype=bool) + if not np.any(obs): + return np.ones((window_cl.shape[0],), dtype=np.float32) + std = np.std(window_cl[:, obs], axis=1).astype(np.float32, copy=False) + std = np.where(std < 1e-8, np.float32(1.0), std) + return std + + +# --------------------------------------------------------------------------- +# Per-channel embedding stability +# --------------------------------------------------------------------------- + + +@torch.no_grad() +def compute_per_channel_embedding_stability( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + n_trials: int = 30, + noise_scale: float = 0.01, + time_indices: Array | None = None, + batch_size: int = 16, + trajectory_batch_size: int = 32, + seed: int = 42, +) -> PerChannelEmbeddingStabilityReport: + """Channel-wise Lipschitz-style stability test. + + For each channel ``c``, perturbs only row ``c`` of the input window and + measures the ratio ``|| embed(X') - embed(X) ||_2 / || X' - X ||_F`` + averaged over ``n_trials`` perturbation trials. The result is the v2 + feature-axis analogue of :func:`compute_embedding_stability` (which + perturbs all channels jointly and returns a single scalar). + + Args: + model: forecast model exposing the ``embed`` interface. + series_ct: ``[C, T]`` series; only the trailing time indices matter. + seq_len: context length ``L`` of the model. + input_mask_t: optional ``[T]`` observed-mask for the series. + device: torch device for the embed calls. + n_trials: number of perturbation trials *per channel and per time + index*. Total perturbation embeds = ``n_trials * |time_indices| * C``. + noise_scale: noise amplitude as a fraction of per-channel std. + time_indices: optional explicit ``[T_idx]`` time-index list. If None, + samples ``n_trials`` indices from the full-window region. + batch_size: chunk size for batched embed of perturbation windows. + trajectory_batch_size: chunk size for the reference-trajectory embed + (separate budget because the reference is computed once over the + full series). + seed: RNG seed for the per-channel noise. + + Returns: + :class:`PerChannelEmbeddingStabilityReport` with shape-``[C]`` summaries. + """ + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T < 2: + raise ValueError( + f'Need at least 2 time steps for per-channel stability test, got T={T}' + ) + C = int(np.asarray(series_ct).shape[0]) + L = int(seq_len) + + rng = np.random.default_rng(int(seed)) + sampled_indices = _select_time_indices( + seq_len=L, + T=T, + n_trials=int(n_trials), + rng=rng, + time_indices=time_indices, + ) + sampled_indices = np.unique(np.clip(sampled_indices, 0, T - 1)) + if sampled_indices.size == 0: + raise ValueError( + 'No valid time indices to sample for per-channel stability.' + ) + + # Collected ratios are gathered into per-channel lists across all + # (time_index, trial) draws so the aggregation is purely vectorised at the + # end. Each accepted draw contributes one float per channel. + per_channel_ratios: list[list[float]] = [[] for _ in range(C)] + n_unique = 0 + + # Number of trials per time index: keep at least 1; rotate noise seeds so + # the trials are not identical across time indices. + trials_per_index = max(1, int(np.ceil(n_trials / sampled_indices.size))) + + for t_idx, t in enumerate(sampled_indices): + win = np.asarray(xw_view[int(t)], dtype=np.float32) # [C, L] + mask = np.asarray(m_view[int(t)], dtype=np.int64) # [L] + obs_mask = mask.astype(bool) + if not np.any(obs_mask): + continue + + std_per_chan = _per_channel_std(win, mask) # [C] + win_mask_f = mask.astype(np.float32, copy=False) # [L] + + # Build a [1 + C * trials_per_index, C, L] probe stack: + # slot 0 = baseline; slots 1..C, C+1..2C, ... = trial-major, + # channel-minor perturbations (channel c of trial r at slot 1 + r*C + c). + n_perturbs = C * trials_per_index + stack = np.empty((1 + n_perturbs, C, L), dtype=np.float32) + stack[0] = win + + # Draw noise once per (trial, channel) at scale alpha * std_c restricted + # to observed positions. Padded positions contribute 0 to both + # numerator (embed sees the same masked input) and denominator (we + # measure Frobenius norm of x' - x, which is zero in masked positions). + noise_unit = rng.standard_normal((trials_per_index, C, L)).astype( + np.float32 + ) + # Apply the observation mask (zero perturbation where mask=0). + noise_unit = noise_unit * win_mask_f[None, None, :] + # Per-channel scale. + noise_unit *= (float(noise_scale) * std_per_chan)[ + None, :, None + ] # [r, C, L] + + # Frobenius norm equals the row-c L2 norm of the per-channel noise. + # Drop trials where every channel ended up with a numerically zero + # noise vector (e.g. constant + tiny noise_scale on a fully-padded + # window) -- they would inject inf into the ratio aggregation. + dx_norm = np.linalg.norm( + noise_unit.reshape(trials_per_index * C, L), ord=2, axis=1 + ).astype(np.float32) + dx_norm = dx_norm.reshape(trials_per_index, C) + + # Materialise perturbed windows: copy ``win`` then overwrite row c with + # ``win[c] + noise[r, c, :]``. + perturbed = np.broadcast_to( + win[None, None, :, :], (trials_per_index, C, C, L) + ).copy() + chan_idx = np.arange(C) + perturbed[:, chan_idx, chan_idx, :] = ( + win[chan_idx, :][None, :, :] + noise_unit + ) # [r, C, L] + + # Flatten trial/channel dims into the leading "slot" axis. + stack[1:] = perturbed.reshape(n_perturbs, C, L) + masks_stack = np.broadcast_to(mask[None, :], (1 + n_perturbs, L)).copy() + + z = _embed_windows_batched( + model, + stack, + masks_stack, + device=device, + batch_size=int(batch_size), + ) # [1 + n_perturbs, D] + z_base = z[0] # [D] + z_pert = z[1:].reshape(trials_per_index, C, -1) # [r, C, D] + + dz_norm = np.linalg.norm( + z_pert - z_base[None, None, :], ord=2, axis=2 + ).astype(np.float32) # [r, C] + + # Aggregate per-channel ratios. Skip (trial, channel) cells where the + # noise vector was numerically zero. + valid_mask = dx_norm > 1e-12 + eps = np.float32(1e-12) + ratios = dz_norm / (dx_norm + eps) + for c in range(C): + valid_c = valid_mask[:, c] + if not np.any(valid_c): + continue + for r_val in ratios[valid_c, c]: + per_channel_ratios[c].append(float(r_val)) + n_unique += 1 + + # Reference scale (matches v1 step_delta_norm_mean) - computed once over + # the full series. Failure-tolerant: if the trajectory is degenerate, fall + # back to NaN. + try: + Z_full = extract_latent_trajectory( + model, + series_ct, + seq_len=L, + input_mask_t=input_mask_t, + device=device, + batch_size=int(trajectory_batch_size), + ) + if Z_full.shape[0] >= 2: + step_deltas = np.linalg.norm( + Z_full[1:] - Z_full[:-1], ord=2, axis=1 + ) + step_delta_mean = float(np.nanmean(step_deltas)) + else: + step_delta_mean = float('nan') + except Exception: + step_delta_mean = float('nan') + + lip_mean = np.full((C,), np.nan, dtype=np.float32) + lip_max = np.full((C,), np.nan, dtype=np.float32) + lip_p50 = np.full((C,), np.nan, dtype=np.float32) + lip_p95 = np.full((C,), np.nan, dtype=np.float32) + n_per_chan = np.zeros((C,), dtype=np.int64) + for c in range(C): + if not per_channel_ratios[c]: + continue + arr = np.asarray(per_channel_ratios[c], dtype=np.float64) + finite = arr[np.isfinite(arr)] + if finite.size == 0: + continue + lip_mean[c] = float(np.mean(finite)) + lip_max[c] = float(np.max(finite)) + lip_p50[c] = float(np.percentile(finite, 50)) + lip_p95[c] = float(np.percentile(finite, 95)) + n_per_chan[c] = int(finite.size) + + return PerChannelEmbeddingStabilityReport( + lip_ratio_mean=lip_mean, + lip_ratio_max=lip_max, + lip_ratio_p50=lip_p50, + lip_ratio_p95=lip_p95, + n_trials_per_channel=n_per_chan, + n_unique_windows=int(n_unique), + step_delta_norm_mean=step_delta_mean, + n_channels=int(C), + ) + + +__all__ = [ + 'PerChannelEmbeddingStabilityReport', + 'compute_per_channel_embedding_stability', +] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py new file mode 100644 index 000000000..dd9b4e0d6 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py @@ -0,0 +1,343 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/integrated_gradients.py +# at af74798bbf7d020d3298f545fb9be383560a18ce. + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +"""Integrated Gradients / Expected Gradients over the embedding layer. + +What this measures +================== +This is a *general*, model-agnostic interpretability primitive. Given any model +that encodes a time-series context window into an embedding, + + e = Enc(x) , x in R^{...} (the input window), e in R^{D} (the encoding), + +it measures the effect of the input on the encoding by **accumulating the +gradients of the embedding layer along a straight-line path from a baseline to +the input** (Integrated Gradients; Sundararajan et al., 2017): + + A_i = (x_i - x0_i) * \\int_0^1 d g(Enc(x0 + a*(x - x0))) / d x_i da , + +where ``g`` reduces the embedding vector to a scalar (default: its L2 norm) and +``x0`` is the baseline (default: zeros, i.e. the "absence of input"). The path +``x0 -> x`` progressively *imputes* the input values into the encoder, and the +accumulated gradient quantifies how strongly those values drive the encoding. + +By the completeness axiom, + + sum_i A_i = g(Enc(x)) - g(Enc(x0)) , + +which is reported as a convergence diagnostic. + +Baseline choice (important for instance-normalized encoders) +============================================================ +Instance normalization ``(x - mean) / std`` is invariant to shifting and scaling +the input. A straight-line path from a *zero or constant* baseline to ``x`` can +therefore become the same normalized series at every step, making the embedding +flat along the path and degrading IG completeness at the degenerate endpoint. +The default white-noise baseline is matched to the input's global mean/std, which +breaks that invariance. Averaging several such baselines (``n_baselines > 1``) +produces the Expected-Gradients estimator and reduces variance. + +Design +====== +* **Model-agnostic.** The core depends only on a differentiable + ``embed_fn: Tensor[n, *feat] -> Tensor[n, D]`` that maps a *batch* of inputs + to a batch of embeddings. Nothing here knows about channels, patches, + missingness, or any specific architecture. +* **Real gradients.** Unlike the gradient-free probes elsewhere in + this package, this uses autograd: interpolation points are pushed through the + encoder in one or more batches and ``torch.autograd.grad`` yields the + gradients with respect to the input path only (each step's embedding depends + only on its own row). +* **Global, not per-axis.** The headline output is a single scalar effect over + the whole embedding layer plus a saliency map in the input's own shape. No + channel/feature-axis decomposition is imposed by this primitive. + +Cost: one forward/gradient pass per interpolation chunk. +""" + +import warnings +from collections.abc import Callable +from dataclasses import dataclass +from typing import Literal + +import numpy as np +import torch + +Array = np.ndarray +EmbedFn = Callable[[torch.Tensor], torch.Tensor] +Reduce = Literal['l2', 'sum', 'mean'] +BaselineMode = Literal['noise', 'zero', 'mean'] + + +@dataclass(frozen=True) +class EmbeddingAttribution: + """Result of Integrated Gradients over the embedding layer. + + * ``attribution``: per-input-element Integrated Gradients, in the input's + own shape (a model-agnostic saliency map over the context window). + * ``overall_effect``: ``sum_i attribution_i`` -- the net signed effect of + the input on the (reduced) embedding. Equal to ``embedding_delta`` up to + the Riemann approximation error. + * ``abs_effect``: ``sum_i |attribution_i|`` -- total saliency mass, a + magnitude summary that does not cancel across positions. + * ``embedding_delta``: ``g(Enc(x)) - g(Enc(x0))`` measured directly. + * ``embedding_delta_abs_mean``: mean absolute endpoint change across + Expected-Gradients baselines. This is the stable scale used below. + * ``convergence_delta``: ``|overall_effect - embedding_delta| / + (embedding_delta_abs_mean + eps)``; the Integrated-Gradients completeness + residual (-> 0 as ``n_steps`` grows). Using ``|mean(delta)|`` in the + denominator, as the old implementation did, explodes whenever endpoint + changes from different noise baselines cancel. + """ + + attribution: Array + overall_effect: float + abs_effect: float + embedding_delta: float + embedding_delta_abs_mean: float + convergence_delta: float + n_steps: int + n_baselines: int + baseline: str + reduce: str + embedding_dim: int + + +def _reduce_embedding(emb: torch.Tensor, reduce: Reduce) -> torch.Tensor: + """Reduce an ``[n, D]`` (or ``[n, ...]``) embedding batch to a scalar per row.""" + flat = emb.reshape(emb.shape[0], -1) + if reduce == 'l2': + return torch.linalg.vector_norm(flat, dim=1) + if reduce == 'sum': + return flat.sum(dim=1) + if reduce == 'mean': + return flat.mean(dim=1) + raise ValueError( + f"Unknown reduce {reduce!r}; expected 'l2' | 'sum' | 'mean'." + ) + + +def _ig_single( + embed_fn: EmbedFn, + x_t: torch.Tensor, + x0: torch.Tensor, + *, + n_steps: int, + reduce: Reduce, + internal_batch_size: int | None = None, +) -> tuple[Array, float, int]: + """One Integrated-Gradients pass for a fixed baseline ``x0``. + + Returns ``(attribution, embedding_delta, embedding_dim)``. + """ + delta = x_t - x0 # [*feat] + dev = x_t.device + + chunk = int(internal_batch_size or n_steps) + if chunk < 1: + raise ValueError( + f'internal_batch_size must be >= 1 when provided, got {internal_batch_size}' + ) + chunk = min(chunk, int(n_steps)) + + grad_sum = torch.zeros_like(x_t) + expand_prefix = (1,) * x_t.ndim + for start in range(0, int(n_steps), chunk): + stop = min(int(n_steps), start + chunk) + count = stop - start + + # Midpoint Riemann nodes for this chunk. + alphas = ( + torch.arange(start, stop, device=dev, dtype=torch.float32) + 0.5 + ) / int(n_steps) + x_interp = x0.unsqueeze(0) + alphas.reshape( + (count,) + expand_prefix + ) * delta.unsqueeze(0) + x_interp = x_interp.clone().requires_grad_(True) + + with torch.enable_grad(): + emb = embed_fn(x_interp) # [count, D] + if emb.shape[0] != count: + raise RuntimeError( + f'embed_fn must preserve the leading batch dim: got {emb.shape[0]} rows for {count} inputs.' + ) + g = _reduce_embedding(emb, reduce) # [count] + # Request only input-path gradients. Using .backward() here would + # also materialize parameter gradients for large encoders and keep + # them resident across integration batches. + grad = torch.autograd.grad( + g.sum(), x_interp, retain_graph=False, create_graph=False + )[0] + + grad_sum += grad.detach().sum(dim=0) + del emb, g, grad, x_interp + + avg_grad = grad_sum / float(n_steps) # [*feat] + attribution = (delta * avg_grad).detach().cpu().numpy().astype(np.float32) + + with torch.no_grad(): + ends = torch.stack([x0, x_t], dim=0) + emb_ends = embed_fn(ends) + g_ends = _reduce_embedding(emb_ends, reduce) + emb_dim = int(emb_ends.reshape(emb_ends.shape[0], -1).shape[1]) + embedding_delta = float((g_ends[1] - g_ends[0]).item()) + return attribution, embedding_delta, emb_dim + + +def integrated_gradients_embedding( + embed_fn: EmbedFn, + x: Array | torch.Tensor, + *, + baseline: BaselineMode | Array | torch.Tensor | float = 'noise', + n_steps: int = 64, + n_baselines: int = 1, + internal_batch_size: int | None = None, + reduce: Reduce = 'l2', + seed: int = 0, + device: torch.device | str | None = None, +) -> EmbeddingAttribution: + """Accumulate embedding-layer gradients along the baseline->input path. + + Args: + embed_fn: differentiable map from a *batch* of inputs ``[n, *feat]`` to a + batch of embeddings ``[n, D]`` (or any ``[n, ...]`` reduced to a + scalar per row). This callable is the only model-specific input. + x: a single input window, shape ``[*feat]`` (no batch dim). + baseline: path start. Either a mode string or an explicit reference: + + * ``"noise"`` (default) -- white noise matched to ``x``'s global + mean/std. Recommended for instance-normalized models; with + ``n_baselines > 1`` this becomes the Expected-Gradients estimator. + * ``"zero"`` / ``"mean"`` / a constant float -- a *constant* baseline. + **Degenerate for instance-normalized backbones** (emits a warning). + * an array shaped like ``x`` -- an explicit baseline. + n_steps: number of Riemann (midpoint) steps for the path integral. + n_baselines: number of independent ``"noise"`` baselines to average over + (Expected Gradients). Ignored (forced to 1) for explicit/constant + baselines. + internal_batch_size: maximum number of interpolation points to embed at + once. ``None`` keeps the original one-batch behavior; smaller values + trade a little runtime for much lower activation memory. + reduce: how the embedding vector is reduced to the scalar objective + ``g`` -- ``'l2'`` (default), ``'sum'`` or ``'mean'``. + seed: RNG seed for the noise baseline(s). + device: device for the computation; defaults to ``x``'s device (or CPU). + + Returns: + :class:`EmbeddingAttribution`. + """ + if n_steps < 1: + raise ValueError(f'n_steps must be >= 1, got {n_steps}') + if n_baselines < 1: + raise ValueError(f'n_baselines must be >= 1, got {n_baselines}') + + if isinstance(x, torch.Tensor): + dev = torch.device(device) if device is not None else x.device + x_t = x.detach().to(device=dev, dtype=torch.float32) + else: + dev = ( + torch.device(device) if device is not None else torch.device('cpu') + ) + x_t = torch.as_tensor(np.asarray(x, dtype=np.float32), device=dev) + + # Build the list of baseline tensors. + baselines: list[torch.Tensor] = [] + if isinstance(baseline, str) and baseline == 'noise': + mu = float(x_t.mean().item()) + sigma = float(x_t.std().item()) + sigma = sigma if sigma > 1e-8 else 1.0 + rng = np.random.default_rng(seed) + for _ in range(n_baselines): + noise = rng.standard_normal(tuple(x_t.shape)).astype(np.float32) + baselines.append(torch.as_tensor(mu + sigma * noise, device=dev)) + baseline_name = 'noise' + else: + if n_baselines != 1: + warnings.warn( + "n_baselines is ignored for non-'noise' baselines; using 1.", + stacklevel=2, + ) + if isinstance(baseline, str) and baseline in ('zero', 'mean'): + const = 0.0 if baseline == 'zero' else float(x_t.mean().item()) + baselines.append(torch.full_like(x_t, const)) + baseline_name = baseline + warnings.warn( + f"A constant '{baseline}' baseline is degenerate for instance-normalized models " + "(scale/shift invariance) and typically yields ~0 attribution; prefer baseline='noise'.", + stacklevel=2, + ) + elif isinstance(baseline, (int, float)): + baselines.append(torch.full_like(x_t, float(baseline))) + baseline_name = f'const({float(baseline):g})' + warnings.warn( + "A constant baseline is degenerate for instance-normalized models; prefer baseline='noise'.", + stacklevel=2, + ) + else: + x0 = ( + baseline.detach().to(device=dev, dtype=torch.float32) + if isinstance(baseline, torch.Tensor) + else torch.as_tensor( + np.asarray(baseline, dtype=np.float32), device=dev + ) + ) + if x0.shape != x_t.shape: + raise ValueError( + f'baseline shape {tuple(x0.shape)} must match x shape {tuple(x_t.shape)}' + ) + baselines.append(x0) + baseline_name = 'array' + + attrs: list[Array] = [] + deltas: list[float] = [] + emb_dim = 0 + for x0 in baselines: + attr, edelta, emb_dim = _ig_single( + embed_fn, + x_t, + x0, + n_steps=n_steps, + reduce=reduce, + internal_batch_size=internal_batch_size, + ) + attrs.append(attr) + deltas.append(edelta) + + attribution = np.mean(np.stack(attrs, axis=0), axis=0).astype(np.float32) + embedding_delta = float(np.mean(deltas)) + embedding_delta_abs_mean = float(np.mean(np.abs(deltas))) + overall = float(attribution.sum()) + abs_effect = float(np.abs(attribution).sum()) + eps = 1e-12 + convergence = float( + abs(overall - embedding_delta) / (embedding_delta_abs_mean + eps) + ) + + return EmbeddingAttribution( + attribution=attribution, + overall_effect=overall, + abs_effect=abs_effect, + embedding_delta=embedding_delta, + embedding_delta_abs_mean=embedding_delta_abs_mean, + convergence_delta=convergence, + n_steps=int(n_steps), + n_baselines=len(baselines), + baseline=baseline_name, + reduce=str(reduce), + embedding_dim=int(emb_dim), + ) + + +__all__ = [ + 'EmbeddingAttribution', + 'integrated_gradients_embedding', +] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py new file mode 100644 index 000000000..84662f021 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py @@ -0,0 +1,1725 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/interpretability.py +# at af74798bbf7d020d3298f545fb9be383560a18ce. + +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +""" +Model-agnostic interpretability utilities for time series forecasting. + +Pipeline structure (latent interface -> semantic flow -> lag x horizon matrix -> +local surrogates), implemented as a stable, model-agnostic approximation: + - Build a latent trajectory by embedding a rolling window at each time index. + - Define a scalar "flow magnitude" per step from consecutive latent states + (delta norm + optional scale term). + - Aggregate these magnitudes into a lag x horizon influence matrix and + normalize per horizon via softmax. + - Fit horizon-specific *weighted sparse linear* surrogates using + time-series-preserving perturbations. + +The result is horizon-resolved, temporally continuous, model-agnostic +explanations without retraining the forecaster. + +Stability / quality notes: +- The pipeline assumes temporal smoothness of the embedding: small input + changes should yield proportionally small latent changes. If not, flow + magnitudes may reflect representation noise. +- Use SemanticFlowConfig.smooth_latent_alpha for optional temporal smoothing + of Z. +- The latent trajectory is built over [history; forecast]. The forecast + segment is out-of-distribution (model-generated). Flow there can be noisier; + use flow_ratio_forecast_vs_history and flow_variance_ratio_forecast_vs_history + on ForecastExplanation to gauge whether attributions that depend on the + extended segment are likely to be volatile (ratio > 1 suggests more noise). +""" + +import warnings +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal, Protocol + +import numpy as np +import torch + +if TYPE_CHECKING: + from sdm_client.explain._kumo_ts.channel_flow import ChannelFlowConfig + +Array = np.ndarray + + +class ForecastModel(Protocol): + """Minimal protocol for models exposing forecast and embedding interfaces.""" + + def __call__(self, *, x_enc: torch.Tensor, input_mask: torch.Tensor) -> Any: + """Forward pass returning an object with a `.forecast` tensor [B, C, H].""" + + def embed(self, *, x_enc: torch.Tensor, input_mask: torch.Tensor) -> Any: + """Embedding pass returning an object with `.embeddings` tensor [B, D].""" + + +@dataclass(frozen=True) +class SemanticFlowConfig: + """ + Configuration for semantic-flow computation. + + Args: + flow_kind: + - 'delta_l2': m_t = ||z_{t+1} - z_t||_2 (latent displacement; no output sensitivity). + - 'output_aware': m_t = |(∂y/∂Z_t)(Z_{t+1}-Z_t)| (first-order forecast effect). + Requires dy_dZ in compute_semantic_flow_magnitudes. + scale_weight: + Optional extra term based on latent norm changes (delta_l2 only): + scale_weight * clip(|log(||z_{t+1}|| / ||z_t||)|, 0, 10) + The log-ratio term is capped at 10 to limit the influence of extreme norm jumps. + smooth_latent_alpha: + If in (0, 1), smooth the latent trajectory with EMA before computing flow: + Z_smooth[t] = alpha * Z_smooth[t-1] + (1 - alpha) * Z[t]. + Can improve robustness when embeddings are noisy (Lipschitz-like regularization). + output_aware_aggregation: + When flow_kind is 'output_aware', how to aggregate over horizons if dy_dZ has shape (T, H, D): + 'l2' => m_t = sqrt(sum_h (grad_t_h @ delta_t)^2), 'sum' => m_t = sum_h |grad_t_h @ delta_t|. + eps: + Numerical stability. + """ + + flow_kind: Literal['delta_l2', 'output_aware'] = 'delta_l2' + scale_weight: float = 0.0 + smooth_latent_alpha: float = 0.0 + output_aware_aggregation: Literal['l2', 'sum'] = 'l2' + eps: float = 1e-12 + + +@dataclass(frozen=True) +class TrajectoryStabilityReport: + """ + Summary of temporal smoothness for a latent trajectory. + + The trajectory is centered by a reference latent state and optionally scaled by the + per-dimension standard deviation of the reference segment. Lower zero-crossing, + direction-flip, and relative-jitter values indicate smoother latent evolution. + """ + + zero_crossing_rate_mean: float + zero_crossing_rate_p95: float + direction_flip_rate_mean: float + direction_flip_rate_p95: float + relative_jitter_mean: float + relative_jitter_p95: float + occupancy_positive_mean: float + occupancy_negative_mean: float + n_time_steps: int + n_dimensions: int + + +@dataclass(frozen=True) +class PerturbationConfig: + """ + Structure-preserving perturbations for local surrogates. + + block-bootstrap: resamples contiguous blocks to preserve local autocorrelation. + fourier-phase-preserving noise: keeps Fourier phase but perturbs amplitude mildly to preserve seasonality. + """ + + n_samples: int = 128 + block_len: int = 32 + fourier_amp_sigma: float = 0.05 + mix_original: float = 0.25 # 0 = fully perturbed, 1 = fully original + seed: int = 13 + + +@dataclass(frozen=True) +class SurrogateConfig: + """ + Horizon-specific local surrogate settings. + + We fit a weighted L1-regularized linear model (ISTA) independently for each horizon h. + """ + + n_lags: int = 64 + l1_alpha: float = 5e-3 + distance_lambda: float = 1.0 + max_iter: int = 300 + tol: float = 1e-5 + + +@dataclass(frozen=True) +class ForecastExplanation: + """ + Explanation outputs. + + Shapes: + - baseline_forecast: [C, H] + - lag_horizon_scores: [K, H] (unnormalized, larger means more influence) + - lag_horizon_attributions: [K, H] (softmax-normalized over lags for each horizon) + - surrogate_coef: [C, H, P] (may be None if surrogates disabled; P = C * surrogate_n_lags) + - surrogate_intercept: [C, H] (may be None if surrogates disabled) + + Segment quality (forecast vs history): + - flow_ratio_forecast_vs_history: mean flow in forecast segment / mean flow in history. + >1 means the extended (OOD) segment is more volatile; attributions that weight by + flow in that region may be noisier. + - flow_variance_ratio_forecast_vs_history: variance of flow in forecast / variance in history. + - Set to None if segment split is invalid (e.g. too short). + + Additional diagnostics: + - curvature_ratio_forecast_vs_history: compares second-difference energy of Z in forecast vs history. + - latent_diag_mahalanobis_ratio_forecast_vs_history: compares a diagonal-Mahalanobis latent distance + in forecast vs history (OOD shift indicator). + + Feature-axis (v2) outputs (populated only when ``explain_forecast`` is + called with ``channel_axis=True``): + - per_channel_flow: [T-1, C] -- per-channel decomposition of latent + flow (phi_tau(c)). + - lag_channel_horizon_scores: [K, C, H] -- joint score tensor before + normalization. + - lag_channel_horizon_attributions: [K, C, H] -- softmax-normalized + joint lag x channel x horizon attribution. + - channel_horizon_attributions: [C, H] -- channel-marginal of the + joint attribution; suitable for feature-axis evaluations. + - channel_flow_method: which Jacobian estimator produced the above. + - channel_flow_residual_ratio_mean / _p95: trust-region diagnostic for + the Jacobian variant. ``|| Delta Z - sum_c Delta Z^(c) || / ||Delta Z||`` + averaged over transitions; lower is better. + """ + + baseline_forecast: Array + lag_horizon_scores: Array + lag_horizon_attributions: Array + flow_magnitudes: Array + latent_trajectory: Array + surrogate_coef: Array | None = None + surrogate_intercept: Array | None = None + surrogate_feature_layout: str | None = None + flow_ratio_forecast_vs_history: float | None = None + flow_variance_ratio_forecast_vs_history: float | None = None + curvature_ratio_forecast_vs_history: float | None = None + latent_diag_mahalanobis_ratio_forecast_vs_history: float | None = None + # v2 feature-axis outputs (None when channel_axis=False) + per_channel_flow: Array | None = None + lag_channel_horizon_scores: Array | None = None + lag_channel_horizon_attributions: Array | None = None + channel_horizon_attributions: Array | None = None + channel_flow_method: str | None = None + channel_flow_residual_ratio_mean: float | None = None + channel_flow_residual_ratio_p95: float | None = None + + +def _flow_segment_ratios( + flow_magnitudes: Array, # [T-1] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> tuple[float | None, float | None]: + """ + Compare flow in history vs forecast (OOD) segment to gauge attribution quality. + + The latent trajectory is built over [history; forecast]. Flow in the forecast segment + (windows that include model-generated future) can be noisier; higher ratio means + attributions that depend on that segment are more likely to be volatile. + + Returns: + (flow_ratio, variance_ratio): mean(flow_forecast)/mean(flow_history) and + var(flow_forecast)/var(flow_history). None if segment split is invalid. + """ + m = np.asarray(flow_magnitudes, dtype=np.float32) + m = np.where(np.isfinite(m), m, np.nan) + L = int(context_len) + H = int(forecast_horizon) + if L <= 0 or H <= 0 or m.shape[0] < L + H - 1: + return None, None + # History: transitions 0..L-2 (windows purely in history) + m_hist = m[0 : L - 1] + # Forecast: transitions L-1..L+H-2 (windows extending into forecast) + m_fcst = m[L - 1 : L + H - 1] + if m_hist.size == 0 or m_fcst.size == 0: + return None, None + mean_hist = float(np.nanmean(m_hist)) + eps + mean_fcst = float(np.nanmean(m_fcst)) + eps + flow_ratio = mean_fcst / mean_hist + var_hist = float(np.nanvar(m_hist)) + eps + var_fcst = float(np.nanvar(m_fcst)) + eps + var_ratio = var_fcst / var_hist + return flow_ratio, var_ratio + + +def _curvature_segment_ratio( + Z: Array, # [T, D] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> float | None: + """ + Curvature/jitter diagnostic: ratio of second-difference energy in forecast vs history. + + Define curvature per step: + c_t = ||Z_{t+2} - 2 Z_{t+1} + Z_t||_2, t=0..T-3. + + Returns: + mean(c in forecast segment) / mean(c in history segment), or None if invalid split. + """ + Z = np.asarray(Z, dtype=np.float32) + if Z.ndim != 2 or Z.shape[0] < 3: + return None + T = Z.shape[0] + L = int(context_len) + H = int(forecast_horizon) + if L <= 1 or H <= 0 or T < L + H: + return None + # second differences live on indices 0..T-3; segment boundary at latent index L-1. + dd = Z[2:] - 2.0 * Z[1:-1] + Z[:-2] # [T-2, D] + c = np.linalg.norm(dd, ord=2, axis=1) + c = np.where(np.isfinite(c), c, np.nan) + + # history curvature uses steps fully before boundary: t=0..(L-3) + c_hist = c[0 : max(0, L - 2)] + # forecast curvature uses steps starting at boundary: t=(L-2)..(L+H-3) (clipped) + c_fcst = c[max(0, L - 2) : min(c.shape[0], L + H - 2)] + if c_hist.size == 0 or c_fcst.size == 0: + return None + return (float(np.nanmean(c_fcst)) + eps) / (float(np.nanmean(c_hist)) + eps) + + +def _latent_diag_mahalanobis_ratio( + Z: Array, # [T, D] + context_len: int, + forecast_horizon: int, + eps: float = 1e-12, +) -> float | None: + """ + OOD shift diagnostic: compare diagonal-Mahalanobis distance of latents in forecast vs history. + + Fit (mu, var) on history latents Z[0:L], then compute: + d2(z) = sum_i ( (z_i - mu_i)^2 / (var_i + eps) ) + Return mean(d2 in forecast latents) / mean(d2 in history latents). + """ + Z = np.asarray(Z, dtype=np.float32) + if Z.ndim != 2: + return None + T = Z.shape[0] + L = int(context_len) + H = int(forecast_horizon) + if L <= 1 or H <= 0 or T < L + H: + return None + + Z_hist = Z[:L] + Z_fcst = Z[L : L + H] + if Z_hist.shape[0] < 2 or Z_fcst.shape[0] < 1: + return None + + mu = np.nanmean(np.where(np.isfinite(Z_hist), Z_hist, np.nan), axis=0) + var = np.nanvar(np.where(np.isfinite(Z_hist), Z_hist, np.nan), axis=0) + var = np.where(np.isfinite(var) & (var > 1e-8), var, 1.0).astype(np.float32) + + def d2(A: Array) -> Array: + A = np.where(np.isfinite(A), A, np.nan) + return np.nansum( + ((A - mu[None, :]) ** 2) / (var[None, :] + eps), axis=1 + ) + + d2_hist = d2(Z_hist) + d2_fcst = d2(Z_fcst) + if not np.isfinite(d2_hist).any() or not np.isfinite(d2_fcst).any(): + return None + return (float(np.nanmean(d2_fcst)) + eps) / ( + float(np.nanmean(d2_hist)) + eps + ) + + +def _softmax(x: Array, axis: int = 0, eps: float = 1e-12) -> Array: + x = x - np.max(x, axis=axis, keepdims=True) + ex = np.exp(x) + den = np.sum(ex, axis=axis, keepdims=True) + return ex / np.maximum(den, eps) + + +def _as_numpy(x: Any) -> Array: + if isinstance(x, np.ndarray): + return x + if isinstance(x, torch.Tensor): + return x.detach().cpu().numpy() + return np.asarray(x) + + +@torch.no_grad() +def _forecast_autoregressive( + model: ForecastModel, + x_enc: torch.Tensor, + input_mask: torch.Tensor, + *, + model_horizon: int, + target_horizon: int, +) -> Array: + """ + Autoregressive forecasting (batched) to extend beyond model's native horizon. + + Returns: numpy array [B, C, target_horizon] + """ + if target_horizon <= 0: + raise ValueError('target_horizon must be positive') + if model_horizon <= 0: + raise ValueError('model_horizon must be positive') + + B, C, seq_len = x_enc.shape + device = x_enc.device + + def _finite_forecast(value: Array, *, stage: str) -> Array: + value = np.asarray(value, dtype=np.float32) + if not np.isfinite(value).all(): + n_bad = int((~np.isfinite(value)).sum()) + raise FloatingPointError( + f'Model forecast produced {n_bad} non-finite value(s) during {stage}' + ) + return value + + if target_horizon <= model_horizon: + with torch.amp.autocast('cuda', enabled=device.type == 'cuda'): + out = model(x_enc=x_enc, input_mask=input_mask) + forecast = _as_numpy(out.forecast[:, :, :target_horizon]).astype( + np.float32, copy=False + ) + return _finite_forecast(forecast, stage='direct forecasting') + + num_iters = int(np.ceil(target_horizon / model_horizon)) + cur_x = x_enc.clone() + cur_mask = input_mask.clone() + preds_chunks: list[Array] = [] + remaining = target_horizon + + for _ in range(num_iters): + with torch.amp.autocast('cuda', enabled=device.type == 'cuda'): + out = model(x_enc=cur_x, input_mask=cur_mask) + chunk = out.forecast.detach() + if not bool(torch.isfinite(chunk).all()): + n_bad = int((~torch.isfinite(chunk)).sum().item()) + raise FloatingPointError( + f'Model forecast produced {n_bad} non-finite value(s) during autoregressive forecasting' + ) + steps = min(model_horizon, remaining) + chunk_trimmed = chunk[:, :, :steps] + preds_chunks.append( + chunk_trimmed.to(device='cpu', dtype=torch.float32).numpy() + ) + remaining -= steps + if remaining <= 0: + break + + extended = torch.cat([cur_x, chunk_trimmed], dim=2) + cur_x = extended[:, :, -seq_len:] + cur_mask = torch.ones(B, seq_len, dtype=cur_mask.dtype, device=device) + + return np.concatenate(preds_chunks, axis=2).astype(np.float32, copy=False) + + +def _channel_replacement_rows(arr_cl: Array, *, replacement: str) -> Array: + arr = np.asarray(arr_cl, dtype=np.float32) + C, L = arr.shape + if replacement == 'zero': + return np.zeros((C, L), dtype=np.float32) + if replacement == 'local_mean': + return np.repeat( + arr.mean(axis=1, keepdims=True).astype(np.float32), L, axis=1 + ) + raise ValueError(f'Unsupported replacement={replacement!r}') + + +def compute_target_channel_input_jacobian_importance( + model: ForecastModel, + *, + x_context_ct: Array, + input_mask_l: Array, + device: torch.device, + target_channel: int, + model_horizon: int, + forecast_horizon: int, + replacement: Literal['local_mean', 'zero'] = 'local_mean', + forecast_batch_size: int = 8, + finite_difference_scale: float = 0.1, + prefer_autograd: bool = True, +) -> Array: + """Target-specific directional replacement effect by channel and horizon.""" + arr = np.asarray(x_context_ct, dtype=np.float32) + if arr.ndim != 2: + raise ValueError(f'Expected x_context_ct [C,L], got {arr.shape}') + C, L = arr.shape + H = int(forecast_horizon) + target = int(target_channel) + if not (0 <= target < C): + raise ValueError(f'target_channel out of range for C={C}: {target}') + mask = np.asarray(input_mask_l, dtype=np.int64) + if mask.shape != (L,): + raise ValueError( + f'Expected input_mask_l shape {(L,)}, got {mask.shape}' + ) + + baseline = _channel_replacement_rows(arr, replacement=str(replacement)) + delta = arr - baseline + active_direction = np.any(np.abs(delta) > 1e-12, axis=1) + + if prefer_autograd: + delta_t = torch.from_numpy(delta[None]).to( + device=device, dtype=torch.float32 + ) + x_t = ( + torch.from_numpy(arr[None]) + .to(device=device, dtype=torch.float32) + .requires_grad_(True) + ) + m_t = torch.from_numpy(mask[None]).to(device=device, dtype=torch.long) + with torch.enable_grad(): + out = model(x_enc=x_t, input_mask=m_t) + forecast = out.forecast[:, target, :H] + if forecast.shape[-1] < H: + raise ValueError( + f'Model returned horizon={forecast.shape[-1]}, expected at least {H}' + ) + if forecast.requires_grad: + importance = np.zeros((C, H), dtype=np.float32) + input_is_connected = True + for h in range(H): + grad = torch.autograd.grad( + forecast[:, h].sum(), + x_t, + retain_graph=h < H - 1, + create_graph=False, + allow_unused=True, + )[0] + if grad is None: + input_is_connected = False + break + score_c = (grad * delta_t).sum(dim=-1).abs()[0] + active_t = torch.as_tensor( + active_direction, + dtype=torch.bool, + device=score_c.device, + ) + score_c = torch.where( + active_t, score_c, torch.zeros_like(score_c) + ) + importance[:, h] = ( + score_c.detach().cpu().numpy().astype(np.float32) + ) + if input_is_connected: + importance[target, :] = 0.0 + if not np.isfinite(importance).all(): + n_bad = int((~np.isfinite(importance)).sum()) + raise FloatingPointError( + f'Jacobian attribution produced {n_bad} non-finite value(s)' + ) + return importance.astype(np.float32, copy=False) + + eps = float(finite_difference_scale) + if not (0.0 < eps <= 1.0): + raise ValueError( + f'finite_difference_scale must be in (0, 1], got {finite_difference_scale}' + ) + importance = np.zeros((C, H), dtype=np.float32) + chans = [c for c in range(C) if c != target] + channel_batch = max(1, int(forecast_batch_size) // 2) + for start in range(0, len(chans), channel_batch): + chunk = chans[start : start + channel_batch] + stack = np.broadcast_to(arr[None], (2 * len(chunk), C, L)).copy() + for i, c in enumerate(chunk): + stack[i, c, :] = arr[c, :] - eps * delta[c, :] + stack[len(chunk) + i, c, :] = arr[c, :] + eps * delta[c, :] + masks = np.broadcast_to(mask[None], (2 * len(chunk), L)).copy() + xb = torch.from_numpy(stack).to(device=device, dtype=torch.float32) + mb = torch.from_numpy(masks).to(device=device, dtype=torch.long) + yb = _forecast_autoregressive( + model, + xb, + mb, + model_horizon=int(model_horizon), + target_horizon=H, + )[:, target, :] + yb = np.asarray(yb, dtype=np.float32) + effects = np.abs(yb[len(chunk) :] - yb[: len(chunk)]) / (2.0 * eps) + for i, c in enumerate(chunk): + importance[c, :] = effects[i] + if not np.isfinite(importance).all(): + n_bad = int((~np.isfinite(importance)).sum()) + raise FloatingPointError( + f'Finite-difference attribution produced {n_bad} non-finite value(s)' + ) + return importance.astype(np.float32, copy=False) + + +@torch.no_grad() +def _embed_batch( + model: ForecastModel, x_enc: torch.Tensor, input_mask: torch.Tensor +) -> Array: + out = model.embed(x_enc=x_enc, input_mask=input_mask) + if not hasattr(out, 'embeddings') or out.embeddings is None: + raise RuntimeError('model.embed(...) did not return `.embeddings`') + return _as_numpy(out.embeddings).astype(np.float32) + + +def _sliding_window_view( + a: Array, window_shape: int, *, axis: int = 0 +) -> Array: + try: + from numpy.lib.stride_tricks import sliding_window_view # type: ignore[attr-defined] + except Exception: + from numpy.lib.stride_tricks import as_strided + + def sliding_window_view( + a: Array, window_shape: int, *, axis: int = 0 + ) -> Array: + if axis != 0: + raise ValueError( + 'fallback sliding_window_view only supports axis=0' + ) + a = np.asarray(a) + n = a.shape[0] + w = int(window_shape) + if w <= 0 or w > n: + raise ValueError('invalid window_shape') + shape = (n - w + 1, w) + a.shape[1:] + strides = (a.strides[0],) + a.strides + return as_strided(a, shape=shape, strides=strides) + + return sliding_window_view(a, window_shape=window_shape, axis=axis) + + +def _rolling_window_sources( + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask (1=real,0=pad/missing) +) -> tuple[Array, Array, int]: + """ + Prepare rolling-window views used to materialize batches on demand. + """ + if series_ct.ndim != 2: + raise ValueError(f'Expected series [C,T], got shape {series_ct.shape}') + _, T = series_ct.shape + L = int(seq_len) + if L <= 0: + raise ValueError('seq_len must be positive') + + mask_t = None + if input_mask_t is not None: + mask_t = np.asarray(input_mask_t, dtype=np.int64).reshape(-1) + if mask_t.shape != (T,): + raise ValueError( + f'Expected input_mask_t shape {(T,)}, got {mask_t.shape}' + ) + if T == 0: + C = int(series_ct.shape[0]) + return ( + np.zeros((0, C, L), dtype=np.float32), + np.zeros((0, L), dtype=np.int64), + 0, + ) + + x = np.asarray(series_ct, dtype=np.float32) + pad = L - 1 + if pad > 0: + x_pad = np.pad( + x, + ((0, 0), (pad, 0)), + mode='constant', + constant_values=np.float32(0.0), + ) + else: + x_pad = x + x_view = _sliding_window_view(x_pad, window_shape=L, axis=1) + xw_view = np.transpose(x_view, (1, 0, 2)) + + if mask_t is None: + mask_src = np.ones((T,), dtype=np.int64) + else: + mask_src = mask_t.astype(np.int64, copy=False) + if pad > 0: + mask_pad = np.pad( + mask_src, (pad, 0), mode='constant', constant_values=np.int64(0) + ) + else: + mask_pad = mask_src + m_view = _sliding_window_view(mask_pad, window_shape=L, axis=0) + return xw_view, m_view, T + + +def _rolling_window_batch( + xw_view: Array, + m_view: Array, + *, + start: int, + stop: int, +) -> tuple[Array, Array]: + """ + Build only the requested rolling windows [start:stop]. + + Returns sliced views when possible so callers can defer materialization until + they actually need contiguous/writable arrays (for example at torch conversion). + """ + start_i = max(0, int(start)) + stop_i = max(start_i, int(stop)) + batch = stop_i - start_i + C = int(xw_view.shape[1]) if xw_view.ndim >= 2 else 0 + L = int(xw_view.shape[2]) if xw_view.ndim >= 3 else 0 + if batch == 0: + return np.zeros((0, C, L), dtype=np.float32), np.zeros( + (0, L), dtype=np.int64 + ) + return ( + np.asarray(xw_view[start_i:stop_i], dtype=np.float32), + np.asarray(m_view[start_i:stop_i], dtype=np.int64), + ) + + +def _rolling_windows( + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask (1=real,0=pad/missing) +) -> tuple[Array, Array]: + """ + Build rolling model-input windows for every time index. + + Returns: + x_windows: [T, C, seq_len] + masks: [T, seq_len] + """ + L = int(seq_len) + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=L, input_mask_t=input_mask_t + ) + if T == 0: + C = int(np.asarray(series_ct).shape[0]) + return np.zeros((0, C, L), dtype=np.float32), np.zeros( + (0, L), dtype=np.int64 + ) + x_batch, m_batch = _rolling_window_batch(xw_view, m_view, start=0, stop=T) + return np.ascontiguousarray(x_batch), np.ascontiguousarray(m_batch) + + +def extract_latent_trajectory( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array + | None = None, # [T] optional observed mask for the series + device: torch.device, + batch_size: int = 32, +) -> Array: + """ + Latent Representation Interface (model-agnostic): + - Builds a latent state Z_t for each time t by embedding the last `seq_len` values up to t. + + Returns: Z [T, D] + """ + xw_view, m_view, T = _rolling_window_sources( + series_ct, seq_len=seq_len, input_mask_t=input_mask_t + ) + if T == 0: + return np.zeros((0, 0), dtype=np.float32) + Z_chunks: list[Array] = [] + for i in range(0, T, batch_size): + x_batch, m_batch = _rolling_window_batch( + xw_view, m_view, start=i, stop=i + batch_size + ) + xb = torch.from_numpy(np.ascontiguousarray(x_batch)).to( + device=device, dtype=torch.float32 + ) + mb = torch.from_numpy(np.ascontiguousarray(m_batch)).to( + device=device, dtype=torch.long + ) + Z_chunks.append(_embed_batch(model, xb, mb)) + Z = np.concatenate(Z_chunks, axis=0) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 before downstream computation.', + UserWarning, + stacklevel=2, + ) + Z = np.nan_to_num(Z, nan=0.0, posinf=0.0, neginf=0.0).astype(np.float32) + return Z + + +def _signed_states(values_td: Array, *, deadband: float) -> np.ndarray: + states = np.zeros(values_td.shape, dtype=np.int8) + states[values_td > deadband] = 1 + states[values_td < -deadband] = -1 + return states + + +def _state_change_rate(states_td: np.ndarray) -> np.ndarray: + if states_td.ndim != 2: + raise ValueError(f'Expected states [T,D], got shape {states_td.shape}') + if states_td.shape[0] < 2: + return np.full((states_td.shape[1],), np.nan, dtype=np.float32) + prev = states_td[:-1] + cur = states_td[1:] + valid = (prev != 0) & (cur != 0) + changed = (prev != cur) & valid + denom = np.sum(valid, axis=0).astype(np.float32) + numer = np.sum(changed, axis=0).astype(np.float32) + out = np.full((states_td.shape[1],), np.nan, dtype=np.float32) + nonzero = denom > 0 + out[nonzero] = numer[nonzero] / denom[nonzero] + return out + + +def _safe_mean_and_p95(values_d: Array) -> tuple[float, float]: + vals = np.asarray(values_d, dtype=np.float32).reshape(-1) + finite = vals[np.isfinite(vals)] + if finite.size == 0: + return float('nan'), float('nan') + return float(np.mean(finite)), float(np.percentile(finite, 95)) + + +def summarize_trajectory_stability( + Z_td: Array, + *, + reference_mask_t: Array | None = None, + reference_mode: Literal['mean', 'median'] = 'mean', + normalize: bool = True, + zero_band: float = 0.05, + eps: float = 1e-8, +) -> TrajectoryStabilityReport: + """ + Quantify how often a latent trajectory oscillates around its reference state. + + We center each latent dimension by a reference vector, optionally divide by its + reference-segment standard deviation, then compute: + - zero-crossing rate: how often the trajectory changes sign around the reference + - direction-flip rate: how often consecutive step directions reverse + - relative jitter: mean absolute step size divided by mean absolute level + - occupancy: fraction of time spent above/below the centered reference + """ + Z = np.asarray(Z_td, dtype=np.float32) + if Z.ndim != 2: + raise ValueError( + f'Expected latent trajectory [T,D], got shape {Z.shape}' + ) + if Z.shape[0] < 2: + raise ValueError( + 'Need at least two latent states to summarize trajectory stability' + ) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 for trajectory stability.', + UserWarning, + stacklevel=2, + ) + Z = np.where(np.isfinite(Z), Z, 0.0).astype(np.float32) + + T, D = Z.shape + if reference_mask_t is None: + ref_mask = np.ones((T,), dtype=bool) + else: + ref_mask = np.asarray(reference_mask_t, dtype=bool).reshape(-1) + if ref_mask.shape != (T,): + raise ValueError( + f'Expected reference_mask_t shape {(T,)}, got {ref_mask.shape}' + ) + if not np.any(ref_mask): + ref_mask = np.ones((T,), dtype=bool) + Z_ref = Z[ref_mask] + + if reference_mode == 'mean': + center = np.mean(Z_ref, axis=0, dtype=np.float32) + else: + center = np.median(Z_ref, axis=0).astype(np.float32) + + Z_centered = Z - center[None, :] + if normalize: + scale = np.std(Z_ref, axis=0).astype(np.float32) + scale[scale < eps] = 1.0 + Z_centered = Z_centered / scale[None, :] + + states = _signed_states(Z_centered, deadband=float(zero_band)) + zero_crossing_rate_d = _state_change_rate(states) + + deltas = Z_centered[1:] - Z_centered[:-1] + delta_states = _signed_states(deltas, deadband=float(zero_band)) + direction_flip_rate_d = _state_change_rate(delta_states) + + level_mag = np.mean(np.abs(Z_centered), axis=0) + step_mag = np.mean(np.abs(deltas), axis=0) + relative_jitter_d = step_mag / (level_mag + float(eps)) + + return TrajectoryStabilityReport( + zero_crossing_rate_mean=_safe_mean_and_p95(zero_crossing_rate_d)[0], + zero_crossing_rate_p95=_safe_mean_and_p95(zero_crossing_rate_d)[1], + direction_flip_rate_mean=_safe_mean_and_p95(direction_flip_rate_d)[0], + direction_flip_rate_p95=_safe_mean_and_p95(direction_flip_rate_d)[1], + relative_jitter_mean=_safe_mean_and_p95(relative_jitter_d)[0], + relative_jitter_p95=_safe_mean_and_p95(relative_jitter_d)[1], + occupancy_positive_mean=float(np.mean(Z_centered > float(zero_band))), + occupancy_negative_mean=float(np.mean(Z_centered < -float(zero_band))), + n_time_steps=int(T), + n_dimensions=int(D), + ) + + +@torch.no_grad() +def compute_trajectory_stability( + model: ForecastModel, + series_ct: Array, # [C, T] + *, + seq_len: int, + input_mask_t: Array | None = None, + device: torch.device, + batch_size: int = 32, + reference_mode: Literal['mean', 'median'] = 'mean', + normalize: bool = True, + zero_band: float = 0.05, + eps: float = 1e-8, +) -> TrajectoryStabilityReport: + """ + Build the latent trajectory for a series and summarize its temporal smoothness. + """ + Z = extract_latent_trajectory( + model, + series_ct, + seq_len=seq_len, + input_mask_t=input_mask_t, + device=device, + batch_size=batch_size, + ) + return summarize_trajectory_stability( + Z, + reference_mask_t=input_mask_t, + reference_mode=reference_mode, + normalize=normalize, + zero_band=zero_band, + eps=eps, + ) + + +def _smooth_latent_trajectory(Z: Array, alpha: float) -> Array: + """ + EMA along time (returns new array): + Z_smooth[t] = alpha * Z_smooth[t-1] + (1-alpha) * Z[t] + with the first row unchanged. + + Uses a vectorized closed form for speed on large [T, D] arrays and falls + back to the sequential recurrence if alpha is so extreme that the power + scaling becomes numerically unstable. + """ + if Z.shape[0] < 2 or alpha <= 0 or alpha >= 1: + return Z + + out = np.asarray(Z, dtype=np.float32).copy() + T = out.shape[0] + alpha_f = float(alpha) + + # Closed form: + # y[t] = alpha^t * (x[0] + (1-alpha) * sum_{k=1}^t x[k] / alpha^k) + # This avoids the Python O(T) recurrence loop while preserving the exact EMA. + idx = np.arange(1, T, dtype=np.float64) + with np.errstate(over='ignore', under='ignore', invalid='ignore'): + pow_alpha = np.power(alpha_f, idx) + inv_pow_alpha = np.power(alpha_f, -idx) + + if np.all(np.isfinite(pow_alpha)) and np.all(np.isfinite(inv_pow_alpha)): + scaled = out[1:].astype(np.float64, copy=False) * inv_pow_alpha[:, None] + csum = np.cumsum(scaled, axis=0, dtype=np.float64) + out[1:] = ( + pow_alpha[:, None] + * ( + out[0].astype(np.float64, copy=False)[None, :] + + (1.0 - alpha_f) * csum + ) + ).astype(np.float32) + return out + + for t in range(1, T): + out[t] = alpha_f * out[t - 1] + (1.0 - alpha_f) * out[t] + return out + + +def compute_semantic_flow_magnitudes( + Z: Array, + cfg: SemanticFlowConfig, + dy_dZ: Array | None = None, +) -> Array: + """ + Semantic Flow Computation Unit: + - Computes a per-step scalar flow magnitude from consecutive latent states. + + If SemanticFlowConfig.smooth_latent_alpha is in (0, 1), applies EMA smoothing to Z + before computing flow (Lipschitz-like regularization when embeddings are noisy). + + For flow_kind 'output_aware': requires dy_dZ. Then + m_t = |(∂y/∂Z_t)(Z_{t+1}-Z_t)| (first-order effect of latent step on forecast). + dy_dZ must have shape (T, D) or (T, H, D). T must match Z.shape[0]. If (T, H, D), + magnitudes are aggregated over horizons using output_aware_aggregation. Assumptions: + forecast (or surrogate) is differentiable w.r.t. Z_t and depends on more than Z_{L-1} + for non-degenerate lag resolution. + + Returns: m [T-1] + """ + if Z.ndim != 2: + raise ValueError(f'Expected Z [T,D], got shape {Z.shape}') + if Z.shape[0] < 2: + raise ValueError('Need at least two latent states to compute flow.') + + T, D = Z.shape + + # Optional temporal smoothing of latent trajectory + if 0 < cfg.smooth_latent_alpha < 1: + Z = _smooth_latent_trajectory(Z, cfg.smooth_latent_alpha) + + # Sanitize NaN in latent trajectory (e.g. from embed on out-of-distribution windows) + if np.any(~np.isfinite(Z)): + warnings.warn( + 'Latent trajectory Z contains non-finite values (NaN/inf); replacing with 0 for flow computation. ' + 'This can happen when the model embeds windows that include forecast values.', + UserWarning, + stacklevel=2, + ) + Z = np.where(np.isfinite(Z), Z, 0.0).astype(np.float32) + + d = Z[1:] - Z[:-1] # [T-1, D] + + if cfg.flow_kind == 'output_aware': + if dy_dZ is None: + raise ValueError( + "flow_kind='output_aware' requires dy_dZ (gradient of forecast w.r.t. Z_t)." + ) + dy_dZ = np.asarray(dy_dZ, dtype=np.float32) + if dy_dZ.shape[0] != T: + raise ValueError( + f'dy_dZ.shape[0] must equal Z.shape[0] ({T}), got {dy_dZ.shape[0]}' + ) + if dy_dZ.ndim == 2: + # [T, D] => scalar effect per step: m_t = |dy_dZ[t] @ delta_t| + if dy_dZ.shape[1] != D: + raise ValueError( + f'dy_dZ shape [T,D] expects D={D}, got {dy_dZ.shape[1]}' + ) + # m_t = |dy_dZ[t] @ d[t]| for t = 0..T-2; we need dy_dZ at indices 0..T-2 (first T-1 rows) + grad_t = dy_dZ[:-1] # [T-1, D] + dot = np.sum(grad_t * d, axis=1) # [T-1] + m = np.abs(dot).astype(np.float32) + elif dy_dZ.ndim == 3: + # [T, H, D] => aggregate over horizons + H = dy_dZ.shape[1] + if dy_dZ.shape[2] != D: + raise ValueError( + f'dy_dZ shape [T,H,D] expects D={D}, got {dy_dZ.shape[2]}' + ) + grad_t = dy_dZ[:-1] # [T-1, H, D] + # dot[t,h] = grad_t[t,h] @ d[t] + dot = np.einsum('thd,td->th', grad_t, d) # [T-1, H] + if cfg.output_aware_aggregation == 'l2': + m = np.sqrt(np.sum(dot**2, axis=1)).astype(np.float32) + else: + m = np.sum(np.abs(dot), axis=1).astype(np.float32) + else: + raise ValueError( + f'dy_dZ must be 2D [T,D] or 3D [T,H,D], got shape {dy_dZ.shape}' + ) + if np.any(~np.isfinite(m)): + m = np.where(np.isfinite(m), m, 0.0).astype(np.float32) + return m + + if cfg.flow_kind != 'delta_l2': + raise ValueError(f'Unsupported flow_kind={cfg.flow_kind}') + + delta = np.linalg.norm(d, ord=2, axis=1).astype(np.float32) + if np.any(~np.isfinite(delta)): + delta = np.where(np.isfinite(delta), delta, 0.0).astype(np.float32) + + if cfg.scale_weight > 0: + n0 = np.linalg.norm(Z[:-1], ord=2, axis=1) + n1 = np.linalg.norm(Z[1:], ord=2, axis=1) + ratio = (n1 + cfg.eps) / (n0 + cfg.eps) + ratio = np.clip(ratio, 1e-6, 1e6) + log_scale = np.abs(np.log(ratio)).astype(np.float32) + log_scale = np.clip(log_scale, 0.0, 10.0) + return delta + float(cfg.scale_weight) * log_scale + + return delta + + +def lag_horizon_attribution( + flow_magnitudes: Array, # [T-1] + *, + t_index: int, + n_lags: int, + horizon: int, + softmax_tau: float = 1.0, + horizon_kernel: Literal['exp', 'none'] = 'exp', + kernel_min_scale: float = 4.0, + kernel_max_scale: float | None = None, +) -> tuple[Array, Array]: + """ + Lag-Horizon Attribution Engine. + + We compute a lag x horizon score matrix from *history* flow magnitudes (transitions up to t_index), + then normalize horizon-wise with softmax over lags. + + Why history-only? + - The latent trajectory is built over [history; forecast]. The forecast part is model-generated (OOD). + Including forecast-segment flow in the lag-score adds a horizon-dependent *constant* across lags, + which makes the horizon-wise softmax identical across horizons (a degeneracy). + - For horizon-resolved explanations, we instead weight the history flow with a horizon-dependent kernel + so that far horizons can distribute weight over longer temporal scales. + + Returns: + scores: [K, H] (cumulative-flow score; larger => more influence) + attributions: [K, H] (softmax-normalized over lags for each horizon) + + Note: The attribution matrix is in general *full*, not upper triangular. Each lag j can + influence every horizon h, because we sum flow along the path from t-j to t+h; there is no + structural constraint that lag j only affects horizon h when h >= j. + """ + m = np.asarray(flow_magnitudes, dtype=np.float32).copy() + if np.any(~np.isfinite(m)): + warnings.warn( + 'flow_magnitudes contain non-finite values; replacing with 0 for attribution.', + UserWarning, + stacklevel=2, + ) + m = np.where(np.isfinite(m), m, 0.0).astype(np.float32) + + Tm = m.shape[0] # transitions count (Z length - 1) + K = int(n_lags) + H = int(horizon) + if K <= 0 or H <= 0: + raise ValueError('n_lags and horizon must be positive') + if not (0 <= t_index <= Tm): + raise ValueError(f't_index must be in [0,{Tm}], got {t_index}') + + # History transitions are indices 0..t_index-1 inclusive (count = t_index). + # A lag j uses the last j history transitions: p = (t_index-j) .. (t_index-1). + if t_index < 1: + raise ValueError( + 't_index must be >= 1 to attribute history flow to lags.' + ) + if t_index < K: + raise ValueError(f'n_lags must be <= t_index={t_index}, got {K}') + + # Horizon-dependent kernel over transition age a=0..K-1 (0=most recent history transition). + if horizon_kernel not in ('exp', 'none'): + raise ValueError(f'Unsupported horizon_kernel={horizon_kernel}') + min_s = float(kernel_min_scale) + max_s = ( + float(kernel_max_scale) if kernel_max_scale is not None else float(K) + ) + if min_s <= 0 or max_s <= 0: + raise ValueError( + 'kernel_min_scale and kernel_max_scale must be positive' + ) + max_s = max(max_s, min_s) + + scores = np.zeros((K, H), dtype=np.float32) + # Pre-slice history flow (length t_index). We only need last K steps for attribution. + hist = m[:t_index] # [t_index] + hist_tail = hist[max(0, t_index - K) : t_index] # [<=K], oldest..newest + # Reverse so index 0 = most recent, consistent with "age" + hist_rev = hist_tail[::-1].astype( + np.float32, copy=False + ) # [<=K], most recent..older + + # Vectorized horizon kernels. The previous implementation recomputed ages/weights/cumsum per horizon. + # Here we broadcast weights across horizons and compute all cumulative sums in one pass (chunked to + # cap memory when K*H is large). + L = int(hist_rev.shape[0]) + if H == 1: + scales_h = np.array([min_s], dtype=np.float32) + else: + u_h = (np.arange(H, dtype=np.float32) / float(H - 1)).astype( + np.float32 + ) # 0..1 + scales_h = (min_s + u_h * (max_s - min_s)).astype(np.float32) + + if horizon_kernel == 'none': + csum = np.cumsum(hist_rev, dtype=np.float32) # [L] + scores[:L, :] = csum[:, None] + else: + scales_h = np.maximum(scales_h, np.float32(1e-6)) + ages_l = np.arange(L, dtype=np.float32)[:, None] # [L,1] + + # Choose a horizon chunk size to keep the intermediate [L,chunk] weight matrix bounded. + # (float32 => 4 bytes per entry) + target_bytes = 64 * 1024 * 1024 # ~64MiB + bytes_per_h = max(1, L * 4) + chunk = int(max(1, min(H, target_bytes // bytes_per_h))) + + for h0 in range(0, H, chunk): + h1 = min(H, h0 + chunk) + s = scales_h[h0:h1][None, :] # [1,chunk] float32 + w_lh = np.exp(-ages_l / s) # [L,chunk] float32 + hw_lh = hist_rev[:, None] * w_lh + csum_lh = np.cumsum(hw_lh, axis=0, dtype=np.float32) # [L,chunk] + scores[:L, h0:h1] = csum_lh + + # Horizon-wise softmax over lags. + tau = max(float(softmax_tau), 1e-6) + zero_score_cols = np.all(scores == 0.0, axis=0) + if np.any(zero_score_cols): + warnings.warn( + f'{int(np.sum(zero_score_cols))} horizon(s) have all-zero lag scores; ' + 'returning uniform lag attributions for those columns.', + UserWarning, + stacklevel=2, + ) + attributions = _softmax(scores / tau, axis=0) + # If any column is all zero or had NaN, softmax can yield NaN; fallback to uniform + if np.any(~np.isfinite(attributions)): + uniform = np.ones((K, H), dtype=np.float32) / float(K) + attributions = np.where( + np.isfinite(attributions), attributions, uniform + ) + return scores, attributions + + +def _block_bootstrap( + series_ct: Array, *, block_len: int, rng: np.random.Generator +) -> Array: + C, L = series_ct.shape + b = max(1, int(block_len)) + n_blocks = int(np.ceil(L / b)) + out = np.empty((C, n_blocks * b), dtype=np.float32) + for i in range(n_blocks): + s = int(rng.integers(0, max(1, L - b + 1))) + out[:, i * b : (i + 1) * b] = series_ct[:, s : s + b] + return out[:, :L] + + +def _fourier_phase_preserving_noise( + series_ct: Array, *, amp_sigma: float, rng: np.random.Generator +) -> Array: + if amp_sigma <= 0: + return series_ct.astype(np.float32, copy=True) + + C, L = series_ct.shape + out = np.empty_like(series_ct, dtype=np.float32) + for c in range(C): + x = series_ct[c].astype(np.float32) + X = np.fft.rfft(x) + amp = np.abs(X) + phase = np.angle(X) + + # multiplicative log-amplitude noise keeps phase unchanged + noise = rng.normal( + loc=0.0, scale=float(amp_sigma), size=amp.shape + ).astype(np.float32) + amp2 = amp * np.exp(noise) + X2 = amp2 * np.exp(1j * phase) + x2 = np.fft.irfft(X2, n=L).real.astype(np.float32) + + # Match mean/std to original to avoid drift. + mu0, sd0 = float(x.mean()), float(x.std() + 1e-8) + mu1, sd1 = float(x2.mean()), float(x2.std() + 1e-8) + x2 = (x2 - mu1) * (sd0 / sd1) + mu0 + out[c] = x2 + return out + + +def generate_structure_preserving_perturbations( + x_context_ct: Array, cfg: PerturbationConfig +) -> Array: + """ + Generate perturbations that preserve temporal continuity and seasonality. + + Returns: samples [N, C, L] + """ + x0 = np.asarray(x_context_ct, dtype=np.float32) + if x0.ndim != 2: + raise ValueError(f'Expected x_context [C,L], got {x0.shape}') + C, L = x0.shape + + rng = np.random.default_rng(int(cfg.seed)) + out = np.empty((int(cfg.n_samples), C, L), dtype=np.float32) + mix = float(cfg.mix_original) + for i in range(int(cfg.n_samples)): + xb = _block_bootstrap(x0, block_len=cfg.block_len, rng=rng) + xf = _fourier_phase_preserving_noise( + xb, amp_sigma=cfg.fourier_amp_sigma, rng=rng + ) + out[i] = mix * x0 + (1.0 - mix) * xf + return out + + +def _weighted_standardize( + X: Array, w: Array, eps: float = 1e-12 +) -> tuple[Array, Array, Array]: + """ + Weighted standardization column-wise. + + Returns Xs, mean, std. + """ + w = w.reshape(-1, 1).astype(np.float32) + wsum = float(np.sum(w)) + eps + mu = np.sum(w * X, axis=0) / wsum + var = np.sum(w * (X - mu) ** 2, axis=0) / wsum + sd = np.sqrt(np.maximum(var, eps)) + return (X - mu) / sd, mu.astype(np.float32), sd.astype(np.float32) + + +def _ista_weighted_lasso( + X: Array, + y: Array, + w: Array, + *, + alpha: float, + max_iter: int, + tol: float, +) -> tuple[Array, float]: + """ + Weighted Lasso via ISTA: + min_b 1/2 ||sqrt(w) (X b - y)||^2 + alpha ||b||_1 + + Returns: + coef: [P] + intercept: scalar (computed in original space) + """ + X = np.asarray(X, dtype=np.float32) + y = np.asarray(y, dtype=np.float32).reshape(-1) + w = np.asarray(w, dtype=np.float32).reshape(-1) + if X.ndim != 2: + raise ValueError('X must be 2D') + n, p = X.shape + if y.shape[0] != n or w.shape[0] != n: + raise ValueError('Mismatched shapes between X, y, w') + + # Weighted standardize X; center y + Xs, mu_x, sd_x = _weighted_standardize(X, w) + wsum = float(np.sum(w)) + 1e-12 + mu_y = float(np.sum(w * y) / wsum) + yc = y - mu_y + + # Precompute for gradient with weights + sw = np.sqrt(np.maximum(w, 0.0)).astype(np.float32) + Xw = Xs * sw[:, None] + yw = yc * sw + + # Lipschitz constant of grad = ||Xw||_2^2 (spectral norm squared). + # Use power iteration on A=(Xw^T Xw) with a convergence check. + # Underestimating L makes ISTA steps too large; we also add backtracking below. + v = np.ones((p,), dtype=np.float32) / np.sqrt(max(1, p)) + power_tol = 1e-4 + max_power_iter = 100 + for _ in range(max_power_iter): + Av = Xw.T @ (Xw @ v) + nAv = float(np.linalg.norm(Av) + 1e-12) + v_next = (Av / nAv).astype(np.float32) + if float(np.linalg.norm(v_next - v)) <= power_tol: + v = v_next + break + v = v_next + Av = Xw.T @ (Xw @ v) + L = float(v @ Av) + if not np.isfinite(L) or L <= 0: + # Safe fallback bound: ||Xw||_F^2 >= ||Xw||_2^2 + L = float(np.sum(Xw.astype(np.float64) ** 2)) + 1e-12 + else: + L = L + 1e-12 + step = 1.0 / L + + def soft_threshold(a: Array, thr: float) -> Array: + return np.sign(a) * np.maximum(np.abs(a) - thr, 0.0) + + b = np.zeros((p,), dtype=np.float32) + last_obj = np.inf + max_backtrack = 25 + for _ in range(int(max_iter)): + r = Xw @ b - yw + grad = Xw.T @ r + obj_cur = 0.5 * float(r @ r) + float(alpha) * float(np.sum(np.abs(b))) + + # ISTA step; backtrack if objective fails to decrease (guards against L underestimation). + step_local = step + b_new = soft_threshold(b - step_local * grad, step_local * float(alpha)) + + # objective (for convergence check) + r2 = Xw @ b_new - yw + obj = 0.5 * float(r2 @ r2) + float(alpha) * float(np.sum(np.abs(b_new))) + bt = 0 + while (not np.isfinite(obj) or obj > obj_cur) and bt < max_backtrack: + step_local *= 0.5 + b_new = soft_threshold( + b - step_local * grad, step_local * float(alpha) + ) + r2 = Xw @ b_new - yw + obj = 0.5 * float(r2 @ r2) + float(alpha) * float( + np.sum(np.abs(b_new)) + ) + bt += 1 + + step = min(step, step_local) + if abs(last_obj - obj) <= float(tol) * max(1.0, last_obj): + b = b_new + break + b = b_new + last_obj = obj + + # Unstandardize: y ≈ mu_y + sum_j ( (x_j - mu_xj)/sd_xj ) * b_j + # => y ≈ (mu_y - sum_j mu_xj/sd_xj * b_j) + sum_j x_j * (b_j/sd_xj) + coef = (b / sd_x).astype(np.float32) + intercept = float(mu_y - np.sum((mu_x / sd_x) * b)) + return coef, intercept + + +def fit_horizon_surrogates( + model: ForecastModel, + *, + x_context_ct: Array, # [C, L] + input_mask_l: Array, # [L] + model_horizon: int, + forecast_horizon: int, + device: torch.device, + pert_cfg: PerturbationConfig, + surr_cfg: SurrogateConfig, + batch_size: int = 16, + n_jobs: int | None = None, +) -> tuple[Array, Array, str]: + """ + Local Surrogate Modeling Module. + + We fit a weighted sparse linear model per horizon h and channel c: + y_hat[c,h] ≈ intercept[c,h] + X_lags · coef[c,h,:] + + Features are lagged values of the context window: + X = flatten([C, K]) for last K lags (oldest->newest within that slice). + + Weights: + w_i = exp(-distance_lambda * ||Z_i - Z_0||^2) + where Z_i is an embedding of the (perturbed) context window. + """ + x0 = np.asarray(x_context_ct, dtype=np.float32) + C, L = x0.shape + K = int(surr_cfg.n_lags) + if K <= 0 or K > L: + raise ValueError(f'Surrogate n_lags must be in [1,{L}], got {K}') + + # Baseline embedding for weighting + x0_t = torch.from_numpy(x0[None, :, :]).to( + device=device, dtype=torch.float32 + ) + m0_t = torch.from_numpy( + np.asarray(input_mask_l[None, :], dtype=np.int64) + ).to(device=device, dtype=torch.long) + z0 = _embed_batch(model, x0_t, m0_t)[0] # [D] + + # Perturbations + samples = generate_structure_preserving_perturbations( + x0, pert_cfg + ) # [N, C, L] + N = samples.shape[0] + + # Build features from last K lags + X = samples[:, :, -K:] # [N,C,K] + X = X.reshape(N, C * K).astype(np.float32) # [N, P] + feature_layout = ( + f'flatten(C={C},lags={K}) with ordering [c0_lag0..lagK-1, c1_lag0..]' + ) + + # Embed perturbed samples for weights, and forecast to build y targets. + Z_list: list[Array] = [] + Y_list: list[Array] = [] + mask = np.asarray(input_mask_l, dtype=np.int64) + for i in range(0, N, batch_size): + xb = torch.from_numpy(samples[i : i + batch_size]).to( + device=device, dtype=torch.float32 + ) + mb = torch.from_numpy(np.tile(mask[None, :], (xb.shape[0], 1))).to( + device=device, dtype=torch.long + ) + Z_list.append(_embed_batch(model, xb, mb)) + Yb = _forecast_autoregressive( + model, + xb, + mb, + model_horizon=model_horizon, + target_horizon=forecast_horizon, + ) # [b,C,H] + Y_list.append(Yb) + + Z = np.concatenate(Z_list, axis=0) # [N,D] + Y = np.concatenate(Y_list, axis=0) # [N,C,H] + + # Local weights around baseline + dz = Z - z0[None, :] + dist2 = np.sum(dz * dz, axis=1).astype(np.float32) + w = ( + np.exp(-float(surr_cfg.distance_lambda) * dist2).astype(np.float32) + + 1e-12 + ) + + # Fit per horizon+channel. Each (c, h) regression is independent and + # CPU-bound (NumPy / BLAS), so we farm them out to a thread pool when + # ``n_jobs > 1``. ISTA's inner loops call into NumPy linalg which + # releases the GIL, so threads scale better than processes here and + # avoid pickling the (potentially large) shared X / w buffers. + H = int(forecast_horizon) + P = X.shape[1] + coef = np.zeros((C, H, P), dtype=np.float32) # [C,H,P] + intercept = np.zeros((C, H), dtype=np.float32) # [C,H] + + alpha = float(surr_cfg.l1_alpha) + max_iter = int(surr_cfg.max_iter) + tol = float(surr_cfg.tol) + + def _solve_one(args: tuple[int, int]) -> tuple[int, int, Array, float]: + c_idx, h_idx = args + b, a0 = _ista_weighted_lasso( + X, + Y[:, c_idx, h_idx], + w, + alpha=alpha, + max_iter=max_iter, + tol=tol, + ) + return c_idx, h_idx, b, a0 + + work_items = [(c, h) for c in range(C) for h in range(H)] + + # Default: 1 thread (matches historical behaviour). Callers that want + # the parallel path opt in via ``n_jobs`` (typically the OS CPU count + # divided by the number of GPU workers, so threads do not oversubscribe + # cores in a multi-GPU run). + if n_jobs is not None and int(n_jobs) > 1 and len(work_items) > 1: + from sdm_client.explain._parallel import parallel_apply_threads + + for c_idx, h_idx, b, a0 in parallel_apply_threads( + _solve_one, work_items, n_jobs=int(n_jobs) + ): + coef[c_idx, h_idx] = b + intercept[c_idx, h_idx] = a0 + else: + for item in work_items: + c_idx, h_idx, b, a0 = _solve_one(item) + coef[c_idx, h_idx] = b + intercept[c_idx, h_idx] = a0 + + return coef, intercept, feature_layout + + +def explain_forecast( + model: ForecastModel, + *, + x_context_ct: Array, # [C, L] + input_mask_l: Array, # [L] + model_horizon: int, + forecast_horizon: int, + device: torch.device, + n_lags: int = 128, + flow_cfg: SemanticFlowConfig | None = None, + softmax_tau: float = 1.0, + surrogate: bool = True, + pert_cfg: PerturbationConfig | None = None, + surr_cfg: SurrogateConfig | None = None, + latent_batch_size: int = 32, + surrogate_n_jobs: int | None = None, + # v2 feature-axis switches + channel_axis: bool = False, + chan_cfg: ChannelFlowConfig | None = None, # forward ref; imported lazily + channel_softmax_tau: float | None = None, + channel_output_aware: bool = False, + channel_target: int | None = None, +) -> ForecastExplanation: + """ + End-to-end interpretability pipeline: + 1) Forecast (for extension into the future) + 2) Latent trajectory extraction over [history + forecast] + 3) Semantic flow magnitudes + 4) Lag x Horizon attribution matrix + horizon-wise softmax + 5) Optional horizon-specific local surrogates with structure-preserving perturbations + + When ``channel_axis=True`` (and the input has C > 1 channels) we additionally + run the v2 feature-axis stages: per-channel Jacobian-flow decomposition + and joint lag x channel x horizon attribution. + + Pass ``chan_cfg`` to control the per-channel flow estimator. When + ``chan_cfg`` is None we default to ``ChannelFlowConfig()``, the fast O(C) + estimator suitable for routine use. + """ + flow_cfg = flow_cfg or SemanticFlowConfig() + pert_cfg = pert_cfg or PerturbationConfig() + if surr_cfg is None: + # Preserve existing behavior: cap surrogate lag features to 64 by default. + # Emit a warning so callers who set n_lags>64 aren't surprised. + if int(n_lags) > 64: + warnings.warn( + f'explain_forecast default SurrogateConfig caps n_lags to 64 ' + f'(got n_lags={int(n_lags)}). Pass surr_cfg=SurrogateConfig(n_lags=...) ' + f'to override.', + UserWarning, + stacklevel=2, + ) + surr_cfg = SurrogateConfig(n_lags=min(64, int(n_lags))) + K = int(n_lags) + + x0 = np.asarray(x_context_ct, dtype=np.float32) + if x0.ndim != 2: + raise ValueError(f'Expected x_context [C,L], got {x0.shape}') + C, L = x0.shape + if L < 2: + raise ValueError( + f'x_context must have length >= 2 for lag attribution, got L={L}' + ) + max_lags = L - 1 + if K <= 0 or max_lags < K: + raise ValueError(f'n_lags must be in [1,{max_lags}], got {K}') + + mask = np.asarray(input_mask_l, dtype=np.int64) + if mask.shape != (L,): + raise ValueError(f'Expected input_mask [L], got {mask.shape}') + + # --- 1) baseline forecast --- + x_t = torch.from_numpy(x0[None, :, :]).to( + device=device, dtype=torch.float32 + ) + m_t = torch.from_numpy(mask[None, :]).to(device=device, dtype=torch.long) + base = _forecast_autoregressive( + model, + x_t, + m_t, + model_horizon=int(model_horizon), + target_horizon=int(forecast_horizon), + )[0] # [C,H] + + # --- 2) build extended series and latent trajectory --- + series_ext = np.concatenate([x0, base], axis=1) # [C, L+H] + mask_ext = np.concatenate( + [mask, np.ones((int(forecast_horizon),), dtype=np.int64)], axis=0 + ) # [L+H] + Z = extract_latent_trajectory( + model, + series_ext, + seq_len=L, + input_mask_t=mask_ext, + device=device, + batch_size=latent_batch_size, + ) # [T,D] + + # --- 3) semantic flow magnitudes --- + m = compute_semantic_flow_magnitudes(Z, flow_cfg) # [T-1] + + # --- 3b) segment quality: forecast vs history flow (OOD volatility) --- + flow_ratio, flow_var_ratio = _flow_segment_ratios( + m, context_len=L, forecast_horizon=int(forecast_horizon) + ) + curvature_ratio = _curvature_segment_ratio( + Z, context_len=L, forecast_horizon=int(forecast_horizon) + ) + maha_ratio = _latent_diag_mahalanobis_ratio( + Z, context_len=L, forecast_horizon=int(forecast_horizon) + ) + + # --- 4) lag×horizon attribution --- + # t corresponds to last observed index in the context window. + t_index = L - 1 + scores, attrib = lag_horizon_attribution( + m, + t_index=t_index, + n_lags=K, + horizon=int(forecast_horizon), + softmax_tau=float(softmax_tau), + ) + + # --- 5) horizon-specific surrogates --- + coef = None + intercept = None + feature_layout = None + if surrogate: + coef, intercept, feature_layout = fit_horizon_surrogates( + model, + x_context_ct=x0, + input_mask_l=mask, + model_horizon=int(model_horizon), + forecast_horizon=int(forecast_horizon), + device=device, + pert_cfg=pert_cfg, + surr_cfg=surr_cfg, + n_jobs=surrogate_n_jobs, + ) + + # --- 6) v2 feature-axis stages (optional) --- + per_chan_flow = None + lag_chan_scores = None + lag_chan_attrib = None + chan_horizon_attrib = None + chan_method = None + chan_resid_mean = None + chan_resid_p95 = None + if channel_axis: + from sdm_client.explain._kumo_ts.channel_flow import ( # local import avoids circular dependency at module load + ChannelFlowConfig, + channel_horizon_marginal, + compute_per_channel_flow, + lag_channel_horizon_attribution, + ) + + chan_cfg_eff = chan_cfg if chan_cfg is not None else ChannelFlowConfig() + if channel_output_aware: + if channel_target is None: + raise ValueError( + 'channel_output_aware=True requires channel_target (the forecast ' + 'channel whose prediction the attribution should explain).' + ) + chan_horizon_attrib = ( + compute_target_channel_input_jacobian_importance( + model, + x_context_ct=x0, + input_mask_l=mask, + device=device, + target_channel=int(channel_target), + model_horizon=int(model_horizon), + forecast_horizon=int(forecast_horizon), + ) + ) + chan_method = 'target_input_jacobian' + else: + report = compute_per_channel_flow( + model, + series_ext, + seq_len=L, + input_mask_t=mask_ext, + device=device, + cfg=chan_cfg_eff, + ) + per_chan_flow = report.per_channel_flow + chan_method = report.method + chan_resid_mean = report.residual_ratio_mean + chan_resid_p95 = report.residual_ratio_p95 + chan_tau = ( + float(channel_softmax_tau) + if channel_softmax_tau is not None + else float(softmax_tau) + ) + lag_chan_scores, lag_chan_attrib = lag_channel_horizon_attribution( + per_chan_flow, + t_index=t_index, + n_lags=K, + horizon=int(forecast_horizon), + softmax_tau=chan_tau, + normalize='joint', + ) + chan_horizon_attrib = channel_horizon_marginal(lag_chan_attrib) + + return ForecastExplanation( + baseline_forecast=base, + lag_horizon_scores=scores, + lag_horizon_attributions=attrib, + flow_magnitudes=m, + latent_trajectory=Z, + surrogate_coef=coef, + surrogate_intercept=intercept, + surrogate_feature_layout=feature_layout, + flow_ratio_forecast_vs_history=flow_ratio, + flow_variance_ratio_forecast_vs_history=flow_var_ratio, + curvature_ratio_forecast_vs_history=curvature_ratio, + latent_diag_mahalanobis_ratio_forecast_vs_history=maha_ratio, + per_channel_flow=per_chan_flow, + lag_channel_horizon_scores=lag_chan_scores, + lag_channel_horizon_attributions=lag_chan_attrib, + channel_horizon_attributions=chan_horizon_attrib, + channel_flow_method=chan_method, + channel_flow_residual_ratio_mean=chan_resid_mean, + channel_flow_residual_ratio_p95=chan_resid_p95, + ) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py new file mode 100644 index 000000000..e8c4046a4 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py @@ -0,0 +1,1893 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/sdk/forecasting.py +# at af74798bbf7d020d3298f545fb9be383560a18ce: the pages of the forecast +# report, the artifacts written beside it, and the explanation as JSON. + +r"""Drawing a forecast explanation, as Kumo-TS draws it.""" + +from __future__ import annotations + +import json +import logging +import types +from contextlib import contextmanager +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +import numpy as np +import pandas as pd +import torch + +from sdm_client.explain._kumo_ts.channel_stability import ( + PerChannelEmbeddingStabilityReport, +) +from sdm_client.explain._kumo_ts.interpretability import ( + ForecastExplanation, + TrajectoryStabilityReport, +) + +# Module scope in the file these were taken from, and dropped by the move. +# Without them the integrated-gradients page and every warning path here +# raise NameError the moment they run. +logger = logging.getLogger(__name__) + + +def _save_lag_horizon_artifacts( + out_dir: Path, + attributions: np.ndarray, + scores: np.ndarray | None = None, + *, + na_rep: str = 'nan', +) -> Path | None: + """Write lag x horizon attribution CSVs and a heatmap PNG. + + Returns the path to the heatmap PNG if matplotlib is available, else None. + """ + K, H = attributions.shape + + lag_cols = [f'horizon_{h}' for h in range(H)] + df_matrix = pd.DataFrame(attributions, columns=lag_cols) + df_matrix.insert(0, 'lag', [f'lag_{j}' for j in range(K)]) + df_matrix.to_csv( + out_dir / 'lag_horizon_attributions.csv', index=False, na_rep=na_rep + ) + + rows = [] + for j in range(K): + for h in range(H): + row = { + 'lag': j, + 'horizon': h, + 'attribution': float(attributions[j, h]), + } + if scores is not None: + row['score'] = float(scores[j, h]) + rows.append(row) + pd.DataFrame(rows).to_csv( + out_dir / 'lag_horizon_long.csv', index=False, na_rep=na_rep + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + fig, ax = plt.subplots(figsize=(max(8, H * 0.15), max(6, K * 0.05))) + im = ax.imshow( + attributions, aspect='auto', cmap='viridis', interpolation='nearest' + ) + ax.set_xlabel('Forecast horizon') + ax.set_ylabel('Lag (past time step)') + ax.set_xticks(np.linspace(0, H - 1, min(12, H), dtype=int)) + ax.set_xticklabels(np.linspace(0, H - 1, min(12, H), dtype=int)) + ax.set_yticks(np.linspace(0, K - 1, min(12, K), dtype=int)) + ax.set_yticklabels(np.linspace(0, K - 1, min(12, K), dtype=int)) + plt.colorbar(im, ax=ax, label='Attribution') + plt.tight_layout() + heatmap_path = out_dir / 'lag_horizon_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _topk_lag_steps_per_horizon( + scores: np.ndarray, + *, + top_k: int = 5, +) -> tuple[np.ndarray | None, list[list[str]]]: + """Compute marginal per-step lag weights and produce top-k summary rows.""" + if scores.ndim != 2 or scores.shape[0] < 2 or scores.shape[1] < 1: + return None, [] + step_scores = np.vstack([scores[0:1, :], np.diff(scores, axis=0)]) + step_scores = step_scores - np.max(step_scores, axis=0, keepdims=True) + step_probs = np.exp(step_scores) + step_probs = step_probs / np.maximum( + np.sum(step_probs, axis=0, keepdims=True), 1e-12 + ) + + H = step_probs.shape[1] + rows: list[list[str]] = [] + for h in range(H): + order = np.argsort(-step_probs[:, h])[:top_k] + row: list[str] = [f'horizon_{h}'] + for idx in order: + lag_step = int(idx) + 1 + w = float(step_probs[idx, h]) + row.append(str(lag_step)) + row.append(f'{w:.4f}') + while len(row) < 1 + 2 * top_k: + row.extend(['', '']) + rows.append(row) + return step_probs, rows + + +def _semantic_flow_segments( + flow: np.ndarray, + *, + context_len: int, + forecast_horizon: int, +) -> tuple[np.ndarray, np.ndarray, int]: + """Split flow_magnitudes into (history, forecast) using the same convention as + ``interpretability._flow_segment_ratios``. + + Returns ``(history_flow, forecast_flow, boundary_index)`` where ``boundary_index`` + is the transition index that marks the first window touching the forecast segment. + """ + f = np.asarray(flow, dtype=np.float32).reshape(-1) + T_trans = int(f.shape[0]) + L = int(context_len) + H = int(forecast_horizon) + boundary = max(0, L - 1) + hist = f[0:boundary] if T_trans > 0 else f + fcst = f[boundary : min(T_trans, L + H - 1)] if T_trans > 0 else f + return hist, fcst, boundary + + +def _save_semantic_flow_csv( + out_dir: Path, + flow: np.ndarray, + *, + context_len: int, + forecast_horizon: int, + na_rep: str = 'nan', +) -> Path: + """Persist per-transition latent flow magnitudes with a segment label. + + Columns: ``transition_index, segment, flow_magnitude`` where ``segment`` is + ``"history"`` for transitions whose window sits inside the input context and + ``"forecast"`` for transitions whose window extends into the model-generated + future. Transitions outside both segments (only possible when ``T-1 > L+H-1``) + are labeled ``"tail"``. + """ + f = np.asarray(flow, dtype=np.float32).reshape(-1) + T_trans = int(f.shape[0]) + L = int(context_len) + H = int(forecast_horizon) + boundary = max(0, L - 1) + fcst_end = min(T_trans, L + H - 1) + + segments = np.full((T_trans,), 'tail', dtype=object) + segments[0:boundary] = 'history' + segments[boundary:fcst_end] = 'forecast' + + df = pd.DataFrame( + { + 'transition_index': np.arange(T_trans, dtype=np.int64), + 'segment': segments, + 'flow_magnitude': f, + } + ) + out_path = out_dir / 'semantic_flow.csv' + df.to_csv(out_path, index=False, na_rep=na_rep) + return out_path + + +def _semantic_flow_page( + pdf: Any, + plt: Any, + *, + explanation: ForecastExplanation, + context_len: int, + forecast_horizon: int, +) -> None: + """Append a single PDF page summarizing semantic flow magnitudes. + + Layout mirrors the trajectory-stability page: title, gray blurb, a primary + visual (line chart of flow over transitions with the history/forecast split + annotated), two side-by-side tables (per-segment summary + diagnostics), and + a monospace reading guide. + """ + if getattr(explanation, 'flow_magnitudes', None) is None: + return + flow = np.asarray(explanation.flow_magnitudes, dtype=np.float32).reshape(-1) + T_trans = int(flow.shape[0]) + if T_trans == 0: + return + + hist, fcst, boundary = _semantic_flow_segments( + flow, + context_len=context_len, + forecast_horizon=forecast_horizon, + ) + + def _stats(arr: np.ndarray) -> tuple[str, str, str, str, str, str]: + a = np.asarray(arr, dtype=np.float32) + a = a[np.isfinite(a)] + if a.size == 0: + return ('--', '--', '--', '--', '--', '0') + return ( + f'{float(np.mean(a)):.4f}', + f'{float(np.median(a)):.4f}', + f'{float(np.percentile(a, 95)):.4f}', + f'{float(np.max(a)):.4f}', + f'{float(np.var(a)):.4f}', + f'{int(a.size)}', + ) + + hist_s = _stats(hist) + fcst_s = _stats(fcst) + + def _fmt(x: Any) -> str: + if x is None: + return 'n/a' + try: + xv = float(x) + except (TypeError, ValueError): + return 'n/a' + return f'{xv:.4f}' if np.isfinite(xv) else 'n/a' + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Semantic flow magnitudes', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + r'Per-step latent flow is $m_t = \Vert \mathbf{z}_{t+1} - \mathbf{z}_t \Vert_2$' + ' over the trajectory built on\n' + '[history; forecast]. This is the temporal signal that drives the lag x horizon\n' + 'heatmap; bigger spikes contribute more to attribution. Compare the history\n' + 'segment against the forecast segment to gauge representation-level stability.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + ax = fig.add_axes((0.08, 0.55, 0.84, 0.23)) + x_axis = np.arange(T_trans) + ax.plot( + x_axis, flow, linewidth=1.0, color='#1f77b4', label='flow magnitude' + ) + if 0 < boundary < T_trans: + ax.axvspan(boundary, T_trans - 1, color='#f0f0f0', alpha=0.7, zorder=0) + ax.axvline( + boundary, + color='black', + linestyle='--', + linewidth=0.9, + label='history / forecast split', + ) + if hist.size > 0: + hist_mean = float(np.nanmean(hist)) + ax.hlines( + hist_mean, + 0, + max(0, boundary - 1), + colors='#2ca02c', + linestyles=':', + linewidth=1.2, + label=f'history mean ({hist_mean:.3f})', + ) + if fcst.size > 0: + fcst_mean = float(np.nanmean(fcst)) + fcst_end_idx = max( + boundary, + min(T_trans, int(context_len) + int(forecast_horizon) - 1) - 1, + ) + ax.hlines( + fcst_mean, + boundary, + fcst_end_idx, + colors='#d62728', + linestyles=':', + linewidth=1.2, + label=f'forecast mean ({fcst_mean:.3f})', + ) + ax.set_xlabel(r'Latent transition index ($t \rightarrow t+1$)') + ax.set_ylabel(r'$\Vert \mathbf{z}_{t+1} - \mathbf{z}_t \Vert_2$') + ax.legend(loc='upper right', fontsize=8, framealpha=0.85) + + seg_rows = [ + ['Mean', hist_s[0], fcst_s[0]], + ['Median', hist_s[1], fcst_s[1]], + ['P95', hist_s[2], fcst_s[2]], + ['Max', hist_s[3], fcst_s[3]], + ['Variance', hist_s[4], fcst_s[4]], + ['Transitions', hist_s[5], fcst_s[5]], + ] + ax_t1 = fig.add_axes((0.06, 0.32, 0.42, 0.18)) + ax_t1.axis('off') + table_seg = ax_t1.table( + cellText=seg_rows, + colLabels=['Metric', 'History', 'Forecast'], + colWidths=[0.4, 0.3, 0.3], + loc='upper center', + cellLoc='center', + ) + table_seg.auto_set_font_size(False) + table_seg.set_fontsize(8) + table_seg.scale(1.0, 1.3) + for c in range(3): + cell = table_seg[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + diag_rows = [ + [ + 'Flow ratio (forecast/history)', + _fmt(explanation.flow_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>1.5$ OOD-volatile', + ], + [ + 'Flow variance ratio', + _fmt(explanation.flow_variance_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>2$ noisy', + ], + [ + 'Curvature ratio', + _fmt(explanation.curvature_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $>1.5$ jaggy', + ], + [ + 'Latent diag-Mahalanobis ratio', + _fmt(explanation.latent_diag_mahalanobis_ratio_forecast_vs_history), + r'$\approx 1$ healthy, $\gg 1$ OOD shift', + ], + ] + ax_t2 = fig.add_axes((0.52, 0.32, 0.42, 0.18)) + ax_t2.axis('off') + table_diag = ax_t2.table( + cellText=diag_rows, + colLabels=['Diagnostic', 'Value', 'Heuristic'], + colWidths=[0.42, 0.18, 0.40], + loc='upper center', + cellLoc='center', + ) + table_diag.auto_set_font_size(False) + table_diag.set_fontsize(8) + table_diag.scale(1.0, 1.3) + for c in range(3): + cell = table_diag[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Per-segment table: mean / median / p95 / max / variance of latent\n' + ' flow magnitudes split into history (transitions fully inside the\n' + ' input window) and forecast (transitions whose window touches the\n' + ' model-generated future).\n' + ' - Flow ratio: average forecast flow divided by average history flow. Values\n' + " near 1 mean the model's latent dynamics in the OOD segment match history.\n" + ' Large values flag attributions in that region as likely noisy.\n' + ' - Flow variance ratio: same comparison on variance.\n' + ' - Curvature ratio: second-difference energy of Z; spikes when the\n' + ' forecast segment becomes much jaggier than history.\n' + ' - Latent diag-Mahalanobis ratio: per-dim distance of forecast latents\n' + ' from the history mean (scaled by history variance). Values well above 1 indicate a\n' + ' representation-level OOD shift.\n' + '\n' + 'These scalars are also under explanation.diagnostics in explanation.json,\n' + 'and the full series is exported as semantic_flow.csv.' + ) + fig.text( + 0.06, + 0.30, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + linespacing=1.05, + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _save_channel_axis_artifacts( + out_dir: Path, + channel_horizon_attributions: np.ndarray, + channel_labels: list[str] | None = None, + *, + na_rep: str = 'nan', +) -> Path | None: + """Write the [C, H] channel x horizon attribution CSV and a heatmap PNG. + + Returns the path to the heatmap PNG if matplotlib is available, else None. + """ + A = np.asarray(channel_horizon_attributions, dtype=np.float32) + if A.ndim != 2: + return None + C, H = A.shape + labels = ( + channel_labels + if (channel_labels and len(channel_labels) == C) + else [f'channel_{c}' for c in range(C)] + ) + + df = pd.DataFrame(A, columns=[f'horizon_{h}' for h in range(H)]) + df.insert(0, 'channel', labels) + df.to_csv( + out_dir / 'channel_horizon_attributions.csv', index=False, na_rep=na_rep + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + fig, ax = plt.subplots(figsize=(max(8, H * 0.15), max(4, C * 0.4))) + im = ax.imshow(A, aspect='auto', cmap='viridis', interpolation='nearest') + ax.set_xlabel('Forecast horizon') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, H - 1, min(12, H), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels(xt) + plt.colorbar(im, ax=ax, label='Attribution') + plt.tight_layout() + heatmap_path = out_dir / 'channel_horizon_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _channel_axis_page( + pdf: Any, + plt: Any, + *, + explanation: ForecastExplanation, + channel_labels: list[str] | None = None, +) -> None: + """Append one PDF page for the feature-axis (channel x horizon) attribution. + + Primary visual: a [C, H] heatmap of how much each input channel contributes to + each forecast step. A side bar summarizes each channel's total attribution + (summed over horizons) as a single feature-importance score. + """ + A = getattr(explanation, 'channel_horizon_attributions', None) + if A is None: + return + A = np.asarray(A, dtype=np.float32) + if A.ndim != 2 or A.shape[0] < 1 or A.shape[1] < 1: + return + C, H = A.shape + labels = ( + channel_labels + if (channel_labels and len(channel_labels) == C) + else [f'channel_{c}' for c in range(C)] + ) + importance = A.sum(axis=1) + method = getattr(explanation, 'channel_flow_method', None) or 'jacobian' + resid = getattr(explanation, 'channel_flow_residual_ratio_mean', None) + target_jacobian = method == 'target_input_jacobian' + intro = ( + 'Which input channel drives each target forecast step. Each cell is the magnitude of\n' + "the target forecast's local directional response when that channel moves from its\n" + 'local-mean replacement to the observed input. Rows are channels and columns are\n' + 'forecast steps; brighter = a stronger target-specific effect.' + if target_jacobian + else "Which input channel (feature) drives each forecast step. The model's response is\n" + 'decomposed along the feature axis into per-channel contributions, then aggregated\n' + 'per horizon. Rows are input channels, columns are forecast steps; brighter = that\n' + 'channel matters more there.' + ) + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Feature-axis attribution (channel x horizon)', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + intro, + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.08, 0.40, 0.56, 0.42)) + im = ax.imshow(A, aspect='auto', cmap='viridis', interpolation='nearest') + ax.set_xlabel('Forecast horizon (0 = first predicted step)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, H - 1, min(12, H), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels(xt) + fig.colorbar( + im, + ax=ax, + fraction=0.046, + pad=0.04, + label='Directional effect' if target_jacobian else 'Attribution', + ) + + axb = fig.add_axes((0.72, 0.40, 0.22, 0.42)) + y = np.arange(C) + axb.barh(y, importance, color='#1f77b4') + axb.set_yticks(y) + axb.set_yticklabels([]) + axb.invert_yaxis() # channel 0 at top, aligned with the heatmap rows + axb.set_title('Channel importance\n(sum over horizons)', fontsize=9) + axb.set_xlabel( + 'Total effect' if target_jacobian else 'Total attribution', fontsize=8 + ) + axb.tick_params(axis='both', labelsize=7) + + top_c = int(np.argmax(importance)) + resid_line = ( + f' - Estimator: {method}. Jacobian trust ratio (mean residual): {resid:.3f}\n' + ' (lower = more reliable first-order split; high values flag strong\n' + ' cross-channel interaction the first-order decomposition cannot capture).\n' + if resid is not None + else f' - Estimator: {method}.\n' + ) + heatmap_note = ( + " - Heatmap cell (channel c, horizon h): magnitude of the target forecast's\n" + ' first-order directional replacement effect; columns are not normalized.\n' + if target_jacobian + else ' - Heatmap cell (channel c, horizon h): share of the forecast at step h\n' + ' attributable to input channel c (each horizon column sums to 1 over channels).\n' + ) + bar_note = 'total effect' if target_jacobian else 'total attribution' + note = ( + 'How to read this page\n' + '---------------------\n' + + heatmap_note + + f" - Right bar: each channel's {bar_note} summed across horizons -- a single\n" + ' feature-importance score per input channel.\n' + f' - Most influential channel overall: {labels[top_c]}.\n' + + resid_line + + '\n' + 'Full channel-by-horizon values are exported as channel_horizon_attributions.csv.' + ) + fig.text( + 0.06, + 0.30, + note, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + linespacing=1.05, + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _feature_axis_embedding_stability_frame( + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> pd.DataFrame: + """Return the complete feature-axis embedding-stability report.""" + n_channels = int(report.n_channels) + labels = ( + channel_labels + if channel_labels is not None and len(channel_labels) == n_channels + else [f'channel_{c}' for c in range(n_channels)] + ) + return pd.DataFrame( + { + 'feature': labels, + 'lip_ratio_mean': np.asarray( + report.lip_ratio_mean, dtype=np.float32 + ), + 'lip_ratio_p50': np.asarray(report.lip_ratio_p50, dtype=np.float32), + 'lip_ratio_p95': np.asarray(report.lip_ratio_p95, dtype=np.float32), + 'lip_ratio_max': np.asarray(report.lip_ratio_max, dtype=np.float32), + 'n_trials_per_channel': np.asarray( + report.n_trials_per_channel, dtype=np.int64 + ), + 'n_unique_windows': int(report.n_unique_windows), + 'step_delta_norm_mean': float(report.step_delta_norm_mean), + } + ) + + +def _save_feature_axis_embedding_stability_csv( + out_dir: Path, + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> Path: + """Write the complete feature-axis embedding-stability report.""" + out_path = out_dir / 'feature_axis_embedding_stability.csv' + _feature_axis_embedding_stability_frame(report, channel_labels).to_csv( + out_path, index=False, na_rep='nan' + ) + return out_path + + +def _feature_axis_embedding_stability_page( + pdf: Any, + plt: Any, + *, + report: PerChannelEmbeddingStabilityReport, + channel_labels: list[str] | None = None, +) -> None: + """Append the feature-axis embedding-stability summary.""" + frame = _feature_axis_embedding_stability_frame(report, channel_labels) + shown = frame.sort_values( + 'lip_ratio_p95', ascending=False, na_position='last' + ).head(10) + + def _fmt(value: Any) -> str: + numeric = float(value) + return f'{numeric:.4f}' if np.isfinite(numeric) else 'n/a' + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Feature-axis embedding stability', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'This shows the delta between two embedding points after a small, controlled change to one feature.\n' + r'Each sensitivity score is $\Vert \Delta \mathbf{z} \Vert_2' + r'\,/\, \Vert \Delta \mathbf{x}_c \Vert_2$.' + '\nLower values mean less latent movement per unit feature change; compare features\n' + 'within the same model and dataset because embedding scales are model-specific.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + table_rows = [ + [ + row.feature, + _fmt(row.lip_ratio_mean), + _fmt(row.lip_ratio_p50), + _fmt(row.lip_ratio_p95), + _fmt(row.lip_ratio_max), + str(int(row.n_trials_per_channel)), + ] + for row in shown.itertuples(index=False) + ] + table_ax = fig.add_axes((0.06, 0.50, 0.88, 0.28)) + table_ax.axis('off') + table = table_ax.table( + cellText=table_rows, + colLabels=['Feature', 'Mean', 'P50', 'P95', 'Max', 'Trials'], + colWidths=[0.30, 0.14, 0.14, 0.14, 0.14, 0.14], + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(8) + table.scale(1.0, 1.2) + for c in range(6): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Mean / P50 / P95 / Max: summaries of the sensitivity score across\n' + ' small feature changes. Lower values mean the embedding\n' + ' moves less per unit change in that feature.\n' + ' - P95: conservative tail sensitivity. Rows are ranked by P95; the highest\n' + ' values identify features whose small changes can move the embedding most.\n' + ' - Trials: valid sensitivity measurements retained for that feature.\n' + f' - Sample coverage: {int(report.n_unique_windows)} unique windows. Mean\n' + f' baseline latent step: {_fmt(report.step_delta_norm_mean)} (reference only).\n' + ' - Compare values only within the same model and dataset because embedding\n' + ' scales are model-specific. A larger ratio is sensitivity, not by itself a defect.\n' + '\n' + 'All features and raw report fields are exported to\n' + 'feature_axis_embedding_stability.csv and explanation.json.' + ) + fig.text( + 0.06, + 0.43, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + + pdf.savefig(fig) + plt.close(fig) + + +@contextmanager +def _normalization_statistics_gradient( + model: torch.nn.Module, *, enabled: bool +): + """Temporarily include supported normalization statistics in autograd.""" + if not enabled: + yield 0 + return + + restores: list[tuple[object, object, bool]] = [] + for module in model.modules(): + if not all( + hasattr(module, name) + for name in ('_get_statistics', '_normalize', 'eps') + ): + continue + + original = module._get_statistics + had_instance_override = '_get_statistics' in vars(module) + + def _get_statistics( + self: Any, x: torch.Tensor, mask: torch.Tensor | None = None + ) -> None: + if mask is None: + mask = torch.ones((x.shape[0], x.shape[-1]), device=x.device) + expanded = ( + mask.to(device=x.device) + .unsqueeze(1) + .expand(-1, x.shape[1], -1) + .bool() + ) + masked_x = torch.where( + expanded, x, torch.full_like(x, float('nan')) + ) + mean = torch.nanmean(masked_x, dim=-1, keepdim=True) + variance = (masked_x - mean).square().nanmean(dim=-1, keepdim=True) + raw_stdev = variance.sqrt() + eps_sq = torch.as_tensor( + float(self.eps) ** 2, + dtype=variance.dtype, + device=variance.device, + ) + safe_stdev = variance.clamp_min(eps_sq).sqrt() + self.mean = mean + self.stdev = ( + raw_stdev.detach() + safe_stdev - safe_stdev.detach() + self.eps + ) + + module._get_statistics = types.MethodType(_get_statistics, module) + restores.append((module, original, had_instance_override)) + + try: + yield len(restores) + finally: + for module, original, had_instance_override in reversed(restores): + if had_instance_override: + module._get_statistics = original + else: + delattr(module, '_get_statistics') + + +def _compute_integrated_gradients_report( + *, + model: torch.nn.Module, + x_context_ct: np.ndarray, + input_mask_l: np.ndarray, + device: torch.device, + channel_labels: list[str], + baseline: Any, + n_steps: int, + n_baselines: int, + internal_batch_size: int | None, + reduce: str, + seed: int, + grad_through_norm: bool, +) -> dict[str, Any]: + """Run embedding integrated gradients for the current SDK context window.""" + from integrated_gradients import integrated_gradients_embedding + + x_tensor = torch.as_tensor( + np.asarray(x_context_ct, dtype=np.float32), device=device + ) + input_mask = torch.as_tensor( + np.asarray(input_mask_l, dtype=np.int64), device=device + ) + + def embed_fn(x: torch.Tensor) -> torch.Tensor: + if x.ndim != 3: + raise ValueError( + f'SDK embedding input must be [batch, channels, context], got {tuple(x.shape)}' + ) + mask = ( + input_mask.reshape(1, -1).expand(x.shape[0], -1).to(device=x.device) + ) + with _normalization_statistics_gradient( + model, enabled=grad_through_norm + ): + output = model.embed(x_enc=x, input_mask=mask) + embeddings = ( + output.embeddings if hasattr(output, 'embeddings') else output + ) + return embeddings.reshape(embeddings.shape[0], -1) + + attribution = integrated_gradients_embedding( + embed_fn, + x_tensor, + baseline=baseline, + n_steps=n_steps, + n_baselines=n_baselines, + internal_batch_size=internal_batch_size, + reduce=reduce, + seed=seed, + device=device, + ) + + A = np.asarray(attribution.attribution, dtype=np.float32) + if A.ndim != 2: + raise ValueError( + f'integrated gradients attribution must be [C, L], got shape {A.shape}' + ) + + C, _ = A.shape + labels = ( + channel_labels + if len(channel_labels) == C + else [f'channel_{c}' for c in range(C)] + ) + abs_A = np.abs(A) + channel_abs_effect = abs_A.sum(axis=1).astype(np.float32) + channel_signed_effect = A.sum(axis=1).astype(np.float32) + total_abs = float(channel_abs_effect.sum()) + channel_abs_share = ( + (channel_abs_effect / total_abs).astype(np.float32) + if total_abs > 1e-12 + else np.zeros_like(channel_abs_effect, dtype=np.float32) + ) + time_abs_effect = abs_A.sum(axis=0).astype(np.float32) + top_order = np.argsort(-channel_abs_effect)[: min(10, C)] + + return { + 'attribution': A, + 'channel_labels': labels, + 'channel_abs_effect': channel_abs_effect, + 'channel_signed_effect': channel_signed_effect, + 'channel_abs_share': channel_abs_share, + 'time_abs_effect': time_abs_effect, + 'top_channels': [ + { + 'channel': labels[int(i)], + 'abs_effect': float(channel_abs_effect[int(i)]), + 'signed_effect': float(channel_signed_effect[int(i)]), + 'abs_share': float(channel_abs_share[int(i)]), + } + for i in top_order + ], + 'overall_effect': float(attribution.overall_effect), + 'abs_effect': float(attribution.abs_effect), + 'embedding_delta': float(attribution.embedding_delta), + 'embedding_delta_abs_mean': float(attribution.embedding_delta_abs_mean), + 'convergence_delta': float(attribution.convergence_delta), + 'n_steps': int(attribution.n_steps), + 'n_baselines': int(attribution.n_baselines), + 'baseline': str(attribution.baseline), + 'reduce': str(attribution.reduce), + 'embedding_dim': int(attribution.embedding_dim), + 'grad_through_norm': bool(grad_through_norm), + } + + +def _save_integrated_gradients_artifacts( + out_dir: Path, + integrated_gradients_report: dict[str, Any], + *, + na_rep: str = 'nan', +) -> Path | None: + """Write integrated-gradients CSVs and a signed heatmap PNG.""" + A = np.asarray( + integrated_gradients_report.get('attribution'), dtype=np.float32 + ) + if A.ndim != 2: + return None + C, L = A.shape + labels = integrated_gradients_report.get('channel_labels') + labels = ( + labels + if isinstance(labels, list) and len(labels) == C + else [f'channel_{c}' for c in range(C)] + ) + + df_matrix = pd.DataFrame(A.T, columns=labels) + df_matrix.insert(0, 'lag_from_last', np.arange(L - 1, -1, -1, dtype=int)) + df_matrix.insert(0, 'context_index', np.arange(L, dtype=int)) + df_matrix.to_csv( + out_dir / 'integrated_gradients_attributions.csv', + index=False, + na_rep=na_rep, + ) + + summary = pd.DataFrame( + { + 'channel': labels, + 'signed_effect': np.asarray( + integrated_gradients_report['channel_signed_effect'], + dtype=np.float32, + ), + 'abs_effect': np.asarray( + integrated_gradients_report['channel_abs_effect'], + dtype=np.float32, + ), + 'abs_share': np.asarray( + integrated_gradients_report['channel_abs_share'], + dtype=np.float32, + ), + } + ) + summary.to_csv( + out_dir / 'integrated_gradients_channel_summary.csv', + index=False, + na_rep=na_rep, + ) + + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + except ImportError: + return None + + scale = ( + float(np.nanpercentile(np.abs(A), 99)) if np.isfinite(A).any() else 0.0 + ) + if scale <= 1e-12: + scale = float(np.nanmax(np.abs(A))) if np.isfinite(A).any() else 1.0 + if scale <= 1e-12: + scale = 1.0 + + fig, ax = plt.subplots(figsize=(max(8, L * 0.02), max(4, C * 0.35))) + im = ax.imshow( + A, + aspect='auto', + cmap='coolwarm', + interpolation='nearest', + vmin=-scale, + vmax=scale, + ) + ax.set_xlabel('Input context lag (0 = most recent)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, L - 1, min(12, L), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels((L - 1 - xt).astype(int)) + plt.colorbar(im, ax=ax, label='Signed IG attribution') + plt.tight_layout() + heatmap_path = out_dir / 'integrated_gradients_heatmap.png' + plt.savefig(heatmap_path, dpi=120) + plt.close(fig) + return heatmap_path + + +def _integrated_gradients_page( + pdf: Any, + plt: Any, + *, + integrated_gradients_report: dict[str, Any] | None, +) -> None: + """Append one PDF page for embedding integrated gradients.""" + if integrated_gradients_report is None: + return + A = np.asarray( + integrated_gradients_report.get('attribution'), dtype=np.float32 + ) + if A.ndim != 2 or A.shape[0] < 1 or A.shape[1] < 1: + return + C, L = A.shape + labels = integrated_gradients_report.get('channel_labels') + labels = ( + labels + if isinstance(labels, list) and len(labels) == C + else [f'channel_{c}' for c in range(C)] + ) + abs_effect = np.asarray( + integrated_gradients_report.get('channel_abs_effect'), dtype=np.float32 + ) + if abs_effect.shape != (C,): + abs_effect = np.abs(A).sum(axis=1) + + scale = ( + float(np.nanpercentile(np.abs(A), 99)) if np.isfinite(A).any() else 0.0 + ) + if scale <= 1e-12: + scale = float(np.nanmax(np.abs(A))) if np.isfinite(A).any() else 1.0 + if scale <= 1e-12: + scale = 1.0 + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Integrated gradients (embedding sensitivity)', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'Signed input attributions for the model embedding along the baseline-to-input path.\n' + 'Rows are input channels and columns are the context timesteps; lag 0 is the most\n' + 'recent input. Positive and negative colors show direction, while magnitude shows strength.', + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.08, 0.38, 0.58, 0.43)) + im = ax.imshow( + A, + aspect='auto', + cmap='coolwarm', + interpolation='nearest', + vmin=-scale, + vmax=scale, + ) + ax.set_xlabel('Input context lag (0 = most recent)') + ax.set_ylabel('Input channel') + ax.set_yticks(range(C)) + ax.set_yticklabels(labels, fontsize=8) + xt = np.linspace(0, L - 1, min(12, L), dtype=int) + ax.set_xticks(xt) + ax.set_xticklabels((L - 1 - xt).astype(int)) + fig.colorbar( + im, ax=ax, fraction=0.046, pad=0.04, label='Signed attribution' + ) + + axb = fig.add_axes((0.74, 0.38, 0.22, 0.43)) + y = np.arange(C) + axb.barh(y, abs_effect, color='#2a9d8f') + axb.set_yticks(y) + axb.set_yticklabels([]) + axb.invert_yaxis() + axb.set_title( + r'Channel effect' '\n' r'($\sum |\mathrm{IG}|$)', + fontsize=9, + math_fontfamily='dejavusans', + ) + axb.set_xlabel('Absolute effect', fontsize=8) + axb.tick_params(axis='both', labelsize=7) + + top_c = int(np.argmax(abs_effect)) + baseline = integrated_gradients_report.get('baseline') + reduce = integrated_gradients_report.get('reduce') + steps = integrated_gradients_report.get('n_steps') + n_baselines = integrated_gradients_report.get('n_baselines') + convergence = _scalar_to_jsonable( + integrated_gradients_report.get('convergence_delta') + ) + emb_delta = _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta') + ) + grad_norm = bool(integrated_gradients_report.get('grad_through_norm')) + note = ( + 'How to read this page\n' + '---------------------\n' + ' - Heatmap cell (channel c, lag l): signed contribution of that input value\n' + ' to the scalar embedding objective used by integrated gradients.\n' + ' - Right bar: per-channel absolute effect, summed over all context timesteps.\n' + f' - Most influential channel by absolute IG: {labels[top_c]}.\n' + f' - Config: baseline={baseline}, steps={steps}, baselines={n_baselines}, reduce={reduce}.\n' + f' - RevIN/statistics gradient path enabled: {grad_norm}.\n' + f' - Embedding delta: {emb_delta}; convergence delta: {convergence}.\n' + '\n' + 'Full values are exported as integrated_gradients_attributions.csv and\n' + 'integrated_gradients_channel_summary.csv.' + ) + fig.text( + 0.06, + 0.30, + note, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + + pdf.savefig(fig) + plt.close(fig) + + +def _build_pdf_report( + pdf_path: Path, + *, + dataset_name: str | None = None, + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + target_column: str, + timestamp_column: str, + heatmap_path: Path | None, + topk_rows: list[list[str]], + top_k: int, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + context_len: int | None = None, + forecast_horizon: int | None = None, + channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> Path | None: + """Compose a multi-page PDF with the forecast and attribution heatmap.""" + try: + import matplotlib as mpl + + mpl.use('Agg') + import matplotlib.pyplot as plt + from matplotlib.backends.backend_pdf import PdfPages + except ImportError: + return None + + attrib = np.asarray(explanation.lag_horizon_attributions) + K, H = attrib.shape + flow_magnitudes = getattr(explanation, 'flow_magnitudes', None) + show_heatmap = heatmap_path is not None and heatmap_path.exists() + show_topk = bool(topk_rows) + show_semantic_flow = ( + context_len is not None + and forecast_horizon is not None + and flow_magnitudes is not None + and np.asarray(flow_magnitudes).size > 0 + ) + show_trajectory_stability = trajectory_report is not None + show_feature_axis = ( + getattr(explanation, 'channel_horizon_attributions', None) is not None + ) + show_feature_axis_stability = ( + feature_axis_embedding_stability_report is not None + ) + show_integrated_gradients = integrated_gradients_report is not None + + with PdfPages(pdf_path) as pdf: + fig = plt.figure(figsize=(8.5, 11)) + fig.text( + 0.5, + 0.94, + 'Kumo-Forecast Interpretability Report', + ha='center', + fontsize=18, + fontweight='bold', + ) + fig.text( + 0.5, + 0.905, + datetime.now(tz=timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC'), + ha='center', + fontsize=10, + color='gray', + ) + + sections = [ + section + for available, section in [ + ( + True, + [ + 'Forecast preview: line chart of predicted target values.' + ], + ), + ( + show_heatmap, + [ + 'Lag x Horizon attribution heatmap: how much each past step', + ' contributes to each forecast step.', + ' a) lag=0 is the most recent input.', + ' b) Softmax-normalized weights; brighter cells = time steps', + ' that contribute more to the forecast.', + ], + ), + ( + show_topk, + ['Top-k lag steps per horizon (marginal contributions).'], + ), + ( + show_semantic_flow, + [ + 'Semantic flow magnitudes: per-transition latent flow and', + ' forecast-vs-history diagnostics.', + ], + ), + ( + show_trajectory_stability, + [ + 'Latent trajectory stability: temporal-smoothness metrics', + ' over the context window.', + ], + ), + ( + show_feature_axis, + [ + 'Feature-axis attribution: which input channel drives each', + ' forecast step (multivariate inputs only).', + ], + ), + ( + show_feature_axis_stability, + [ + 'Feature-axis embedding stability: per-channel sensitivity', + ' to small, controlled input changes (multivariate inputs only).', + ], + ), + ( + show_integrated_gradients, + [ + 'Integrated gradients: signed input-channel/time', + ' sensitivity for the model embedding.', + ], + ), + ] + if available + ] + + summary = [ + 'Overview', + '--------', + f'Dataset: {dataset_name or ""}', + f'Target column: {target_column}', + f'Timestamp column: {timestamp_column}', + f'Forecast steps (H): {H}', + f'Lag context size (K): {K}', + '', + 'What is in this report', + '----------------------', + ] + for number, section in enumerate(sections, start=1): + summary.extend([f'{number}. {section[0]}', *section[1:]]) + fig.text( + 0.08, + 0.85, + '\n'.join(summary), + ha='left', + va='top', + fontsize=10, + family='monospace', + ) + pdf.savefig(fig) + plt.close(fig) + + fig, ax = plt.subplots(figsize=(11, 6)) + if ( + timestamp_column in forecast_df.columns + and f'{target_column}_forecast' in forecast_df.columns + ): + ax.plot( + forecast_df[timestamp_column], + forecast_df[f'{target_column}_forecast'], + marker='o', + linewidth=1.5, + ) + ax.set_xlabel(timestamp_column) + ax.set_ylabel(f'{target_column} (forecast, original scale)') + ax.set_title(f'Forecast preview: {target_column}') + fig.autofmt_xdate() + else: + ax.text( + 0.5, 0.5, 'Forecast columns not found', ha='center', va='center' + ) + ax.axis('off') + plt.tight_layout() + pdf.savefig(fig) + plt.close(fig) + + if show_heatmap: + try: + from matplotlib.image import imread + except ImportError: + imread = None + fig = plt.figure(figsize=(11, 8.5)) + if imread is not None: + ax = fig.add_axes((0.05, 0.18, 0.9, 0.72)) + ax.imshow(imread(str(heatmap_path))) + ax.axis('off') + else: + ax = fig.add_axes((0.05, 0.18, 0.9, 0.72)) + ax.text( + 0.5, + 0.5, + 'Heatmap PNG could not be embedded.', + ha='center', + va='center', + ) + ax.axis('off') + fig.text( + 0.5, + 0.94, + 'Lag x Horizon attribution heatmap', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.5, + 0.10, + 'Vertical axis: lag back from the last observation (0 = most recent).\n' + 'Horizontal axis: forecast step (0 = first predicted step).\n' + 'Brighter = that past step has more influence on that forecast step.', + ha='center', + va='center', + fontsize=9, + color='gray', + ) + pdf.savefig(fig) + plt.close(fig) + + if show_topk: + header = ['Horizon'] + for r in range(1, top_k + 1): + header.extend([f'Rank-{r}\nLag', f'Rank-{r}\nProb']) + + rows_per_page = 30 + chunks = [ + topk_rows[i : i + rows_per_page] + for i in range(0, len(topk_rows), rows_per_page) + ] + num_cols = 1 + 2 * top_k + horizon_col = 0.12 + data_col = max(0.05, (1.0 - horizon_col) / max(1, num_cols - 1)) + col_widths = [horizon_col] + [data_col] * (num_cols - 1) + + for idx, chunk in enumerate(chunks, start=1): + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + f'Top-{top_k} lag steps per horizon (page {idx}/{len(chunks)})', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.91, + 'Horizon: which forecast step (0 = first predicted step).\n' + 'Rank-r Lag: how many steps back from the last observation ' + 'for the r-th most influential past step\n' + ' (1 = most recent past step). Ranked from highest to ' + 'lowest contribution.\n' + 'Rank-r Prob: marginal softmax weight of that ranked lag step ' + 'on that horizon\n' + ' -- higher means it contributed more to the forecast.', + ha='left', + va='top', + fontsize=9, + color='gray', + ) + + ax = fig.add_axes((0.04, 0.04, 0.92, 0.78)) + ax.axis('off') + table = ax.table( + cellText=chunk, + colLabels=header, + colWidths=col_widths, + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(8) + table.scale(1.0, 1.25) + for c in range(len(header)): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + cell.set_height(cell.get_height() * 1.6) + + pdf.savefig(fig) + plt.close(fig) + + if show_semantic_flow: + try: + _semantic_flow_page( + pdf, + plt, + explanation=explanation, + context_len=int(context_len), + forecast_horizon=int(forecast_horizon), + ) + except Exception as e: + logger.warning('Semantic flow page skipped: %s', e) + + if show_trajectory_stability: + r = trajectory_report + rows = [ + [ + 'Zero-crossing rate (mean / p95)', + f'{r.zero_crossing_rate_mean:.4f}', + f'{r.zero_crossing_rate_p95:.4f}', + ], + [ + 'Direction-flip rate (mean / p95)', + f'{r.direction_flip_rate_mean:.4f}', + f'{r.direction_flip_rate_p95:.4f}', + ], + [ + 'Relative jitter (mean / p95)', + f'{r.relative_jitter_mean:.4f}', + f'{r.relative_jitter_p95:.4f}', + ], + [ + 'Occupancy positive / negative', + f'{r.occupancy_positive_mean:.4f}', + f'{r.occupancy_negative_mean:.4f}', + ], + [ + 'Latent shape (T / D)', + f'{int(r.n_time_steps)}', + f'{int(r.n_dimensions)}', + ], + ] + + fig = plt.figure(figsize=(11, 8.5)) + fig.text( + 0.5, + 0.95, + 'Latent trajectory stability', + ha='center', + fontsize=14, + fontweight='bold', + ) + fig.text( + 0.06, + 0.90, + 'Per-dimension temporal-smoothness metrics for the latent trajectory.\n' + 'Lower zero-crossing, direction-flip, and relative-jitter values indicate\n' + "a smoother embedding (supports the framework's stability assumption).\n" + r'Relative jitter compares $\mathrm{mean}(|\Delta z|)$ with ' + r'$\mathrm{mean}(|z-z_{\mathrm{center}}|)$.', + ha='left', + va='top', + fontsize=9, + fontfamily='DejaVu Sans', + math_fontfamily='dejavusans', + color='gray', + ) + + ax = fig.add_axes((0.08, 0.45, 0.84, 0.35)) + ax.axis('off') + table = ax.table( + cellText=rows, + colLabels=['Metric', 'Value 1', 'Value 2'], + colWidths=[0.5, 0.25, 0.25], + loc='upper center', + cellLoc='center', + ) + table.auto_set_font_size(False) + table.set_fontsize(9) + table.scale(1.0, 1.4) + for c in range(3): + cell = table[(0, c)] + cell.set_facecolor('#dddddd') + cell.set_text_props(weight='bold') + + interp_text = ( + 'How to read these metrics\n' + '-------------------------\n' + ' - Zero-crossing rate: fraction of consecutive steps where the centered\n' + ' latent value flips sign. Lower => trajectory stays on one side of the\n' + ' reference for longer (less oscillation).\n' + ' - Direction-flip rate: fraction of steps where the latent step direction\n' + ' reverses sign. Lower => monotone, smoother dynamics.\n' + ' - Relative jitter: average latent step size divided by average displacement\n' + ' from the reference. Lower => small smooth steps\n' + ' relative to overall amplitude.\n' + ' - Occupancy positive / negative: fraction of time the centered trajectory\n' + ' sits above / below the deadband. Asymmetry can flag regime drift.\n' + ' - Latent shape (T / D): number of latent time steps and embedding dim;\n' + ' sanity-check that T matches the context length used for this run.\n' + '\n' + 'Pair these with the diagnostics block in explanation.json\n' + '(flow_ratio_forecast_vs_history, curvature_ratio_forecast_vs_history,\n' + 'latent_diag_mahalanobis_ratio_forecast_vs_history) for the forecast-vs-\n' + 'history comparison.' + ) + fig.text( + 0.06, + 0.40, + interp_text, + ha='left', + va='top', + fontsize=9, + family='monospace', + color='#333333', + ) + pdf.savefig(fig) + plt.close(fig) + + # Feature-axis page last (and only for multivariate inputs), matching + # its position in the cover summary. + if show_feature_axis: + try: + _channel_axis_page( + pdf, + plt, + explanation=explanation, + channel_labels=channel_labels, + ) + except Exception as e: + logger.warning('Feature-axis page skipped: %s', e) + + if show_feature_axis_stability: + try: + _feature_axis_embedding_stability_page( + pdf, + plt, + report=feature_axis_embedding_stability_report, + channel_labels=channel_labels, + ) + except Exception as e: + logger.warning( + 'Feature-axis embedding-stability page skipped: %s', e + ) + + if show_integrated_gradients: + try: + _integrated_gradients_page( + pdf, + plt, + integrated_gradients_report=integrated_gradients_report, + ) + except Exception as e: + logger.warning('Integrated-gradients page skipped: %s', e) + + return pdf_path + + +def _array_to_jsonable(arr: Any) -> Any: + """Convert a numpy array (or torch tensor / scalar / None) into JSON-friendly data.""" + if arr is None: + return None + if isinstance(arr, np.ndarray): + return ( + np.where(np.isfinite(arr), arr, None).tolist() + if arr.dtype.kind == 'f' + else arr.tolist() + ) + try: + return _array_to_jsonable(np.asarray(arr)) + except Exception: + return None + + +def _scalar_to_jsonable(x: Any) -> Any: + if x is None: + return None + try: + v = float(x) + except (TypeError, ValueError): + return None + return v if np.isfinite(v) else None + + +def _trajectory_report_to_dict( + report: TrajectoryStabilityReport | None, +) -> dict[str, Any] | None: + """Convert a TrajectoryStabilityReport into a JSON-friendly dict (or None).""" + if report is None: + return None + return { + 'zero_crossing_rate_mean': _scalar_to_jsonable( + report.zero_crossing_rate_mean + ), + 'zero_crossing_rate_p95': _scalar_to_jsonable( + report.zero_crossing_rate_p95 + ), + 'direction_flip_rate_mean': _scalar_to_jsonable( + report.direction_flip_rate_mean + ), + 'direction_flip_rate_p95': _scalar_to_jsonable( + report.direction_flip_rate_p95 + ), + 'relative_jitter_mean': _scalar_to_jsonable( + report.relative_jitter_mean + ), + 'relative_jitter_p95': _scalar_to_jsonable(report.relative_jitter_p95), + 'occupancy_positive_mean': _scalar_to_jsonable( + report.occupancy_positive_mean + ), + 'occupancy_negative_mean': _scalar_to_jsonable( + report.occupancy_negative_mean + ), + 'n_time_steps': int(report.n_time_steps), + 'n_dimensions': int(report.n_dimensions), + } + + +def _feature_axis_embedding_stability_to_dict( + report: PerChannelEmbeddingStabilityReport | None, + *, + channel_labels: list[str] | None = None, +) -> dict[str, Any] | None: + """Convert a feature-axis embedding-stability report to JSON.""" + if report is None: + return None + frame = _feature_axis_embedding_stability_frame(report, channel_labels) + return { + 'channel_labels': frame['feature'].tolist(), + 'lip_ratio_mean': _array_to_jsonable( + frame['lip_ratio_mean'].to_numpy() + ), + 'lip_ratio_p50': _array_to_jsonable(frame['lip_ratio_p50'].to_numpy()), + 'lip_ratio_p95': _array_to_jsonable(frame['lip_ratio_p95'].to_numpy()), + 'lip_ratio_max': _array_to_jsonable(frame['lip_ratio_max'].to_numpy()), + 'n_trials_per_channel': _array_to_jsonable( + frame['n_trials_per_channel'].to_numpy() + ), + 'n_unique_windows': int(report.n_unique_windows), + 'step_delta_norm_mean': _scalar_to_jsonable( + report.step_delta_norm_mean + ), + } + + +def _integrated_gradients_to_dict( + integrated_gradients_report: dict[str, Any] | None, + *, + include_full_arrays: bool = True, +) -> dict[str, Any] | None: + """Convert an integrated-gradients report into a JSON-friendly dict.""" + if integrated_gradients_report is None: + return None + + payload: dict[str, Any] = { + 'baseline': integrated_gradients_report.get('baseline'), + 'reduce': integrated_gradients_report.get('reduce'), + 'n_steps': int(integrated_gradients_report.get('n_steps', 0)), + 'n_baselines': int(integrated_gradients_report.get('n_baselines', 0)), + 'embedding_dim': int( + integrated_gradients_report.get('embedding_dim', 0) + ), + 'grad_through_norm': bool( + integrated_gradients_report.get('grad_through_norm', False) + ), + 'overall_effect': _scalar_to_jsonable( + integrated_gradients_report.get('overall_effect') + ), + 'abs_effect': _scalar_to_jsonable( + integrated_gradients_report.get('abs_effect') + ), + 'embedding_delta': _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta') + ), + 'embedding_delta_abs_mean': _scalar_to_jsonable( + integrated_gradients_report.get('embedding_delta_abs_mean') + ), + 'convergence_delta': _scalar_to_jsonable( + integrated_gradients_report.get('convergence_delta') + ), + 'channel_labels': list( + integrated_gradients_report.get('channel_labels', []) + ), + 'channel_signed_effect': _array_to_jsonable( + integrated_gradients_report.get('channel_signed_effect') + ), + 'channel_abs_effect': _array_to_jsonable( + integrated_gradients_report.get('channel_abs_effect') + ), + 'channel_abs_share': _array_to_jsonable( + integrated_gradients_report.get('channel_abs_share') + ), + 'top_channels': integrated_gradients_report.get('top_channels', []), + } + if include_full_arrays: + payload['attribution'] = _array_to_jsonable( + integrated_gradients_report.get('attribution') + ) + payload['time_abs_effect'] = _array_to_jsonable( + integrated_gradients_report.get('time_abs_effect') + ) + return payload + + +def _explanation_to_dict( + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + *, + target_column: str, + timestamp_column: str = 'timestamp', + dataset_name: str | None = None, + include_full_arrays: bool = True, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> dict[str, Any]: + """Render the (forecast, explanation) pair as a JSON-serializable dict.""" + fc = forecast_df.copy() + if timestamp_column in fc.columns and pd.api.types.is_datetime64_any_dtype( + fc[timestamp_column] + ): + fc[timestamp_column] = fc[timestamp_column].dt.strftime( + '%Y-%m-%dT%H:%M:%S' + ) + forecast_records = fc.to_dict(orient='records') + + base = np.asarray(explanation.baseline_forecast) + scores = np.asarray(explanation.lag_horizon_scores) + attrib = np.asarray(explanation.lag_horizon_attributions) + C, H = base.shape if base.ndim == 2 else (None, None) + K = attrib.shape[0] if attrib.ndim == 2 else None + + surrogate_block: dict[str, Any] | None + if explanation.surrogate_coef is not None: + surrogate_block = { + 'coef': _array_to_jsonable(explanation.surrogate_coef), + 'intercept': _array_to_jsonable(explanation.surrogate_intercept), + 'feature_layout': explanation.surrogate_feature_layout, + } + else: + surrogate_block = None + + explanation_block: dict[str, Any] = { + 'shapes': { + 'C_channels': int(C) if C is not None else None, + 'H_horizon': int(H) if H is not None else None, + 'K_lags': int(K) if K is not None else None, + }, + 'baseline_forecast': _array_to_jsonable(base), + 'lag_horizon_scores': _array_to_jsonable(scores), + 'lag_horizon_attributions': _array_to_jsonable(attrib), + 'surrogate': surrogate_block, + 'diagnostics': { + 'flow_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.flow_ratio_forecast_vs_history + ), + 'flow_variance_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.flow_variance_ratio_forecast_vs_history + ), + 'curvature_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.curvature_ratio_forecast_vs_history + ), + 'latent_diag_mahalanobis_ratio_forecast_vs_history': _scalar_to_jsonable( + explanation.latent_diag_mahalanobis_ratio_forecast_vs_history + ), + 'latent_trajectory_shape': ( + list(np.asarray(explanation.latent_trajectory).shape) + if getattr(explanation, 'latent_trajectory', None) is not None + else None + ), + }, + 'trajectory_stability': _trajectory_report_to_dict(trajectory_report), + } + + # Feature-axis (channel) attribution -- only present for multivariate inputs. + chan_attrib = getattr(explanation, 'channel_horizon_attributions', None) + stability_block = _feature_axis_embedding_stability_to_dict( + feature_axis_embedding_stability_report, + channel_labels=channel_labels, + ) + if chan_attrib is not None or stability_block is not None: + feature_axis: dict[str, Any] = {} + if chan_attrib is not None: + feature_axis.update( + { + 'method': getattr(explanation, 'channel_flow_method', None), + 'channel_horizon_attributions': _array_to_jsonable( + np.asarray(chan_attrib) + ), + 'residual_ratio_mean': _scalar_to_jsonable( + explanation.channel_flow_residual_ratio_mean + ), + 'residual_ratio_p95': _scalar_to_jsonable( + explanation.channel_flow_residual_ratio_p95 + ), + } + ) + if ( + include_full_arrays + and getattr(explanation, 'per_channel_flow', None) is not None + ): + feature_axis['per_channel_flow'] = _array_to_jsonable( + np.asarray(explanation.per_channel_flow) + ) + if stability_block is not None: + feature_axis['embedding_stability'] = stability_block + explanation_block['feature_axis'] = feature_axis + + if include_full_arrays: + explanation_block['flow_magnitudes'] = _array_to_jsonable( + explanation.flow_magnitudes + ) + explanation_block['latent_trajectory'] = _array_to_jsonable( + explanation.latent_trajectory + ) + + ig_block = _integrated_gradients_to_dict( + integrated_gradients_report, + include_full_arrays=include_full_arrays, + ) + if ig_block is not None: + explanation_block['integrated_gradients'] = ig_block + + return { + 'metadata': { + 'dataset_name': dataset_name, + 'target_column': target_column, + 'timestamp_column': timestamp_column, + 'generated_at': datetime.now(tz=timezone.utc).strftime( + '%Y-%m-%dT%H:%M:%SZ' + ), + 'include_full_arrays': bool(include_full_arrays), + }, + 'forecast': forecast_records, + 'explanation': explanation_block, + } + + +def _save_explanation_json( + *, + forecast_df: pd.DataFrame, + explanation: ForecastExplanation, + path: str | Path, + target_column: str, + timestamp_column: str = 'timestamp', + dataset_name: str | None = None, + include_full_arrays: bool = True, + indent: int | None = 2, + trajectory_report: TrajectoryStabilityReport | None = None, + feature_axis_embedding_stability_report: PerChannelEmbeddingStabilityReport + | None = None, + channel_labels: list[str] | None = None, + integrated_gradients_report: dict[str, Any] | None = None, +) -> Path: + """Persist the (forecast, explanation) pair as a JSON file.""" + out_path = Path(path) + out_path.parent.mkdir(parents=True, exist_ok=True) + + payload = _explanation_to_dict( + forecast_df, + explanation, + target_column=target_column, + timestamp_column=timestamp_column, + dataset_name=dataset_name, + include_full_arrays=include_full_arrays, + trajectory_report=trajectory_report, + feature_axis_embedding_stability_report=feature_axis_embedding_stability_report, + channel_labels=channel_labels, + integrated_gradients_report=integrated_gradients_report, + ) + with out_path.open('w', encoding='utf-8') as fh: + json.dump(payload, fh, indent=indent, allow_nan=False) + return out_path diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py new file mode 100644 index 000000000..1e96e31ef --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -0,0 +1,77 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""structured-data-models' forecaster, as the attribution code expects one. + +The ported attribution is written against a protocol of two methods rather +than against a class: a forward pass that returns a forecast, and an embedding +pass that returns one vector per window. structured-data-models' forecaster +has both, under its own names, so what stands between them is this. + +The embedding is the model's own, the one it builds retrieval keys from. An +attribution is a statement about what the model did, so reducing its encoder +output some other way here would attribute something the model never computed. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +import torch + + +@dataclass(frozen=True) +class _Forecast: + forecast: torch.Tensor + + +@dataclass(frozen=True) +class _Embedding: + embeddings: torch.Tensor + + +class Forecaster: + r"""Wraps ``sdm.models.KumoForecast`` for the attribution code. + + Args: + model: The loaded ``KumoForecast``. + """ + + def __init__(self, model: Any) -> None: + self._inner = model.model + + @property + def context_size(self) -> int: + r"""How many steps the model reads.""" + return int(self._inner.context_size) + + @property + def prediction_size(self) -> int: + r"""How many steps it forecasts in one pass.""" + return int(self._inner.prediction_size) + + def __call__( + self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> _Forecast: + r"""The forecast for ``x_enc`` of shape ``[B, C, R]``.""" + return _Forecast(forecast=self._inner(x_enc)) + + def embed( + self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> _Embedding: + r"""One embedding per window of ``x_enc``, shaped ``[B, D]``.""" + return _Embedding(embeddings=self.embed_tensor(x_enc)) + + def embed_tensor(self, x_enc: torch.Tensor) -> torch.Tensor: + r"""The embedding as a plain tensor, differentiably. + + Kept apart from :meth:`embed` because integrated gradients needs the + path from the input to it to carry gradients, and the protocol's own + method is called where they are not wanted. + """ + from sdm.models.kumo.timeseries.forecast.darr import embed + + encoded, _, _ = self._inner.encode(x_enc) + return embed(encoded) diff --git a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py index 524d34560..456124609 100644 --- a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -20,6 +20,7 @@ from __future__ import annotations from collections.abc import Mapping, Sequence +from dataclasses import replace from typing import Any from sdm_api.generated.tfm_api import PredictionItem @@ -39,14 +40,14 @@ _NEIGHBOURS = 64 _TEMPERATURE = 0.05 -_KNOBS = ('alpha', 'k', 'temperature') +_KNOBS = ('alpha', 'k', 'temperature', 'feature_axis') class Forecast: r"""Reads a ``kumo-forecast`` request into the model.""" model_id = 'kumo-forecast' - outputs = {'forecasting': ('prediction',)} + outputs = {'forecasting': ('prediction', 'explanation')} @staticmethod def installed() -> bool: @@ -228,10 +229,53 @@ def answer( 'the model answered with a malformed output', code='INTERNAL_ERROR', ) - return [ + items = [ PredictionItem(row_index=0, forecast_step=step, prediction=value) for step, value in enumerate(forecast.tolist(), start=1) ] + if 'explanation' in fields and items: + items[0] = replace( + items[0], + explanation=self._explained( + model, payload, target, horizon, forecast, alongside + ), + ) + return items + + def _explained( + self, + model: Any, + payload: Mapping[str, Any], + target: str, + horizon: int, + forecast: Any, + alongside: Any, + ) -> dict[str, Any]: + r"""Why that forecast, attributed to the history it was made from. + + The attribution reads the model's gradients and walks its latent + trajectory, so it reads the model itself rather than its answer, and + exists only where the model runs here. + """ + from sdm_client.explain import explanation_of + + table = payload['context']['instance_table'] + spec = payload['schema']['instance_table'] + keys = key_columns(spec) - {target} + channels = [name for name in table['columns'] if name not in keys] + history = Shape.of(spec, dict.fromkeys(channels, 'numerical')).tensor( + table, 'the history' + ) + options = payload.get('inference') or {} + return explanation_of( + model, + history.numerical.detach().cpu().numpy().T, + channels=channels, + target=target, + horizon=horizon, + forecast=forecast.detach().cpu().numpy(), + feature_axis=bool(options.get('feature_axis', False)), + ) @staticmethod def _warn_where_retrieval_does_nothing( diff --git a/packages/structured-data-models-client/src/sdm_client/models.py b/packages/structured-data-models-client/src/sdm_client/models.py index fd45023f0..36f00b325 100644 --- a/packages/structured-data-models-client/src/sdm_client/models.py +++ b/packages/structured-data-models-client/src/sdm_client/models.py @@ -197,9 +197,11 @@ profile=TIMESERIES, runtime=RuntimeContract( tasks=frozenset({'forecasting'}), - outputs=frozenset({'prediction'}), + outputs=frozenset({'prediction', 'explanation'}), sessions=False, - inference_options=frozenset({'alpha', 'k', 'temperature'}), + inference_options=frozenset( + {'alpha', 'k', 'temperature', 'feature_axis'} + ), ), ) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py b/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py index 5064ac7af..1330ed172 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/__init__.py @@ -10,5 +10,6 @@ """ from sdm_client.reporting.anomaly import anomaly_report +from sdm_client.reporting.forecast import forecast_report -__all__ = ['anomaly_report'] +__all__ = ['anomaly_report', 'forecast_report'] diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py new file mode 100644 index 000000000..c763a7082 --- /dev/null +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -0,0 +1,149 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +r"""A forecast explanation, drawn as Kumo-TS draws it. + +The pages come from that package. What is new is that they are drawn from an +explanation that travelled as data: the client carries one as the contract's +``explanation`` field, plain JSON, because that is what an output field is. +The arrays the pages read are all in it, so the drawing reads them back. + +A page whose data is not there is not drawn. Feature-axis attribution is the +one that is usually absent, because it costs several times the rest and is +asked for separately. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np + +from sdm_client.errors import MissingExtraError, StructuredDataError + +if TYPE_CHECKING: # pragma: no cover - imported for typing only. + from sdm_client.result import PredictionResult + + +def forecast_report( + result: PredictionResult, + output_path: str | Path, + *, + dataset_name: str | None = None, + top_k: int = 5, +) -> Path: + r"""Draw why ``result`` is the forecast it is. + + Args: + result: What :meth:`SDMClient.predict ` + answered for a forecast asked with ``'explanation'`` among its + output fields. + output_path: Where to write the PDF. + dataset_name: A name for the run, shown on the first page. + top_k: How many lags to list per horizon. + + Raises: + MissingExtraError: If matplotlib is not installed. + StructuredDataError: If the answer carries no explanation. + + >>> result = client.predict( + ... request, model=KumoForecast(), + ... outputs=['prediction', 'explanation'], + ... ) + >>> forecast_report(result, 'forecast.pdf') + """ + carried = result.explanation + if not carried: + raise StructuredDataError( + 'this answer carries no explanation. Ask for one with ' + "outputs=['prediction', 'explanation']; it is not computed " + 'unless it is asked for, because it costs far more than the ' + 'forecast does', + code='INVALID_REQUEST', + ) + pages = _pages() + frame, target, step = _forecast_frame(carried) + explanation = _explanation(carried) + attributions = np.asarray(explanation.lag_horizon_attributions) + _, topk_rows = pages._topk_lag_steps_per_horizon(attributions, top_k=top_k) + drawn = pages._build_pdf_report( + Path(output_path), + dataset_name=dataset_name, + forecast_df=frame, + explanation=explanation, + target_column=target, + timestamp_column=step, + heatmap_path=None, + topk_rows=topk_rows, + top_k=top_k, + context_len=_context_len(carried), + forecast_horizon=attributions.shape[1], + channel_labels=_channels(carried), + ) + if drawn is None: # pragma: no cover - matplotlib is present by here + raise MissingExtraError('report', 'matplotlib') + return drawn + + +def _pages() -> Any: + try: + from sdm_client.explain._kumo_ts import pages + except ImportError as error: # pragma: no cover - the extra is absent + raise MissingExtraError('report', 'matplotlib') from error + return pages + + +def _explanation(carried: dict[str, Any]) -> Any: + r"""The explanation as the drawing expects it, read back from the data. + + Only the arrays the pages read are restored. A field the explanation did + not carry stays absent, and the page that would have drawn it is not + drawn, which is what "this was not computed" looks like on paper. + """ + from sdm_client.explain._kumo_ts.interpretability import ( + ForecastExplanation, + ) + + block = carried.get('explanation') or {} + + def array(name: str) -> Any: + value = block.get(name) + return None if value is None else np.asarray(value, dtype=float) + + return ForecastExplanation( + baseline_forecast=array('baseline_forecast'), + lag_horizon_scores=array('lag_horizon_scores'), + lag_horizon_attributions=array('lag_horizon_attributions'), + flow_magnitudes=array('flow_magnitudes'), + latent_trajectory=array('latent_trajectory'), + channel_horizon_attributions=array('channel_horizon_attributions'), + ) + + +def _forecast_frame(carried: dict[str, Any]) -> tuple[Any, str, str]: + import pandas as pd + + rows = carried.get('forecast') or [] + frame = pd.DataFrame(rows) + target = str((carried.get('metadata') or {}).get('target_column') or '') + step = 'forecast_step' + if f'{target}_forecast' not in frame.columns: + raise StructuredDataError( + f'this explanation names {target!r} as the series forecast and ' + f'carries {sorted(frame.columns)}, which does not include it', + code='INVALID_RESPONSE', + ) + return frame, target, step + + +def _channels(carried: dict[str, Any]) -> list[str] | None: + labels = (carried.get('metadata') or {}).get('channel_labels') + return None if labels is None else [str(name) for name in labels] + + +def _context_len(carried: dict[str, Any]) -> int | None: + block = (carried.get('explanation') or {}).get('diagnostics') or {} + shape = block.get('latent_trajectory_shape') + return None if not shape else int(shape[0]) diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py new file mode 100644 index 000000000..0cd83e1a9 --- /dev/null +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -0,0 +1,147 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Why a forecast is the forecast it is, and the report that draws it. + +An explanation walks a window per step of the model's context, so it costs +tens of seconds where a forecast costs a fraction of one. It is computed once +here and read by every test that needs one. +""" + +from __future__ import annotations + +import numpy as np +import pandas as pd +import pytest + +from sdm_client import KumoForecast, Request, SDMClient, StructuredDataError + +pytest.importorskip('matplotlib', reason='needs the report extra') + +from sdm_client.reporting import forecast_report # noqa: E402 + +pytestmark = pytest.mark.filterwarnings('ignore') + + +def history(rows: int = 600) -> pd.DataFrame: + step = np.arange(rows, dtype=float) + return pd.DataFrame({'flow': np.sin(step / 9), 'temp': np.cos(step / 7)}) + + +@pytest.fixture(scope='module') +def explained(forecast): + with SDMClient.in_process(forecast) as client: + return client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + +def pages(path) -> int: + raw = path.read_bytes() + return raw.count(b'/Type /Page') - raw.count(b'/Type /Pages') + + +def test_an_explanation_comes_back_when_it_is_asked_for(explained): + """It reads the model's gradients and its latent trajectory, so it is + produced where the model runs and nowhere else.""" + carried = explained.explanation + + assert isinstance(carried, dict) + assert set(carried) >= {'forecast', 'explanation', 'metadata'} + + +def test_the_attribution_covers_every_lag_and_every_step(explained): + block = explained.explanation['explanation'] + attributions = np.asarray(block['lag_horizon_attributions']) + + assert attributions.shape == (block['shapes']['K_lags'], 4) + assert np.isfinite(attributions).all() + + +def test_an_explanation_is_data_rather_than_an_object(explained): + """It travels as the contract's `explanation` field, so it has to be + what that field carries.""" + import json + + assert json.loads(json.dumps(explained.explanation)) + + +def test_a_forecast_asked_without_one_does_not_pay_for_it(forecast): + """It costs far more than the forecast, so it is not computed unless it + was asked for.""" + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction'], + ) + + assert result.explanation is None + + +def test_a_report_is_drawn_from_an_explanation(explained, tmp_path): + written = forecast_report(explained, tmp_path / 'forecast.pdf') + + assert written.exists() + assert pages(written) >= 3 + + +def test_the_report_names_the_series_and_the_lag_window(explained, tmp_path): + """Read off the data the page is drawn from. The text in this PDF is + compressed, so sniffing its bytes for a word tests the encoder rather + than the report.""" + metadata = explained.explanation['metadata'] + + assert metadata['target_column'] == 'flow' + assert metadata['channel_labels'] == ['flow', 'temp'] + assert forecast_report( + explained, tmp_path / 'forecast.pdf', dataset_name='flow' + ).exists() + + +def test_a_forecast_with_no_explanation_says_how_to_ask_for_one( + forecast, tmp_path +): + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction'], + ) + + with pytest.raises(StructuredDataError) as caught: + forecast_report(result, tmp_path / 'forecast.pdf') + assert 'explanation' in str(caught.value) + + +def test_a_history_shorter_than_the_model_reads_cannot_be_attributed( + forecast, +): + """The attribution is about the window the model read, and a history + shorter than that window is not one it read.""" + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast(history(100), target='flow', horizon=2), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert '512' in str(caught.value) + + +def test_only_this_model_is_asked_to_explain_a_forecast(anomaly): + """`explanation` is a field the forecaster produces, not every model.""" + from sdm_client import KumoAnomaly + + frame = pd.DataFrame({'flow': np.sin(np.arange(60) / 9)}) + with SDMClient.in_process(anomaly) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.anomaly(frame, inference={'num_samples': 1}), + model=KumoAnomaly(), + outputs=['prediction', 'explanation'], + ) + assert 'explanation' in str(caught.value) diff --git a/pyproject.toml b/pyproject.toml index 22aaba07f..8f4fe7df7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,12 @@ target-version = "py310" # illustrated. extend-exclude = [ "packages/structured-data-models-pql/src/predictive_query/grammar", + # Kumo-TS's forecast attribution, vendored as that package wrote it, down + # to putting `from __future__` above its own module docstrings. Excluded + # from mypy for the same reason; the two lists move together. Checked for + # the lints that are not style first: an undefined name here would be a + # line this move dropped, and two were. + "packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts", "packages/structured-data-models-api/src/sdm_api/generated/tfm_api.py", "*.md", ] @@ -86,6 +92,10 @@ exclude = [ # ANTLR's output, regenerated from the grammar rather than edited. Excluded # from ruff for the same reason; the two lists move together. "packages/structured-data-models-pql/src/predictive_query/grammar/", + # Kumo-TS's forecast attribution, vendored as that package wrote it. An + # attribution is a statement about what a model did, so the arithmetic + # that makes it is not this repository's to retype. + "packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/", ] # --- Baseline recorded 2026-09-17 ------------------------------------------- From d5e29c433f287d00d69d28d407781ffdf645cb22 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 08:12:56 -0800 Subject: [PATCH 02/13] Attribute the model that answered, in the space it answered in Ten defects, and three of them meant the numbers were wrong rather than the plumbing. An attribution that is confidently wrong is worse than none, so these are the ones that matter. The shim fed raw readings to the inner model. The public path standardises first, with frozen statistics, so what was being attributed was a model reading numbers it never sees. The window is standardised now, as upstream standardises before it attributes, and the baseline forecast is put back in the readings' own scale before it travels. The padding mask was discarded. The trajectory builder pads its windows and says which steps are padding; dropping that read the padding as observed zeros, and a constant series showed its latent trajectory moving. The forecaster has no mask argument and reads an unobserved step as NaN, whose statistics its normalisation already ignores, so that is how the mask is applied. A flat series moved 8.53 before and 0.011 after. An explanation of a retrieval-blended forecast described the direct forward pass, which is a different number from the one returned. Asking for both is refused, naming the knob to drop. Then the report, which was reconstructing an explanation it had written itself and getting five things wrong: the top lags were ranked from the attributions rather than the scores they are differenced from, the context length counted the horizon as history, the feature-axis block and all four diagnostics were read flat where they are nested and so were silently lost after costing minutes to compute, and feature-axis attribution was offered for horizons past the one forward pass it reads. `[report]` now brings torch, which the forecast pages import. Two helper imports this move left pointing at Kumo-TS are corrected; one of them raised ModuleNotFoundError the moment the integrated-gradients page ran. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../pyproject.toml | 6 +- .../src/sdm_client/explain/_explain.py | 56 ++++++++- .../explain/_kumo_ts/interpretability.py | 6 +- .../src/sdm_client/explain/_model.py | 39 +++++- .../src/sdm_client/in_process/forecast.py | 34 +++++ .../src/sdm_client/reporting/forecast.py | 56 +++++++-- .../test_a_forecast_says_what_it_rested_on.py | 116 ++++++++++++++++++ tests/test_release_contract.py | 6 +- uv.lock | 79 ++++++------ 9 files changed, 337 insertions(+), 61 deletions(-) diff --git a/packages/structured-data-models-client/pyproject.toml b/packages/structured-data-models-client/pyproject.toml index cdf02c57f..e168b0bf9 100644 --- a/packages/structured-data-models-client/pyproject.toml +++ b/packages/structured-data-models-client/pyproject.toml @@ -93,7 +93,11 @@ in-process = ["structured-data-models>=0.2.1,<0.3; python_version >= '3.11'"] # not given one. `all` does not carry it for the same reason it does not carry # `databricks-serving`: it is a thing to do with an answer rather than a # backend to read. -report = ["matplotlib>=3.8,<4"] +# Drawing a forecast explanation reads the attribution's own tensors, so this +# brings torch as well as matplotlib. structured-data-models brings torch too, +# and a forecast explanation needs that package anyway; this is so that asking +# for `[report]` alone is enough to draw what you were given. +report = ["matplotlib>=3.8,<4", "torch>=2.7"] all = [ "structured-data-models-client[relational,sqlite,duckdb,postgres,snowflake,databricks,lakebase,s3]", ] diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index 64740b69c..b25b94511 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -12,6 +12,7 @@ from __future__ import annotations +from dataclasses import replace from typing import Any import numpy as np @@ -62,7 +63,19 @@ def explanation_of( f'history is {history.shape[-1]}', code='UNSUPPORTED_SHAPE', ) - window = history[..., -forecaster.context_size :] + # Standardised first, as the model's own path standardises before it + # reads anything. The attribution then works in the space the model works + # in; handing it raw readings attributed a model being fed numbers it + # never sees. + if feature_axis and horizon > forecaster.prediction_size: + raise StructuredDataError( + f'feature-axis attribution reads one forward pass, which covers ' + f'{forecaster.prediction_size} steps, and this forecast is ' + f'{horizon}. Ask for it over a horizon the model reaches in one ' + f'pass, or ask for the explanation without it', + code='UNSUPPORTED_SHAPE', + ) + window = _standardised(model, history[..., -forecaster.context_size :]) explanation = explain_forecast( forecaster, x_context_ct=np.ascontiguousarray(window, dtype='float32'), @@ -76,10 +89,40 @@ def explanation_of( channel_target=channels.index(target) if feature_axis else None, channel_output_aware=feature_axis, ) - return _as_dict(explanation, channels, target, horizon, forecast) + return _as_dict(model, explanation, channels, target, horizon, forecast) + + +def _standardised(model: Any, window: np.ndarray) -> np.ndarray: + r"""``window`` through the model's own frozen standardisation.""" + import pandas as pd + from sdm import TableTensor + + frame = pd.DataFrame( + {str(i): row for i, row in enumerate(np.asarray(window, dtype=float))} + ) + table = TableTensor.from_pandas( + frame, dict.fromkeys(frame.columns, 'numerical') + ) + standardised = model.default_recipe().target.transform(table) + return standardised.numerical.detach().cpu().numpy().T + + +def _in_original_scale(model: Any, values: np.ndarray) -> np.ndarray: + r"""The inverse of :func:`_standardised`, for what is drawn.""" + import pandas as pd + from sdm import TableTensor + + array = np.asarray(values, dtype=float) + frame = pd.DataFrame({str(i): row for i, row in enumerate(array)}) + table = TableTensor.from_pandas( + frame, dict.fromkeys(frame.columns, 'numerical') + ) + restored = model.default_recipe().target.inverse_transform(table) + return restored.numerical.detach().cpu().numpy().T def _as_dict( + model: Any, explanation: Any, channels: list[str], target: str, @@ -93,6 +136,15 @@ def _as_dict( """ from sdm_client.explain._kumo_ts.pages import _explanation_to_dict + # The attribution works standardised, so what it calls the baseline + # forecast is standardised too. The report draws it beside readings, so + # it is put back in their scale before it travels. + explanation = replace( + explanation, + baseline_forecast=_in_original_scale( + model, np.asarray(explanation.baseline_forecast) + ), + ) frame = pd.DataFrame( { 'forecast_step': range(1, horizon + 1), diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py index 84662f021..2c7eb1dd8 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py @@ -1482,8 +1482,10 @@ def _solve_one(args: tuple[int, int]) -> tuple[int, int, Array, float]: # the parallel path opt in via ``n_jobs`` (typically the OS CPU count # divided by the number of GPU workers, so threads do not oversubscribe # cores in a multi-GPU run). - if n_jobs is not None and int(n_jobs) > 1 and len(work_items) > 1: - from sdm_client.explain._parallel import parallel_apply_threads + # Kumo-TS threads this across cores with a helper this port leaves + # behind, because it exists to feed several GPUs. The branch below does + # the same work in order. + if False: # pragma: no cover - the threaded path is not ported for c_idx, h_idx, b, a0 in parallel_apply_threads( _solve_one, work_items, n_jobs=int(n_jobs) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index 1e96e31ef..d1d07af44 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -12,6 +12,13 @@ The embedding is the model's own, the one it builds retrieval keys from. An attribution is a statement about what the model did, so reducing its encoder output some other way here would attribute something the model never computed. + +The windows it is handed are padded, and which steps are padding arrives as a +mask. structured-data-models' forecaster takes no mask: it reads an +unobserved step as ``NaN``, and its normalisation ignores those when it takes +a window's statistics. So the mask is applied as ``NaN`` here. Dropping it +instead made padding into observed zeros, and a flat series then showed the +latent trajectory moving when it had not. """ from __future__ import annotations @@ -56,15 +63,17 @@ def __call__( self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None ) -> _Forecast: r"""The forecast for ``x_enc`` of shape ``[B, C, R]``.""" - return _Forecast(forecast=self._inner(x_enc)) + return _Forecast(forecast=self._inner(_observed(x_enc, input_mask))) def embed( self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None ) -> _Embedding: r"""One embedding per window of ``x_enc``, shaped ``[B, D]``.""" - return _Embedding(embeddings=self.embed_tensor(x_enc)) + return _Embedding(embeddings=self.embed_tensor(x_enc, input_mask)) - def embed_tensor(self, x_enc: torch.Tensor) -> torch.Tensor: + def embed_tensor( + self, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None + ) -> torch.Tensor: r"""The embedding as a plain tensor, differentiably. Kept apart from :meth:`embed` because integrated gradients needs the @@ -73,5 +82,27 @@ def embed_tensor(self, x_enc: torch.Tensor) -> torch.Tensor: """ from sdm.models.kumo.timeseries.forecast.darr import embed - encoded, _, _ = self._inner.encode(x_enc) + encoded, _, _ = self._inner.encode(_observed(x_enc, input_mask)) return embed(encoded) + + +def _observed(x: torch.Tensor, mask: torch.Tensor | None) -> torch.Tensor: + r"""``x`` with the steps the mask calls padding marked unobserved. + + The forecaster has no mask argument and reads ``NaN`` as unobserved: its + normalisation takes a window's statistics over what is there, and zeroes + what is not once they are taken. + """ + if mask is None: + return x + keep = torch.as_tensor(mask, device=x.device).bool() + if keep.all(): + return x + # The mask's last axis is steps and anything before it is the window it + # belongs to; the readings have a channel axis between the two. It is one + # mask for every channel of a window, so the channel axis is where the + # singleton goes. + keep = keep.unsqueeze(-2) + while keep.ndim < x.ndim: + keep = keep.unsqueeze(0) + return x.masked_fill(~keep.expand_as(x), float('nan')) diff --git a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py index 456124609..3a92e4d79 100644 --- a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -233,6 +233,13 @@ def answer( PredictionItem(row_index=0, forecast_step=step, prediction=value) for step, value in enumerate(forecast.tolist(), start=1) ] + if 'explanation' in fields: + self._refuse_where_retrieval_answered( + model, + alpha, + len(payload['context']['instance_table']['rows']), + horizon, + ) if 'explanation' in fields and items: items[0] = replace( items[0], @@ -277,6 +284,33 @@ def _explained( feature_axis=bool(options.get('feature_axis', False)), ) + @staticmethod + def _refuse_where_retrieval_answered( + model: Any, alpha: float, history: int, horizon: int + ) -> None: + r"""Refuse to explain a forecast retrieval had a hand in. + + The attribution describes the model's own forward pass. Where + retrieval contributes, the forecast returned is a blend of that pass + and windows pulled from history, and attributing the pass would + describe a number nobody was given. + """ + if alpha >= 1.0: + return + needed = model.model.context_size + max( + model.model.prediction_size, horizon + ) + if history < needed: + return + raise StructuredDataError( + f'alpha={alpha} blends retrieved history into this forecast, and ' + f"an explanation describes the model's own forward pass only. " + f'Explaining it would describe a forecast that was not returned. ' + f'Ask for the explanation with alpha=1, or ask for the forecast ' + f'without one', + code='UNSUPPORTED_REQUEST', + ) + @staticmethod def _warn_where_retrieval_does_nothing( model: Any, alpha: float, history: int, horizon: int diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index c763a7082..c4c02ecea 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -78,7 +78,7 @@ def forecast_report( heatmap_path=None, topk_rows=topk_rows, top_k=top_k, - context_len=_context_len(carried), + context_len=_context_len(carried, attributions.shape[1]), forecast_horizon=attributions.shape[1], channel_labels=_channels(carried), ) @@ -107,18 +107,41 @@ def _explanation(carried: dict[str, Any]) -> Any: ) block = carried.get('explanation') or {} - - def array(name: str) -> Any: - value = block.get(name) + # Serialised under `feature_axis`, not beside the lag arrays. Reading it + # flat found nothing and the page that draws it was skipped although it + # had been computed, which costs minutes. + feature_axis = block.get('feature_axis') or {} + diagnostics = block.get('diagnostics') or {} + + def array(source: dict[str, Any], name: str) -> Any: + value = source.get(name) return None if value is None else np.asarray(value, dtype=float) + def scalar(name: str) -> float | None: + value = diagnostics.get(name) + return None if value is None else float(value) + return ForecastExplanation( - baseline_forecast=array('baseline_forecast'), - lag_horizon_scores=array('lag_horizon_scores'), - lag_horizon_attributions=array('lag_horizon_attributions'), - flow_magnitudes=array('flow_magnitudes'), - latent_trajectory=array('latent_trajectory'), - channel_horizon_attributions=array('channel_horizon_attributions'), + baseline_forecast=array(block, 'baseline_forecast'), + lag_horizon_scores=array(block, 'lag_horizon_scores'), + lag_horizon_attributions=array(block, 'lag_horizon_attributions'), + flow_magnitudes=array(block, 'flow_magnitudes'), + latent_trajectory=array(block, 'latent_trajectory'), + channel_horizon_attributions=array( + feature_axis, 'channel_horizon_attributions' + ), + per_channel_flow=array(feature_axis, 'per_channel_flow'), + channel_flow_method=feature_axis.get('method'), + flow_ratio_forecast_vs_history=scalar('flow_ratio_forecast_vs_history'), + flow_variance_ratio_forecast_vs_history=scalar( + 'flow_variance_ratio_forecast_vs_history' + ), + curvature_ratio_forecast_vs_history=scalar( + 'curvature_ratio_forecast_vs_history' + ), + latent_diag_mahalanobis_ratio_forecast_vs_history=scalar( + 'latent_diag_mahalanobis_ratio_forecast_vs_history' + ), ) @@ -143,7 +166,16 @@ def _channels(carried: dict[str, Any]) -> list[str] | None: return None if labels is None else [str(name) for name in labels] -def _context_len(carried: dict[str, Any]) -> int | None: +def _context_len(carried: dict[str, Any], horizon: int) -> int | None: + r"""How many of the trajectory's steps are history. + + The trajectory runs the context and then the horizon, so its length is + both put together. Reading it as the context alone told the page every + transition was history and none was forecast. + """ block = (carried.get('explanation') or {}).get('diagnostics') or {} shape = block.get('latent_trajectory_shape') - return None if not shape else int(shape[0]) + if not shape: + return None + steps = int(shape[0]) - horizon + return steps if steps > 0 else None diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 0cd83e1a9..307b90d27 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -82,6 +82,122 @@ def test_a_forecast_asked_without_one_does_not_pay_for_it(forecast): assert result.explanation is None +def test_a_flat_series_has_almost_nowhere_to_move(forecast): + """The trajectory builder pads its windows and says which steps are + padding. Reading the padding as observed zeros made a constant series + look like it moved.""" + flat = pd.DataFrame({'flow': np.full(600, 10.0)}) + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(flat, target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + flow = np.asarray(result.explanation['explanation']['flow_magnitudes']) + assert float(flow.sum()) < 0.5 + + +def test_a_forecast_retrieval_had_a_hand_in_is_not_explained(forecast): + """The attribution describes the model's own forward pass. Where + retrieval contributes, explaining that pass describes a number the + caller was never given.""" + history_long = history(600) + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + history_long, + target='flow', + horizon=4, + inference={'alpha': 0.0}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'alpha' in str(caught.value) + + +def test_the_attribution_reads_the_model_s_own_scale(forecast): + """The model standardises before it reads anything, so the attribution + works there too. Handing it raw readings attributed a model being fed + numbers it never sees.""" + from sdm_client.explain._explain import _standardised + + raw = np.array([[1.0, 2.0, 3.0]]) + standardised = _standardised(forecast, raw) + + assert not np.allclose(standardised, raw) + assert np.allclose( + standardised, (raw + 5.671202659606934) / 8.693312644958496, atol=1e-4 + ) + + +def test_what_is_drawn_is_in_the_readings_own_scale(explained): + """The attribution works standardised; a reader does not.""" + baseline = np.asarray( + explained.explanation['explanation']['baseline_forecast'] + ) + + assert np.abs(baseline).max() < 5.0 + + +def test_the_feature_axis_needs_a_horizon_one_pass_reaches(forecast): + """It reads a single forward pass, which covers the model's own horizon + and no more.""" + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + history(600), + target='flow', + horizon=80, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'feature-axis' in str(caught.value) + + +def test_the_diagnostics_survive_being_written_and_read(explained): + """They are computed, serialised, and read back for the page that prints + them, which printed n/a for every one of them.""" + from sdm_client.reporting.forecast import _explanation + + restored = _explanation(explained.explanation) + + assert restored.flow_ratio_forecast_vs_history is not None + assert restored.curvature_ratio_forecast_vs_history is not None + + +def test_the_top_lags_are_ranked_from_the_scores(explained): + """That helper differences a cumulative score into a per-step weight. + Handing it the normalised attribution ranked the lags near-backwards.""" + from sdm_client.explain._kumo_ts import pages + + block = explained.explanation['explanation'] + scores = np.asarray(block['lag_horizon_scores']) + attributions = np.asarray(block['lag_horizon_attributions']) + _, from_scores = pages._topk_lag_steps_per_horizon(scores, top_k=3) + _, from_attributions = pages._topk_lag_steps_per_horizon( + attributions, top_k=3 + ) + + assert from_scores != from_attributions + + +def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): + """The trajectory runs the context and then the horizon. Reading its + length as the context said every transition was history.""" + from sdm_client.reporting.forecast import _context_len + + block = explained.explanation['explanation'] + steps = block['diagnostics']['latent_trajectory_shape'][0] + + assert _context_len(explained.explanation, 4) == steps - 4 + + def test_a_report_is_drawn_from_an_explanation(explained, tmp_path): written = forecast_report(explained, tmp_path / 'forecast.pdf') diff --git a/tests/test_release_contract.py b/tests/test_release_contract.py index 294f7ad35..4040098ed 100644 --- a/tests/test_release_contract.py +++ b/tests/test_release_contract.py @@ -1240,8 +1240,9 @@ def test_every_advertised_extra_of_the_client_resolves_to_a_real_target( one of the few it does not. databricks-sdk and structured-data-models are imported by the - client's own transports, and matplotlib by the one module that draws - an answer, so the client is the distribution that declares them. + client's own transports, and matplotlib and torch by the modules + that draw an answer, so the client is the distribution that declares + them. """ client = _pyproject('structured-data-models-client')['project'] known = set(_distributions()) @@ -1258,6 +1259,7 @@ def test_every_advertised_extra_of_the_client_resolves_to_a_real_target( 'requests-mock', 'databricks-sdk', 'matplotlib', + 'torch', 'structured-data-models', }, ( f'extra {extra!r} requires {name!r}, which is not one of ' diff --git a/uv.lock b/uv.lock index 78ab2dcf7..f9a38e768 100644 --- a/uv.lock +++ b/uv.lock @@ -895,7 +895,7 @@ name = "cuda-bindings" version = "13.4.4" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cuda-pathfinder", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "cuda-pathfinder", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/9b/1e/d90a8af3d589776c70e92d43d7a0234260709a1d552d105f4dd3bdf48fa3/cuda_bindings-13.4.4-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:90f85a00fc89dd4a8f7c4beb0a2f3f788b845c8496fe84adc1217830206db9e0", size = 6512106, upload-time = "2026-10-14T12:35:04.07Z" }, @@ -930,43 +930,43 @@ wheels = [ [package.optional-dependencies] cublas = [ - { name = "nvidia-cublas", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cuda-nvrtc", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cudart = [ - { name = "nvidia-cuda-runtime", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-runtime", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cufft = [ - { name = "nvidia-cufft", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cufft", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cufile = [ - { name = "nvidia-cufile", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cufile", marker = "(platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cupti = [ - { name = "nvidia-cuda-cupti", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-cupti", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] curand = [ - { name = "nvidia-curand", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-curand", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cusolver = [ - { name = "nvidia-cublas", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cusolver", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-cusparse", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusolver", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] cusparse = [ - { name = "nvidia-cusparse", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvjitlink = [ - { name = "nvidia-nvjitlink", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvrtc = [ - { name = "nvidia-cuda-nvrtc", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] nvtx = [ - { name = "nvidia-nvtx", marker = "(python_full_version >= '3.11' and platform_machine == 'aarch64' and sys_platform == 'linux') or (python_full_version >= '3.11' and platform_machine == 'x86_64' and sys_platform == 'linux')" }, + { name = "nvidia-nvtx", marker = "(python_full_version < '3.11' and platform_machine == 'AMD64' and sys_platform == 'win32') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux')" }, ] [[package]] @@ -2530,7 +2530,7 @@ name = "nvidia-cublas" version = "13.1.1.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cuda-nvrtc", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/a7/a1/0bd24ee8c8d03adac032fd2909426a00c88f8c57961b1277ded97f91119f/nvidia_cublas-13.1.1.3-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:b7a210458267ac818974c53038fbec2e969d5c99f305ab15c72522fa9f001dd5", size = 542848918, upload-time = "2026-04-08T18:46:22.985Z" }, @@ -2569,7 +2569,7 @@ name = "nvidia-cudnn-cu13" version = "9.24.0.43" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/ca/30/7c257e3d5cb4fecb147b93895c66e29c93f8e76d74b45bb418ff0587c4ec/nvidia_cudnn_cu13-9.24.0.43-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:a6812a554a1ff0413e9c52b84c26c050380649ab9615f9c16bded368ce9f421f", size = 650976863, upload-time = "2026-07-02T16:23:39.248Z" }, @@ -2581,7 +2581,7 @@ name = "nvidia-cufft" version = "12.0.0.61" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/8b/ae/f417a75c0259e85c1d2f83ca4e960289a5f814ed0cea74d18c353d3e989d/nvidia_cufft-12.0.0.61-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2708c852ef8cd89d1d2068bdbece0aa188813a0c934db3779b9b1faa8442e5f5", size = 214053554, upload-time = "2025-09-04T08:31:38.196Z" }, @@ -2611,9 +2611,9 @@ name = "nvidia-cusolver" version = "12.0.4.66" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-cublas", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "nvidia-cusparse", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-cublas", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-cusparse", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/c8/c3/b30c9e935fc01e3da443ec0116ed1b2a009bb867f5324d3f2d7e533e776b/nvidia_cusolver-12.0.4.66-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:02c2457eaa9e39de20f880f4bd8820e6a1cfb9f9a34f820eb12a155aa5bc92d2", size = 223467760, upload-time = "2025-09-04T08:33:04.222Z" }, @@ -2625,7 +2625,7 @@ name = "nvidia-cusparse" version = "12.6.3.3" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "nvidia-nvjitlink", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" }, + { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.11' and sys_platform == 'emscripten') or (python_full_version < '3.11' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/f8/94/5c26f33738ae35276672f12615a64bd008ed5be6d1ebcb23579285d960a9/nvidia_cusparse-12.6.3.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:80bcc4662f23f1054ee334a15c72b8940402975e0eab63178fc7e670aa59472c", size = 162155568, upload-time = "2025-09-04T08:33:42.864Z" }, @@ -4426,6 +4426,7 @@ relational = [ report = [ { name = "matplotlib", version = "3.10.9", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "matplotlib", version = "3.11.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "torch" }, ] s3 = [ { name = "structured-data-models-connectors", extra = ["s3"] }, @@ -4462,6 +4463,7 @@ requires-dist = [ { name = "structured-data-models-connectors", extras = ["sqlite"], marker = "extra == 'sqlite'", editable = "packages/structured-data-models-connectors" }, { name = "structured-data-models-pql", editable = "packages/structured-data-models-pql" }, { name = "structured-data-models-relational-engine", marker = "extra == 'relational'", editable = "packages/structured-data-models-relational-engine" }, + { name = "torch", marker = "extra == 'report'", specifier = ">=2.7" }, { name = "urllib3", specifier = ">=1.26" }, ] provides-extras = ["relational", "sqlite", "duckdb", "snowflake", "databricks", "postgres", "lakebase", "s3", "databricks-serving", "in-process", "report", "all", "test"] @@ -4791,21 +4793,22 @@ name = "torch" version = "2.14.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "cuda-bindings", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "cuda-toolkit", extra = ["cublas", "cudart", "cufft", "cufile", "cupti", "curand", "cusolver", "cusparse", "nvjitlink", "nvrtc", "nvtx"], marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "filelock", marker = "python_full_version >= '3.11'" }, - { name = "fsspec", marker = "python_full_version >= '3.11'" }, - { name = "jinja2", marker = "python_full_version >= '3.11'" }, + { name = "cuda-bindings", marker = "sys_platform == 'linux'" }, + { name = "cuda-toolkit", extra = ["cublas", "cudart", "cufft", "cufile", "cupti", "curand", "cusolver", "cusparse", "nvjitlink", "nvrtc", "nvtx"], marker = "sys_platform == 'linux'" }, + { name = "filelock" }, + { name = "fsspec" }, + { name = "jinja2" }, + { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "networkx", version = "3.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" }, { name = "networkx", version = "3.7", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, - { name = "nvidia-cudnn-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-cusparselt-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-nccl-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "nvidia-nvshmem-cu13", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "setuptools", marker = "python_full_version >= '3.11'" }, - { name = "sympy", marker = "python_full_version >= '3.11'" }, - { name = "triton", marker = "python_full_version >= '3.11' and sys_platform == 'linux'" }, - { name = "typing-extensions", marker = "python_full_version >= '3.11'" }, + { name = "nvidia-cudnn-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-cusparselt-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-nccl-cu13", marker = "sys_platform == 'linux'" }, + { name = "nvidia-nvshmem-cu13", marker = "sys_platform == 'linux'" }, + { name = "setuptools" }, + { name = "sympy" }, + { name = "triton", marker = "sys_platform == 'linux'" }, + { name = "typing-extensions" }, ] wheels = [ { url = "https://files.pythonhosted.org/packages/7a/45/b0c389051ed02d77227202caf2c2abb1706ca4362781eb79bd6707359970/torch-2.14.1-cp310-cp310-macosx_14_0_arm64.whl", hash = "sha256:e24b9815001d18e73e76eae1ea25f8ef908c6103e857378ad20f8f6cf5c954f5", size = 127249640, upload-time = "2026-09-30T17:43:48.426Z" }, From ad4982941e2ae9860fd58c353daaa51288f04df2 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 08:26:46 -0800 Subject: [PATCH 03/13] Rank the lags from the scores, draw the heatmap, refuse a gapped channel The top-lag fix in the last commit never landed: the call had been reflowed onto one line, the edit matched nothing, and the test written for it compared the helper against itself rather than the report's own call, so it passed over the bug it was meant to catch. It asserts on what the report passes now. The attribution heatmap is a page drawn from an image on disk, and the path to it was hardcoded to nothing, so every report left that page out although the matrix was right there. The artifacts are written now, and `artifacts_dir` keeps them: the CSVs beside the images are the ones Kumo-TS writes. Feature-axis attribution replaces a channel with its own average over the window, which a single missing reading makes undefined. The channel then reads as inactive and is reported as having no influence, which is a confident answer about a column nothing was learnt about. That is upstream's arithmetic and this port does not rewrite it, so the case is refused instead. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/explain/_explain.py | 13 ++++ .../src/sdm_client/reporting/forecast.py | 64 +++++++++++---- .../test_a_forecast_says_what_it_rested_on.py | 78 ++++++++++++++++--- 3 files changed, 130 insertions(+), 25 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index b25b94511..3c9a3c66e 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -67,6 +67,19 @@ def explanation_of( # reads anything. The attribution then works in the space the model works # in; handing it raw readings attributed a model being fed numbers it # never sees. + if feature_axis and not np.isfinite(history).all(): + # Feature-axis attribution perturbs a channel towards its own mean + # over the window, and that mean is NaN if any reading in it is + # missing. The channel then reads as inactive and is given no + # influence at all, which is a confident answer about a column + # nothing was learnt about. Refused rather than reported. + raise StructuredDataError( + 'feature-axis attribution replaces a channel with its own ' + 'average, which a gap in the readings makes undefined, and the ' + 'channel is then reported as having no influence. Fill the gaps, ' + 'or ask for the explanation without the feature axis', + code='UNSUPPORTED_SHAPE', + ) if feature_axis and horizon > forecaster.prediction_size: raise StructuredDataError( f'feature-axis attribution reads one forward pass, which covers ' diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index c4c02ecea..b4483741e 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -16,6 +16,9 @@ from __future__ import annotations +import tempfile +from collections.abc import Iterator +from contextlib import contextmanager from pathlib import Path from typing import TYPE_CHECKING, Any @@ -33,6 +36,7 @@ def forecast_report( *, dataset_name: str | None = None, top_k: int = 5, + artifacts_dir: str | Path | None = None, ) -> Path: r"""Draw why ``result`` is the forecast it is. @@ -43,6 +47,10 @@ def forecast_report( output_path: Where to write the PDF. dataset_name: A name for the run, shown on the first page. top_k: How many lags to list per horizon. + artifacts_dir: Where to keep the CSVs and images the pages are drawn + from. They are written either way, because the attribution + heatmap is a page drawn from an image on disk; naming a + directory is what keeps them afterwards. Raises: MissingExtraError: If matplotlib is not installed. @@ -67,21 +75,32 @@ def forecast_report( frame, target, step = _forecast_frame(carried) explanation = _explanation(carried) attributions = np.asarray(explanation.lag_horizon_attributions) - _, topk_rows = pages._topk_lag_steps_per_horizon(attributions, top_k=top_k) - drawn = pages._build_pdf_report( - Path(output_path), - dataset_name=dataset_name, - forecast_df=frame, - explanation=explanation, - target_column=target, - timestamp_column=step, - heatmap_path=None, - topk_rows=topk_rows, - top_k=top_k, - context_len=_context_len(carried, attributions.shape[1]), - forecast_horizon=attributions.shape[1], - channel_labels=_channels(carried), + # Scores, not attributions. That helper differences a cumulative score + # into a per-step weight, and handing it the normalised attribution + # ranked the lags in very nearly the opposite order. + _, topk_rows = pages._topk_lag_steps_per_horizon( + np.asarray(explanation.lag_horizon_scores), top_k=top_k ) + with _artifacts(artifacts_dir) as out_dir: + heatmap = pages._save_lag_horizon_artifacts( + out_dir, + attributions, + np.asarray(explanation.lag_horizon_scores), + ) + drawn = pages._build_pdf_report( + Path(output_path), + dataset_name=dataset_name, + forecast_df=frame, + explanation=explanation, + target_column=target, + timestamp_column=step, + heatmap_path=heatmap, + topk_rows=topk_rows, + top_k=top_k, + context_len=_context_len(carried, attributions.shape[1]), + forecast_horizon=attributions.shape[1], + channel_labels=_channels(carried), + ) if drawn is None: # pragma: no cover - matplotlib is present by here raise MissingExtraError('report', 'matplotlib') return drawn @@ -179,3 +198,20 @@ def _context_len(carried: dict[str, Any], horizon: int) -> int | None: return None steps = int(shape[0]) - horizon return steps if steps > 0 else None + + +@contextmanager +def _artifacts(named: str | Path | None) -> Iterator[Path]: + r"""Where the images and CSVs the pages read are written. + + The attribution heatmap is a page drawn from a file, so there is always + somewhere for it to be. A caller who named a directory keeps what was + written there; one who did not gets a temporary one that goes away. + """ + if named is not None: + out_dir = Path(named) + out_dir.mkdir(parents=True, exist_ok=True) + yield out_dir + return + with tempfile.TemporaryDirectory(prefix='sdm-forecast-') as temporary: + yield Path(temporary) diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 307b90d27..9eef773a5 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -171,20 +171,33 @@ def test_the_diagnostics_survive_being_written_and_read(explained): assert restored.curvature_ratio_forecast_vs_history is not None -def test_the_top_lags_are_ranked_from_the_scores(explained): - """That helper differences a cumulative score into a per-step weight. - Handing it the normalised attribution ranked the lags near-backwards.""" +def test_the_top_lags_are_ranked_from_the_scores(explained, tmp_path): + """That helper differences a cumulative score into a per-step weight, so + handing it the normalised attribution ranks the lags near-backwards. + + Asserted on what the report passes. Comparing the helper against itself + said nothing about the call that draws the page, and passed while the + report still handed over the wrong array. + """ from sdm_client.explain._kumo_ts import pages + from sdm_client.reporting import forecast as module - block = explained.explanation['explanation'] - scores = np.asarray(block['lag_horizon_scores']) - attributions = np.asarray(block['lag_horizon_attributions']) - _, from_scores = pages._topk_lag_steps_per_horizon(scores, top_k=3) - _, from_attributions = pages._topk_lag_steps_per_horizon( - attributions, top_k=3 - ) + seen = [] + original = pages._topk_lag_steps_per_horizon - assert from_scores != from_attributions + def watched(scores, **kwargs): + seen.append(np.asarray(scores)) + return original(scores, **kwargs) + + pages._topk_lag_steps_per_horizon = watched + try: + module.forecast_report(explained, tmp_path / 'f.pdf') + finally: + pages._topk_lag_steps_per_horizon = original + + block = explained.explanation['explanation'] + assert len(seen) == 1 + assert np.allclose(seen[0], np.asarray(block['lag_horizon_scores'])) def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): @@ -198,6 +211,49 @@ def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): assert _context_len(explained.explanation, 4) == steps - 4 +def test_the_attribution_heatmap_is_drawn(explained, tmp_path): + """It is a page drawn from an image on disk, and hardcoding no image + dropped it from every report although the matrix was right there.""" + artifacts = tmp_path / 'artifacts' + written = forecast_report( + explained, tmp_path / 'f.pdf', artifacts_dir=artifacts + ) + + assert (artifacts / 'lag_horizon_heatmap.png').exists() + assert pages(written) >= 4 + + +def test_the_artifacts_are_kept_only_where_a_place_was_named( + explained, tmp_path +): + """They are written either way, because a page reads one of them.""" + before = set(tmp_path.iterdir()) + forecast_report(explained, tmp_path / 'f.pdf') + + assert set(tmp_path.iterdir()) - before == {tmp_path / 'f.pdf'} + + +def test_a_channel_with_a_gap_is_not_called_uninfluential(forecast): + """The feature axis replaces a channel with its own average, which a gap + makes undefined; the channel then reads as having no influence at all.""" + frame = history(600) + frame.loc[5, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'gap' in str(caught.value) + + def test_a_report_is_drawn_from_an_explanation(explained, tmp_path): written = forecast_report(explained, tmp_path / 'forecast.pdf') From 88e56ec6362cca5c24eb15cdf28730f8de39bcc5 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 08:41:09 -0800 Subject: [PATCH 04/13] Read the window that is attributed, and write the files the pages name The gap guard read the whole history and the attribution reads the last 512 steps of it, so a reading missing long before the window refused a question identical to one that answers. It checks the window now, and says which. A report drew pages that name `semantic_flow.csv` and the channel-axis CSV beside it and wrote neither, so a reader following the page found nothing. Each is written where the data behind it was computed. And the feature axis sets the forecast series' own effect aside rather than measuring it, because perturbing the thing being predicted moves it by construction. It reaches the page as a zero among measured numbers, where it reads as the least influential channel. The explanation now records which channel that is; the arithmetic and the page are upstream's and stay as they are. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/explain/_explain.py | 22 ++++++++---- .../src/sdm_client/reporting/forecast.py | 18 ++++++++++ .../test_a_forecast_says_what_it_rested_on.py | 35 ++++++++++++++++++- 3 files changed, 68 insertions(+), 7 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index 3c9a3c66e..498cd6954 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -67,17 +67,20 @@ def explanation_of( # reads anything. The attribution then works in the space the model works # in; handing it raw readings attributed a model being fed numbers it # never sees. - if feature_axis and not np.isfinite(history).all(): + window_only = history[..., -forecaster.context_size :] + if feature_axis and not np.isfinite(window_only).all(): # Feature-axis attribution perturbs a channel towards its own mean # over the window, and that mean is NaN if any reading in it is # missing. The channel then reads as inactive and is given no # influence at all, which is a confident answer about a column # nothing was learnt about. Refused rather than reported. raise StructuredDataError( - 'feature-axis attribution replaces a channel with its own ' - 'average, which a gap in the readings makes undefined, and the ' - 'channel is then reported as having no influence. Fill the gaps, ' - 'or ask for the explanation without the feature axis', + f'feature-axis attribution replaces a channel with its own ' + f'average over the window it reads, which a gap in that window ' + f'makes undefined, and the channel is then reported as having no ' + f'influence. The window is the last {forecaster.context_size} ' + f'steps; fill its gaps, or ask for the explanation without the ' + f'feature axis', code='UNSUPPORTED_SHAPE', ) if feature_axis and horizon > forecaster.prediction_size: @@ -88,7 +91,7 @@ def explanation_of( f'pass, or ask for the explanation without it', code='UNSUPPORTED_SHAPE', ) - window = _standardised(model, history[..., -forecaster.context_size :]) + window = _standardised(model, window_only) explanation = explain_forecast( forecaster, x_context_ct=np.ascontiguousarray(window, dtype='float32'), @@ -176,4 +179,11 @@ def _as_dict( # either way, and a report that cannot say which channel is which is # harder to read than one that can. rendered.setdefault('metadata', {})['channel_labels'] = list(channels) + # The feature axis perturbs each channel and watches the forecast move. + # Perturbing the series being forecast moves it by construction, so that + # channel's own effect is set aside rather than measured, and it reaches + # the page as a zero beside measured numbers. Saying so is what keeps a + # reader from taking it for the least influential channel. + if rendered.get('explanation', {}).get('feature_axis'): + rendered['metadata']['feature_axis_excludes'] = target return rendered diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index b4483741e..6e2fada63 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -87,6 +87,24 @@ def forecast_report( attributions, np.asarray(explanation.lag_horizon_scores), ) + # The pages name these files, so a report that draws the pages and + # writes none of them points a reader at nothing. Each is written + # where the data behind it was computed. + horizon = attributions.shape[1] + context = _context_len(carried, horizon) + if explanation.flow_magnitudes is not None and context: + pages._save_semantic_flow_csv( + out_dir, + np.asarray(explanation.flow_magnitudes), + context_len=context, + forecast_horizon=horizon, + ) + if explanation.channel_horizon_attributions is not None: + pages._save_channel_axis_artifacts( + out_dir, + np.asarray(explanation.channel_horizon_attributions), + channel_labels=_channels(carried), + ) drawn = pages._build_pdf_report( Path(output_path), dataset_name=dataset_name, diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 9eef773a5..42beee9cb 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -211,6 +211,39 @@ def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): assert _context_len(explained.explanation, 4) == steps - 4 +def test_a_gap_outside_the_window_is_not_a_gap_in_it(forecast): + """The attribution reads the last 512 steps, so a reading missing before + them is not missing from what it reads. Checking the whole history + refused a question identical to one it answers.""" + frame = history(600) + frame.loc[0, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + assert result.explanation is not None + + +def test_the_files_the_pages_name_are_written(explained, tmp_path): + """A page that names a file beside a report a reader cannot find points + them at nothing.""" + artifacts = tmp_path / 'artifacts' + forecast_report(explained, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = {path.name for path in artifacts.iterdir()} + + assert 'lag_horizon_heatmap.png' in written + assert 'semantic_flow.csv' in written + + def test_the_attribution_heatmap_is_drawn(explained, tmp_path): """It is a page drawn from an image on disk, and hardcoding no image dropped it from every report although the matrix was right there.""" @@ -237,7 +270,7 @@ def test_a_channel_with_a_gap_is_not_called_uninfluential(forecast): """The feature axis replaces a channel with its own average, which a gap makes undefined; the channel then reads as having no influence at all.""" frame = history(600) - frame.loc[5, 'temp'] = np.nan + frame.loc[599, 'temp'] = np.nan with SDMClient.in_process(forecast) as client: with pytest.raises(StructuredDataError) as caught: From b4a8a0e8bfb1820dbd80e2eab6b242ff93170313 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 08:58:36 -0800 Subject: [PATCH 05/13] Rank only what was measured, and refuse to attribute what cannot matter Recording that the feature axis excludes the forecast series was not a fix: the note never reached the page, which went on ranking the excluded channel among measured ones and, where the measured effects were small, called it the most influential of them all. Its row is not a measurement, so it is taken out of the matrix and out of the labels before anything is drawn. And a forecaster built without channel mixing cannot let a column measured alongside the series reach the forecast, while the embedding still pools that column, so an attribution moved for something that changes nothing. Asking to explain such a forecast over more than one channel is refused. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/explain/_explain.py | 13 +++++ .../src/sdm_client/explain/_model.py | 9 ++++ .../src/sdm_client/reporting/forecast.py | 39 +++++++++++++- .../test_a_forecast_says_what_it_rested_on.py | 54 +++++++++++++++++++ 4 files changed, 113 insertions(+), 2 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index 498cd6954..f8d1a8e68 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -67,6 +67,19 @@ def explanation_of( # reads anything. The attribution then works in the space the model works # in; handing it raw readings attributed a model being fed numbers it # never sees. + if len(channels) > 1 and not forecaster.mixes_channels: + # Without channel mixing and without retrieval, a covariate cannot + # reach the forecast at all. The embedding still pools every channel, + # so an attribution would move when one of them moves and report an + # influence the forecast does not have. + raise StructuredDataError( + 'this forecaster does not mix channels, so nothing measured ' + 'alongside the series can reach the forecast, and an attribution ' + 'over them would report an influence there is none of. Explain a ' + 'history of the series alone, or use a forecaster that mixes ' + 'channels', + code='UNSUPPORTED_REQUEST', + ) window_only = history[..., -forecaster.context_size :] if feature_axis and not np.isfinite(window_only).all(): # Feature-axis attribution perturbs a channel towards its own mean diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index d1d07af44..f0860ffff 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -54,6 +54,15 @@ def context_size(self) -> int: r"""How many steps the model reads.""" return int(self._inner.context_size) + @property + def mixes_channels(self) -> bool: + r"""Whether a channel can reach the forecast of another one. + + Without it, a column measured alongside the series contributes + nothing to the forecast, though the embedding still pools it. + """ + return self._inner.cross_channel is not None + @property def prediction_size(self) -> int: r"""How many steps it forecasts in one pass.""" diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 6e2fada63..3e2bff933 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -74,6 +74,14 @@ def forecast_report( pages = _pages() frame, target, step = _forecast_frame(carried) explanation = _explanation(carried) + # The feature axis sets the forecast series' own effect aside rather than + # measuring it, and it reaches here as a zero. Left in, the page ranks it + # among measured channels and has called it the most influential of them. + # A row that is not a measurement does not belong in a matrix of + # measurements, so it is taken out along with its label. + explanation, channels = _without_the_unmeasured( + explanation, _channels(carried), carried + ) attributions = np.asarray(explanation.lag_horizon_attributions) # Scores, not attributions. That helper differences a cumulative score # into a per-step weight, and handing it the normalised attribution @@ -103,7 +111,7 @@ def forecast_report( pages._save_channel_axis_artifacts( out_dir, np.asarray(explanation.channel_horizon_attributions), - channel_labels=_channels(carried), + channel_labels=channels, ) drawn = pages._build_pdf_report( Path(output_path), @@ -117,7 +125,7 @@ def forecast_report( top_k=top_k, context_len=_context_len(carried, attributions.shape[1]), forecast_horizon=attributions.shape[1], - channel_labels=_channels(carried), + channel_labels=channels, ) if drawn is None: # pragma: no cover - matplotlib is present by here raise MissingExtraError('report', 'matplotlib') @@ -233,3 +241,30 @@ def _artifacts(named: str | Path | None) -> Iterator[Path]: return with tempfile.TemporaryDirectory(prefix='sdm-forecast-') as temporary: yield Path(temporary) + + +def _without_the_unmeasured( + explanation: Any, channels: list[str] | None, carried: dict[str, Any] +) -> tuple[Any, list[str] | None]: + r"""``explanation`` with any channel it did not measure removed.""" + from dataclasses import replace + + excluded = (carried.get('metadata') or {}).get('feature_axis_excludes') + attributions = explanation.channel_horizon_attributions + if excluded is None or attributions is None or not channels: + return explanation, channels + if excluded not in channels: + return explanation, channels + keep = [name != excluded for name in channels] + return ( + replace( + explanation, + channel_horizon_attributions=np.asarray(attributions)[keep], + per_channel_flow=( + None + if explanation.per_channel_flow is None + else np.asarray(explanation.per_channel_flow)[keep] + ), + ), + [name for name in channels if name != excluded], + ) diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 42beee9cb..df9bef808 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -244,6 +244,60 @@ def test_the_files_the_pages_name_are_written(explained, tmp_path): assert 'semantic_flow.csv' in written +def test_the_series_own_channel_is_not_ranked_among_the_measured( + forecast, tmp_path +): + """Its effect is set aside rather than measured, so it arrives as a zero. + Left among real numbers the page ranked it, and with small effects + elsewhere it called the excluded channel the most influential of all.""" + from sdm_client.reporting.forecast import ( + _channels, + _explanation, + _without_the_unmeasured, + ) + + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast( + history(600), + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + carried = result.explanation + assert carried['metadata']['feature_axis_excludes'] == 'flow' + _, channels = _without_the_unmeasured( + _explanation(carried), _channels(carried), carried + ) + assert channels == ['temp'] + + +def test_a_forecaster_that_cannot_use_a_covariate_does_not_attribute_one( + sdm, +): + """Without channel mixing a column measured alongside the series reaches + the forecast not at all, while the embedding still pools it, so an + attribution moves for something that changes nothing.""" + import torch + + torch.manual_seed(0) + flat = sdm.models.KumoForecast( + cross_channel=False, pretrained=False, device='cpu' + ) + with SDMClient.in_process(flat) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast(history(600), target='flow', horizon=2), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'mix channels' in str(caught.value) + + def test_the_attribution_heatmap_is_drawn(explained, tmp_path): """It is a page drawn from an image on disk, and hardcoding no image dropped it from every report although the matrix was right there.""" From b55c8ad01aeb3cb189a5404c3c586d2bdb444775 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 09:22:21 -0800 Subject: [PATCH 06/13] Measure the channel effects, and draw the weights the caption describes The feature axis took the autograd path, and autograd is the wrong answer for this forecaster: it normalises each window by statistics it takes without gradients, so a gradient through it measures sensitivity with the normalisation held still. It read some hundreds of times larger than the difference the same perturbation makes. Upstream patches its own normaliser to carry those gradients, by a method name this one does not have, so the patch found nothing and passed in silence. The forward pass is no longer differentiable, which is what selects the difference instead. The heatmap's rows are single past steps and it was handed the cumulative scores those are differenced out of, so a flat run of history read as the most influential part of the window while the table beside it ranked the newest step first. It is drawn from the per-step weights the same helper already returns. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/explain/_model.py | 18 +++++++- .../src/sdm_client/reporting/forecast.py | 10 ++++- .../test_a_forecast_says_what_it_rested_on.py | 44 +++++++++++++++++++ 3 files changed, 68 insertions(+), 4 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index f0860ffff..e9190258c 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -71,8 +71,22 @@ def prediction_size(self) -> int: def __call__( self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None ) -> _Forecast: - r"""The forecast for ``x_enc`` of shape ``[B, C, R]``.""" - return _Forecast(forecast=self._inner(_observed(x_enc, input_mask))) + r"""The forecast for ``x_enc`` of shape ``[B, C, R]``. + + Deliberately not differentiable. The attribution reaches for autograd + where the forecast carries gradients and falls back to finite + differences where it does not, and autograd is the wrong answer for + this forecaster: it normalises each window by statistics it takes + without gradients, so a gradient through it measures sensitivity with + that normalisation held still. It came out some hundreds of times + larger than the difference the same perturbation actually makes. + + The upstream package patches its own normaliser to carry those + gradients, by a method name this one does not have, so the patch + finds nothing here and passes in silence. + """ + with torch.no_grad(): + return _Forecast(forecast=self._inner(_observed(x_enc, input_mask))) def embed( self, *, x_enc: torch.Tensor, input_mask: torch.Tensor | None = None diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 3e2bff933..e092684c0 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -86,13 +86,19 @@ def forecast_report( # Scores, not attributions. That helper differences a cumulative score # into a per-step weight, and handing it the normalised attribution # ranked the lags in very nearly the opposite order. - _, topk_rows = pages._topk_lag_steps_per_horizon( + # That helper returns the per-step weights it ranks from, and those are + # what the heatmap's own caption describes. Drawn from the cumulative + # scores instead, it read a run of flat history as the most influential + # part of the window while the table beside it ranked the newest step + # first. + marginal, topk_rows = pages._topk_lag_steps_per_horizon( np.asarray(explanation.lag_horizon_scores), top_k=top_k ) + per_step = attributions if marginal is None else np.asarray(marginal) with _artifacts(artifacts_dir) as out_dir: heatmap = pages._save_lag_horizon_artifacts( out_dir, - attributions, + per_step, np.asarray(explanation.lag_horizon_scores), ) # The pages name these files, so a report that draws the pages and diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index df9bef808..031aa2ca7 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -298,6 +298,50 @@ def test_a_forecaster_that_cannot_use_a_covariate_does_not_attribute_one( assert 'mix channels' in str(caught.value) +def test_the_heatmap_shows_what_its_caption_says(explained, tmp_path): + """Its rows are single past steps, and it was handed the cumulative + scores those are differenced out of, so a flat run read as the most + influential part of the window while the table ranked the newest first. + """ + from sdm_client.explain._kumo_ts import pages + + seen = [] + original = pages._save_lag_horizon_artifacts + + def watched(out_dir, attributions, scores=None, **kwargs): + seen.append(np.asarray(attributions)) + return original(out_dir, attributions, scores, **kwargs) + + pages._save_lag_horizon_artifacts = watched + try: + forecast_report(explained, tmp_path / 'f.pdf') + finally: + pages._save_lag_horizon_artifacts = original + + block = explained.explanation['explanation'] + marginal, _ = pages._topk_lag_steps_per_horizon( + np.asarray(block['lag_horizon_scores']), top_k=5 + ) + assert len(seen) == 1 + assert np.allclose(seen[0], np.asarray(marginal)) + + +def test_the_channel_effects_are_measured_not_differentiated(forecast): + """This forecaster normalises each window by statistics it takes without + gradients, so a gradient through it holds that normalisation still and + reports a sensitivity hundreds of times what a perturbation produces. + The forward pass is not differentiable, which is what selects the + difference the attribution would otherwise skip.""" + import torch + + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + window = torch.zeros(1, 2, shim.context_size, requires_grad=True) + + assert not shim(x_enc=window).forecast.requires_grad + + def test_the_attribution_heatmap_is_drawn(explained, tmp_path): """It is a page drawn from an image on disk, and hardcoding no image dropped it from every report although the matrix was right there.""" From 51062a6ee62ff784003ab67e59a4252100d00180 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 13:19:13 -0800 Subject: [PATCH 07/13] Reach every name the ported attribution reads Moving a module into a package rewrites where its imports point, and a name resolved by the layout it came from is resolved by nothing here. Two were left behind: the integrated-gradients entry point, which upstream imports from a module beside it, and a threading helper in a branch that was already unreachable. The first raises NameError the moment that page is computed; the second is dead, and deleted rather than kept with an import it cannot have. Both are the same mistake, so the check is for the mistake: every name the ported modules read is walked and resolved up front, and an import of a bare sibling module is refused outright, because that is the shape the move leaves behind. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../explain/_kumo_ts/interpretability.py | 24 ++--- .../src/sdm_client/explain/_kumo_ts/pages.py | 4 +- ...the_ported_pages_resolve_what_they_name.py | 97 +++++++++++++++++++ 3 files changed, 106 insertions(+), 19 deletions(-) create mode 100644 packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py index 2c7eb1dd8..96ea8055c 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py @@ -1478,25 +1478,13 @@ def _solve_one(args: tuple[int, int]) -> tuple[int, int, Array, float]: work_items = [(c, h) for c in range(C) for h in range(H)] - # Default: 1 thread (matches historical behaviour). Callers that want - # the parallel path opt in via ``n_jobs`` (typically the OS CPU count - # divided by the number of GPU workers, so threads do not oversubscribe - # cores in a multi-GPU run). # Kumo-TS threads this across cores with a helper this port leaves - # behind, because it exists to feed several GPUs. The branch below does - # the same work in order. - if False: # pragma: no cover - the threaded path is not ported - - for c_idx, h_idx, b, a0 in parallel_apply_threads( - _solve_one, work_items, n_jobs=int(n_jobs) - ): - coef[c_idx, h_idx] = b - intercept[c_idx, h_idx] = a0 - else: - for item in work_items: - c_idx, h_idx, b, a0 = _solve_one(item) - coef[c_idx, h_idx] = b - intercept[c_idx, h_idx] = a0 + # behind, because it exists to feed several GPUs. `n_jobs` is read and + # kept for the signature it came with; the work is done in order. + for item in work_items: + c_idx, h_idx, b, a0 = _solve_one(item) + coef[c_idx, h_idx] = b + intercept[c_idx, h_idx] = a0 return coef, intercept, feature_layout diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py index e8c4046a4..35d954147 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py @@ -817,7 +817,9 @@ def _compute_integrated_gradients_report( grad_through_norm: bool, ) -> dict[str, Any]: """Run embedding integrated gradients for the current SDK context window.""" - from integrated_gradients import integrated_gradients_embedding + from sdm_client.explain._kumo_ts.integrated_gradients import ( + integrated_gradients_embedding, + ) x_tensor = torch.as_tensor( np.asarray(x_context_ct, dtype=np.float32), device=device diff --git a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py new file mode 100644 index 000000000..2de2a07bd --- /dev/null +++ b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py @@ -0,0 +1,97 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. +# All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Every name the ported attribution reads is a name it can reach. + +Moving a module into a package rewrites where its imports point, and a name +that was resolved by the layout it came from is resolved by nothing here. The +failure is a `NameError` at the moment the line runs, which for a page drawn +once in a long explanation is a long way from the move that caused it. These +walk every function of the ported modules and check up front. +""" + +from __future__ import annotations + +import ast +import builtins +import importlib +import pkgutil +from pathlib import Path + +import pytest + +pytest.importorskip('torch', reason='the ported attribution runs on torch') + +PORTED = 'sdm_client.explain._kumo_ts' +NAMES = sorted( + found.name + for found in pkgutil.iter_modules(importlib.import_module(PORTED).__path__) +) +MODULES = [f'{PORTED}.{name}' for name in NAMES] + + +def named(tree: ast.AST) -> set[str]: + """Every global name the module's code reads, bound names aside.""" + bound: set[str] = set() + read: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, ast.Name): + (bound if isinstance(node.ctx, ast.Store) else read).add(node.id) + elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): + bound.add(node.name) + arguments = node.args + for argument in ( + arguments.args + + arguments.posonlyargs + + arguments.kwonlyargs + + [a for a in (arguments.vararg, arguments.kwarg) if a] + ): + bound.add(argument.arg) + elif isinstance(node, ast.ClassDef): + bound.add(node.name) + elif isinstance(node, (ast.Import, ast.ImportFrom)): + for alias in node.names: + bound.add(alias.asname or alias.name.split('.')[0]) + elif isinstance(node, ast.ExceptHandler) and node.name: + bound.add(node.name) + elif isinstance(node, ast.Global): + bound.update(node.names) + elif isinstance(node, (ast.comprehension,)): + for target in ast.walk(node.target): + if isinstance(target, ast.Name): + bound.add(target.id) + return read - bound + + +@pytest.mark.parametrize('module_name', MODULES) +def test_the_ported_module_resolves_every_name_it_reads(module_name): + module = importlib.import_module(module_name) + source = ast.parse(Path(module.__file__).read_text(encoding='utf-8')) + unresolved = { + name + for name in named(source) + if not hasattr(module, name) and not hasattr(builtins, name) + } + + assert not unresolved + + +@pytest.mark.parametrize('module_name', MODULES) +def test_the_ported_module_imports_nothing_from_where_it_came_from( + module_name, +): + """An import of a bare top-level module is the shape the move leaves + behind: upstream ran these as scripts beside one another.""" + module = importlib.import_module(module_name) + source = ast.parse(Path(module.__file__).read_text(encoding='utf-8')) + sibling = { + node.module + for node in ast.walk(source) + if isinstance(node, ast.ImportFrom) + and node.level == 0 + and node.module is not None + and node.module.split('.')[0] in NAMES + } + + assert not sibling From 63aa77643b464871b45a059463b08bd3977e5eba Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 13:50:06 -0800 Subject: [PATCH 08/13] Compute the three measures whose pages were never drawn Three of the explanation's pages were written and never reached: the smoothness of the model's latent state over the history, how steadily the embedding reads each channel, and what the model read reading by reading. Nothing computed them, so each travelled as a null and each page was skipped, which is indistinguishable from a model that had nothing to say. The first costs nothing: the attribution already walks the trajectory, and its history prefix is exactly what a second walk would produce, which is asserted against one. The second is asked for alongside the feature axis, whose question it answers, and is bounded, because its probes are a window per channel per trial and a copy of each and so grow with the square of the channels; past the bound the page is left out and the feature axis it was asked beside is not. The third needed two corrections before it said anything. It explains the movement of the embedding's length, and this forecaster's embedding is a retrieval key scaled to unit length, so that length is one whatever it was given: every reading came back a billionth of nothing. And the gradient it reads does not reach the input, because each window is divided by statistics taken over the window itself and those are taken without gradients, so the attribution described a pass that did not happen. On the published weights it accounted for none of the movement it explains and overshot it by half again; through the statistics it accounts for all but a twenty-fifth of a percent. That correction is held for the length of one attribution and measured against an invariant that does not depend on the weights: a normalised window has the same sum of squares whatever it was made from, so moving it cannot change that sum, and a gradient that says otherwise is not the gradient. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- CHANGELOG.md | 9 + .../src/sdm_client/explain/_explain.py | 158 +++++++++- .../src/sdm_client/explain/_model.py | 61 ++++ .../src/sdm_client/in_process/forecast.py | 11 +- .../src/sdm_client/models.py | 8 +- .../src/sdm_client/reporting/forecast.py | 88 ++++++ .../test_a_forecast_says_what_it_rested_on.py | 290 ++++++++++++++++++ 7 files changed, 621 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d14fb470..73ddaeae2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -67,6 +67,15 @@ these packages. All five distributions share one version and one entry. `sdm_client.percentile_thresholds()` draws one such line from the scores alone, by percentile, widened by how scattered the scores are. Install the drawing with the `report` extra. +- `sdm_client.reporting.forecast_report()` draws why a `kumo-forecast` + answer is the forecast it is, from the explanation the answer carries: how + far back in the window each forecast step rests, how the model's latent + state moved over the history and how smoothly, and, asked for separately + because each costs several times the forecast, how much each channel + measured alongside the series contributed, how steadily the model reads + each of them, and what it read reading by reading. The last is asked for + with the `integrated_gradients` inference option and the rest with + `feature_axis`. ### Changed diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index f8d1a8e68..a20fdcfcf 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -24,6 +24,34 @@ #: defaults; both cost time roughly in proportion. _LAGS = 128 +#: How many times each channel is nudged when the stability of the embedding +#: is measured. Upstream's default, named here because the memory the probes +#: take is worked out from it before they are built. +_STABILITY_TRIALS = 30 + +#: The most the stability probes may take. They are one window per channel +#: per trial and a copy of each, so the memory grows with the square of the +#: number of channels: forty channels of a 512-step window is already most of +#: a gigabyte once both stacks are counted. +_STABILITY_BYTES = 256 * 1024 * 1024 + +#: How finely the path from a reference window to the real one is walked +#: when the embedding is attributed step by step, and how many of those +#: points are embedded at once. Upstream's step count; the batch bounds the +#: activations rather than the answer, which does not depend on it. +_GRADIENT_STEPS = 64 +_GRADIENT_BATCH = 8 + +#: What of the embedding the attribution explains the movement of. Upstream +#: explains the length of it, which cannot be the answer here: this +#: forecaster's embedding is a retrieval key and is scaled to unit length +#: before it is returned, so its length is one whatever it was given, and +#: attributing a constant attributed nothing. Measured on the published +#: weights: the length moved by 2e-07 between a real window and a reference +#: one and every reading came back a billionth, where the sum moves and is +#: explained. +_GRADIENT_OBJECTIVE = 'sum' + def explanation_of( model: Any, @@ -34,6 +62,7 @@ def explanation_of( horizon: int, forecast: np.ndarray, feature_axis: bool = False, + integrated_gradients: bool = False, ) -> dict[str, Any]: r"""Attribute ``forecast`` to the history it was made from. @@ -47,6 +76,10 @@ def explanation_of( forecast: What came back, one value per step. feature_axis: Also attribute across channels rather than only across lags. It costs several times the rest put together. + integrated_gradients: Also attribute the model's own reading of the + window, reading by reading, by walking the path from a reference + window to this one. It is the only attribution here that reads + the model's gradients rather than watching its output move. Raises: StructuredDataError: If the history is shorter than the model reads. @@ -104,6 +137,7 @@ def explanation_of( f'pass, or ask for the explanation without it', code='UNSUPPORTED_SHAPE', ) + device = next(model.parameters()).device window = _standardised(model, window_only) explanation = explain_forecast( forecaster, @@ -111,14 +145,88 @@ def explanation_of( input_mask_l=np.ones(forecaster.context_size, dtype='float32'), model_horizon=forecaster.prediction_size, forecast_horizon=horizon, - device=next(model.parameters()).device, + device=device, n_lags=min(_LAGS, forecaster.context_size), surrogate=False, channel_axis=feature_axis, channel_target=channels.index(target) if feature_axis else None, channel_output_aware=feature_axis, ) - return _as_dict(model, explanation, channels, target, horizon, forecast) + return _as_dict( + model, + explanation, + channels, + target, + horizon, + forecast, + smoothness=_smoothness_of(explanation, forecaster.context_size), + stability=( + _stability_of(forecaster, window, device) if feature_axis else None + ), + gradients=( + _gradients_of(forecaster, window, channels, device) + if integrated_gradients + else None + ), + ) + + +def _smoothness_of(explanation: Any, context_size: int) -> Any: + r"""How smoothly the model's latent state moved over the history. + + Read off the trajectory the attribution already walked rather than walked + again. That trajectory runs the history and then the forecast, one state + per step, and its first ``context_size`` states are exactly the states a + second walk over the history alone would produce, because each one is the + window ending at its own step and the forecast is not in any of them. + """ + from sdm_client.explain._kumo_ts.interpretability import ( + summarize_trajectory_stability, + ) + + trajectory = np.asarray(explanation.latent_trajectory) + history = trajectory[:context_size] + if history.shape[0] < 2: + return None + return summarize_trajectory_stability(history) + + +def _stability_of(forecaster: Any, window: np.ndarray, device: Any) -> Any: + r"""How much the embedding moves when one channel is nudged. + + Asked for alongside the feature axis, because it answers the question the + feature axis raises: an influence attributed to a channel the embedding + treats erratically is an influence measured through a derivative that is + not there. + """ + import warnings + + from sdm_client.core.warnings import SDMWarning + from sdm_client.explain._kumo_ts.channel_stability import ( + compute_per_channel_embedding_stability, + ) + + channels, steps = window.shape + probes = 2 * (1 + _STABILITY_TRIALS * channels) * channels * steps * 4 + if probes > _STABILITY_BYTES: + warnings.warn( + f'the stability of the embedding is measured by nudging each of ' + f'these {channels} channels {_STABILITY_TRIALS} times, which ' + f'would take {probes // (1024 * 1024)} MiB of probes at once. ' + f'That page is left out of this explanation; the rest of the ' + f'feature axis is not', + SDMWarning, + stacklevel=2, + ) + return None + return compute_per_channel_embedding_stability( + forecaster, + np.ascontiguousarray(window, dtype='float32'), + seq_len=int(steps), + input_mask_t=np.ones(steps, dtype='float32'), + device=device, + n_trials=_STABILITY_TRIALS, + ) def _standardised(model: Any, window: np.ndarray) -> np.ndarray: @@ -150,6 +258,45 @@ def _in_original_scale(model: Any, values: np.ndarray) -> np.ndarray: return restored.numerical.detach().cpu().numpy().T +def _gradients_of( + forecaster: Any, window: np.ndarray, channels: list[str], device: Any +) -> Any: + r"""What the model read, reading by reading, by integrated gradients. + + Held inside the forecaster's differentiable normalisation, because a + gradient taken outside it describes a forward pass with each window's own + statistics frozen, which is a different pass from the one that answered. + What that costs is measurable and was measured, on the published + weights because an untrained forecaster's embedding barely moves at all + and the measure divides by how far it moved: an attribution has to add + up to the movement it explains, and taken outside this it accounted for + none of that movement and overshot it by half again, where taken inside + it accounts for all but a twenty-fifth of a percent. The ported code offers + a patch of its own for the same purpose and finds nothing to patch here, + since it looks for a method this forecaster spells another way; the flag + it records is true either way, and true. + """ + from sdm_client.explain._kumo_ts.pages import ( + _compute_integrated_gradients_report, + ) + + with forecaster.differentiable_normalisation(): + return _compute_integrated_gradients_report( + model=forecaster, + x_context_ct=np.ascontiguousarray(window, dtype='float32'), + input_mask_l=np.ones(window.shape[-1], dtype='float32'), + device=device, + channel_labels=list(channels), + baseline='noise', + n_steps=_GRADIENT_STEPS, + n_baselines=1, + internal_batch_size=_GRADIENT_BATCH, + reduce=_GRADIENT_OBJECTIVE, + seed=0, + grad_through_norm=True, + ) + + def _as_dict( model: Any, explanation: Any, @@ -157,6 +304,10 @@ def _as_dict( target: str, horizon: int, forecast: np.ndarray, + *, + smoothness: Any = None, + stability: Any = None, + gradients: Any = None, ) -> dict[str, Any]: r"""The explanation as the contract carries one: plain JSON data. @@ -186,6 +337,9 @@ def _as_dict( target_column=target, timestamp_column='forecast_step', channel_labels=list(channels), + trajectory_report=smoothness, + feature_axis_embedding_stability_report=stability, + integrated_gradients_report=gradients, ) # Upstream keeps the labels only where feature-axis attribution ran, and # they name the channels of every explanation. The client knows them diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index e9190258c..40a94c8ff 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -23,6 +23,8 @@ from __future__ import annotations +from collections.abc import Iterator +from contextlib import contextmanager from dataclasses import dataclass from typing import Any @@ -63,6 +65,40 @@ def mixes_channels(self) -> bool: """ return self._inner.cross_channel is not None + def modules(self) -> Iterator[torch.nn.Module]: + r"""The forecaster's own modules, for code that walks them.""" + return self._inner.modules() + + @contextmanager + def differentiable_normalisation(self) -> Iterator[None]: + r"""The forecaster with its normalisation carrying gradients. + + Each window is divided by statistics taken over the window itself, + and those are taken without gradients. A gradient through the model + as it stands therefore measures what a step does with the mean and + the spread of its own window held still, which is not what the step + does: the attribution came out some hundreds of times larger than the + change the same perturbation actually makes. + + So the statistics are taken again, differentiably, for as long as + this is held. Everything else about the forward pass is unchanged, + and the numbers it produces are the same ones. + """ + from sdm.nn import RevIN + + patched = [ + module + for module in self._inner.modules() + if isinstance(module, RevIN) + ] + for module in patched: + module.stats = _statistics + try: + yield + finally: + for module in patched: + del module.stats + @property def prediction_size(self) -> int: r"""How many steps it forecasts in one pass.""" @@ -129,3 +165,28 @@ def _observed(x: torch.Tensor, mask: torch.Tensor | None) -> torch.Tensor: while keep.ndim < x.ndim: keep = keep.unsqueeze(0) return x.masked_fill(~keep.expand_as(x), float('nan')) + + +def _statistics( + x: torch.Tensor, + mask: torch.Tensor | None = None, + correction: int = 1, +) -> tuple[torch.Tensor, torch.Tensor]: + r"""``RevIN.stats``, computed so that gradients reach the input. + + The same arithmetic as the method it stands in for, which is what makes + the forward pass it takes part in produce the same numbers. + """ + if mask is not None: + x = x.masked_fill(mask, torch.nan) + x = x.double() + mean = x.nanmean(dim=-1, keepdim=True) + variance = (x - mean).square().nanmean(dim=-1, keepdim=True) + if correction != 0: + count = (~x.isnan()).sum(dim=-1, keepdim=True) + variance = variance * ( + count.double() / (count - correction).clamp(min=1) + ) + deviation = variance.sqrt() + absent = mean.isnan() + return mean.masked_fill(absent, 0.0), deviation.masked_fill(absent, 1.0) diff --git a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py index 3a92e4d79..bff8546e8 100644 --- a/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/in_process/forecast.py @@ -40,7 +40,13 @@ _NEIGHBOURS = 64 _TEMPERATURE = 0.05 -_KNOBS = ('alpha', 'k', 'temperature', 'feature_axis') +_KNOBS = ( + 'alpha', + 'k', + 'temperature', + 'feature_axis', + 'integrated_gradients', +) class Forecast: @@ -282,6 +288,9 @@ def _explained( horizon=horizon, forecast=forecast.detach().cpu().numpy(), feature_axis=bool(options.get('feature_axis', False)), + integrated_gradients=bool( + options.get('integrated_gradients', False) + ), ) @staticmethod diff --git a/packages/structured-data-models-client/src/sdm_client/models.py b/packages/structured-data-models-client/src/sdm_client/models.py index 36f00b325..9ab71b5cf 100644 --- a/packages/structured-data-models-client/src/sdm_client/models.py +++ b/packages/structured-data-models-client/src/sdm_client/models.py @@ -200,7 +200,13 @@ outputs=frozenset({'prediction', 'explanation'}), sessions=False, inference_options=frozenset( - {'alpha', 'k', 'temperature', 'feature_axis'} + { + 'alpha', + 'k', + 'temperature', + 'feature_axis', + 'integrated_gradients', + } ), ), ) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index e092684c0..3464424de 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -95,6 +95,9 @@ def forecast_report( np.asarray(explanation.lag_horizon_scores), top_k=top_k ) per_step = attributions if marginal is None else np.asarray(marginal) + smoothness = _smoothness(carried) + stability = _stability(carried) + gradients = (carried.get('explanation') or {}).get('integrated_gradients') with _artifacts(artifacts_dir) as out_dir: heatmap = pages._save_lag_horizon_artifacts( out_dir, @@ -119,6 +122,12 @@ def forecast_report( np.asarray(explanation.channel_horizon_attributions), channel_labels=channels, ) + if gradients is not None: + pages._save_integrated_gradients_artifacts(out_dir, gradients) + if stability is not None: + pages._save_feature_axis_embedding_stability_csv( + out_dir, stability, channels + ) drawn = pages._build_pdf_report( Path(output_path), dataset_name=dataset_name, @@ -132,6 +141,9 @@ def forecast_report( context_len=_context_len(carried, attributions.shape[1]), forecast_horizon=attributions.shape[1], channel_labels=channels, + trajectory_report=smoothness, + feature_axis_embedding_stability_report=stability, + integrated_gradients_report=gradients, ) if drawn is None: # pragma: no cover - matplotlib is present by here raise MissingExtraError('report', 'matplotlib') @@ -196,6 +208,82 @@ def scalar(name: str) -> float | None: ) +def _smoothness(carried: dict[str, Any]) -> Any: + r"""How smoothly the latent state moved, read back from the data.""" + from sdm_client.explain._kumo_ts.interpretability import ( + TrajectoryStabilityReport, + ) + + block = (carried.get('explanation') or {}).get('trajectory_stability') + if not block: + return None + rates = ( + 'zero_crossing_rate_mean', + 'zero_crossing_rate_p95', + 'direction_flip_rate_mean', + 'direction_flip_rate_p95', + 'relative_jitter_mean', + 'relative_jitter_p95', + 'occupancy_positive_mean', + 'occupancy_negative_mean', + ) + if any(block.get(name) is None for name in rates): + return None + read = {name: float(block[name]) for name in rates} + return TrajectoryStabilityReport( + zero_crossing_rate_mean=read['zero_crossing_rate_mean'], + zero_crossing_rate_p95=read['zero_crossing_rate_p95'], + direction_flip_rate_mean=read['direction_flip_rate_mean'], + direction_flip_rate_p95=read['direction_flip_rate_p95'], + relative_jitter_mean=read['relative_jitter_mean'], + relative_jitter_p95=read['relative_jitter_p95'], + occupancy_positive_mean=read['occupancy_positive_mean'], + occupancy_negative_mean=read['occupancy_negative_mean'], + n_time_steps=int(block.get('n_time_steps') or 0), + n_dimensions=int(block.get('n_dimensions') or 0), + ) + + +def _stability(carried: dict[str, Any]) -> Any: + r"""How much the embedding moved when a channel was nudged. + + The labels it carries are its own: the page reads them off the report + where there are as many as there are channels, and that count includes + the series being forecast, which the channel attribution beside it sets + aside. Rebuilt with the channel labels of the explanation instead, the + two would be the same length and name different channels. + """ + from sdm_client.explain._kumo_ts.channel_stability import ( + PerChannelEmbeddingStabilityReport, + ) + + feature_axis = (carried.get('explanation') or {}).get('feature_axis') or {} + block = feature_axis.get('embedding_stability') + if not block: + return None + labels = block.get('channel_labels') or [] + ratios = { + name: np.asarray(block.get(name), dtype=float) + for name in ( + 'lip_ratio_mean', + 'lip_ratio_max', + 'lip_ratio_p50', + 'lip_ratio_p95', + ) + } + return PerChannelEmbeddingStabilityReport( + **ratios, + n_trials_per_channel=np.asarray( + block.get('n_trials_per_channel'), dtype='int64' + ), + n_unique_windows=int(block.get('n_unique_windows') or 0), + step_delta_norm_mean=float( + block.get('step_delta_norm_mean') or float('nan') + ), + n_channels=len(labels), + ) + + def _forecast_frame(carried: dict[str, Any]) -> tuple[Any, str, str]: import pandas as pd diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 031aa2ca7..66a9b0454 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -39,6 +39,34 @@ def explained(forecast): ) +class Carrying: + """An answer carrying an explanation, for drawing one that was edited. + + A result's explanation is what it came back with and cannot be assigned + over, and a page is drawn or not drawn by whether its block is there. + """ + + def __init__(self, explanation): + self.explanation = explanation + + +def without(result, *names, under=None): + """What `result` carries, less the block(s) `names` asks for.""" + carried = dict(result.explanation) + block = dict(carried['explanation']) + if under is None: + for name in names: + block.pop(name, None) + else: + block[under] = { + key: value + for key, value in block[under].items() + if key not in names + } + carried['explanation'] = block + return Carrying(carried) + + def pages(path) -> int: raw = path.read_bytes() return raw.count(b'/Type /Page') - raw.count(b'/Type /Pages') @@ -448,3 +476,265 @@ def test_only_this_model_is_asked_to_explain_a_forecast(anomaly): outputs=['prediction', 'explanation'], ) assert 'explanation' in str(caught.value) + + +def test_the_smoothness_of_the_latent_state_is_measured(explained): + """Reported as null for every run before it was computed, so its page + was never drawn.""" + block = explained.explanation['explanation']['trajectory_stability'] + + assert block is not None + assert block['n_time_steps'] == 512 + assert 0.0 <= block['zero_crossing_rate_mean'] <= 1.0 + + +def test_the_smoothness_is_the_history_walked_once(explained, forecast): + """It is read off the trajectory the attribution already walked rather + than walked again, so it has to be what a second walk would say.""" + import torch + + from sdm_client.explain._explain import _standardised + from sdm_client.explain._kumo_ts.interpretability import ( + compute_trajectory_stability, + ) + from sdm_client.explain._model import Forecaster + + carried = explained.explanation + window = _standardised( + forecast, history().to_numpy().T[:, -512:].astype('float32') + ) + walked = compute_trajectory_stability( + Forecaster(forecast), + np.ascontiguousarray(window, dtype='float32'), + seq_len=512, + input_mask_t=np.ones(512, dtype='float32'), + device=torch.device('cpu'), + ) + + read = carried['explanation']['trajectory_stability'] + assert read['relative_jitter_mean'] == pytest.approx( + walked.relative_jitter_mean, rel=1e-5 + ) + assert read['zero_crossing_rate_mean'] == pytest.approx( + walked.zero_crossing_rate_mean, rel=1e-5 + ) + + +def test_the_smoothness_page_is_drawn(explained, tmp_path): + before = pages(forecast_report(explained, tmp_path / 'f.pdf')) + stripped = without(explained, 'trajectory_stability') + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +@pytest.fixture(scope='module') +def over_channels(forecast): + with SDMClient.in_process(forecast) as client: + return client.predict( + Request.forecast( + history(), + target='flow', + horizon=4, + inference={'feature_axis': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + +def test_the_embedding_is_measured_for_every_channel(over_channels): + """Asked for alongside the feature axis, because it answers the question + the feature axis raises: an influence attributed through a derivative + that is not there is not an influence.""" + block = over_channels.explanation['explanation']['feature_axis'] + measured = block['embedding_stability'] + + assert measured['channel_labels'] == ['flow', 'temp'] + assert all(count > 0 for count in measured['n_trials_per_channel']) + assert all(np.isfinite(measured['lip_ratio_mean'])) + + +def test_the_embedding_is_not_measured_without_the_feature_axis(explained): + """It costs a window per channel per trial, which is the feature axis's + own order of cost and not the lag attribution's.""" + block = explained.explanation['explanation'].get('feature_axis') or {} + + assert 'embedding_stability' not in block + + +def test_the_embedding_stability_page_is_drawn(over_channels, tmp_path): + before = pages(forecast_report(over_channels, tmp_path / 'f.pdf')) + stripped = without( + over_channels, 'embedding_stability', under='feature_axis' + ) + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +def test_too_many_channels_leave_the_page_out_rather_than_the_rest(forecast): + """The probes are a window per channel per trial and a copy of each, so + their memory grows with the square of the channels. Past the cap the + page is left out and the feature axis it was asked beside is not.""" + import warnings + + from sdm_client.core.warnings import SDMWarning + from sdm_client.explain import _explain + + frame = history() + with SDMClient.in_process(forecast) as client: + request = Request.forecast( + frame, + target='flow', + horizon=4, + inference={'feature_axis': True}, + ) + with warnings.catch_warnings(record=True) as raised: + warnings.simplefilter('always') + kept = _explain._STABILITY_BYTES + _explain._STABILITY_BYTES = 1 + try: + result = client.predict( + request, + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + finally: + _explain._STABILITY_BYTES = kept + + block = result.explanation['explanation']['feature_axis'] + assert 'embedding_stability' not in block + assert block['channel_horizon_attributions'] is not None + assert any( + issubclass(one.category, SDMWarning) + and 'MiB of probes' in str(one.message) + for one in raised + ) + + +@pytest.fixture(scope='module') +def by_gradient(forecast): + with SDMClient.in_process(forecast) as client: + return client.predict( + Request.forecast( + history(), + target='flow', + horizon=4, + inference={'integrated_gradients': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + + +def test_the_gradient_attribution_covers_the_window_it_read(by_gradient): + block = by_gradient.explanation['explanation']['integrated_gradients'] + + assert np.asarray(block['attribution']).shape == (2, 512) + assert block['channel_labels'] == ['flow', 'temp'] + assert sum(block['channel_abs_share']) == pytest.approx(1.0, rel=1e-5) + + +@pytest.mark.parametrize( + ('differentiable', 'reads'), + [(False, False), (True, True)], +) +def test_the_gradient_is_taken_through_the_normalisation( + sdm, differentiable, reads +): + """Each window is divided by statistics taken over the window itself, + and those are taken without gradients. A gradient through the model as it + stands therefore describes a pass with each window's own mean and spread + held still, which is not the pass that answered. + + Measured against an invariant rather than against the model, so it holds + whatever the weights are: a normalised window has the same sum of squares + whatever it was made from, so moving the window cannot change it and the + true derivative is exactly zero. + """ + import torch + from sdm.nn import RevIN + + from sdm_client.explain._model import _statistics + + torch.manual_seed(0) + revin = RevIN(eps=1e-5) + window = torch.randn(1, 3, 16, dtype=torch.float32) + direction = torch.randn_like(window) + direction /= direction.norm() + + moved = window.clone().requires_grad_(True) + statistics = _statistics if differentiable else RevIN.stats + mean, scale = statistics(moved, correction=0) + revin(moved, mean, scale).square().sum().backward() + along = float((moved.grad * direction).sum()) + + assert (abs(along) < 1e-4) is reads + + +def test_the_normalisation_is_left_as_it_was_found(forecast): + """It is patched for the length of one attribution. Left patched, every + forecast after it runs through a normaliser this client replaced.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + with shim.differentiable_normalisation(): + patched = [ + 'stats' in vars(module) + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ] + + assert any(patched) + assert not any( + 'stats' in vars(module) + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ) + + +def test_the_length_of_the_embedding_is_not_what_is_explained(forecast): + """This forecaster's embedding is a retrieval key, scaled to unit length + before it is returned, so its length is one whatever it was given. + Explaining that explains a constant, and every reading came back zero.""" + import torch + + from sdm_client.explain._explain import _standardised + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + window = _standardised( + forecast, history().to_numpy().T[:, -512:].astype('float32') + ) + embedded = shim.embed( + x_enc=torch.as_tensor(window, dtype=torch.float32)[None], + input_mask=torch.ones(1, 512), + ).embeddings + + assert float(embedded.norm()) == pytest.approx(1.0, rel=1e-5) + + +def test_a_forecast_asked_without_gradients_does_not_pay_for_them(explained): + """They walk a path of sixty-four windows and take a gradient at each.""" + assert 'integrated_gradients' not in explained.explanation['explanation'] + + +def test_the_gradient_page_is_drawn(by_gradient, tmp_path): + before = pages(forecast_report(by_gradient, tmp_path / 'f.pdf')) + stripped = without(by_gradient, 'integrated_gradients') + + after = pages(forecast_report(stripped, tmp_path / 'g.pdf')) + + assert before == after + 1 + + +def test_the_files_the_gradient_page_names_are_written(by_gradient, tmp_path): + artifacts = tmp_path / 'artifacts' + forecast_report(by_gradient, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = {path.name for path in artifacts.iterdir()} + + assert 'integrated_gradients_attributions.csv' in written + assert 'integrated_gradients_channel_summary.csv' in written From db270493503693c4b9a6f5923562c2f3cfc6c361 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Tue, 3 Nov 2026 14:10:27 -0800 Subject: [PATCH 09/13] Say it once, where the reader is already looking The reasoning sat in comments beside the code it was about, where a reader reaches it only by reading the body. It belongs in the docstring, which is what a reader opens first and what the documentation carries, so each one is folded into the docstring of the thing it explains. Nothing is dropped. The ported modules keep their own: they are the code as it was written, and this repository does not edit them. That code also named the repository it was written in, in a package name, in headers and in prose. What a reader needs is that it is kept as written, so that an attribution from here is a statement about what the model did rather than about an arithmetic someone rewrote, and that is what it says now. The package is named for what it holds. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../{_kumo_ts => _attribution}/__init__.py | 3 +- .../channel_flow.py | 5 +- .../channel_stability.py | 7 +- .../integrated_gradients.py | 3 - .../interpretability.py | 10 +-- .../{_kumo_ts => _attribution}/pages.py | 14 ++-- .../src/sdm_client/explain/_explain.py | 74 ++++++++++--------- .../src/sdm_client/explain/_model.py | 9 ++- .../src/sdm_client/reporting/forecast.py | 60 ++++++++------- .../test_a_forecast_says_what_it_rested_on.py | 8 +- ...the_ported_pages_resolve_what_they_name.py | 2 +- pyproject.toml | 8 +- 12 files changed, 100 insertions(+), 103 deletions(-) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/__init__.py (77%) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/channel_flow.py (99%) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/channel_stability.py (98%) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/integrated_gradients.py (99%) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/interpretability.py (99%) rename packages/structured-data-models-client/src/sdm_client/explain/{_kumo_ts => _attribution}/pages.py (99%) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py similarity index 77% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py index a6419fbfd..c31256c89 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/__init__.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/__init__.py @@ -2,9 +2,8 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -r"""Kumo-TS's forecast attribution and its report, as that package wrote them. +r"""The forecast attribution and its report, as they were written. -Adapted from NVIDIA/Kumo-TS at af74798bbf7d020d3298f545fb9be383560a18ce. Kept together and kept as written: an attribution is a statement about what a model did, and rewriting the arithmetic that makes it would make it a statement about something else. diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py similarity index 99% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py index 3bb6afb18..6406082ae 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_flow.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_flow.py @@ -2,9 +2,6 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/channel_flow.py -# at af74798bbf7d020d3298f545fb9be383560a18ce. - # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 @@ -33,7 +30,7 @@ if TYPE_CHECKING: from collections.abc import Sequence -from sdm_client.explain._kumo_ts.interpretability import ( +from sdm_client.explain._attribution.interpretability import ( Array, ForecastModel, _embed_batch, diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py similarity index 98% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py index c3394dcec..5f76d48d6 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/channel_stability.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/channel_stability.py @@ -2,9 +2,6 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/channel_stability.py -# at af74798bbf7d020d3298f545fb9be383560a18ce. - # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 @@ -69,8 +66,8 @@ import numpy as np import torch -from sdm_client.explain._kumo_ts.channel_flow import _embed_windows_batched -from sdm_client.explain._kumo_ts.interpretability import ( +from sdm_client.explain._attribution.channel_flow import _embed_windows_batched +from sdm_client.explain._attribution.interpretability import ( Array, ForecastModel, _rolling_window_sources, diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py similarity index 99% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py index dd9b4e0d6..9b2689921 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/integrated_gradients.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/integrated_gradients.py @@ -2,9 +2,6 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/integrated_gradients.py -# at af74798bbf7d020d3298f545fb9be383560a18ce. - # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py similarity index 99% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py index 96ea8055c..2071af33a 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/interpretability.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/interpretability.py @@ -2,9 +2,6 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/interpretability.py -# at af74798bbf7d020d3298f545fb9be383560a18ce. - # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 @@ -47,7 +44,7 @@ import torch if TYPE_CHECKING: - from sdm_client.explain._kumo_ts.channel_flow import ChannelFlowConfig + from sdm_client.explain._attribution.channel_flow import ChannelFlowConfig Array = np.ndarray @@ -1478,9 +1475,6 @@ def _solve_one(args: tuple[int, int]) -> tuple[int, int, Array, float]: work_items = [(c, h) for c in range(C) for h in range(H)] - # Kumo-TS threads this across cores with a helper this port leaves - # behind, because it exists to feed several GPUs. `n_jobs` is read and - # kept for the signature it came with; the work is done in order. for item in work_items: c_idx, h_idx, b, a0 = _solve_one(item) coef[c_idx, h_idx] = b @@ -1638,7 +1632,7 @@ def explain_forecast( chan_resid_mean = None chan_resid_p95 = None if channel_axis: - from sdm_client.explain._kumo_ts.channel_flow import ( # local import avoids circular dependency at module load + from sdm_client.explain._attribution.channel_flow import ( # local import avoids circular dependency at module load ChannelFlowConfig, channel_horizon_marginal, compute_per_channel_flow, diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py similarity index 99% rename from packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py rename to packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py index 35d954147..b7b052890 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/pages.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py @@ -2,11 +2,11 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -# Adapted from NVIDIA/Kumo-TS, Kumo-Forecast/sdk/forecasting.py -# at af74798bbf7d020d3298f545fb9be383560a18ce: the pages of the forecast -# report, the artifacts written beside it, and the explanation as JSON. +r"""Drawing a forecast explanation, as it was written to be drawn. -r"""Drawing a forecast explanation, as Kumo-TS draws it.""" +The pages of the forecast report, the artifacts written beside them, and the +explanation as JSON. +""" from __future__ import annotations @@ -22,10 +22,10 @@ import pandas as pd import torch -from sdm_client.explain._kumo_ts.channel_stability import ( +from sdm_client.explain._attribution.channel_stability import ( PerChannelEmbeddingStabilityReport, ) -from sdm_client.explain._kumo_ts.interpretability import ( +from sdm_client.explain._attribution.interpretability import ( ForecastExplanation, TrajectoryStabilityReport, ) @@ -817,7 +817,7 @@ def _compute_integrated_gradients_report( grad_through_norm: bool, ) -> dict[str, Any]: """Run embedding integrated gradients for the current SDK context window.""" - from sdm_client.explain._kumo_ts.integrated_gradients import ( + from sdm_client.explain._attribution.integrated_gradients import ( integrated_gradients_embedding, ) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index a20fdcfcf..f9b969121 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -82,10 +82,29 @@ def explanation_of( the model's gradients rather than watching its output move. Raises: - StructuredDataError: If the history is shorter than the model reads. + StructuredDataError: If the history is shorter than the model reads, + if the forecaster cannot mix channels while more than one + travelled, or, for the feature axis, if the window it reads has + a gap in it or the horizon runs past one forward pass. + + Without channel mixing and without retrieval, a column measured + alongside the series cannot reach the forecast at all, while the + embedding still pools it, so an attribution would move when it moves and + report an influence the forecast does not have. Feature-axis attribution + replaces a channel with its own average over the window it reads, and a + gap makes that average undefined, which reads as a channel with no + influence: a confident answer about a column nothing was learnt about. + Both are refused rather than reported. + + The window is standardised first, as the model's own path standardises + before it reads anything, so the attribution works in the space the + model works in. Handing it raw readings attributed a model being fed + numbers it never sees. """ - from sdm_client.explain._kumo_ts.interpretability import explain_forecast + from sdm_client.explain._attribution.interpretability import ( + explain_forecast, + ) from sdm_client.explain._model import Forecaster forecaster = Forecaster(model) @@ -96,15 +115,7 @@ def explanation_of( f'history is {history.shape[-1]}', code='UNSUPPORTED_SHAPE', ) - # Standardised first, as the model's own path standardises before it - # reads anything. The attribution then works in the space the model works - # in; handing it raw readings attributed a model being fed numbers it - # never sees. if len(channels) > 1 and not forecaster.mixes_channels: - # Without channel mixing and without retrieval, a covariate cannot - # reach the forecast at all. The embedding still pools every channel, - # so an attribution would move when one of them moves and report an - # influence the forecast does not have. raise StructuredDataError( 'this forecaster does not mix channels, so nothing measured ' 'alongside the series can reach the forecast, and an attribution ' @@ -115,11 +126,6 @@ def explanation_of( ) window_only = history[..., -forecaster.context_size :] if feature_axis and not np.isfinite(window_only).all(): - # Feature-axis attribution perturbs a channel towards its own mean - # over the window, and that mean is NaN if any reading in it is - # missing. The channel then reads as inactive and is given no - # influence at all, which is a confident answer about a column - # nothing was learnt about. Refused rather than reported. raise StructuredDataError( f'feature-axis attribution replaces a channel with its own ' f'average over the window it reads, which a gap in that window ' @@ -180,7 +186,7 @@ def _smoothness_of(explanation: Any, context_size: int) -> Any: second walk over the history alone would produce, because each one is the window ending at its own step and the forecast is not in any of them. """ - from sdm_client.explain._kumo_ts.interpretability import ( + from sdm_client.explain._attribution.interpretability import ( summarize_trajectory_stability, ) @@ -202,7 +208,7 @@ def _stability_of(forecaster: Any, window: np.ndarray, device: Any) -> Any: import warnings from sdm_client.core.warnings import SDMWarning - from sdm_client.explain._kumo_ts.channel_stability import ( + from sdm_client.explain._attribution.channel_stability import ( compute_per_channel_embedding_stability, ) @@ -276,7 +282,7 @@ def _gradients_of( since it looks for a method this forecaster spells another way; the flag it records is true either way, and true. """ - from sdm_client.explain._kumo_ts.pages import ( + from sdm_client.explain._attribution.pages import ( _compute_integrated_gradients_report, ) @@ -311,14 +317,25 @@ def _as_dict( ) -> dict[str, Any]: r"""The explanation as the contract carries one: plain JSON data. - Rendered by the code that drew it upstream, so a report built from this - and one built there say the same things in the same words. + Rendered by the code that drew it, so a report built from this and one + built where that code came from say the same things in the same words. + + The attribution works standardised, so what it calls the baseline + forecast is standardised too, and the report draws it beside readings; + it is put back in their scale before it travels. The channel labels + travel with every explanation rather than only with the feature axis, + which is where that code keeps them: the client knows them either way, + and a report that cannot say which channel is which is harder to read + than one that can. + + The feature axis perturbs each channel and watches the forecast move. + Perturbing the series being forecast moves it by construction, so that + channel's own effect is set aside rather than measured and reaches the + page as a zero beside measured numbers. Saying which channel that was is + what keeps a reader from taking it for the least influential one. """ - from sdm_client.explain._kumo_ts.pages import _explanation_to_dict + from sdm_client.explain._attribution.pages import _explanation_to_dict - # The attribution works standardised, so what it calls the baseline - # forecast is standardised too. The report draws it beside readings, so - # it is put back in their scale before it travels. explanation = replace( explanation, baseline_forecast=_in_original_scale( @@ -341,16 +358,7 @@ def _as_dict( feature_axis_embedding_stability_report=stability, integrated_gradients_report=gradients, ) - # Upstream keeps the labels only where feature-axis attribution ran, and - # they name the channels of every explanation. The client knows them - # either way, and a report that cannot say which channel is which is - # harder to read than one that can. rendered.setdefault('metadata', {})['channel_labels'] = list(channels) - # The feature axis perturbs each channel and watches the forecast move. - # Perturbing the series being forecast moves it by construction, so that - # channel's own effect is set aside rather than measured, and it reaches - # the page as a zero beside measured numbers. Saying so is what keeps a - # reader from taking it for the least influential channel. if rendered.get('explanation', {}).get('feature_axis'): rendered['metadata']['feature_axis_excludes'] = target return rendered diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index 40a94c8ff..8b2ad29c9 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -151,16 +151,17 @@ def _observed(x: torch.Tensor, mask: torch.Tensor | None) -> torch.Tensor: The forecaster has no mask argument and reads ``NaN`` as unobserved: its normalisation takes a window's statistics over what is there, and zeroes what is not once they are taken. + + The mask's last axis is steps and anything before it is the window the + steps belong to; the readings have a channel axis between the two. It is + one mask for every channel of a window, so the channel axis is where the + singleton goes. """ if mask is None: return x keep = torch.as_tensor(mask, device=x.device).bool() if keep.all(): return x - # The mask's last axis is steps and anything before it is the window it - # belongs to; the readings have a channel axis between the two. It is one - # mask for every channel of a window, so the channel axis is where the - # singleton goes. keep = keep.unsqueeze(-2) while keep.ndim < x.ndim: keep = keep.unsqueeze(0) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 3464424de..7e892e5f0 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -2,12 +2,12 @@ # All rights reserved. # SPDX-License-Identifier: Apache-2.0 -r"""A forecast explanation, drawn as Kumo-TS draws it. +r"""A forecast explanation, drawn as it was written to be drawn. -The pages come from that package. What is new is that they are drawn from an -explanation that travelled as data: the client carries one as the contract's -``explanation`` field, plain JSON, because that is what an output field is. -The arrays the pages read are all in it, so the drawing reads them back. +What is new is that the pages are drawn from an explanation that travelled as +data: the client carries one as the contract's ``explanation`` field, plain +JSON, because that is what an output field is. The arrays the pages read are +all in it, so the drawing reads them back. A page whose data is not there is not drawn. Feature-axis attribution is the one that is usually absent, because it costs several times the rest and is @@ -56,6 +56,25 @@ def forecast_report( MissingExtraError: If matplotlib is not installed. StructuredDataError: If the answer carries no explanation. + The feature axis sets the forecast series' own effect aside rather than + measuring it, and it arrives as a zero. Left in, the page ranks it among + measured channels and has called it the most influential of them, so it + is taken out along with its label: a row that is not a measurement does + not belong in a matrix of measurements. + + The lags are ranked from the scores rather than from the attributions. + That helper differences a cumulative score into a per-step weight, and + handing it the normalised attribution ranked the lags in very nearly the + opposite order. It returns those per-step weights, which are what the + heatmap's own caption describes; drawn from the cumulative scores + instead, the heatmap read a run of flat history as the most influential + part of the window while the table beside it ranked the newest step + first. + + Each artifact is written where the data behind it was computed, because + the pages name those files and a report that draws the pages and writes + none of them points a reader at nothing. + >>> result = client.predict( ... request, model=KumoForecast(), ... outputs=['prediction', 'explanation'], @@ -74,23 +93,10 @@ def forecast_report( pages = _pages() frame, target, step = _forecast_frame(carried) explanation = _explanation(carried) - # The feature axis sets the forecast series' own effect aside rather than - # measuring it, and it reaches here as a zero. Left in, the page ranks it - # among measured channels and has called it the most influential of them. - # A row that is not a measurement does not belong in a matrix of - # measurements, so it is taken out along with its label. explanation, channels = _without_the_unmeasured( explanation, _channels(carried), carried ) attributions = np.asarray(explanation.lag_horizon_attributions) - # Scores, not attributions. That helper differences a cumulative score - # into a per-step weight, and handing it the normalised attribution - # ranked the lags in very nearly the opposite order. - # That helper returns the per-step weights it ranks from, and those are - # what the heatmap's own caption describes. Drawn from the cumulative - # scores instead, it read a run of flat history as the most influential - # part of the window while the table beside it ranked the newest step - # first. marginal, topk_rows = pages._topk_lag_steps_per_horizon( np.asarray(explanation.lag_horizon_scores), top_k=top_k ) @@ -104,9 +110,6 @@ def forecast_report( per_step, np.asarray(explanation.lag_horizon_scores), ) - # The pages name these files, so a report that draws the pages and - # writes none of them points a reader at nothing. Each is written - # where the data behind it was computed. horizon = attributions.shape[1] context = _context_len(carried, horizon) if explanation.flow_magnitudes is not None and context: @@ -152,7 +155,7 @@ def forecast_report( def _pages() -> Any: try: - from sdm_client.explain._kumo_ts import pages + from sdm_client.explain._attribution import pages except ImportError as error: # pragma: no cover - the extra is absent raise MissingExtraError('report', 'matplotlib') from error return pages @@ -164,15 +167,16 @@ def _explanation(carried: dict[str, Any]) -> Any: Only the arrays the pages read are restored. A field the explanation did not carry stays absent, and the page that would have drawn it is not drawn, which is what "this was not computed" looks like on paper. + + The channel attribution is serialised under ``feature_axis`` rather than + beside the lag arrays. Read flat it was found nowhere, and the page that + draws it was skipped although it had been computed, which costs minutes. """ - from sdm_client.explain._kumo_ts.interpretability import ( + from sdm_client.explain._attribution.interpretability import ( ForecastExplanation, ) block = carried.get('explanation') or {} - # Serialised under `feature_axis`, not beside the lag arrays. Reading it - # flat found nothing and the page that draws it was skipped although it - # had been computed, which costs minutes. feature_axis = block.get('feature_axis') or {} diagnostics = block.get('diagnostics') or {} @@ -210,7 +214,7 @@ def scalar(name: str) -> float | None: def _smoothness(carried: dict[str, Any]) -> Any: r"""How smoothly the latent state moved, read back from the data.""" - from sdm_client.explain._kumo_ts.interpretability import ( + from sdm_client.explain._attribution.interpretability import ( TrajectoryStabilityReport, ) @@ -253,7 +257,7 @@ def _stability(carried: dict[str, Any]) -> Any: aside. Rebuilt with the channel labels of the explanation instead, the two would be the same length and name different channels. """ - from sdm_client.explain._kumo_ts.channel_stability import ( + from sdm_client.explain._attribution.channel_stability import ( PerChannelEmbeddingStabilityReport, ) diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 66a9b0454..9506433a3 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -207,7 +207,7 @@ def test_the_top_lags_are_ranked_from_the_scores(explained, tmp_path): said nothing about the call that draws the page, and passed while the report still handed over the wrong array. """ - from sdm_client.explain._kumo_ts import pages + from sdm_client.explain._attribution import pages from sdm_client.reporting import forecast as module seen = [] @@ -331,7 +331,7 @@ def test_the_heatmap_shows_what_its_caption_says(explained, tmp_path): scores those are differenced out of, so a flat run read as the most influential part of the window while the table ranked the newest first. """ - from sdm_client.explain._kumo_ts import pages + from sdm_client.explain._attribution import pages seen = [] original = pages._save_lag_horizon_artifacts @@ -493,10 +493,10 @@ def test_the_smoothness_is_the_history_walked_once(explained, forecast): than walked again, so it has to be what a second walk would say.""" import torch - from sdm_client.explain._explain import _standardised - from sdm_client.explain._kumo_ts.interpretability import ( + from sdm_client.explain._attribution.interpretability import ( compute_trajectory_stability, ) + from sdm_client.explain._explain import _standardised from sdm_client.explain._model import Forecaster carried = explained.explanation diff --git a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py index 2de2a07bd..b47c64410 100644 --- a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py +++ b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py @@ -23,7 +23,7 @@ pytest.importorskip('torch', reason='the ported attribution runs on torch') -PORTED = 'sdm_client.explain._kumo_ts' +PORTED = 'sdm_client.explain._attribution' NAMES = sorted( found.name for found in pkgutil.iter_modules(importlib.import_module(PORTED).__path__) diff --git a/pyproject.toml b/pyproject.toml index 8f4fe7df7..39eb6f008 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,12 +48,12 @@ target-version = "py310" # illustrated. extend-exclude = [ "packages/structured-data-models-pql/src/predictive_query/grammar", - # Kumo-TS's forecast attribution, vendored as that package wrote it, down + # The forecast attribution, kept as it was written, down # to putting `from __future__` above its own module docstrings. Excluded # from mypy for the same reason; the two lists move together. Checked for # the lints that are not style first: an undefined name here would be a # line this move dropped, and two were. - "packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts", + "packages/structured-data-models-client/src/sdm_client/explain/_attribution", "packages/structured-data-models-api/src/sdm_api/generated/tfm_api.py", "*.md", ] @@ -92,10 +92,10 @@ exclude = [ # ANTLR's output, regenerated from the grammar rather than edited. Excluded # from ruff for the same reason; the two lists move together. "packages/structured-data-models-pql/src/predictive_query/grammar/", - # Kumo-TS's forecast attribution, vendored as that package wrote it. An + # The forecast attribution, kept as it was written. An # attribution is a statement about what a model did, so the arithmetic # that makes it is not this repository's to retype. - "packages/structured-data-models-client/src/sdm_client/explain/_kumo_ts/", + "packages/structured-data-models-client/src/sdm_client/explain/_attribution/", ] # --- Baseline recorded 2026-09-17 ------------------------------------------- From 368641f3f3f6db8700134a99380b918580f499d1 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Wed, 4 Nov 2026 09:29:44 -0800 Subject: [PATCH 10/13] Hold the explanation to what its pages say it is The differentiable normalisation deleted its patch rather than putting back what each module had. Two of these held at once left the inner one removing the outer one's patch, and the outer one raising on a name that was no longer there; a module carrying statistics of its own lost them. Integrated gradients measure against a baseline of noise over the window they read, so one gap makes that baseline NaN and every attribution taken against it reads as no influence at all. Only the feature axis refused a gapped window; both do now, since both work the window into a baseline. The embedding-stability page and its CSV were drawn under the channel attribution's labels, which set the forecast series aside. The two lists were different lengths, so the page numbered the channels instead of naming them. Stability now hands back the labels it is about. A trajectory that does not move has a mean step of zero, which was read as a measurement that was never taken and drawn as unavailable. Three pages send the reader to explanation.json for the diagnostics and the values they only summarise, and nothing wrote one. The check that every ported name resolves merged every scope into one, so a parameter in one function answered for a global another function reads and nothing defines; it now asks Python's own scope analysis. It also read only `from x import y`, and `import x` leaves the same module missing. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../sdm_client/explain/_attribution/pages.py | 13 ++- .../src/sdm_client/explain/_explain.py | 25 ++-- .../src/sdm_client/explain/_model.py | 32 +++-- .../src/sdm_client/reporting/forecast.py | 51 +++++--- .../test_a_forecast_says_what_it_rested_on.py | 110 ++++++++++++++++++ ...the_ported_pages_resolve_what_they_name.py | 75 ++++++------ 6 files changed, 234 insertions(+), 72 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py index b7b052890..4da73becb 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_attribution/pages.py @@ -1151,9 +1151,17 @@ def _build_pdf_report( context_len: int | None = None, forecast_horizon: int | None = None, channel_labels: list[str] | None = None, + feature_axis_stability_channel_labels: list[str] | None = None, integrated_gradients_report: dict[str, Any] | None = None, ) -> Path | None: - """Compose a multi-page PDF with the forecast and attribution heatmap.""" + """Compose a multi-page PDF with the forecast and attribution heatmap. + + ``feature_axis_stability_channel_labels`` names the channels the + embedding-stability report is about, which include the series being + forecast. ``channel_labels`` names the ones the channel attribution is + about, which do not. Drawing the stability page under the latter left + the two lists different lengths and the channels numbered instead. + """ try: import matplotlib as mpl @@ -1556,7 +1564,8 @@ def _build_pdf_report( pdf, plt, report=feature_axis_embedding_stability_report, - channel_labels=channel_labels, + channel_labels=feature_axis_stability_channel_labels + or channel_labels, ) except Exception as e: logger.warning( diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py index f9b969121..d3b9eef95 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_explain.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_explain.py @@ -125,14 +125,25 @@ def explanation_of( code='UNSUPPORTED_REQUEST', ) window_only = history[..., -forecaster.context_size :] - if feature_axis and not np.isfinite(window_only).all(): + over_the_window = [ + name + for name, asked in ( + ('the feature axis', feature_axis), + ('integrated gradients', integrated_gradients), + ) + if asked + ] + if over_the_window and not np.isfinite(window_only).all(): raise StructuredDataError( - f'feature-axis attribution replaces a channel with its own ' - f'average over the window it reads, which a gap in that window ' - f'makes undefined, and the channel is then reported as having no ' - f'influence. The window is the last {forecaster.context_size} ' - f'steps; fill its gaps, or ask for the explanation without the ' - f'feature axis', + f'this explanation was asked for ' + f'{" and ".join(over_the_window)}, and each of those measures ' + f'against a baseline worked out from the window it reads -- a ' + f'channel replaced by its own average, or the window replaced by ' + f'noise. A gap makes that baseline undefined, and every ' + f'attribution taken against it is then NaN, which reads as no ' + f'influence at all. The window is the last ' + f'{forecaster.context_size} steps; fill its gaps, or ask for the ' + f'explanation without them', code='UNSUPPORTED_SHAPE', ) if feature_axis and horizon > forecaster.prediction_size: diff --git a/packages/structured-data-models-client/src/sdm_client/explain/_model.py b/packages/structured-data-models-client/src/sdm_client/explain/_model.py index 8b2ad29c9..c12b873a0 100644 --- a/packages/structured-data-models-client/src/sdm_client/explain/_model.py +++ b/packages/structured-data-models-client/src/sdm_client/explain/_model.py @@ -83,21 +83,35 @@ def differentiable_normalisation(self) -> Iterator[None]: So the statistics are taken again, differentiably, for as long as this is held. Everything else about the forward pass is unchanged, and the numbers it produces are the same ones. + + What each module had before is put back rather than deleted. Two of + these held at once over the same forecaster left the inner one + deleting the outer one's patch on its way out, and the outer one + then raising on a name that was no longer there; a module that + carried its own statistics before any of this lost them outright. """ from sdm.nn import RevIN - patched = [ - module - for module in self._inner.modules() - if isinstance(module, RevIN) - ] - for module in patched: - module.stats = _statistics + held: list[tuple[torch.nn.Module, bool, Any]] = [] try: + for module in self._inner.modules(): + if not isinstance(module, RevIN): + continue + held.append( + ( + module, + 'stats' in module.__dict__, + module.__dict__.get('stats'), + ) + ) + module.stats = _statistics yield finally: - for module in patched: - del module.stats + for module, had_its_own, previous in reversed(held): + if had_its_own: + module.stats = previous + else: + module.__dict__.pop('stats', None) @property def prediction_size(self) -> int: diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 7e892e5f0..b4f2108a6 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -16,6 +16,7 @@ from __future__ import annotations +import json import tempfile from collections.abc import Iterator from contextlib import contextmanager @@ -102,9 +103,10 @@ def forecast_report( ) per_step = attributions if marginal is None else np.asarray(marginal) smoothness = _smoothness(carried) - stability = _stability(carried) + stability, stability_channels = _stability(carried) gradients = (carried.get('explanation') or {}).get('integrated_gradients') with _artifacts(artifacts_dir) as out_dir: + _saved_as_json(out_dir, carried) heatmap = pages._save_lag_horizon_artifacts( out_dir, per_step, @@ -129,7 +131,7 @@ def forecast_report( pages._save_integrated_gradients_artifacts(out_dir, gradients) if stability is not None: pages._save_feature_axis_embedding_stability_csv( - out_dir, stability, channels + out_dir, stability, stability_channels ) drawn = pages._build_pdf_report( Path(output_path), @@ -146,6 +148,7 @@ def forecast_report( channel_labels=channels, trajectory_report=smoothness, feature_axis_embedding_stability_report=stability, + feature_axis_stability_channel_labels=stability_channels, integrated_gradients_report=gradients, ) if drawn is None: # pragma: no cover - matplotlib is present by here @@ -248,14 +251,15 @@ def _smoothness(carried: dict[str, Any]) -> Any: ) -def _stability(carried: dict[str, Any]) -> Any: - r"""How much the embedding moved when a channel was nudged. +def _stability(carried: dict[str, Any]) -> tuple[Any, list[str] | None]: + r"""How much the embedding moved when a channel was nudged, and the + channels it is about. - The labels it carries are its own: the page reads them off the report - where there are as many as there are channels, and that count includes - the series being forecast, which the channel attribution beside it sets - aside. Rebuilt with the channel labels of the explanation instead, the - two would be the same length and name different channels. + The labels it carries are its own and are handed back beside it. There + are as many of them as there are channels, and that count includes the + series being forecast, which the channel attribution beside it sets + aside. Drawn under the explanation's labels instead, the two lists were + different lengths, and the page fell back to numbering the channels. """ from sdm_client.explain._attribution.channel_stability import ( PerChannelEmbeddingStabilityReport, @@ -264,8 +268,8 @@ def _stability(carried: dict[str, Any]) -> Any: feature_axis = (carried.get('explanation') or {}).get('feature_axis') or {} block = feature_axis.get('embedding_stability') if not block: - return None - labels = block.get('channel_labels') or [] + return None, None + labels = [str(name) for name in block.get('channel_labels') or []] ratios = { name: np.asarray(block.get(name), dtype=float) for name in ( @@ -275,17 +279,18 @@ def _stability(carried: dict[str, Any]) -> Any: 'lip_ratio_p95', ) } + reference = block.get('step_delta_norm_mean') return PerChannelEmbeddingStabilityReport( **ratios, n_trials_per_channel=np.asarray( block.get('n_trials_per_channel'), dtype='int64' ), n_unique_windows=int(block.get('n_unique_windows') or 0), - step_delta_norm_mean=float( - block.get('step_delta_norm_mean') or float('nan') - ), + step_delta_norm_mean=float('nan') + if reference is None + else float(reference), n_channels=len(labels), - ) + ), labels def _forecast_frame(carried: dict[str, Any]) -> tuple[Any, str, str]: @@ -341,6 +346,22 @@ def _artifacts(named: str | Path | None) -> Iterator[Path]: yield Path(temporary) +def _saved_as_json(out_dir: Path, carried: dict[str, Any]) -> Path: + r"""The explanation these pages were drawn from, written out beside them. + + Three of the pages send the reader to ``explanation.json`` for the + diagnostics block and for the values they only summarise, and nothing + wrote one, so the reader was sent to a file that was never there. + + What is written is the answer's own explanation, unchanged: the pages + read nothing else, so anything derived here could disagree with them. + """ + out_path = out_dir / 'explanation.json' + with out_path.open('w', encoding='utf-8') as handle: + json.dump(carried, handle, indent=2, allow_nan=False) + return out_path + + def _without_the_unmeasured( explanation: Any, channels: list[str] | None, carried: dict[str, Any] ) -> tuple[Any, list[str] | None]: diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 9506433a3..55d2138a4 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -18,6 +18,7 @@ from sdm_client import KumoForecast, Request, SDMClient, StructuredDataError pytest.importorskip('matplotlib', reason='needs the report extra') +pytest.importorskip('torch', reason='the attribution runs on torch') from sdm_client.reporting import forecast_report # noqa: E402 @@ -270,6 +271,7 @@ def test_the_files_the_pages_name_are_written(explained, tmp_path): assert 'lag_horizon_heatmap.png' in written assert 'semantic_flow.csv' in written + assert 'explanation.json' in written def test_the_series_own_channel_is_not_ranked_among_the_measured( @@ -413,6 +415,28 @@ def test_a_channel_with_a_gap_is_not_called_uninfluential(forecast): assert 'gap' in str(caught.value) +def test_a_gradient_over_a_gap_is_not_an_attribution(forecast): + """Integrated gradients measure against a baseline of noise over the + window, and one gap makes the whole baseline NaN: every attribution + taken against it reads as no influence at all.""" + frame = history(600) + frame.loc[599, 'temp'] = np.nan + + with SDMClient.in_process(forecast) as client: + with pytest.raises(StructuredDataError) as caught: + client.predict( + Request.forecast( + frame, + target='flow', + horizon=4, + inference={'integrated_gradients': True}, + ), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + assert 'integrated gradients' in str(caught.value) + + def test_a_report_is_drawn_from_an_explanation(explained, tmp_path): written = forecast_report(explained, tmp_path / 'forecast.pdf') @@ -575,6 +599,52 @@ def test_the_embedding_stability_page_is_drawn(over_channels, tmp_path): assert before == after + 1 +def test_the_stability_csv_names_the_channels_it_measured( + over_channels, tmp_path +): + """The channels it measured include the series being forecast, which the + channel attribution beside it sets aside. Drawn under the attribution's + labels the two lists were different lengths, and the page numbered the + channels instead of naming them.""" + import pandas as pd + + artifacts = tmp_path / 'artifacts' + forecast_report(over_channels, tmp_path / 'f.pdf', artifacts_dir=artifacts) + written = pd.read_csv(artifacts / 'feature_axis_embedding_stability.csv') + + assert written['feature'].tolist() == ['flow', 'temp'] + + +@pytest.mark.parametrize('reference', [0.0, 1.5, None]) +def test_a_reference_scale_of_zero_is_a_reference_scale(reference): + """A trajectory that does not move has a mean step of zero, which read + as a measurement that was never taken.""" + from sdm_client.reporting.forecast import _stability + + report, labels = _stability( + { + 'explanation': { + 'feature_axis': { + 'embedding_stability': { + 'channel_labels': ['flow', 'temp'], + 'lip_ratio_mean': [1.0, 2.0], + 'lip_ratio_max': [1.0, 2.0], + 'lip_ratio_p50': [1.0, 2.0], + 'lip_ratio_p95': [1.0, 2.0], + 'n_trials_per_channel': [3, 3], + 'n_unique_windows': 4, + 'step_delta_norm_mean': reference, + } + } + } + } + ) + + assert labels == ['flow', 'temp'] + read = report.step_delta_norm_mean + assert np.isnan(read) if reference is None else read == reference + + def test_too_many_channels_leave_the_page_out_rather_than_the_rest(forecast): """The probes are a window per channel per trial and a copy of each, so their memory grows with the square of the channels. Past the cap the @@ -696,6 +766,46 @@ def test_the_normalisation_is_left_as_it_was_found(forecast): ) +def test_the_normalisation_survives_being_held_twice(forecast): + """The inner one deleted the outer one's patch on its way out, and the + outer one then raised on a name that was no longer there.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + revins = [ + module + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ] + with shim.differentiable_normalisation(): + with shim.differentiable_normalisation(): + pass + inner = [vars(module).get('stats') for module in revins] + + assert all(held is not None for held in inner) + assert not any('stats' in vars(module) for module in revins) + + +def test_a_normalisation_of_its_own_is_put_back(forecast): + """A module that carried its own statistics before any of this lost + them outright: the patch was deleted rather than replaced.""" + from sdm_client.explain._model import Forecaster + + shim = Forecaster(forecast) + revin = next( + module + for module in shim.modules() + if hasattr(module, 'eps') and hasattr(module, 'stats') + ) + theirs = revin.stats + revin.stats = theirs + + with shim.differentiable_normalisation(): + pass + + assert vars(revin).get('stats') is theirs + + def test_the_length_of_the_embedding_is_not_what_is_explained(forecast): """This forecaster's embedding is a retrieval key, scaled to unit length before it is returned, so its length is one whatever it was given. diff --git a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py index b47c64410..d57b7cbe6 100644 --- a/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py +++ b/packages/structured-data-models-client/tests/test_the_ported_pages_resolve_what_they_name.py @@ -17,6 +17,7 @@ import builtins import importlib import pkgutil +import symtable from pathlib import Path import pytest @@ -31,46 +32,34 @@ MODULES = [f'{PORTED}.{name}' for name in NAMES] -def named(tree: ast.AST) -> set[str]: - """Every global name the module's code reads, bound names aside.""" - bound: set[str] = set() - read: set[str] = set() - for node in ast.walk(tree): - if isinstance(node, ast.Name): - (bound if isinstance(node.ctx, ast.Store) else read).add(node.id) - elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): - bound.add(node.name) - arguments = node.args - for argument in ( - arguments.args - + arguments.posonlyargs - + arguments.kwonlyargs - + [a for a in (arguments.vararg, arguments.kwarg) if a] - ): - bound.add(argument.arg) - elif isinstance(node, ast.ClassDef): - bound.add(node.name) - elif isinstance(node, (ast.Import, ast.ImportFrom)): - for alias in node.names: - bound.add(alias.asname or alias.name.split('.')[0]) - elif isinstance(node, ast.ExceptHandler) and node.name: - bound.add(node.name) - elif isinstance(node, ast.Global): - bound.update(node.names) - elif isinstance(node, (ast.comprehension,)): - for target in ast.walk(node.target): - if isinstance(target, ast.Name): - bound.add(target.id) - return read - bound +def read_as_globals(source: str, filename: str) -> set[str]: + """Every name the module's code reads and expects to find around it. + + Asked of Python's own scope analysis rather than worked out from the + tree. Collecting bindings by walking merges every scope into one, and a + parameter named `logger` in one function then resolves a `logger` that + another function reads and nothing defines. + """ + found: set[str] = set() + pending = [symtable.symtable(source, filename, 'exec')] + while pending: + scope = pending.pop() + pending.extend(scope.get_children()) + found.update( + symbol.get_name() + for symbol in scope.get_symbols() + if symbol.is_referenced() and symbol.is_global() + ) + return found @pytest.mark.parametrize('module_name', MODULES) def test_the_ported_module_resolves_every_name_it_reads(module_name): module = importlib.import_module(module_name) - source = ast.parse(Path(module.__file__).read_text(encoding='utf-8')) + source = Path(module.__file__).read_text(encoding='utf-8') unresolved = { name - for name in named(source) + for name in read_as_globals(source, module.__file__) if not hasattr(module, name) and not hasattr(builtins, name) } @@ -82,16 +71,24 @@ def test_the_ported_module_imports_nothing_from_where_it_came_from( module_name, ): """An import of a bare top-level module is the shape the move leaves - behind: upstream ran these as scripts beside one another.""" + behind: upstream ran these as scripts beside one another. Both spellings + of it, because `import channel_flow` leaves the same module missing as + `from channel_flow import ...` does.""" module = importlib.import_module(module_name) source = ast.parse(Path(module.__file__).read_text(encoding='utf-8')) sibling = { - node.module + named for node in ast.walk(source) - if isinstance(node, ast.ImportFrom) - and node.level == 0 - and node.module is not None - and node.module.split('.')[0] in NAMES + for named in ( + [node.module] + if isinstance(node, ast.ImportFrom) + and node.level == 0 + and node.module is not None + else [alias.name for alias in node.names] + if isinstance(node, ast.Import) + else [] + ) + if named.split('.')[0] in NAMES } assert not sibling From 5f12d6e683cbd194d854d507127c80bf2f33f882 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Wed, 4 Nov 2026 10:36:11 -0800 Subject: [PATCH 11/13] Write a value JSON cannot spell as null, not as nothing at all The explanation writes its arrays that way already and had not done it to the summaries nested inside them. One such value raised, and this is written before a page is drawn, so it cost the whole report rather than the one number it was about. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/reporting/forecast.py | 24 ++++++++++++++++--- .../test_a_forecast_says_what_it_rested_on.py | 19 +++++++++++++++ 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index b4f2108a6..2fc6a0390 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -17,6 +17,8 @@ from __future__ import annotations import json +import math +import numbers import tempfile from collections.abc import Iterator from contextlib import contextmanager @@ -353,15 +355,31 @@ def _saved_as_json(out_dir: Path, carried: dict[str, Any]) -> Path: diagnostics block and for the values they only summarise, and nothing wrote one, so the reader was sent to a file that was never there. - What is written is the answer's own explanation, unchanged: the pages - read nothing else, so anything derived here could disagree with them. + What is written is the answer's own explanation: the pages read nothing + else, so anything derived here could disagree with them. The only thing + changed on the way out is that a value no JSON reader accepts is + written as null, which is what the explanation already does to the + arrays it carries and had not done to the summaries nested inside them. + Writing one as it stood raised, and this is written before a page is + drawn, so one such value cost the whole report. """ out_path = out_dir / 'explanation.json' with out_path.open('w', encoding='utf-8') as handle: - json.dump(carried, handle, indent=2, allow_nan=False) + json.dump(_readable(carried), handle, indent=2, allow_nan=False) return out_path +def _readable(value: Any) -> Any: + r"""``value`` with everything JSON has no spelling for written as null.""" + if isinstance(value, dict): + return {name: _readable(held) for name, held in value.items()} + if isinstance(value, (list, tuple)): + return [_readable(held) for held in value] + if isinstance(value, bool) or not isinstance(value, numbers.Real): + return value + return None if not math.isfinite(float(value)) else value + + def _without_the_unmeasured( explanation: Any, channels: list[str] | None, carried: dict[str, Any] ) -> tuple[Any, list[str] | None]: diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 55d2138a4..728dae8e4 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -274,6 +274,25 @@ def test_the_files_the_pages_name_are_written(explained, tmp_path): assert 'explanation.json' in written +def test_a_value_json_cannot_spell_does_not_cost_the_report( + explained, tmp_path +): + """The explanation is written out before any page is drawn, so one + value no JSON reader accepts took the whole report with it.""" + import json + + artifacts = tmp_path / 'artifacts' + carried = dict(explained.explanation) + carried['diagnostics'] = {'top': [{'share': float('nan')}]} + + forecast_report( + Carrying(carried), tmp_path / 'f.pdf', artifacts_dir=artifacts + ) + written = json.loads((artifacts / 'explanation.json').read_text()) + + assert written['diagnostics']['top'][0]['share'] is None + + def test_the_series_own_channel_is_not_ranked_among_the_measured( forecast, tmp_path ): From 073245e4499a1adc523e661fecb6cb9f69879232 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Wed, 4 Nov 2026 11:02:17 -0800 Subject: [PATCH 12/13] Hand a whole number back as it is JSON spells one of any size. Reading it as a float first raised on one too large to be one, and cost the report the float was never needed for. Co-Authored-By: Claude Opus 5 Signed-off-by: Manush Murali --- .../src/sdm_client/reporting/forecast.py | 9 +++++++-- .../tests/test_a_forecast_says_what_it_rested_on.py | 3 ++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 2fc6a0390..68be8efda 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -370,12 +370,17 @@ def _saved_as_json(out_dir: Path, carried: dict[str, Any]) -> Path: def _readable(value: Any) -> Any: - r"""``value`` with everything JSON has no spelling for written as null.""" + r"""``value`` with everything JSON has no spelling for written as null. + + A whole number is handed back as it is rather than read as a float: JSON + spells one of any size, and one too large to be a float raised here and + cost the report the float was never needed for. + """ if isinstance(value, dict): return {name: _readable(held) for name, held in value.items()} if isinstance(value, (list, tuple)): return [_readable(held) for held in value] - if isinstance(value, bool) or not isinstance(value, numbers.Real): + if isinstance(value, (bool, int)) or not isinstance(value, numbers.Real): return value return None if not math.isfinite(float(value)) else value diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 728dae8e4..70d25c862 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -283,7 +283,7 @@ def test_a_value_json_cannot_spell_does_not_cost_the_report( artifacts = tmp_path / 'artifacts' carried = dict(explained.explanation) - carried['diagnostics'] = {'top': [{'share': float('nan')}]} + carried['diagnostics'] = {'top': [{'share': float('nan'), 'n': 2**1024}]} forecast_report( Carrying(carried), tmp_path / 'f.pdf', artifacts_dir=artifacts @@ -291,6 +291,7 @@ def test_a_value_json_cannot_spell_does_not_cost_the_report( written = json.loads((artifacts / 'explanation.json').read_text()) assert written['diagnostics']['top'][0]['share'] is None + assert written['diagnostics']['top'][0]['n'] == 2**1024 def test_the_series_own_channel_is_not_ranked_among_the_measured( From cf237eab958e59861c75fb5fdd6dd62d8730ea22 Mon Sep 17 00:00:00 2001 From: Manush Murali Date: Thu, 5 Nov 2026 14:11:58 -0800 Subject: [PATCH 13/13] Read a forecast's explanation where it travels Main now keeps explanations as per-row gradients and a column analysis, and deprecates `result.explanation`. Three things followed for a forecast asked for one, and the module's tests ignore every warning, so none of them failed. The adapter built its result through the deprecated `explanation=` argument, and the report read the deprecated property. Both now read the explanation from the step it came back on, which is where the model put it. The answer was reported as missing the explanation it carried, because only gradients counted as one. An item's explanation now counts too. For the other models every explained item is decoded into a gradient, so their answer is unchanged. A column analysis was computed from the forecast's history, which is not a set of labelled rows. Each reading of the series was taken for a class and the result carried thirty of them. The analysis is now computed only for models that learn from labelled rows. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Manush Murali --- .../src/sdm_client/adapters/forecast.py | 4 - .../src/sdm_client/client.py | 17 ++- .../src/sdm_client/reporting/forecast.py | 4 +- .../src/sdm_client/result.py | 4 +- .../test_a_forecast_says_what_it_rested_on.py | 121 +++++++++++++----- 5 files changed, 110 insertions(+), 40 deletions(-) diff --git a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py index 02b7d1189..985b7c969 100644 --- a/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/adapters/forecast.py @@ -124,16 +124,12 @@ def answered( f'it cannot be put in order', code='INVALID_RESPONSE', ) - explanation = next( - (item.explanation for item in items if item.explanation), None - ) result = PredictionResult( model=model, request_id=request_id, items=items, metadata=dict(metadata or {}), outputs=outputs, - explanation=explanation, ) result._names_its_rows = False result._names_its_step = True diff --git a/packages/structured-data-models-client/src/sdm_client/client.py b/packages/structured-data-models-client/src/sdm_client/client.py index 47c1efa81..3a1255b87 100644 --- a/packages/structured-data-models-client/src/sdm_client/client.py +++ b/packages/structured-data-models-client/src/sdm_client/client.py @@ -25,6 +25,8 @@ from types import TracebackType from typing import Any +from predictive_query import RELATIONAL, TABULAR + from sdm_client.base import ( ModelAdapter, ModelCapabilities, @@ -558,7 +560,9 @@ def _answer( _analysed_or_warned( lambda: ColumnExplanations(_LabelledRows.of(request, calls[0])) ) - if analysed and 'explanation' in fields + if analysed + and 'explanation' in fields + and _learns_from_labels(adapter.spec) else None ) # Every call's rows are kept. A request past the endpoint's per-call @@ -1294,6 +1298,17 @@ def _pinned_dtypes(pinned: Mapping[str, Any]) -> dict[str, str] | None: } +def _learns_from_labels(spec: ModelSpec) -> bool: + r"""Whether ``spec``'s model is shown labelled rows to learn from. + + A column analysis reads those rows, so it is computed only for a model + that has them. A forecast's context is a history rather than labelled + examples. Read as though it were one, each reading of the series was + taken for a class. + """ + return spec.profile in (TABULAR, RELATIONAL) + + def _analysed_or_warned( analyse: Callable[[], ColumnExplanations], ) -> ColumnExplanations | None: diff --git a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py index 68be8efda..7655829b6 100644 --- a/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py +++ b/packages/structured-data-models-client/src/sdm_client/reporting/forecast.py @@ -84,7 +84,9 @@ def forecast_report( ... ) >>> forecast_report(result, 'forecast.pdf') """ - carried = result.explanation + carried = next( + (item.explanation for item in result.items if item.explanation), None + ) if not carried: raise StructuredDataError( 'this answer carries no explanation. Ask for one with ' diff --git a/packages/structured-data-models-client/src/sdm_client/result.py b/packages/structured-data-models-client/src/sdm_client/result.py index 14d0cebe3..fb4a67afa 100644 --- a/packages/structured-data-models-client/src/sdm_client/result.py +++ b/packages/structured-data-models-client/src/sdm_client/result.py @@ -158,7 +158,9 @@ def _carries(self, name: str) -> bool: was refused before the request was sent. """ if name == 'explanation': - return bool(self._explanations.gradients) + return bool(self._explanations.gradients) or any( + getattr(item, 'explanation', None) for item in self.items + ) if name not in _ITEM_FIELDS: return True return any( diff --git a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py index 70d25c862..82a3163b5 100644 --- a/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py +++ b/packages/structured-data-models-client/tests/test_a_forecast_says_what_it_rested_on.py @@ -11,11 +11,20 @@ from __future__ import annotations +import warnings + import numpy as np import pandas as pd import pytest - -from sdm_client import KumoForecast, Request, SDMClient, StructuredDataError +from sdm_api.generated.tfm_api import PredictionItem + +from sdm_client import ( + KumoForecast, + Request, + SDMClient, + SDMWarning, + StructuredDataError, +) pytest.importorskip('matplotlib', reason='needs the report extra') pytest.importorskip('torch', reason='the attribution runs on torch') @@ -31,13 +40,34 @@ def history(rows: int = 600) -> pd.DataFrame: @pytest.fixture(scope='module') -def explained(forecast): - with SDMClient.in_process(forecast) as client: - return client.predict( - Request.forecast(history(), target='flow', horizon=4), - model=KumoForecast(), - outputs=['prediction', 'explanation'], - ) +def answered(forecast): + """An explained forecast, and what the client warned of answering it.""" + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + with SDMClient.in_process(forecast) as client: + result = client.predict( + Request.forecast(history(), target='flow', horizon=4), + model=KumoForecast(), + outputs=['prediction', 'explanation'], + ) + return result, [ + str(warning.message) + for warning in caught + if issubclass(warning.category, SDMWarning) + or 'explanation' in str(warning.message) + ] + + +@pytest.fixture(scope='module') +def explained(answered): + return answered[0] + + +def carried_by(result): + """The explanation an answer carries, on the step it came back on.""" + return next( + (item.explanation for item in result.items if item.explanation), None + ) class Carrying: @@ -48,12 +78,16 @@ class Carrying: """ def __init__(self, explanation): - self.explanation = explanation + self.items = ( + PredictionItem( + row_index=0, forecast_step=1, explanation=explanation + ), + ) def without(result, *names, under=None): """What `result` carries, less the block(s) `names` asks for.""" - carried = dict(result.explanation) + carried = dict(carried_by(result)) block = dict(carried['explanation']) if under is None: for name in names: @@ -76,14 +110,35 @@ def pages(path) -> int: def test_an_explanation_comes_back_when_it_is_asked_for(explained): """It reads the model's gradients and its latent trajectory, so it is produced where the model runs and nowhere else.""" - carried = explained.explanation + carried = carried_by(explained) assert isinstance(carried, dict) assert set(carried) >= {'forecast', 'explanation', 'metadata'} +def test_an_explained_forecast_is_answered_as_it_was_asked(answered): + """The explanation rides on the forecast's first step. The answer is + not said to be missing it, is not built through a deprecated argument, + and carries no column analysis, which reads labelled rows and a + history is not that.""" + result, warned = answered + + assert warned == [] + assert result.explanations.columns is None + + +def test_the_report_reads_no_deprecated_part_of_the_answer(explained, tmp_path): + with warnings.catch_warnings(): + warnings.filterwarnings( + 'error', + message=r'result\.explanation is deprecated', + category=DeprecationWarning, + ) + forecast_report(explained, tmp_path / 'f.pdf') + + def test_the_attribution_covers_every_lag_and_every_step(explained): - block = explained.explanation['explanation'] + block = carried_by(explained)['explanation'] attributions = np.asarray(block['lag_horizon_attributions']) assert attributions.shape == (block['shapes']['K_lags'], 4) @@ -95,7 +150,7 @@ def test_an_explanation_is_data_rather_than_an_object(explained): what that field carries.""" import json - assert json.loads(json.dumps(explained.explanation)) + assert json.loads(json.dumps(carried_by(explained))) def test_a_forecast_asked_without_one_does_not_pay_for_it(forecast): @@ -108,7 +163,7 @@ def test_a_forecast_asked_without_one_does_not_pay_for_it(forecast): outputs=['prediction'], ) - assert result.explanation is None + assert carried_by(result) is None def test_a_flat_series_has_almost_nowhere_to_move(forecast): @@ -123,7 +178,7 @@ def test_a_flat_series_has_almost_nowhere_to_move(forecast): outputs=['prediction', 'explanation'], ) - flow = np.asarray(result.explanation['explanation']['flow_magnitudes']) + flow = np.asarray(carried_by(result)['explanation']['flow_magnitudes']) assert float(flow.sum()) < 0.5 @@ -165,7 +220,7 @@ def test_the_attribution_reads_the_model_s_own_scale(forecast): def test_what_is_drawn_is_in_the_readings_own_scale(explained): """The attribution works standardised; a reader does not.""" baseline = np.asarray( - explained.explanation['explanation']['baseline_forecast'] + carried_by(explained)['explanation']['baseline_forecast'] ) assert np.abs(baseline).max() < 5.0 @@ -194,7 +249,7 @@ def test_the_diagnostics_survive_being_written_and_read(explained): them, which printed n/a for every one of them.""" from sdm_client.reporting.forecast import _explanation - restored = _explanation(explained.explanation) + restored = _explanation(carried_by(explained)) assert restored.flow_ratio_forecast_vs_history is not None assert restored.curvature_ratio_forecast_vs_history is not None @@ -224,7 +279,7 @@ def watched(scores, **kwargs): finally: pages._topk_lag_steps_per_horizon = original - block = explained.explanation['explanation'] + block = carried_by(explained)['explanation'] assert len(seen) == 1 assert np.allclose(seen[0], np.asarray(block['lag_horizon_scores'])) @@ -234,10 +289,10 @@ def test_the_history_the_page_is_told_about_excludes_the_forecast(explained): length as the context said every transition was history.""" from sdm_client.reporting.forecast import _context_len - block = explained.explanation['explanation'] + block = carried_by(explained)['explanation'] steps = block['diagnostics']['latent_trajectory_shape'][0] - assert _context_len(explained.explanation, 4) == steps - 4 + assert _context_len(carried_by(explained), 4) == steps - 4 def test_a_gap_outside_the_window_is_not_a_gap_in_it(forecast): @@ -259,7 +314,7 @@ def test_a_gap_outside_the_window_is_not_a_gap_in_it(forecast): outputs=['prediction', 'explanation'], ) - assert result.explanation is not None + assert carried_by(result) is not None def test_the_files_the_pages_name_are_written(explained, tmp_path): @@ -282,7 +337,7 @@ def test_a_value_json_cannot_spell_does_not_cost_the_report( import json artifacts = tmp_path / 'artifacts' - carried = dict(explained.explanation) + carried = dict(carried_by(explained)) carried['diagnostics'] = {'top': [{'share': float('nan'), 'n': 2**1024}]} forecast_report( @@ -318,7 +373,7 @@ def test_the_series_own_channel_is_not_ranked_among_the_measured( outputs=['prediction', 'explanation'], ) - carried = result.explanation + carried = carried_by(result) assert carried['metadata']['feature_axis_excludes'] == 'flow' _, channels = _without_the_unmeasured( _explanation(carried), _channels(carried), carried @@ -368,7 +423,7 @@ def watched(out_dir, attributions, scores=None, **kwargs): finally: pages._save_lag_horizon_artifacts = original - block = explained.explanation['explanation'] + block = carried_by(explained)['explanation'] marginal, _ = pages._topk_lag_steps_per_horizon( np.asarray(block['lag_horizon_scores']), top_k=5 ) @@ -468,7 +523,7 @@ def test_the_report_names_the_series_and_the_lag_window(explained, tmp_path): """Read off the data the page is drawn from. The text in this PDF is compressed, so sniffing its bytes for a word tests the encoder rather than the report.""" - metadata = explained.explanation['metadata'] + metadata = carried_by(explained)['metadata'] assert metadata['target_column'] == 'flow' assert metadata['channel_labels'] == ['flow', 'temp'] @@ -525,7 +580,7 @@ def test_only_this_model_is_asked_to_explain_a_forecast(anomaly): def test_the_smoothness_of_the_latent_state_is_measured(explained): """Reported as null for every run before it was computed, so its page was never drawn.""" - block = explained.explanation['explanation']['trajectory_stability'] + block = carried_by(explained)['explanation']['trajectory_stability'] assert block is not None assert block['n_time_steps'] == 512 @@ -543,7 +598,7 @@ def test_the_smoothness_is_the_history_walked_once(explained, forecast): from sdm_client.explain._explain import _standardised from sdm_client.explain._model import Forecaster - carried = explained.explanation + carried = carried_by(explained) window = _standardised( forecast, history().to_numpy().T[:, -512:].astype('float32') ) @@ -592,7 +647,7 @@ def test_the_embedding_is_measured_for_every_channel(over_channels): """Asked for alongside the feature axis, because it answers the question the feature axis raises: an influence attributed through a derivative that is not there is not an influence.""" - block = over_channels.explanation['explanation']['feature_axis'] + block = carried_by(over_channels)['explanation']['feature_axis'] measured = block['embedding_stability'] assert measured['channel_labels'] == ['flow', 'temp'] @@ -603,7 +658,7 @@ def test_the_embedding_is_measured_for_every_channel(over_channels): def test_the_embedding_is_not_measured_without_the_feature_axis(explained): """It costs a window per channel per trial, which is the feature axis's own order of cost and not the lag attribution's.""" - block = explained.explanation['explanation'].get('feature_axis') or {} + block = carried_by(explained)['explanation'].get('feature_axis') or {} assert 'embedding_stability' not in block @@ -695,7 +750,7 @@ def test_too_many_channels_leave_the_page_out_rather_than_the_rest(forecast): finally: _explain._STABILITY_BYTES = kept - block = result.explanation['explanation']['feature_axis'] + block = carried_by(result)['explanation']['feature_axis'] assert 'embedding_stability' not in block assert block['channel_horizon_attributions'] is not None assert any( @@ -721,7 +776,7 @@ def by_gradient(forecast): def test_the_gradient_attribution_covers_the_window_it_read(by_gradient): - block = by_gradient.explanation['explanation']['integrated_gradients'] + block = carried_by(by_gradient)['explanation']['integrated_gradients'] assert np.asarray(block['attribution']).shape == (2, 512) assert block['channel_labels'] == ['flow', 'temp'] @@ -849,7 +904,7 @@ def test_the_length_of_the_embedding_is_not_what_is_explained(forecast): def test_a_forecast_asked_without_gradients_does_not_pay_for_them(explained): """They walk a path of sixty-four windows and take a gradient at each.""" - assert 'integrated_gradients' not in explained.explanation['explanation'] + assert 'integrated_gradients' not in carried_by(explained)['explanation'] def test_the_gradient_page_is_drawn(by_gradient, tmp_path):