temporalcv 1.0.0__py3-none-any.whl

temporalcv/__init__.py

@@ -0,0 +1,473 @@
+"""
+temporalcv: Temporal cross-validation with leakage protection for time-series ML.
+
+This package 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 series handling (MC-SS, move thresholds)
+- Regime classification (volatility, direction)
+- Conformal prediction intervals with coverage guarantees
+- Time-series-aware bagging with bootstrap strategies
+
+Example
+-------
+>>> from temporalcv import run_gates, WalkForwardCV
+>>> from temporalcv.gates import gate_signal_verification
+>>>
+>>> # Signal verification: does model have predictive power?
+>>> result = gate_signal_verification(model=my_model, X=X, y=y, random_state=42)
+>>> if result.status.name == "HALT":
+...     # Model has signal - could be legitimate or leakage
+...     print("Model has signal - investigate source")
+>>>
+>>> # Aggregate multiple gates
+>>> report = run_gates([result])
+>>> if report.status == "HALT":
+...     print(f"Investigation needed: {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}")
+
+>>> # Conformal prediction intervals
+>>> from temporalcv import SplitConformalPredictor
+>>> conformal = SplitConformalPredictor(alpha=0.05)
+>>> conformal.calibrate(cal_preds, cal_actuals)
+>>> intervals = conformal.predict_interval(test_preds)
+>>> print(f"Coverage: {intervals.coverage(test_actuals):.1%}")
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+# Gates module exports
+from temporalcv.gates import (
+    GateStatus,
+    GateResult,
+    ValidationReport,
+    StratifiedValidationReport,
+    gate_signal_verification,
+    gate_synthetic_ar1,
+    gate_suspicious_improvement,
+    gate_temporal_boundary,
+    gate_residual_diagnostics,
+    gate_theoretical_bounds,
+    run_gates,
+    run_gates_stratified,
+)
+
+# Statistical tests exports
+from temporalcv.statistical_tests import (
+    DMTestResult,
+    PTTestResult,
+    GWTestResult,
+    CWTestResult,
+    MultiModelComparisonResult,
+    MultiHorizonResult,
+    MultiModelHorizonResult,
+    EncompassingTestResult,
+    BidirectionalEncompassingResult,
+    RealityCheckResult,
+    SPATestResult,
+    dm_test,
+    pt_test,
+    gw_test,
+    cw_test,
+    compare_multiple_models,
+    compare_horizons,
+    compare_models_horizons,
+    forecast_encompassing_test,
+    forecast_encompassing_bidirectional,
+    reality_check_test,
+    spa_test,
+    compute_hac_variance,
+)
+
+# Cross-validation exports
+from temporalcv.cv import (
+    SplitInfo,
+    SplitResult,
+    WalkForwardResults,
+    NestedCVResult,
+    WalkForwardCV,
+    CrossFitCV,
+    NestedWalkForwardCV,
+    walk_forward_evaluate,
+)
+
+# Regime classification exports
+from temporalcv.regimes import (
+    classify_volatility_regime,
+    classify_direction_regime,
+    get_combined_regimes,
+    get_regime_counts,
+    mask_low_n_regimes,
+    StratifiedMetricsResult,
+    compute_stratified_metrics,
+)
+
+# High-persistence metrics exports
+from temporalcv.persistence import (
+    MoveDirection,
+    MoveConditionalResult,
+    compute_move_threshold,
+    classify_moves,
+    compute_move_conditional_metrics,
+    compute_direction_accuracy,
+    compute_move_only_mae,
+    compute_persistence_mae,
+)
+
+# Core metrics exports
+from temporalcv.metrics import (
+    compute_mae,
+    compute_mse,
+    compute_rmse,
+    compute_mape,
+    compute_smape,
+    compute_bias,
+    compute_naive_error,
+    compute_mase,
+    compute_mrae,
+    compute_theils_u,
+    compute_forecast_correlation,
+    compute_r_squared,
+)
+
+# Quantile/interval metrics exports
+from temporalcv.metrics import (
+    compute_pinball_loss,
+    compute_crps,
+    compute_interval_score,
+    compute_quantile_coverage,
+    compute_winkler_score,
+)
+
+# Financial/trading metrics exports
+from temporalcv.metrics import (
+    compute_sharpe_ratio,
+    compute_max_drawdown,
+    compute_cumulative_return,
+    compute_information_ratio,
+    compute_hit_rate,
+    compute_profit_factor,
+    compute_calmar_ratio,
+)
+
+# Asymmetric loss exports
+from temporalcv.metrics import (
+    compute_linex_loss,
+    compute_asymmetric_mape,
+    compute_directional_loss,
+    compute_squared_log_error,
+    compute_huber_loss,
+)
+
+# Volatility-weighted metrics exports
+from temporalcv.metrics import (
+    VolatilityEstimator,
+    RollingVolatility,
+    EWMAVolatility,
+    compute_local_volatility,
+    compute_volatility_normalized_mae,
+    compute_volatility_weighted_mae,
+    VolatilityStratifiedResult,
+    compute_volatility_stratified_metrics,
+)
+
+# Conformal prediction exports
+from temporalcv.conformal import (
+    PredictionInterval,
+    SplitConformalPredictor,
+    AdaptiveConformalPredictor,
+    BellmanConformalPredictor,
+    BootstrapUncertainty,
+    evaluate_interval_quality,
+    walk_forward_conformal,
+    CoverageDiagnostics,
+    compute_coverage_diagnostics,
+)
+
+# Bagging exports
+from temporalcv.bagging import (
+    BootstrapStrategy,
+    TimeSeriesBagger,
+    MovingBlockBootstrap,
+    StationaryBootstrap,
+    FeatureBagging,
+    ResidualBootstrap,
+    create_block_bagger,
+    create_stationary_bagger,
+    create_feature_bagger,
+    create_residual_bagger,
+)
+
+# Diagnostics exports
+from temporalcv.diagnostics import (
+    InfluenceDiagnostic,
+    compute_dm_influence,
+    GapSensitivityResult,
+    gap_sensitivity_analysis,
+)
+
+# Inference exports
+from temporalcv.inference import (
+    WildBootstrapResult,
+    wild_cluster_bootstrap,
+)
+
+# Validators exports (theoretical bounds)
+from temporalcv.validators import (
+    theoretical_ar1_mse_bound,
+    theoretical_ar1_mae_bound,
+    theoretical_ar2_mse_bound,
+    check_against_ar1_bounds,
+    generate_ar1_series,
+    generate_ar2_series,
+)
+
+# Guardrails exports (unified validation)
+from temporalcv.guardrails import (
+    GuardrailResult,
+    check_suspicious_improvement,
+    check_minimum_sample_size,
+    check_stratified_sample_size,
+    check_forecast_horizon_consistency,
+    check_residual_autocorrelation,
+    run_all_guardrails,
+)
+
+# Stationarity tests exports
+from temporalcv.stationarity import (
+    StationarityTestResult,
+    StationarityConclusion,
+    JointStationarityResult,
+    adf_test,
+    kpss_test,
+    pp_test,
+    check_stationarity,
+    difference_until_stationary,
+)
+
+# Lag selection exports
+from temporalcv.lag_selection import (
+    LagSelectionResult,
+    select_lag_pacf,
+    select_lag_aic,
+    select_lag_bic,
+    auto_select_lag,
+    suggest_cv_gap,
+)
+
+# Changepoint detection exports
+from temporalcv.changepoint import (
+    Changepoint,
+    ChangepointResult,
+    detect_changepoints,
+    detect_changepoints_variance,
+    detect_changepoints_pelt,
+    classify_regimes_from_changepoints,
+    create_regime_indicators,
+    get_segment_boundaries,
+)
+
+# Financial CV exports
+from temporalcv.cv_financial import (
+    PurgedSplit,
+    PurgedKFold,
+    CombinatorialPurgedCV,
+    PurgedWalkForward,
+    compute_label_overlap,
+    estimate_purge_gap,
+)
+
+__all__ = [
+    "__version__",
+    # Gates
+    "GateStatus",
+    "GateResult",
+    "ValidationReport",
+    "StratifiedValidationReport",
+    "gate_signal_verification",
+    "gate_synthetic_ar1",
+    "gate_suspicious_improvement",
+    "gate_temporal_boundary",
+    "gate_residual_diagnostics",
+    "gate_theoretical_bounds",
+    "run_gates",
+    "run_gates_stratified",
+    # Statistical tests
+    "DMTestResult",
+    "PTTestResult",
+    "GWTestResult",
+    "CWTestResult",
+    "EncompassingTestResult",
+    "BidirectionalEncompassingResult",
+    "RealityCheckResult",
+    "SPATestResult",
+    "MultiHorizonResult",
+    "MultiModelHorizonResult",
+    "MultiModelComparisonResult",
+    "dm_test",
+    "pt_test",
+    "gw_test",
+    "cw_test",
+    "compare_multiple_models",
+    "compare_horizons",
+    "compare_models_horizons",
+    "forecast_encompassing_test",
+    "forecast_encompassing_bidirectional",
+    "reality_check_test",
+    "spa_test",
+    "compute_hac_variance",
+    # Cross-validation
+    "SplitInfo",
+    "SplitResult",
+    "WalkForwardResults",
+    "NestedCVResult",
+    "WalkForwardCV",
+    "CrossFitCV",
+    "NestedWalkForwardCV",
+    "walk_forward_evaluate",
+    # Regime classification
+    "classify_volatility_regime",
+    "classify_direction_regime",
+    "get_combined_regimes",
+    "get_regime_counts",
+    "mask_low_n_regimes",
+    "StratifiedMetricsResult",
+    "compute_stratified_metrics",
+    # High-persistence metrics
+    "MoveDirection",
+    "MoveConditionalResult",
+    "compute_move_threshold",
+    "classify_moves",
+    "compute_move_conditional_metrics",
+    "compute_direction_accuracy",
+    "compute_move_only_mae",
+    "compute_persistence_mae",
+    # Core metrics
+    "compute_mae",
+    "compute_mse",
+    "compute_rmse",
+    "compute_mape",
+    "compute_smape",
+    "compute_bias",
+    "compute_naive_error",
+    "compute_mase",
+    "compute_mrae",
+    "compute_theils_u",
+    "compute_forecast_correlation",
+    "compute_r_squared",
+    # Quantile/interval metrics
+    "compute_pinball_loss",
+    "compute_crps",
+    "compute_interval_score",
+    "compute_quantile_coverage",
+    "compute_winkler_score",
+    # Financial/trading metrics
+    "compute_sharpe_ratio",
+    "compute_max_drawdown",
+    "compute_cumulative_return",
+    "compute_information_ratio",
+    "compute_hit_rate",
+    "compute_profit_factor",
+    "compute_calmar_ratio",
+    # Asymmetric loss functions
+    "compute_linex_loss",
+    "compute_asymmetric_mape",
+    "compute_directional_loss",
+    "compute_squared_log_error",
+    "compute_huber_loss",
+    # Volatility-weighted metrics
+    "VolatilityEstimator",
+    "RollingVolatility",
+    "EWMAVolatility",
+    "compute_local_volatility",
+    "compute_volatility_normalized_mae",
+    "compute_volatility_weighted_mae",
+    "VolatilityStratifiedResult",
+    "compute_volatility_stratified_metrics",
+    # Conformal prediction
+    "PredictionInterval",
+    "SplitConformalPredictor",
+    "AdaptiveConformalPredictor",
+    "BellmanConformalPredictor",
+    "BootstrapUncertainty",
+    "evaluate_interval_quality",
+    "walk_forward_conformal",
+    "CoverageDiagnostics",
+    "compute_coverage_diagnostics",
+    # Bagging
+    "BootstrapStrategy",
+    "TimeSeriesBagger",
+    "MovingBlockBootstrap",
+    "StationaryBootstrap",
+    "FeatureBagging",
+    "ResidualBootstrap",
+    "create_block_bagger",
+    "create_stationary_bagger",
+    "create_feature_bagger",
+    "create_residual_bagger",
+    # Diagnostics
+    "InfluenceDiagnostic",
+    "compute_dm_influence",
+    "GapSensitivityResult",
+    "gap_sensitivity_analysis",
+    # Inference
+    "WildBootstrapResult",
+    "wild_cluster_bootstrap",
+    # Validators (theoretical bounds)
+    "theoretical_ar1_mse_bound",
+    "theoretical_ar1_mae_bound",
+    "theoretical_ar2_mse_bound",
+    "check_against_ar1_bounds",
+    "generate_ar1_series",
+    "generate_ar2_series",
+    # Guardrails (unified validation)
+    "GuardrailResult",
+    "check_suspicious_improvement",
+    "check_minimum_sample_size",
+    "check_stratified_sample_size",
+    "check_forecast_horizon_consistency",
+    "check_residual_autocorrelation",
+    "run_all_guardrails",
+    # Stationarity tests
+    "StationarityTestResult",
+    "StationarityConclusion",
+    "JointStationarityResult",
+    "adf_test",
+    "kpss_test",
+    "pp_test",
+    "check_stationarity",
+    "difference_until_stationary",
+    # Lag selection
+    "LagSelectionResult",
+    "select_lag_pacf",
+    "select_lag_aic",
+    "select_lag_bic",
+    "auto_select_lag",
+    "suggest_cv_gap",
+    # Changepoint detection
+    "Changepoint",
+    "ChangepointResult",
+    "detect_changepoints",
+    "detect_changepoints_variance",
+    "detect_changepoints_pelt",
+    "classify_regimes_from_changepoints",
+    "create_regime_indicators",
+    "get_segment_boundaries",
+    # Financial CV
+    "PurgedSplit",
+    "PurgedKFold",
+    "CombinatorialPurgedCV",
+    "PurgedWalkForward",
+    "compute_label_overlap",
+    "estimate_purge_gap",
+]

temporalcv/bagging/__init__.py

@@ -0,0 +1,215 @@
+"""
+Time Series Bagging Framework.
+
+Generic, model-agnostic bagging for time series with methodologically
+correct bootstrap strategies from the literature.
+
+Available Strategies
+--------------------
+- MovingBlockBootstrap: Block bootstrap preserving local autocorrelation
+- StationaryBootstrap: Geometric block lengths for stationarity
+- FeatureBagging: Random subspace method (feature bootstrap)
+
+Factory Functions
+-----------------
+- create_block_bagger: Create bagger with Moving Block Bootstrap
+- create_stationary_bagger: Create bagger with Stationary Bootstrap
+- create_feature_bagger: Create bagger with Feature Bagging
+
+Example
+-------
+>>> from sklearn.linear_model import Ridge
+>>> from temporalcv.bagging import create_block_bagger
+>>>
+>>> # Create bagged Ridge model
+>>> bagged_ridge = create_block_bagger(Ridge(), n_estimators=20)
+>>> bagged_ridge.fit(X_train, y_train)
+>>> predictions = bagged_ridge.predict(X_test)
+>>> mean, lower, upper = bagged_ridge.predict_interval(X_test)
+
+References
+----------
+- Kunsch (1989). "The Jackknife and Bootstrap for General Stationary"
+- Politis & Romano (1994). "The Stationary Bootstrap"
+- Ho (1998). "The Random Subspace Method"
+- Bergmeir, Hyndman & Benitez (2016). "Bagging Exponential Smoothing"
+"""
+
+from typing import Optional
+
+from temporalcv.bagging.base import (
+    SupportsPredict,
+    BootstrapStrategy,
+    TimeSeriesBagger,
+)
+from temporalcv.bagging.strategies import (
+    MovingBlockBootstrap,
+    StationaryBootstrap,
+    FeatureBagging,
+    ResidualBootstrap,
+    create_residual_bagger,
+)
+
+
+def create_block_bagger(
+    base_model: SupportsPredict,
+    n_estimators: int = 20,
+    block_length: Optional[int] = None,
+    aggregation: str = "mean",
+    random_state: Optional[int] = None,
+) -> TimeSeriesBagger:
+    """
+    Create bagged model with Moving Block Bootstrap.
+
+    Parameters
+    ----------
+    base_model : SupportsPredict
+        Model to bag (e.g., Ridge, ElasticNet)
+    n_estimators : int, default=20
+        Number of bootstrap estimators
+    block_length : int or None, default=None
+        Block length. If None, auto-compute as n^(1/3)
+    aggregation : {"mean", "median"}, default="mean"
+        How to combine predictions
+    random_state : int or None, default=None
+        Random seed for reproducibility. None for non-deterministic.
+
+    Returns
+    -------
+    TimeSeriesBagger
+        Bagged model ready for fit/predict
+
+    Examples
+    --------
+    >>> from sklearn.linear_model import Ridge
+    >>> bagger = create_block_bagger(Ridge(), n_estimators=50)
+    >>> bagger.fit(X_train, y_train)
+
+    See Also
+    --------
+    create_stationary_bagger : Alternative with geometric block lengths.
+    create_feature_bagger : Feature subspace method instead of row bootstrap.
+    MovingBlockBootstrap : The underlying bootstrap strategy.
+    """
+    strategy = MovingBlockBootstrap(block_length=block_length)
+    return TimeSeriesBagger(
+        base_model,
+        strategy,
+        n_estimators=n_estimators,
+        aggregation=aggregation,  # type: ignore[arg-type]
+        random_state=random_state,
+    )
+
+
+def create_stationary_bagger(
+    base_model: SupportsPredict,
+    n_estimators: int = 20,
+    expected_block_length: Optional[float] = None,
+    aggregation: str = "mean",
+    random_state: Optional[int] = None,
+) -> TimeSeriesBagger:
+    """
+    Create bagged model with Stationary Bootstrap.
+
+    Parameters
+    ----------
+    base_model : SupportsPredict
+        Model to bag (e.g., Ridge, ElasticNet)
+    n_estimators : int, default=20
+        Number of bootstrap estimators
+    expected_block_length : float or None, default=None
+        Expected block length. If None, auto-compute as n^(1/3)
+    aggregation : {"mean", "median"}, default="mean"
+        How to combine predictions
+    random_state : int or None, default=None
+        Random seed for reproducibility. None for non-deterministic.
+
+    Returns
+    -------
+    TimeSeriesBagger
+        Bagged model ready for fit/predict
+
+    Examples
+    --------
+    >>> from sklearn.linear_model import ElasticNet
+    >>> bagger = create_stationary_bagger(ElasticNet(), n_estimators=50)
+
+    See Also
+    --------
+    create_block_bagger : Fixed block lengths (simpler).
+    StationaryBootstrap : The underlying bootstrap strategy.
+    """
+    strategy = StationaryBootstrap(expected_block_length=expected_block_length)
+    return TimeSeriesBagger(
+        base_model,
+        strategy,
+        n_estimators=n_estimators,
+        aggregation=aggregation,  # type: ignore[arg-type]
+        random_state=random_state,
+    )
+
+
+def create_feature_bagger(
+    base_model: SupportsPredict,
+    n_estimators: int = 20,
+    max_features: float = 0.7,
+    aggregation: str = "mean",
+    random_state: Optional[int] = None,
+) -> TimeSeriesBagger:
+    """
+    Create bagged model with Feature Bagging (Random Subspace).
+
+    Parameters
+    ----------
+    base_model : SupportsPredict
+        Model to bag (e.g., Ridge, ElasticNet)
+    n_estimators : int, default=20
+        Number of bootstrap estimators
+    max_features : float, default=0.7
+        Fraction of features per estimator (0.0-1.0)
+    aggregation : {"mean", "median"}, default="mean"
+        How to combine predictions
+    random_state : int or None, default=None
+        Random seed for reproducibility. None for non-deterministic.
+
+    Returns
+    -------
+    TimeSeriesBagger
+        Bagged model ready for fit/predict
+
+    Examples
+    --------
+    >>> from sklearn.linear_model import Ridge
+    >>> bagger = create_feature_bagger(Ridge(), max_features=0.6)
+
+    See Also
+    --------
+    create_block_bagger : Bootstrap rows instead of features.
+    FeatureBagging : The underlying bootstrap strategy.
+    """
+    strategy = FeatureBagging(max_features=max_features)
+    return TimeSeriesBagger(
+        base_model,
+        strategy,
+        n_estimators=n_estimators,
+        aggregation=aggregation,  # type: ignore[arg-type]
+        random_state=random_state,
+    )
+
+
+__all__ = [
+    # Core classes
+    "SupportsPredict",
+    "BootstrapStrategy",
+    "TimeSeriesBagger",
+    # Strategies
+    "MovingBlockBootstrap",
+    "StationaryBootstrap",
+    "FeatureBagging",
+    "ResidualBootstrap",
+    # Factory functions
+    "create_block_bagger",
+    "create_stationary_bagger",
+    "create_feature_bagger",
+    "create_residual_bagger",
+]