quantex 0.5.0__tar.gz → 0.5.2__tar.gz

{quantex-0.5.0 → quantex-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: quantex
-Version: 0.5.0
+Version: 0.5.2
 Summary: A simple quant strategy creation and backtesting package.
 License: MIT
 Author: Daniel Green
@@ -12,6 +12,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: fastparquet (>=2024.11.0,<2025.0.0)
+Requires-Dist: matplotlib (>=3.10.8,<4.0.0)
+Requires-Dist: mplfinance (>=0.12.10b0,<0.13.0)
 Requires-Dist: numpy (>=2.4.3,<3.0.0)
 Requires-Dist: optuna (>=4.8.0,<5.0.0)
 Requires-Dist: pandas (>=2.3.0,<3.0.0)

{quantex-0.5.0 → quantex-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantex"
-version = "0.5.0"
+version = "0.5.2"
 description = "A simple quant strategy creation and backtesting package."
 authors = [
     {name = "Daniel Green",email = "dangreen07@outlook.com"}
@@ -15,6 +15,8 @@ dependencies = [
     "tqdm (>=4.67.1,<5.0.0)",
     "numpy (>=2.4.3,<3.0.0)",
     "optuna (>=4.8.0,<5.0.0)",
+    "matplotlib (>=3.10.8,<4.0.0)",
+    "mplfinance (>=0.12.10b0,<0.13.0)",
 ]
 
 [tool.poetry]

{quantex-0.5.0 → quantex-0.5.2}/src/quantex/backtester/backtester.py

@@ -8,6 +8,8 @@ import numpy as np
 import pandas as pd
 from tqdm import tqdm
 
+from ..backtester.walk_forward import WalkForwardResult
+
 from ..broker import Order
 from ..strategy import Strategy
 
@@ -153,7 +155,7 @@ class SimpleBacktester:
             broker.margin_call = self.margin_call
             broker.leverage = self.leverage
             broker.commision = np.float64(self.commission)
-            broker.commision_type = self.commission_type
+            broker.commision_type = self.commission_type  # type: ignore[assignment]
 
         self.strategy.init()
 
@@ -182,7 +184,8 @@ class SimpleBacktester:
             tradeRecord.extend(trades)
             orders.extend(val.complete_orders)
 
-        index = list(self.strategy.positions.values())[0].source.data['Close'].index
+        source = list(self.strategy.positions.values())[0].source
+        index = source.data['Close'].index
         return BacktestReport(
             starting_cash=np.float64(self.cash),
             final_cash=self.PnLRecord[-1],
@@ -193,7 +196,8 @@ class SimpleBacktester:
                 event
                 for broker in self.strategy.positions.values()
                 for event in getattr(broker, "margin_call_events", [])
-            ] or None)
+            ] or None,
+            data=source.data.copy())
     
     def optimize(
         self,
@@ -1536,3 +1540,171 @@ class SimpleBacktester:
             seed=seed,
             progress_bar=progress_bar,
         )
