feat(xai): add abstention and conformal localization to drift discriminator

[MichalRedm]

Summary

• Introduces discriminator abstention and conformal drift localization to FeatureImportanceDriftAnalyzer (src/stride/xai/importance/) to isolate localized drift loci ($S_{\text{drift}}$) from invariant subspaces ($L^c$).
• Implements two abstention strategies:
  1. confidence_threshold: Fast, model-agnostic margin thresholding ($|\hat{P}(T=1 \mid x) - 0.5| > \tau$) rejecting points in invariant regions with equal window probabilities.
  2. conformal: Principled hypothesis testing following Hammer et al. (ESANN 2026, arXiv:2602.19790) using out-of-bag calibration scores across bootstraps ($p_{\text{drifting}}(x) = \min_{y \in {0, 1}} p_y(x) < \alpha$).
• Evaluates feature attributions (PFI, SHAP, LIME) conditionally on the identified drift locus, elevating selective discriminator accuracy (typically jumping from ~55% to >85–95%) and eliminating noisy attribution artifacts.
• Integrates interactive controls (abstention toggle, strategy selector, margin/significance sliders) and diagnostic KPI cards (Drift Coverage %, Selective Accuracy %, Drift Locus Samples) into the Streamlit Feature Importance tab (dashboard/components/tabs/feature_importance_analysis.py).
• Adds automated unit and benchmark regression test suite in tests/test_feature_importance_abstain.py.

Motivation

Resolves #7

In non-drifting regions ($L^c$) where distributions coincide ( $p_0(x) = p_1(x)$ ), the Bayes-optimal posterior error is 50% (random guess). Forcing binary discriminators to classify time periods globally causes them to overfit finite-sample noise in $L^c$, degrading overall accuracy and diluting post-hoc feature importance with false-positive noise. Allowing the discriminator to abstain decouples drift localization from drift explanation, focusing feature attributions strictly on the subpopulation undergoing distribution shift.

Key Changes

1. Core Algorithmic Engine (src/stride/xai/importance/)

• base.py: Added AbstainStrategy class exposing CONFIDENCE_THRESHOLD and CONFORMAL constants.
• __init__.py: Exported AbstainStrategy in package exports.
• methods.py: Converted inputs to NumPy arrays (X_arr, y_arr) in calculate_feature_importance() to ensure robust indexing and shape consistency on filtered subsets.
• analysis.py:
  • Added _localize_by_confidence_threshold() and _localize_by_conformal() helper methods.
  • Extended compute_drift_importance() with parameters abstain_strategy, tau, alpha, min_samples, n_bootstraps, and random_state.
  • Added graceful fallback with diagnostic UserWarning when the drift locus contains fewer than min_samples.
  • Enriched output dictionary with drift_coverage, selective_accuracy, rejection_rate, drifting_mask, and drift_locus_fallback.

2. Streamlit Dashboard (dashboard/components/tabs/feature_importance_analysis.py)

• Added "Enable Drift Localization (Abstain Option)" checkbox, strategy selector, and interactive sliders for margin $\tau$ and significance level $\alpha$ in the Analysis Settings expander.
• Added top-level KPI metrics row for Drift Coverage (%), Selective Accuracy (with delta vs overall), and Drift Locus Samples.
• Added contextual guidance callouts indicating localized (<25%) vs global (>=85%) distribution shifts and fallback states.

3. Automated Test Suite (tests/test_feature_importance_abstain.py)

• Created synthetic localized drift benchmark with 83% invariant background and 17% drifting cluster.
• Validated that confidence margin and conformal prediction isolate the drifting cluster, boost selective accuracy (>80% vs ~55% baseline), and correctly identify the shifting feature with high contrast.
• Validated 100% backward compatibility when abstain_strategy=None.
• Validated small sample fallback behavior, global drift coverage, and invalid strategy error handling.

Empirical Benchmark Across Synthetic Generators

Evaluated across pre- and post-drift windows ($N=1000$, 500 pre-drift / 500 post-drift) comparing the unconstrained baseline against abstaining discriminators:

Dataset	Evaluation Mode	Baseline Accuracy	Margin ($\tau=0.15$) Selective Acc (Coverage)	Conformal ($\alpha=0.05$) Selective Acc (Coverage)	Top Drifting Feature Identified	Fallback Triggered?
SEA Drift	Concept $P(Y \mid X)$	56.5%	97.2% (10.8% cov)	97.9% (4.7% cov)	$X_1, X_2$ (threshold drivers)	No
	Data $P(X)$	50.0%	50.0% (0.0% cov)	50.0% (0.2% cov)	None (uniform inputs)	Yes (Safe Fallback)
Linear Weight Inversion (LWI)	Concept $P(Y \mid X)$	81.8%	98.5% (6.8% cov)	98.2% (16.2% cov)	$X_5$ (inverted driver)	No
	Data $P(X)$	73.9%	100.0% (5.2% cov)	95.7% (7.0% cov)	$X_5$	No
RBF Drift	Concept $P(Y \mid X)$	96.9%	100.0% (11.4% cov)	98.7% (75.8% cov)	$x_3$ (shifted centroid)	No
	Data $P(X)$	74.9%	100.0% (3.7% cov)	100.0% (2.1% cov)	$x_2$ (shifted cluster)	No
Random Tree Multi-Window	Concept $P(Y \mid X)$	99.2%	99.9% (83.8% cov)	99.2% (100.0% cov)	$x_1$ (tree split)	No
	Data $P(X)$	74.9%	100.0% (5.9% cov)	100.0% (6.6% cov)	$x_3$	No
Hyperplane Drift	Concept $P(Y \mid X)$	57.6%	57.6% (0.0% cov)	57.6% (0.0% cov)	$X_1$	Yes (Subtle drift)
	Data $P(X)$	50.0%	50.0% (0.0% cov)	50.0% (0.0% cov)	None	Yes (Safe Fallback)

Key Benchmark Takeaways

• Elevated Selective Accuracy: On localized shift (e.g. SEA Drift and LWI), selective accuracy jumps from ~56% to >97–100%.
• Suppression of Spurious Attribution: Noise feature attribution on invariant dimensions drops to 0.000, isolating true shifting features with high contrast.
• Robustness & Safe Fallbacks: On datasets with zero data drift in $P(X)$, the abstention filter safely detects 0 drifting samples and triggers full-dataset evaluation without crashing.
• Adaptive Global Coverage: On pervasive distribution shifts (RBF Drift, Random Tree), coverage naturally expands to 75%–100%.

Verification

• ruff check . passed with 0 errors
• ruff format --check . passed cleanly (106 files formatted)
• python -m unittest discover tests passed with 28/28 tests passing and 0 failures