Walk Forward Validation

#!/usr/bin/env python3
"""Overfit detection: Deflated Sharpe Ratio and Probability of Backtest Overfitting.

Computes the Deflated Sharpe Ratio (DSR) to assess whether an observed Sharpe
ratio is statistically significant after accounting for multiple testing,
non-normality, and backtest length. Also computes the Probability of Backtest
Overfitting (PBO) using combinatorial purged cross-validation.

Usage:
    python scripts/overfit_detector.py --demo
    python scripts/overfit_detector.py --help

Dependencies:
    uv pip install numpy scipy

Environment Variables:
    None required (--demo mode uses synthetic data).
"""

from __future__ import annotations

import argparse
import dataclasses
import sys
from itertools import combinations
from typing import Optional

import numpy as np
from scipy.stats import norm


# ── Data Classes ────────────────────────────────────────────────────

@dataclasses.dataclass
class DSRResult:
    """Results from Deflated Sharpe Ratio analysis.

    Attributes:
        observed_sr: The observed annualized Sharpe ratio.
        expected_max_sr: Expected maximum SR under the null.
        sr_std_error: Standard error of the SR estimator.
        dsr_pvalue: Probability that observed SR > 0 after deflation.
        num_trials: Number of strategies tested.
        backtest_length: Number of return observations.
        skewness: Return skewness.
        kurtosis: Return kurtosis (not excess).
        is_significant: Whether DSR > 0.95.
    """

    observed_sr: float
    expected_max_sr: float
    sr_std_error: float
    dsr_pvalue: float
    num_trials: int
    backtest_length: int
    skewness: float
    kurtosis: float
    is_significant: bool


@dataclasses.dataclass
class PBOResult:
    """Results from Probability of Backtest Overfitting analysis.

    Attributes:
        pbo: Probability of backtest overfitting.
        n_paths: Number of CPCV paths evaluated.
        n_overfit_paths: Number of paths where IS-best underperforms OOS median.
        logit_values: Logit-transformed relative ranks for each path.
        mean_oos_rank: Mean relative OOS rank of IS-optimal strategy.
        is_overfit: Whether PBO > 0.50.
    """

    pbo: float
    n_paths: int
    n_overfit_paths: int
    logit_values: list[float]
    mean_oos_rank: float
    is_overfit: bool


@dataclasses.dataclass
class MinBTLResult:
    """Minimum Backtest Length result.

    Attributes:
        min_length: Minimum number of observations needed.
        target_sr: Target Sharpe ratio (non-annualized).
        confidence: Confidence level used.
        skewness: Assumed skewness.
        kurtosis: Assumed kurtosis.
    """

    min_length: int
    target_sr: float
    confidence: float
    skewness: float
    kurtosis: float


# ── Deflated Sharpe Ratio ───────────────────────────────────────────

def deflated_sharpe_ratio(
    observed_sr: float,
    num_trials: int,
    backtest_length: int,
    skewness: float = 0.0,
    kurtosis: float = 3.0,
    annualization: float = 1.0,
) -> DSRResult:
    """Compute the Deflated Sharpe Ratio.

    Adjusts the observed Sharpe ratio for multiple testing, non-normality,
    and backtest length. Returns the probability that the observed SR is
    genuinely greater than zero.

    Args:
        observed_sr: Annualized Sharpe ratio of the selected strategy.
        num_trials: Total number of strategies tested (including discarded).
        backtest_length: Number of return observations.
        skewness: Skewness of strategy returns.
        kurtosis: Kurtosis of strategy returns (not excess; normal = 3.0).
        annualization: Annualization factor (e.g., sqrt(365) for daily crypto).
            The observed_sr is de-annualized internally.

    Returns:
        DSRResult with all computed values.
    """
    if num_trials < 1:
        raise ValueError("num_trials must be >= 1")
    if backtest_length < 10:
        raise ValueError("backtest_length must be >= 10")

    # De-annualize the SR for the formula
    sr = observed_sr / annualization if annualization > 1.0 else observed_sr

    # Standard error of the Sharpe ratio estimator
    sr_std = np.sqrt(
        (1.0 - skewness * sr + (kurtosis - 1.0) / 4.0 * sr**2)
        / (backtest_length - 1)
    )

    # Expected maximum SR under null (all strategies have zero true SR)
    euler_mascheroni = 0.5772156649
    if num_trials == 1:
        expected_max_sr = 0.0
    else:
        z1 = norm.ppf(1.0 - 1.0 / num_trials)
        z2 = norm.ppf(1.0 - 1.0 / (num_trials * np.e))
        expected_max_sr = z1 * (1.0 - euler_mascheroni) + euler_mascheroni * z2

    # Deflated SR p-value
    if sr_std > 0:
        dsr = float(norm.cdf((sr - expected_max_sr) / sr_std))
    else:
        dsr = 1.0 if sr > expected_max_sr else 0.0

    return DSRResult(
        observed_sr=observed_sr,
        expected_max_sr=expected_max_sr * annualization,
        sr_std_error=sr_std * annualization,
        dsr_pvalue=dsr,
        num_trials=num_trials,
        backtest_length=backtest_length,
        skewness=skewness,
        kurtosis=kurtosis,
        is_significant=dsr > 0.95,
    )