+
+    def walk_forward_analyze(
+        self,
+        params: dict[str, Any],
+        train_periods: int,
+        test_periods: int,
+        step_periods: int | None = None,
+        constraint: Callable[[dict[str, Any]], bool] | None = None,
+        objective: str = "sharpe",
+        risk_tolerance: dict[str, float] | None = None,
+        min_train_periods: int = 30,
+        min_test_periods: int = 10,
+        progress_bar: bool = True,
+        **optimizer_kwargs: Any,
+    ) -> "WalkForwardResult":
+        """
+        Perform walk-forward analysis on the strategy.
+        
+        Walk-forward analysis is a rigorous method for evaluating trading strategies
+        that simulates real-world deployment conditions. It uses rolling windows to:
+        1. Train: Optimize parameters on historical data
+        2. Test: Evaluate best parameters on unseen future data
+        
+        This method provides a convenient way to run walk-forward analysis directly
+        on the backtester instance without needing to create a separate WalkForwardAnalyzer.
+        
+        Args:
+            params (dict[str, range]): Dictionary mapping strategy attribute names
+                to iterables of candidate values. For example:
+                ```python
+                {
+                    'fast_period': [5, 10, 15, 20],
+                    'slow_period': [20, 30, 40, 50],
+                    'threshold': [0.01, 0.02, 0.05]
+                }
+                ```
+            train_periods (int): Number of periods for each training window.
+                This is the lookback window used for parameter optimization.
+            test_periods (int): Number of periods for each test window.
+                This is the forward-looking window for out-of-sample evaluation.
+            step_periods (int | None, optional): Number of periods to step forward
+                between windows. If None, uses test_periods (non-overlapping windows).
+                Defaults to None.
+            constraint (Callable[[dict[str, Any]], bool] | None, optional): Optional
+                callable that takes a parameter dict and returns True to evaluate
+                or False to skip. Useful for enforcing logical constraints.
+                Defaults to None.
+            objective (str, optional): Metric to optimize. Defaults to "sharpe".
+                Supports: "final_cash", "total_return", "sharpe", "max_drawdown", "trades".
+            risk_tolerance (dict[str, float] | None, optional): Optional maximum
+                allowed values for risk metrics. Defaults to None.
+            min_train_periods (int, optional): Minimum required training periods.
+                Defaults to 30.
+            min_test_periods (int, optional): Minimum required test periods.
+                Defaults to 10.
+            progress_bar (bool, optional): Whether to show progress bar.
+                Defaults to True.
+            **optimizer_kwargs: Additional keyword arguments passed to the
+                optimizer. Can include:
+                - workers (int): For parallel optimization
+                - n_trials (int): For Optuna optimization
+                - timeout (int): For Optuna timeout
+                - random_seed (int): For reproducibility
+                
+        Returns:
+            WalkForwardResult: Object containing:
+                - n_windows: Total number of walk-forward windows
+                - train_periods: Periods in each training window
+                - test_periods: Periods in each test window
+                - window_results: List of WalkForwardWindow objects
+                - aggregated_metrics: Aggregated statistics across windows
+                - all_windows_results_df: DataFrame with all results
+                - plot(): Visualization method for results
+                
+        Example:
+            >>> # Run walk-forward analysis with grid search
+            >>> result = bt.walk_forward_analyze(
+            ...     params={'fast': [5, 10, 20], 'slow': [20, 50, 100]},
+            ...     train_periods=252,  # 1 year training
+            ...     test_periods=63,   # 3 months testing
+            ...     objective='sharpe'
+            ... )
+            >>> print(result)
+            >>> print(f"Average OOS Sharpe: {result.aggregated_metrics['out_of_sample_sharpe_mean']:.2f}")
+            >>> result.plot()
+            
+            >>> # Run with parallel optimization
+            >>> result = bt.walk_forward_analyze(
+            ...     params={'period': range(5, 50, 5)},
+            ...     train_periods=252,
+            ...     test_periods=63,
+            ...     workers=4  # Use parallel optimization
+            ... )
+            
+            >>> # Run with Optuna optimization
+            >>> result = bt.walk_forward_analyze(
+            ...     params={'period': (5, 50)},
+            ...     train_periods=252,
+            ...     test_periods=63,
+            ...     n_trials=100  # Optuna-specific
+            ... )
+        
+        Note:
+            - Walk-forward analysis helps detect overfitting by evaluating parameter
+              stability and out-of-sample performance over multiple time windows
+            - A stability ratio (OOS/IS Sharpe) close to 1.0 indicates robust parameters
+            - Use step_periods < test_periods for overlapping windows with more samples
+        """
+        from .walk_forward import (
+            WalkForwardAnalyzer,
+            WalkForwardResult,
+        )
+        
+        # Handle step_periods - use test_periods if None
+        actual_step = test_periods if step_periods is None else step_periods
+        
+        # Determine which optimizer to use based on kwargs
+        # If workers > 1, use optimize_parallel; if n_trials provided, use optimize_optuna
+        if "n_trials" in optimizer_kwargs:
+            # Use Optuna optimizer
+            optimizer = lambda bt, params, **kw: bt.optimize_optuna(
+                param_space=params,
+                n_trials=kw.get("n_trials", 100),
+                objective=kw.get("objective", objective),
+                risk_tolerance=kw.get("risk_tolerance", risk_tolerance),
+                constraint=kw.get("constraint", constraint),
+                timeout=kw.get("timeout", None),
+                random_seed=kw.get("random_seed", None),
+                workers=kw.get("workers", None),
+                progress_bar=kw.get("progress_bar", False),
+            )
+        elif optimizer_kwargs.get("workers", 1) > 1:
+            # Use parallel optimizer
+            optimizer = lambda bt, params, **kw: bt.optimize_parallel(
+                params=params,
+                constraint=kw.get("constraint", constraint),
+                objective=kw.get("objective", objective),
+                risk_tolerance=kw.get("risk_tolerance", risk_tolerance),
+                workers=kw.get("workers", None),
+                chunksize=kw.get("chunksize", "auto"),
+            )
+        else:
+            # Use sequential optimizer
+            optimizer = lambda bt, params, **kw: bt.optimize(
+                params=params,
+                constraint=kw.get("constraint", constraint),
+                objective=kw.get("objective", objective),
+                risk_tolerance=kw.get("risk_tolerance", risk_tolerance),
+            )
+        
+        # Create analyzer and run analysis
+        analyzer = WalkForwardAnalyzer(
+            backtester=self,
+            train_periods=train_periods,
+            test_periods=test_periods,
+            min_train_periods=min_train_periods,
+            min_test_periods=min_test_periods,
+            selection_criterion=objective,
+        )
+        
+        return analyzer.analyze(
+            optimizer=optimizer,
+            params=params,
+            constraint=constraint,
+            objective=objective,
+            risk_tolerance=risk_tolerance,
+            progress_bar=progress_bar,
+        )

