Tutorials

Step-by-step guides for common temporalcv workflows.

---

New to Time-Series ML?

If you know sklearn but don’t understand why time-series is different, start here:

Foundational Reading (~1 hour)

Resource	Time	What You’ll Learn
00_time_series_fundamentals.ipynb	30 min	Why autocorrelation matters, ACF intuition, three types of leakage
Feature Engineering Safety Guide	15 min	Safe vs dangerous features, decision tree
Metric Selection Guide	15 min	Which metric for which problem

Quick Start Path (~4 hours)

After the foundational reading, complete these notebooks:

Step	Notebook	Concept
1	01_why_temporal_cv	KFold leakage, WalkForwardCV, diagnose your data
2	05_shuffled_target_gate	Definitive leakage detection
3	08_validation_workflow	Complete HALT/WARN/PASS pipeline
4	10_high_persistence_metrics	MASE, MC-SS, move-conditional metrics

Troubleshooting: Diagnostic Flowchart — What to do when validation fails

---

Already Know Time-Series?

If you understand ACF, stationarity, and temporal dependence, skip Tier 0:

Step	Notebook	Concept
1	01_why_temporal_cv	WalkForwardCV, temporalcv gates
2	05_shuffled_target_gate	Definitive leakage detection
3	08_validation_workflow	Complete HALT/WARN/PASS pipeline

See the notebooks README for the complete 14-hour curriculum.

---

Tutorial Documents

Quick-reference markdown tutorials for specific topics:

• Examples Index
• Failure Cases Guide
• Guardrails: The HALT/WARN/PASS Framework
• Lag Selection Guide
• Multi-Horizon Forecasting Tutorial
• Feature Engineering Safety Guide
• Metric Selection Guide
• Validation Diagnostic Flowchart
• Tutorial: Leakage Detection with Validation Gates
• Tutorial: Walk-Forward Cross-Validation
• Tutorial: High-Persistence Time Series
• Tutorial: Uncertainty Quantification

By Topic

Examples & Case Studies:

• Examples Index — All 21 examples with descriptions

• Failure Cases — Learn from common mistakes (Examples 16-20)

Workflow Guides:

• Guardrails — The HALT/WARN/PASS framework decision tree

• Lag Selection — Choosing feature lags and forecast horizons

• Multi-Horizon — Finding your model’s predictability limit

Newcomer Guides:

• Feature Engineering Safety — Safe vs dangerous features

• Metric Selection — Which metric for which problem

• Diagnostic Flowchart — Troubleshooting validation failures

Core Topics:

• Leakage Detection — Detect and prevent data leakage with validation gates

• Walk-Forward CV — Time-series cross-validation with gap enforcement

• High Persistence — Handle high-persistence series with MC-SS metrics

• Uncertainty Quantification — Conformal prediction and bootstrap intervals

---

Interactive Notebooks vs. Markdown Tutorials

Format	Best For	Location
Jupyter Notebooks	Learning, experimentation, running examples	notebooks/
Markdown Tutorials	Quick reference, searching, documentation	docs/tutorials/

Both formats cover similar content. Start with notebooks for learning, use tutorials for quick lookups.

---

Tier 1: Foundation Notebooks (Available)

These notebooks teach why time-series validation is fundamentally different from standard ML:

Notebook	Key Concept	Interactive Link
01_why_temporal_cv	KFold leakage, WalkForwardCV, persistence baseline	Open
02_gap_enforcement	h-step forecasting, gap >= horizon rule	Open
03_persistence_baseline	MASE, why persistence is hard to beat	Open
04_autocorrelation_matters	HAC variance, MA(h-1) error structure	Open

Tier 2: Prevention Notebooks (Available)

These notebooks teach how to detect and prevent common leakage patterns:

Notebook	Key Concept	Interactive Link
05_shuffled_target_gate	Permutation testing for leakage detection	Open
06_feature_engineering_pitfalls	Safe rolling stats, feature selection	Open
07_threshold_leakage	Regime/percentile computation without lookahead	Open
08_validation_workflow	Complete HALT/WARN/PASS pipeline	Open

Tier 3: Evaluation Notebooks (Available)

These notebooks teach how to properly evaluate high-persistence data and compare models:

Notebook	Key Concept	Interactive Link
09_statistical_tests_dm_pt	DM test, PT test, HAC variance	Open
10_high_persistence_metrics	MC-SS, move-conditional, Theil’s U	Open
11_conformal_prediction	Split/Adaptive conformal, intervals	Open
12_regime_stratified_evaluation	Volatility regimes, stratified gates (capstone)	Open