# ── Probability of Backtest Overfitting ─────────────────────────────

def probability_of_backtest_overfitting(
    strategy_returns: np.ndarray,
    n_groups: int = 6,
    n_test_groups: int = 2,
) -> PBOResult:
    """Compute Probability of Backtest Overfitting using CPCV.

    Splits the data into groups, generates all C(N,k) train/test combinations,
    and measures how often the in-sample optimal strategy underperforms
    out-of-sample.

    Args:
        strategy_returns: 2D array of shape (n_observations, n_strategies).
            Each column is a strategy's return time series.
        n_groups: Number of contiguous groups to split data into.
        n_test_groups: Number of groups to use as test in each combination.

    Returns:
        PBOResult with PBO estimate and diagnostics.
    """
    n_obs, n_strategies = strategy_returns.shape
    if n_strategies < 2:
        raise ValueError("Need at least 2 strategies for PBO")
    if n_groups < 3:
        raise ValueError("Need at least 3 groups for meaningful CPCV")

    group_size = n_obs // n_groups
    if group_size < 5:
        raise ValueError(
            f"Each group has only {group_size} observations. "
            f"Reduce n_groups or provide more data."
        )

    # Create group boundaries
    group_bounds: list[tuple[int, int]] = []
    for i in range(n_groups):
        start = i * group_size
        end = (i + 1) * group_size if i < n_groups - 1 else n_obs
        group_bounds.append((start, end))

    logit_values: list[float] = []
    n_overfit = 0

    for test_combo in combinations(range(n_groups), n_test_groups):
        test_set = set(test_combo)

        # Build train and test index arrays
        train_indices: list[int] = []
        test_indices: list[int] = []

        for g_idx in range(n_groups):
            start, end = group_bounds[g_idx]
            indices = list(range(start, end))
            if g_idx in test_set:
                test_indices.extend(indices)
            else:
                train_indices.extend(indices)

        if not train_indices or not test_indices:
            continue

        train_arr = np.array(train_indices)
        test_arr = np.array(test_indices)

        # Compute in-sample performance (mean return) for each strategy
        is_performance = np.mean(strategy_returns[train_arr], axis=0)

        # Select IS-best strategy
        is_best_idx = int(np.argmax(is_performance))

        # Compute out-of-sample performance for all strategies
        oos_performance = np.mean(strategy_returns[test_arr], axis=0)

        # Rank the IS-best strategy in OOS performance
        oos_rank = int(np.sum(oos_performance > oos_performance[is_best_idx]))
        relative_rank = (oos_rank + 1) / n_strategies  # 1-based, normalized

        # Logit transform (clamp to avoid log(0))
        clamped = np.clip(relative_rank, 0.01, 0.99)
        logit = float(np.log(clamped / (1.0 - clamped)))
        logit_values.append(logit)

        if relative_rank > 0.5:
            n_overfit += 1

    n_paths = len(logit_values)
    pbo = n_overfit / n_paths if n_paths > 0 else 1.0
    mean_rank = float(np.mean([
        (1.0 / (1.0 + np.exp(-lv))) for lv in logit_values
    ])) if logit_values else 1.0

    return PBOResult(
        pbo=pbo,
        n_paths=n_paths,
        n_overfit_paths=n_overfit,
        logit_values=logit_values,
        mean_oos_rank=mean_rank,
        is_overfit=pbo > 0.50,
    )


# ── Minimum Backtest Length ─────────────────────────────────────────

def minimum_backtest_length(
    target_sr: float,
    confidence: float = 0.95,
    skewness: float = 0.0,
    kurtosis: float = 3.0,
) -> MinBTLResult:
    """Compute minimum backtest length for a target Sharpe ratio.

    Args:
        target_sr: Target non-annualized Sharpe ratio.
        confidence: Desired confidence level (e.g., 0.95).
        skewness: Assumed skewness of returns.
        kurtosis: Assumed kurtosis (normal = 3.0).

    Returns:
        MinBTLResult with the minimum number of observations.
    """
    if target_sr <= 0:
        raise ValueError("target_sr must be > 0")

    z_alpha = norm.ppf(confidence)
    variance_factor = 1.0 - skewness * target_sr + (kurtosis - 1.0) / 4.0 * target_sr**2
    min_length = int(np.ceil(1.0 + variance_factor * (z_alpha / target_sr) ** 2))

    return MinBTLResult(
        min_length=min_length,
        target_sr=target_sr,
        confidence=confidence,
        skewness=skewness,
        kurtosis=kurtosis,
    )