{quantex-0.5.0 → quantex-0.5.2}/src/quantex/backtester/reports.py

@@ -1,10 +1,13 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
+import mplfinance as mpf
 import numpy as np
 import pandas as pd
 from matplotlib import pyplot as plt
 
+from ..broker.types import Order
+
 
 @dataclass
 class OptimizationResult:
@@ -50,14 +53,17 @@ class BacktestReport:
     final_cash (np.float64): Final cash amount at end of backtest.
     PnlRecord (pd.Series): Time series of P&L values throughout the backtest.
     orders (list[Order]): List of all orders executed during the backtest.
+    tradeRecord (list[np.float64]): List of individual trade P&L values.
     margin_call_events (list[dict]): Margin call events triggered during the run.
+    data (pd.DataFrame): OHLC price data used in the backtest.
     """
     starting_cash: np.float64
     final_cash: np.float64
     PnlRecord: pd.Series
-    orders: list
+    orders: list[Order]
     tradeRecord: list[np.float64]
     margin_call_events: list[dict] | None = None
+    data: pd.DataFrame = field(default_factory=lambda: pd.DataFrame())
 
     @property
     def annual_rf(self):
@@ -161,6 +167,128 @@ class BacktestReport:
         plt.tight_layout()
         plt.show()
 
+    def plot_trades(
+        self,
+        figsize: tuple = (16, 8),
+        style: str = "yahoo",
+        title: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        volume: bool = True,
+    ) -> None:
+        """
+        Plot the price chart with trade entry and exit markers.
+        
+        Creates a candlestick chart showing all trades with:
+        - Green triangles (^) for buy entries
+        - Red triangles (v) for sell exits
+        - Position is closed when an order in the opposite direction is executed
+        
+        Args:
+            figsize (tuple, optional): Figure size as (width, height) in inches.
+                Defaults to (16, 8).
+            style (str, optional): mplfinance style name. Defaults to "yahoo".
+            title (str, optional): Chart title. Defaults to None (uses default title).
+            start_date (str, optional): Start date filter (e.g., '2026-03-01').
+                Defaults to None (show all).
+            end_date (str, optional): End date filter (e.g., '2026-03-31').
+                Defaults to None (show all).
+            volume (bool, optional): Whether to show volume subplot. Defaults to True.
+            
+        Raises:
+            ValueError: If no OHLC data is available in the backtest report.
+            ValueError: If no orders are available.
+        """
+        from ..broker.types import OrderSide
+        
+        if self.data.empty:
+            raise ValueError(
+                "No OHLC data available in backtest report. "
+                "Ensure the backtest was run with data storage enabled."
+            )
+        
+        if not self.orders:
+            raise ValueError("No orders available in backtest report.")
+        
+        # Filter data by date range if specified
+        data = self.data.copy()
+        if start_date is not None:
+            data = data[data.index > start_date]
+        if end_date is not None:
+            data = data[data.index <= end_date]
+        
+        # Create marker series with the same index as the data
+        buy_signal = pd.Series(index=data.index, dtype=float)
+        sell_signal = pd.Series(index=data.index, dtype=float)
+        
+        for order in self.orders:
+            timestamp = order.timestamp
+            
+            # Only set signal if timestamp exists in the data index
+            if timestamp not in data.index:
+                continue
+            
+            # Set the signal at the order timestamp
+            if order.side == OrderSide.BUY:
+                buy_signal.loc[timestamp] = data.loc[timestamp, 'Close'] # type: ignore
+            else:  # OrderSide.SELL
+                sell_signal.loc[timestamp] = data.loc[timestamp, 'Close'] # type: ignore
+        
+        # If no trades to plot and no data, raise an error
+        if data.empty:
+            raise ValueError("No data available to plot. Check your date range.")
+        
+        # Check if there are actual trade markers (non-NaN values)
+        has_buy_signals = not buy_signal.dropna().empty
+        has_sell_signals = not sell_signal.dropna().empty
+        
+        # Build addplot list with markers (only if we have data points)
+        apds = []
+        if has_buy_signals:
+            apds.append(
+                mpf.make_addplot(
+                    buy_signal,
+                    type="scatter",
+                    marker="^",
+                    markersize=120,
+                    color="green",
+                )
+            )
+        if has_sell_signals:
+            apds.append(
+                mpf.make_addplot(
+                    sell_signal,
+                    type="scatter",
+                    marker="v",
+                    markersize=120,
+                    color="red",
+                )
+            )
+        
+        # If no trades found in the date range, warn the user
+        if not apds:
+            import warnings
+            warnings.warn(
+                "No trades found in the specified date range. "
+                "Plotting price data without trade markers."
+            )
+        
+        # Generate default title if not provided
+        if title is None:
+            total_trades = len(self.orders)
+            title = f"Price chart with trade entries/exits ({total_trades} orders)"
+        
+        mpf.plot(
+            data,
+            type="candle",
+            volume=volume,
+            addplot=apds,
+            figsize=figsize,
+            style=style,
+            title=title,
+            warn_too_much_data=len(data) + 5
+        )
+
     def __str__(self) -> str:
         """
         Generate a formatted string summary of backtest results.

