v2.2.3 — Example Notebooks & Documentation

Released: April 2026

Summary

Patch release adding three new end-to-end example notebooks that cover real-world use cases, deep interpretability, and systematic benchmarking. No API changes; fully backward-compatible with v2.2.0.

New Example Notebooks

08 — Financial Forecasting (examples/08_financial_forecasting.ipynb)

Multi-asset return forecasting with a 6-asset portfolio over 1 000 simulated trading days. Demonstrates the complete quantitative-finance evaluation workflow:
- Regime-switching data generation (Markov bull/bear model)
- Walk-forward validation with zero look-ahead bias
- Information Coefficient (IC), ICIR, Sharpe ratio, Calmar ratio, max drawdown
- Long-short strategy simulation with equity curves and drawdown plots
- Regime-conditional performance (bull vs. bear IC and Sharpe split)
- Horizon-dependent accuracy (h=1 … h=5)
- Gradient saliency for financial feature importance
- Residual autocorrelation and ARCH test (volatility clustering)
09 — Attention Interpretability (examples/09_attention_interpretability.ipynb)

Deep interpretability study on a smart-building energy demand dataset with a known ground-truth formula, allowing every attention pattern to be validated against the true signal:
- AttentionExtractor class using MultiHeadAttention and Softmax monkey-patching to capture weights without modifying model code
- VSN (Variable Selection Network) feature importance for static, dynamic, and future inputs
- Cross-attention heatmaps showing which encoder windows each decoder step attends to
- Hierarchical attention patterns across forecast horizon
- Multi-head diversity analysis (cosine similarity matrix, per-head entropy)
- Gradient saliency maps (static, dynamic temporal, future features)
- Horizon-dependent attention profiles
- Contrastive analysis: peak-demand vs. off-peak samples
- Integrated gradients (IG) for non-saturating attribution
- Radar-chart summary comparing saliency methods per feature
10 — Benchmarking (examples/10_benchmarking.ipynb)

Systematic comparison of 7 BaseAttentive architecture variants against Naive / Linear / MLP baselines across six benchmarking axes:
- Architecture variants: BA-Cross, BA-Hier, BA-Cross+Hier, BA-Memory, BA-Transformer, BA-Small, BA-Large
- Accuracy: RMSE, MAE, R², directional accuracy
- Efficiency frontier: parameter count × training time × RMSE Pareto plot
- Hyperparameter sensitivity: embed_dim sweep (8–64) and dropout_rate sweep (0.0–0.3) with train/test overfitting-gap overlay
- Noise robustness: performance degradation across 4 SNR levels
- Per-horizon accuracy profile: RMSE and relative improvement vs. Naive per forecast step
- Statistical significance: bootstrap 95% confidence intervals and pairwise CI-overlap heatmap
- Full leaderboard table + radar chart + architecture selection guide

Documentation Updates

Notebook index updated (docs/notebooks/index.rst) with entries for notebooks 08–10 and a new “Before you run” admonition block explaining the mandatory backend / import ordering for all notebooks and scripts:
```
# Correct order — always follow this pattern
import os
os.environ["BASE_ATTENTIVE_BACKEND"] = "tensorflow"
os.environ["KERAS_BACKEND"]          = "tensorflow"
import keras
import base_attentive
from base_attentive import BaseAttentive
```
The admonition also includes specific guidance for Binder users (run the first cell before any other cell) and local users (restart kernel before changing the backend).

Creation Scripts

scripts/create_nb08.py — creation script for notebook 08
scripts/create_nb09.py — creation script for notebook 09
scripts/create_nb10.py — creation script for notebook 10

All three scripts are reproducible: running them regenerates the notebook JSON from scratch, enabling easy updates and CI-based re-execution.