# ── Multiple Testing Corrections ───────────────────────────────────

def bonferroni_correction(p_values: list[float], alpha: float = 0.05) -> list[bool]:
    """Apply Bonferroni correction to a list of p-values.

    Args:
        p_values: List of p-values from individual strategy tests.
        alpha: Family-wise significance level.

    Returns:
        List of booleans (True = reject null = strategy is significant).
    """
    n = len(p_values)
    adjusted_alpha = alpha / n
    return [p < adjusted_alpha for p in p_values]


def holm_correction(p_values: list[float], alpha: float = 0.05) -> list[bool]:
    """Apply Holm-Bonferroni step-down correction.

    Args:
        p_values: List of p-values.
        alpha: Family-wise significance level.

    Returns:
        List of booleans (True = reject null).
    """
    n = len(p_values)
    sorted_indices = np.argsort(p_values)
    results = [False] * n

    for rank, idx in enumerate(sorted_indices):
        threshold = alpha / (n - rank)
        if p_values[idx] <= threshold:
            results[idx] = True
        else:
            break  # Stop at first non-rejection

    return results


# ── Demo ────────────────────────────────────────────────────────────

def generate_synthetic_strategies(
    n_obs: int = 500,
    n_strategies: int = 20,
    n_genuine: int = 2,
    seed: int = 42,
) -> tuple[np.ndarray, list[str]]:
    """Generate synthetic strategy return streams.

    Creates a mix of strategies with zero true alpha (noise) and a few
    with small genuine alpha, to test overfitting detection.

    Args:
        n_obs: Number of daily observations per strategy.
        n_strategies: Total number of strategies.
        n_genuine: Number of strategies with genuine (small) alpha.
        seed: Random seed.

    Returns:
        Tuple of (returns array [n_obs x n_strategies], strategy names).
    """
    rng = np.random.default_rng(seed)
    daily_vol = 0.03  # ~57% annualized

    returns = np.empty((n_obs, n_strategies))
    names: list[str] = []

    for i in range(n_strategies):
        if i < n_genuine:
            # Genuine alpha: small positive drift
            drift = 0.0003  # ~11% annualized
            returns[:, i] = rng.normal(drift, daily_vol, n_obs)
            names.append(f"alpha_{i+1}")
        else:
            # Zero alpha: pure noise
            returns[:, i] = rng.normal(0.0, daily_vol, n_obs)
            names.append(f"noise_{i-n_genuine+1}")

    return returns, names