{quantex-0.5.0 → quantex-0.5.2}/src/quantex/backtester/walk_forward.py

@@ -7,13 +7,18 @@ optimization uses rolling windows to test parameter stability over time.
 """
 
 from dataclasses import dataclass, field
-from typing import Any, Callable, Protocol
+from datetime import timedelta
+from typing import Any, Callable, Protocol, Union
 
 import numpy as np
 import pandas as pd
 from tqdm import tqdm
 
 
+# Type alias for period specification (int or timedelta)
+PeriodSpec = Union[int, timedelta, pd.Timedelta]
+
+
 @dataclass
 class WalkForwardWindow:
     """
@@ -27,6 +32,10 @@ class WalkForwardWindow:
         test_end (int): Ending index for test data.
         train_periods (int): Number of periods in training.
         test_periods (int): Number of periods in testing.
+        train_periods_spec (PeriodSpec): Original specification for train periods
+            (can be int or timedelta).
+        test_periods_spec (PeriodSpec): Original specification for test periods
+            (can be int or timedelta).
         best_params (dict): Best parameters found during training.
         train_metrics (dict): Metrics computed on training data.
         test_metrics (dict): Metrics computed on test (out-of-sample) data.
@@ -40,9 +49,11 @@ class WalkForwardWindow:
     test_end: int
     train_periods: int
     test_periods: int
