temporalcv Documentation

Temporal cross-validation with leakage protection for time-series ML.

temporalcv provides rigorous validation tools for time-series forecasting, including:

  • Validation gates for detecting data leakage

  • Walk-forward cross-validation with gap enforcement

  • Statistical tests (Diebold-Mariano, Pesaran-Timmermann)

  • High-persistence handling (MC-SS, move thresholds)

  • Regime classification (volatility, direction)

  • Conformal prediction intervals with coverage guarantees

  • Time-series-aware bagging with bootstrap strategies

Quick Example

from temporalcv import run_gates, WalkForwardCV
from temporalcv.gates import gate_signal_verification

# Run signal verification gate
# Note: n_shuffles>=100 required for statistical power in permutation mode
gate_result = gate_signal_verification(my_model, X, y, n_shuffles=100)
report = run_gates([gate_result])
if report.status == "HALT":
    raise ValueError(f"Signal detected — investigate: {report.failures}")

# Move-conditional metrics for high-persistence series
from temporalcv import compute_move_threshold, compute_move_conditional_metrics
threshold = compute_move_threshold(train_actuals)  # From training only!
mc = compute_move_conditional_metrics(predictions, actuals, threshold=threshold)
print(f"MC-SS: {mc.skill_score:.3f}")

Installation

pip install temporalcv

# With all optional dependencies
pip install temporalcv[all]

Getting Started

Examples Gallery

Tutorials

API Guides

Reference

Model Cards

Benchmarks

Help

Indices and tables