def run_demo() -> None:
    """Run the overfit detection demo."""
    print("=" * 72)
    print("Overfit Detection Demo")
    print("=" * 72)
    print()

    # Generate synthetic strategies
    n_strategies = 20
    n_genuine = 2
    n_obs = 500
    returns, names = generate_synthetic_strategies(
        n_obs=n_obs,
        n_strategies=n_strategies,
        n_genuine=n_genuine,
        seed=42,
    )

    print(f"Generated {n_strategies} strategies ({n_genuine} with genuine alpha, "
          f"{n_strategies - n_genuine} noise)")
    print(f"Each strategy has {n_obs} daily return observations")
    print()

    # ── Part 1: Compute Sharpe ratios ──────────────────────────────
    print("-" * 72)
    print("Part 1: Raw Sharpe Ratios (Annualized)")
    print("-" * 72)
    annualization = np.sqrt(365)
    sharpes = []
    for i in range(n_strategies):
        sr = float(np.mean(returns[:, i]) / np.std(returns[:, i]) * annualization)
        sharpes.append(sr)

    # Sort by SR for display
    sorted_idx = np.argsort(sharpes)[::-1]
    print(f"\n{'Rank':>4} {'Strategy':>12} {'Sharpe':>10} {'Type':>8}")
    print("-" * 40)
    for rank, idx in enumerate(sorted_idx[:10]):
        stype = "ALPHA" if idx < n_genuine else "noise"
        print(f"{rank+1:>4} {names[idx]:>12} {sharpes[idx]:>10.3f} {stype:>8}")
    print("  ...")
    print()

    best_idx = int(sorted_idx[0])
    best_sr = sharpes[best_idx]
    best_name = names[best_idx]

    print(f"Best strategy: {best_name} with SR = {best_sr:.3f}")
    print(f"Is it genuine alpha? {'Yes' if best_idx < n_genuine else 'No — it is noise!'}")
    print()

    # ── Part 2: Deflated Sharpe Ratio ──────────────────────────────
    print("-" * 72)
    print("Part 2: Deflated Sharpe Ratio")
    print("-" * 72)

    best_returns = returns[:, best_idx]
    skew = float(np.mean(((best_returns - np.mean(best_returns)) / np.std(best_returns)) ** 3))
    kurt = float(np.mean(((best_returns - np.mean(best_returns)) / np.std(best_returns)) ** 4))

    dsr_result = deflated_sharpe_ratio(
        observed_sr=best_sr,
        num_trials=n_strategies,
        backtest_length=n_obs,
        skewness=skew,
        kurtosis=kurt,
        annualization=annualization,
    )

    print(f"\n  Observed SR:           {dsr_result.observed_sr:.3f}")
    print(f"  Expected Max SR:       {dsr_result.expected_max_sr:.3f}")
    print(f"  SR Std Error:          {dsr_result.sr_std_error:.3f}")
    print(f"  Strategies tested:     {dsr_result.num_trials}")
    print(f"  Backtest length:       {dsr_result.backtest_length} obs")
    print(f"  Return skewness:       {dsr_result.skewness:.3f}")
    print(f"  Return kurtosis:       {dsr_result.kurtosis:.3f}")
    print(f"  DSR p-value:           {dsr_result.dsr_pvalue:.4f}")
    print(f"  Significant (>0.95)?   {'Yes' if dsr_result.is_significant else 'No'}")
    print()

    if not dsr_result.is_significant:
        print("  The DSR says: this Sharpe ratio is not significant after adjusting")
        print("  for the number of strategies tested. Likely overfitted.")
    else:
        print("  The DSR says: this Sharpe ratio remains significant even after")
        print("  adjusting for multiple testing.")
    print()

    # ── Part 3: Probability of Backtest Overfitting ────────────────
    print("-" * 72)
    print("Part 3: Probability of Backtest Overfitting (PBO)")
    print("-" * 72)

    pbo_result = probability_of_backtest_overfitting(
        strategy_returns=returns,
        n_groups=6,
        n_test_groups=2,
    )

    print(f"\n  CPCV paths evaluated:  {pbo_result.n_paths}")
    print(f"  Overfit paths:         {pbo_result.n_overfit_paths}")
    print(f"  PBO:                   {pbo_result.pbo:.3f}")
    print(f"  Mean OOS rank:         {pbo_result.mean_oos_rank:.3f}")
    print(f"  Is overfit (>0.50)?    {'Yes' if pbo_result.is_overfit else 'No'}")
    print()

    if pbo_result.pbo > 0.50:
        print("  PBO > 0.50: Strategy selection process is more likely than not")
        print("  to produce overfitted results.")
    elif pbo_result.pbo > 0.30:
        print("  PBO 0.30-0.50: Elevated overfitting risk. Use additional")
        print("  out-of-sample validation before deploying.")
    else:
        print("  PBO < 0.30: Low overfitting risk. Strategy selection process")
        print("  appears to have genuine predictive power.")
    print()

    # ── Part 4: Minimum Backtest Length ────────────────────────────
    print("-" * 72)
    print("Part 4: Minimum Backtest Length")
    print("-" * 72)

    for sr_target, label in [(0.05, "Low SR (daily ~0.05, ann ~0.96)"),
                              (0.10, "Med SR (daily ~0.10, ann ~1.91)"),
                              (0.20, "High SR (daily ~0.20, ann ~3.82)")]:
        result = minimum_backtest_length(
            target_sr=sr_target, confidence=0.95, skewness=skew, kurtosis=kurt
        )
        years = result.min_length / 365
        print(f"  {label}: {result.min_length} obs ({years:.1f} years)")

    print()

    # ── Part 5: Multiple Testing Correction ────────────────────────
    print("-" * 72)
    print("Part 5: Multiple Testing Correction")
    print("-" * 72)

    # Compute p-values for each strategy (one-sided test: SR > 0)
    p_values: list[float] = []
    for i in range(n_strategies):
        sr_i = np.mean(returns[:, i]) / np.std(returns[:, i])
        se_i = 1.0 / np.sqrt(n_obs)
        p = 1.0 - float(norm.cdf(sr_i / se_i))
        p_values.append(p)

    bonf = bonferroni_correction(p_values, alpha=0.05)
    holm_results = holm_correction(p_values, alpha=0.05)

    print(f"\n{'Strategy':>12} {'p-value':>10} {'Bonferroni':>12} {'Holm':>8} {'Type':>8}")
    print("-" * 56)
    for i in sorted_idx[:10]:
        stype = "ALPHA" if i < n_genuine else "noise"
        print(
            f"{names[i]:>12} {p_values[i]:>10.4f} "
            f"{'Sig' if bonf[i] else '---':>12} "
            f"{'Sig' if holm_results[i] else '---':>8} "
            f"{stype:>8}"
        )

    n_bonf_sig = sum(bonf)
    n_holm_sig = sum(holm_results)
    print(f"\n  Bonferroni significant: {n_bonf_sig}/{n_strategies}")
    print(f"  Holm significant:       {n_holm_sig}/{n_strategies}")
    print()

    # ── Summary ────────────────────────────────────────────────────
    print("=" * 72)
    print("Summary")
    print("=" * 72)
    print(f"  Best raw Sharpe:    {best_sr:.3f} ({best_name})")
    print(f"  DSR p-value:        {dsr_result.dsr_pvalue:.4f} ({'significant' if dsr_result.is_significant else 'NOT significant'})")
    print(f"  PBO:                {pbo_result.pbo:.3f} ({'overfit' if pbo_result.is_overfit else 'acceptable'})")
    print(f"  Bonferroni pass:    {n_bonf_sig} strategies")
    print(f"  Holm pass:          {n_holm_sig} strategies")
    print()
    print("  Key takeaway: Always adjust for multiple testing. A Sharpe of")
    print(f"  {best_sr:.2f} looks great in isolation, but after testing {n_strategies} strategies,")
    print(f"  the DSR reduces it to a p-value of {dsr_result.dsr_pvalue:.3f}.")
    print()