-    best_params: dict
-    train_metrics: dict
-    test_metrics: dict
+    train_periods_spec: PeriodSpec | None = None
+    test_periods_spec: PeriodSpec | None = None
+    best_params: dict = field(default_factory=dict)
+    train_metrics: dict = field(default_factory=dict)
+    test_metrics: dict = field(default_factory=dict)
     train_report: Any = None
     test_report: Any = None
 
@@ -57,8 +68,12 @@ class WalkForwardResult:
     
     Attributes:
         n_windows (int): Total number of walk-forward windows.
-        train_periods (int): Number of periods in each training window.
-        test_periods (int): Number of periods in each test window.
+        train_periods (int): Number of periods in each training window (computed value).
+        test_periods (int): Number of periods in each test window (computed value).
+        train_periods_spec (PeriodSpec): Original specification for train periods
+            (can be int or timedelta).
+        test_periods_spec (PeriodSpec): Original specification for test periods
+            (can be int or timedelta).
         window_results (list[WalkForwardWindow]): Results for each window.
         aggregated_metrics (dict): Aggregated statistics across all windows.
         all_windows_results_df (pd.DataFrame): DataFrame with results from all windows.
@@ -66,6 +81,8 @@ class WalkForwardResult:
     n_windows: int
     train_periods: int
     test_periods: int
+    train_periods_spec: PeriodSpec | None = None
+    test_periods_spec: PeriodSpec | None = None
     window_results: list[WalkForwardWindow] = field(default_factory=list)
     aggregated_metrics: dict = field(default_factory=dict)
     all_windows_results_df: pd.DataFrame = field(default_factory=pd.DataFrame)
@@ -269,7 +286,6 @@ class OptimizerProtocol(Protocol):
     def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
 
 
-@dataclass
 class WalkForwardAnalyzer:
     """
     Analyzer for walk-forward optimization.
@@ -286,10 +302,14 @@ class WalkForwardAnalyzer:
     
     Attributes:
         backtester (SimpleBacktester): The backtester instance to use.
-        train_periods (int): Number of periods for each training window.
-        test_periods (int): Number of periods for each test window.
-        step_periods (int): Number of periods to step forward between windows.
-            If None, uses test_periods (non-overlapping windows).
+        train_periods (PeriodSpec): Number of periods or timedelta for each 
+            training window. Can be an int (number of periods) or a timedelta
+            (e.g., pd.Timedelta('252 days') or timedelta(days=365)).
+        test_periods (PeriodSpec): Number of periods or timedelta for each 
+            test window. Can be an int or timedelta.
+        step_periods (PeriodSpec): Number of periods or timedelta to step 
+            forward between windows. If None, uses test_periods 
+            (non-overlapping windows).
         min_train_periods (int): Minimum required training periods.
         min_test_periods (int): Minimum required test periods.
         selection_criterion (str): Metric to use for selecting best parameters.
@@ -297,13 +317,22 @@ class WalkForwardAnalyzer:
     Example:
         >>> from quantex.backtester.walk_forward import WalkForwardAnalyzer
         >>> from quantex import SimpleBacktester
+        >>> import pandas as pd
+        >>> 
+        >>> # Create analyzer with grid search optimizer (using periods)
+        >>> analyzer = WalkForwardAnalyzer(
+        ...     backtester=bt,
+        ...     train_periods=252,  # 1 year training (252 trading days)
+        ...     test_periods=63,    # 3 months testing
+        ...     step_periods=63     # Move forward 3 months each window
+        ... )
         >>> 
-        >>> # Create analyzer with grid search optimizer
+        >>> # Or using timedelta (data frequency is inferred from the data)
         >>> analyzer = WalkForwardAnalyzer(
         ...     backtester=bt,
-        ...     train_periods=252,  # 1 year training
-        ...     test_periods=63,   # 3 months testing
-        ...     step_periods=63    # Move forward 3 months each window
+        ...     train_periods=pd.Timedelta('252 days'),  # 1 year training
+        ...     test_periods=pd.Timedelta('90 days'),   # 3 months testing
+        ...     step_periods=pd.Timedelta('90 days')    # Move forward 3 months
         ... )
         >>> 
         >>> # Run with grid search
@@ -316,37 +345,28 @@ class WalkForwardAnalyzer:
         >>> print(result)
         >>> print(f"Average out-of-sample Sharpe: {result.aggregated_metrics['out_of_sample_sharpe_mean']:.2f}")
     """
-    backtester: Any
-    train_periods: int
-    test_periods: int
-    step_periods: int = 0  # Will be set to test_periods in __post_init__ if 0
-    min_train_periods: int = 30
-    min_test_periods: int = 10
-    selection_criterion: str = "sharpe"
-
-    def __post_init__(self):
-        """Validate and set default values."""
-        # Handle default step_periods
-        if self.step_periods <= 0:
-            self.step_periods = self.test_periods
-        
-        if self.train_periods < self.min_train_periods:
-            raise ValueError(
-                f"train_periods must be at least {self.min_train_periods}, "
-                f"got {self.train_periods}"
-            )
-        
-        if self.test_periods < self.min_test_periods:
-            raise ValueError(
-                f"test_periods must be at least {self.min_test_periods}, "
-                f"got {self.test_periods}"
-            )
-        
-        if self.step_periods <= 0:
-            raise ValueError("step_periods must be positive")
-        
-        # Get data length from the strategy's data source
-        positions = self.backtester.strategy.positions
+
+    def __init__(
+        self,
+        backtester: Any,
+        train_periods: PeriodSpec,
+        test_periods: PeriodSpec,
+        step_periods: PeriodSpec | None = None,
+        min_train_periods: int = 30,
+        min_test_periods: int = 10,
+        selection_criterion: str = "sharpe",
+    ):
+        """Initialize the WalkForwardAnalyzer."""
+        self.backtester = backtester
+        self._train_periods_spec = train_periods
+        self._test_periods_spec = test_periods
+        self._step_periods_spec = step_periods
+        self.min_train_periods = min_train_periods
+        self.min_test_periods = min_test_periods
+        self.selection_criterion = selection_criterion
+
+        # Get data source for frequency information
+        positions = backtester.strategy.positions
         if not positions:
             raise ValueError(
                 "Strategy must have at least one data source registered. "
@@ -354,32 +374,139 @@ class WalkForwardAnalyzer:
             )
         source = positions[next(iter(positions))].source
         self.data_length = len(source.data)