# ── Main ────────────────────────────────────────────────────────────

def main() -> None:
    """Entry point for overfit detection."""
    parser = argparse.ArgumentParser(
        description="Overfit detection: Deflated Sharpe Ratio and PBO."
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run demo with synthetic backtest results.",
    )
    args = parser.parse_args()

    if not args.demo:
        print("Run with --demo to see overfit detection on synthetic strategies.")
        print("Example: python scripts/overfit_detector.py --demo")
        print()
        print("Or use the functions programmatically:")
        print("  from overfit_detector import deflated_sharpe_ratio, probability_of_backtest_overfitting")
        sys.exit(0)

    run_demo()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Walk-forward validation engine with rolling and expanding windows.

Provides a configurable walk-forward splitter that respects time series ordering,
supports purging and embargo, and produces per-fold metrics. Includes a --demo
mode that generates synthetic price data and runs a simple moving-average
crossover strategy through the validator.

Usage:
    python scripts/walk_forward.py --demo
    python scripts/walk_forward.py --help

Dependencies:
    uv pip install numpy pandas

Environment Variables:
    None required (--demo mode uses synthetic data).
"""

from __future__ import annotations

import argparse
import dataclasses
import sys
from typing import Iterator, Literal, Optional

import numpy as np
import pandas as pd


# ── Configuration ───────────────────────────────────────────────────

@dataclasses.dataclass
class WalkForwardConfig:
    """Configuration for walk-forward validation.

    Attributes:
        train_size: Number of bars in the training window.
        test_size: Number of bars in the test window.
        step_size: Number of bars to advance between folds.
        window_type: 'rolling' (fixed train) or 'expanding' (growing train).
        purge_size: Number of bars to purge from end of training set
            to avoid label leakage.
        embargo_size: Number of bars to skip between train and test
            to avoid autocorrelation leakage.
    """

    train_size: int = 90
    test_size: int = 14
    step_size: int = 14
    window_type: Literal["rolling", "expanding"] = "rolling"
    purge_size: int = 0
    embargo_size: int = 0


@dataclasses.dataclass
class Fold:
    """A single train/test fold.

    Attributes:
        fold_idx: Zero-based fold index.
        train_indices: Array indices for the training set.
        test_indices: Array indices for the test set.
        train_start: Datetime of first training bar (if available).
        train_end: Datetime of last training bar (if available).
        test_start: Datetime of first test bar (if available).
        test_end: Datetime of last test bar (if available).
    """

    fold_idx: int
    train_indices: np.ndarray
    test_indices: np.ndarray
    train_start: Optional[str] = None
    train_end: Optional[str] = None
    test_start: Optional[str] = None
    test_end: Optional[str] = None


@dataclasses.dataclass
class FoldResult:
    """Performance metrics for a single fold."""

    fold_idx: int
    train_sharpe: float
    test_sharpe: float
    train_return: float
    test_return: float
    test_max_drawdown: float
    test_hit_rate: float
    n_train: int
    n_test: int


# ── Walk-Forward Splitter ───────────────────────────────────────────

class WalkForwardValidator:
    """Walk-forward validation splitter with purging and embargo."""

    def __init__(self, config: WalkForwardConfig) -> None:
        self.config = config
        self._validate_config()

    def _validate_config(self) -> None:
        """Validate configuration parameters."""
        if self.config.train_size < 10:
            raise ValueError("train_size must be >= 10")
        if self.config.test_size < 1:
            raise ValueError("test_size must be >= 1")
        if self.config.step_size < 1:
            raise ValueError("step_size must be >= 1")
        if self.config.purge_size < 0:
            raise ValueError("purge_size must be >= 0")
        if self.config.embargo_size < 0:
            raise ValueError("embargo_size must be >= 0")
        if self.config.window_type not in ("rolling", "expanding"):
            raise ValueError("window_type must be 'rolling' or 'expanding'")

    def split(
        self,
        n_samples: int,
        dates: Optional[pd.DatetimeIndex] = None,
    ) -> Iterator[Fold]:
        """Generate walk-forward train/test splits.

        Args:
            n_samples: Total number of observations.
            dates: Optional datetime index for labelling folds.

        Yields:
            Fold objects with train and test indices.
        """
        cfg = self.config
        min_required = cfg.train_size + cfg.purge_size + cfg.embargo_size + cfg.test_size
        if n_samples < min_required:
            raise ValueError(
                f"Need at least {min_required} samples, got {n_samples}"
            )

        fold_idx = 0
        offset = 0

        while True:
            if cfg.window_type == "rolling":
                train_start = offset
                train_end = offset + cfg.train_size
            else:  # expanding
                train_start = 0
                train_end = cfg.train_size + offset

            # Apply purge: remove purge_size bars from end of training
            effective_train_end = train_end - cfg.purge_size

            # Apply embargo: skip embargo_size bars after effective train end
            test_start = train_end + cfg.embargo_size
            test_end = test_start + cfg.test_size

            if test_end > n_samples:
                break

            train_indices = np.arange(train_start, effective_train_end)
            test_indices = np.arange(test_start, test_end)

            fold = Fold(
                fold_idx=fold_idx,
                train_indices=train_indices,
                test_indices=test_indices,
            )

            if dates is not None:
                fold.train_start = str(dates[train_start])
                fold.train_end = str(dates[effective_train_end - 1])
                fold.test_start = str(dates[test_start])
                fold.test_end = str(dates[test_end - 1])

            yield fold
            fold_idx += 1
            offset += cfg.step_size

    def count_folds(self, n_samples: int) -> int:
        """Return the number of folds without generating them."""
        return sum(1 for _ in self.split(n_samples))


# ── Metrics ─────────────────────────────────────────────────────────

def compute_sharpe(returns: np.ndarray, annualization: float = 365.0) -> float:
    """Compute annualized Sharpe ratio from a returns array.

    Args:
        returns: Array of periodic returns.
        annualization: Periods per year (365 for daily crypto).

    Returns:
        Annualized Sharpe ratio, or 0.0 if std is zero.
    """
    if len(returns) < 2 or np.std(returns) == 0:
        return 0.0
    return float(np.mean(returns) / np.std(returns) * np.sqrt(annualization))


def compute_max_drawdown(returns: np.ndarray) -> float:
    """Compute maximum drawdown from a returns array.

    Args:
        returns: Array of periodic returns.

    Returns:
        Maximum drawdown as a negative float (e.g., -0.15 = -15%).
    """
    cumulative = np.cumprod(1.0 + returns)
    running_max = np.maximum.accumulate(cumulative)
    drawdowns = cumulative / running_max - 1.0
    return float(np.min(drawdowns))


def compute_hit_rate(predictions: np.ndarray, actuals: np.ndarray) -> float:
    """Compute directional hit rate.

    Args:
        predictions: Predicted direction signals (positive = long).
        actuals: Actual returns.

    Returns:
        Fraction of correct directional predictions.
    """
    if len(predictions) == 0:
        return 0.0
    correct = np.sign(predictions) == np.sign(actuals)
    return float(np.mean(correct))


# ── Demo Strategy ───────────────────────────────────────────────────

def generate_synthetic_prices(
    n_bars: int = 500,
    seed: int = 42,
    base_price: float = 100.0,
    annual_return: float = 0.10,
    annual_vol: float = 0.80,
) -> pd.DataFrame:
    """Generate synthetic daily price data with realistic crypto volatility.

    Args:
        n_bars: Number of daily bars to generate.
        seed: Random seed for reproducibility.
        base_price: Starting price.
        annual_return: Annualized drift.
        annual_vol: Annualized volatility.

    Returns:
        DataFrame with 'date', 'close', and 'returns' columns.
    """
    rng = np.random.default_rng(seed)
    daily_return = annual_return / 365
    daily_vol = annual_vol / np.sqrt(365)

    # Add regime switching for realism
    regime_length = n_bars // 4
    returns = np.empty(n_bars)
    for i in range(4):
        start = i * regime_length
        end = (i + 1) * regime_length if i < 3 else n_bars
        regime_vol = daily_vol * rng.uniform(0.5, 2.0)
        regime_drift = daily_return * rng.uniform(-2.0, 3.0)
        segment = rng.normal(regime_drift, regime_vol, end - start)
        returns[start:end] = segment

    prices = base_price * np.cumprod(1.0 + returns)
    dates = pd.date_range("2024-01-01", periods=n_bars, freq="D")

    return pd.DataFrame({
        "date": dates,
        "close": prices,
        "returns": returns,
    })


def sma_crossover_signals(
    prices: np.ndarray,
    fast_period: int = 10,
    slow_period: int = 30,
) -> np.ndarray:
    """Generate signals from SMA crossover: +1 (long) or -1 (flat/short).

    Args:
        prices: Array of closing prices.
        fast_period: Fast SMA lookback.
        slow_period: Slow SMA lookback.

    Returns:
        Array of signals (+1 or -1), NaN for warmup period.
    """
    signals = np.full(len(prices), np.nan)
    for i in range(slow_period, len(prices)):
        fast_sma = np.mean(prices[i - fast_period : i])
        slow_sma = np.mean(prices[i - slow_period : i])
        signals[i] = 1.0 if fast_sma > slow_sma else -1.0
    return signals


def run_walk_forward(
    config: WalkForwardConfig,
    df: pd.DataFrame,
    fast_period: int = 10,
    slow_period: int = 30,
) -> list[FoldResult]:
    """Run walk-forward validation on a SMA crossover strategy.

    Args:
        config: Walk-forward configuration.
        df: DataFrame with 'close' and 'returns' columns.
        fast_period: Fast SMA period.
        slow_period: Slow SMA period.

    Returns:
        List of FoldResult for each fold.
    """
    validator = WalkForwardValidator(config)
    prices = df["close"].values
    returns = df["returns"].values
    dates = pd.DatetimeIndex(df["date"])
    results: list[FoldResult] = []

    for fold in validator.split(len(prices), dates):
        # Train: compute signals on training data
        train_prices = prices[fold.train_indices]
        train_returns = returns[fold.train_indices]
        train_signals = sma_crossover_signals(train_prices, fast_period, slow_period)

        # Only use valid (non-NaN) signals
        valid_train = ~np.isnan(train_signals)
        train_strat_returns = train_signals[valid_train] * train_returns[valid_train]

        # Test: compute signals and returns on test data
        # We need lookback prices before test period for SMA computation
        lookback_start = max(0, fold.test_indices[0] - slow_period)
        extended_prices = prices[lookback_start : fold.test_indices[-1] + 1]
        extended_signals = sma_crossover_signals(extended_prices, fast_period, slow_period)

        # Extract only the test portion of signals
        test_offset = fold.test_indices[0] - lookback_start
        test_signals = extended_signals[test_offset:]
        test_returns = returns[fold.test_indices]

        valid_test = ~np.isnan(test_signals)
        if not np.any(valid_test):
            continue

        test_strat_returns = test_signals[valid_test] * test_returns[valid_test]

        result = FoldResult(
            fold_idx=fold.fold_idx,
            train_sharpe=compute_sharpe(train_strat_returns),
            test_sharpe=compute_sharpe(test_strat_returns),
            train_return=float(np.sum(train_strat_returns)),
            test_return=float(np.sum(test_strat_returns)),
            test_max_drawdown=compute_max_drawdown(test_strat_returns),
            test_hit_rate=compute_hit_rate(test_signals[valid_test], test_returns[valid_test]),
            n_train=int(np.sum(valid_train)),
            n_test=int(np.sum(valid_test)),
        )
        results.append(result)

    return results


# ── Display ─────────────────────────────────────────────────────────

def print_results(results: list[FoldResult], config: WalkForwardConfig) -> None:
    """Print walk-forward validation results.

    Args:
        results: List of per-fold results.
        config: The walk-forward configuration used.
    """
    print("=" * 72)
    print("Walk-Forward Validation Report")
    print("=" * 72)
    print(f"  Window type:      {config.window_type}")
    print(f"  Train size:       {config.train_size} bars")
    print(f"  Test size:        {config.test_size} bars")
    print(f"  Step size:        {config.step_size} bars")
    print(f"  Purge:            {config.purge_size} bars")
    print(f"  Embargo:          {config.embargo_size} bars")
    print(f"  Folds:            {len(results)}")
    print()

    # Per-fold table
    print(f"{'Fold':>4} {'Train SR':>10} {'Test SR':>10} {'Test Ret':>10} "
          f"{'Test MDD':>10} {'Hit Rate':>10}")
    print("-" * 60)
    for r in results:
        print(
            f"{r.fold_idx:>4} "
            f"{r.train_sharpe:>10.2f} "
            f"{r.test_sharpe:>10.2f} "
            f"{r.test_return:>9.2%} "
            f"{r.test_max_drawdown:>9.2%} "
            f"{r.test_hit_rate:>9.1%}"
        )

    # Aggregate
    print()
    train_sharpes = [r.train_sharpe for r in results]
    test_sharpes = [r.test_sharpe for r in results]
    test_returns = [r.test_return for r in results]

    mean_train_sr = np.mean(train_sharpes)
    mean_test_sr = np.mean(test_sharpes)
    std_test_sr = np.std(test_sharpes)
    sr_ratio = mean_train_sr / mean_test_sr if mean_test_sr != 0 else float("inf")

    print("Aggregate Metrics:")
    print(f"  Mean Train Sharpe:   {mean_train_sr:.3f}")
    print(f"  Mean Test Sharpe:    {mean_test_sr:.3f}")
    print(f"  Test Sharpe StdDev:  {std_test_sr:.3f}")
    print(f"  Train/Test SR Ratio: {sr_ratio:.2f}")
    print(f"  Mean Test Return:    {np.mean(test_returns):.2%}")
    print(f"  Total Test Return:   {np.sum(test_returns):.2%}")
    print()

    # Overfit warning
    if sr_ratio > 2.0:
        print("  WARNING: Train/Test SR ratio > 2.0 suggests overfitting.")
    elif sr_ratio > 1.5:
        print("  CAUTION: Train/Test SR ratio > 1.5, moderate overfit risk.")
    else:
        print("  Train/Test SR ratio looks reasonable.")

    print()


# ── Main ────────────────────────────────────────────────────────────

def main() -> None:
    """Entry point for walk-forward validation."""
    parser = argparse.ArgumentParser(
        description="Walk-forward validation engine for trading strategies."
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run demo with synthetic price data and SMA crossover strategy.",
    )
    parser.add_argument("--train-size", type=int, default=90, help="Training window size (bars).")
    parser.add_argument("--test-size", type=int, default=14, help="Test window size (bars).")
    parser.add_argument("--step-size", type=int, default=14, help="Step size between folds (bars).")
    parser.add_argument(
        "--window-type",
        choices=["rolling", "expanding"],
        default="rolling",
        help="Window type: rolling or expanding.",
    )
    parser.add_argument("--purge", type=int, default=1, help="Purge size (bars).")
    parser.add_argument("--embargo", type=int, default=3, help="Embargo size (bars).")
    parser.add_argument("--n-bars", type=int, default=500, help="Number of synthetic bars (demo).")
    parser.add_argument("--seed", type=int, default=42, help="Random seed (demo).")

    args = parser.parse_args()

    if not args.demo:
        print("Run with --demo to see walk-forward validation on synthetic data.")
        print("Example: python scripts/walk_forward.py --demo")
        print()
        print("Or use WalkForwardValidator programmatically:")
        print("  from walk_forward import WalkForwardValidator, WalkForwardConfig")
        sys.exit(0)

    print("Generating synthetic price data...")
    df = generate_synthetic_prices(n_bars=args.n_bars, seed=args.seed)
    print(f"  {len(df)} daily bars from {df['date'].iloc[0].date()} to {df['date'].iloc[-1].date()}")
    print(f"  Price range: {df['close'].min():.2f} – {df['close'].max():.2f}")
    print()

    # Run with rolling window
    config_rolling = WalkForwardConfig(
        train_size=args.train_size,
        test_size=args.test_size,
        step_size=args.step_size,
        window_type="rolling",
        purge_size=args.purge,
        embargo_size=args.embargo,
    )

    print("Running rolling-window walk-forward validation...")
    print()
    results_rolling = run_walk_forward(config_rolling, df)
    print_results(results_rolling, config_rolling)

    # Run with expanding window
    config_expanding = WalkForwardConfig(
        train_size=args.train_size,
        test_size=args.test_size,
        step_size=args.step_size,
        window_type="expanding",
        purge_size=args.purge,
        embargo_size=args.embargo,
    )

    print("Running expanding-window walk-forward validation...")
    print()
    results_expanding = run_walk_forward(config_expanding, df)
    print_results(results_expanding, config_expanding)

    # Compare
    print("=" * 72)
    print("Comparison: Rolling vs Expanding")
    print("=" * 72)
    rolling_sr = np.mean([r.test_sharpe for r in results_rolling])
    expanding_sr = np.mean([r.test_sharpe for r in results_expanding])
    print(f"  Rolling  Mean OOS Sharpe: {rolling_sr:.3f}")
    print(f"  Expanding Mean OOS Sharpe: {expanding_sr:.3f}")
    print()
    if abs(rolling_sr - expanding_sr) < 0.3:
        print("  Results are consistent across window types — good sign.")
    else:
        print("  Divergence between window types — investigate regime sensitivity.")
    print()


if __name__ == "__main__":
    main()