+        self.data_index = source.data.index
+
+        # Convert timedelta specifications to period counts
+        self._train_periods_int = self._resolve_periods(train_periods)
+        self._test_periods_int = self._resolve_periods(test_periods)
+
+        if step_periods is None:
+            self._step_periods_int = self._test_periods_int
+        else:
+            self._step_periods_int = self._resolve_periods(step_periods)
+
+        # Validate period counts
+        if self._train_periods_int < self.min_train_periods:
+            raise ValueError(
+                f"train_periods ({train_periods}) resolves to "
+                f"{self._train_periods_int} periods, which is less than "
+                f"the minimum of {self.min_train_periods}"
+            )
+
+        if self._test_periods_int < self.min_test_periods:
+            raise ValueError(
+                f"test_periods ({test_periods}) resolves to "
+                f"{self._test_periods_int} periods, which is less than "
+                f"the minimum of {self.min_test_periods}"
+            )
+
+        if self._step_periods_int <= 0:
+            raise ValueError(
+                f"step_periods ({step_periods}) resolves to "
+                f"{self._step_periods_int}, which must be positive"
+            )
+
+    def _resolve_periods(self, value: PeriodSpec) -> int:
+        """
+        Convert a period specification to number of periods.
+        
+        Args:
+            value: Either an int (number of periods) or a timedelta.
+        
+        Returns:
+            int: Number of periods.
+        """
+        if isinstance(value, (timedelta, pd.Timedelta)):
+            td = pd.Timedelta(value)
+            # Calculate number of periods based on data frequency
+            if len(self.data_index) < 2:
+                raise ValueError(
+                    "Cannot convert timedelta to periods: "
+                    "data source has fewer than 2 data points"
+                )
+            
+            # Determine the frequency of the data
+            # Compute from the first two points (most reliable method)
+            freq_delta = self.data_index[1] - self.data_index[0]
+            freq_delta = pd.Timedelta(freq_delta)
+            
+            if freq_delta.total_seconds() <= 0:
+                raise ValueError(
+                    "Cannot convert timedelta to periods: "
+                    "data frequency could not be determined"
+                )
+            
+            # Calculate number of periods covered by the timedelta
+            periods = int(round(td / freq_delta))
+            
+            if periods <= 0:
+                raise ValueError(
+                    f"timedelta {td} is less than one data period "
+                    f"(frequency: {freq_delta})"
+                )
+            
+            return periods
+        
+        # It's already an int
+        return int(value)
+
+    @property
+    def train_periods_spec(self) -> PeriodSpec:
+        """Original train_periods specification (int or timedelta)."""
+        return self._train_periods_spec
+
+    @property
+    def test_periods_spec(self) -> PeriodSpec:
+        """Original test_periods specification (int or timedelta)."""
+        return self._test_periods_spec
+
+    @property
+    def step_periods_spec(self) -> PeriodSpec | None:
+        """Original step_periods specification (int or timedelta)."""
+        return self._step_periods_spec
+
+    @property
+    def train_periods(self) -> int:
+        """Resolved train_periods as number of periods (int)."""
+        return self._train_periods_int
+
+    @property
+    def test_periods(self) -> int:
+        """Resolved test_periods as number of periods (int)."""
+        return self._test_periods_int
+
+    @property
+    def step_periods(self) -> int:
+        """Resolved step_periods as number of periods (int)."""
+        return self._step_periods_int
 
     def _create_window_splits(self) -> list[tuple[int, int, int, int]]:
         """
         Create the train/test splits for all walk-forward windows.
-        
+
         Returns:
             List of tuples: (train_start, train_end, test_start, test_end)
         """
         splits = []
         train_start = 0
-        step = self.step_periods  # Already validated to be non-None in __post_init__
-        
+        train_periods = self._train_periods_int
+        test_periods = self._test_periods_int
+        step = self._step_periods_int
+
         while True:
-            train_end = train_start + self.train_periods
+            train_end = train_start + train_periods
             test_start = train_end
-            test_end = test_start + self.test_periods
-            
+            test_end = test_start + test_periods
+
             # Check if we have enough data for test period
             if test_end > self.data_length:
                 break
-            
+
             splits.append((train_start, train_end, test_start, test_end))
-            
+
             # Move forward
             train_start += step
-        
+
         return splits
 
     def _slice_strategy_for_window(
@@ -525,8 +652,8 @@ class WalkForwardAnalyzer:
         if n_windows == 0:
             raise ValueError(
                 f"Data length ({self.data_length}) is too short for the configured "
-                f"train_periods ({self.train_periods}) and test_periods ({self.test_periods}). "
-                f"Need at least {self.train_periods + self.test_periods} periods."
+                f"train_periods ({self._train_periods_int}) and test_periods ({self._test_periods_int}). "
+                f"Need at least {self._train_periods_int + self._test_periods_int} periods."
             )
         
         window_results: list[WalkForwardWindow] = []
@@ -608,6 +735,8 @@ class WalkForwardAnalyzer:
                 test_end=test_end,
                 train_periods=train_end - train_start,
                 test_periods=test_end - test_start,
+                train_periods_spec=self._train_periods_spec,
+                test_periods_spec=self._test_periods_spec,
                 best_params=best_params,
                 train_metrics=train_metrics,
                 test_metrics=test_metrics,
@@ -637,8 +766,10 @@ class WalkForwardAnalyzer:
         
         return WalkForwardResult(
             n_windows=n_windows,
-            train_periods=self.train_periods,
-            test_periods=self.test_periods,
+            train_periods=self._train_periods_int,
+            test_periods=self._test_periods_int,
+            train_periods_spec=self._train_periods_spec,
+            test_periods_spec=self._test_periods_spec,
             window_results=window_results,
             aggregated_metrics=aggregated,
             all_windows_results_df=results_df,
@@ -713,9 +844,9 @@ def walk_forward_analyze(
     backtester: Any,
     optimizer: OptimizerProtocol,
     params: dict[str, Any],
-    train_periods: int,
-    test_periods: int,
-    step_periods: int | None = None,
+    train_periods: PeriodSpec,
+    test_periods: PeriodSpec,
+    step_periods: PeriodSpec | None = None,
     constraint: Callable[[dict], bool] | None = None,
     objective: str = "sharpe",
     risk_tolerance: dict[str, float] | None = None,
@@ -734,10 +865,12 @@ def walk_forward_analyze(
         backtester (SimpleBacktester): The backtester instance to use.
         optimizer (OptimizerProtocol): Optimizer function to use.
         params (dict[str, Any]): Parameter space for optimization.
-        train_periods (int): Number of periods for each training window.
-        test_periods (int): Number of periods for each test window.
-        step_periods (int | None, optional): Periods to step between windows.
-            If None, uses test_periods. Defaults to None.
+        train_periods (PeriodSpec): Number of periods or timedelta for each 
+            training window. Can be an int or timedelta.
+        test_periods (PeriodSpec): Number of periods or timedelta for each 
+            test window. Can be an int or timedelta.
+        step_periods (PeriodSpec | None, optional): Periods or timedelta to 
+            step between windows. If None, uses test_periods. Defaults to None.
         constraint (Callable[[dict], bool] | None, optional): Constraint function.
         objective (str, optional): Metric to optimize. Defaults to "sharpe".
         risk_tolerance (dict[str, float] | None, optional): Risk tolerance.
@@ -752,6 +885,7 @@ def walk_forward_analyze(
         WalkForwardResult: Walk-forward analysis results.
     
     Example:
+        Using periods:
         >>> from quantex.backtester.walk_forward import walk_forward_analyze
         >>> result = walk_forward_analyze(
         ...     backtester=bt,
@@ -761,16 +895,25 @@ def walk_forward_analyze(
         ...     test_periods=63,
         ...     objective='sharpe'
         ... )
+        
+        Using timedelta:
+        >>> import pandas as pd
+        >>> result = walk_forward_analyze(
+        ...     backtester=bt,
+        ...     optimizer=lambda bt, params: bt.optimize(params),
+        ...     params={'fast': [5, 10, 20], 'slow': [20, 50, 100]},
+        ...     train_periods=pd.Timedelta('365 days'),
+        ...     test_periods=pd.Timedelta('90 days'),
+        ...     objective='sharpe'
+        ... )
+        
         >>> print(f"Average OOS Sharpe: {result.aggregated_metrics['out_of_sample_sharpe_mean']:.2f}")
     """
-    # Handle step_periods - use test_periods if None
-    actual_step = test_periods if step_periods is None else step_periods
-    
     analyzer = WalkForwardAnalyzer(
         backtester=backtester,
         train_periods=train_periods,
         test_periods=test_periods,
-        step_periods=actual_step,
+        step_periods=step_periods,
         min_train_periods=min_train_periods,
         min_test_periods=min_test_periods,
         selection_criterion=objective,