quantex 0.4.4__tar.gz → 0.4.6__tar.gz

{quantex-0.4.4 → quantex-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: quantex
-Version: 0.4.4
+Version: 0.4.6
 Summary: A simple quant strategy creation and backtesting package.
 License: MIT
 Author: Daniel Green

{quantex-0.4.4 → quantex-0.4.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantex"
-version = "0.4.4"
+version = "0.4.6"
 description = "A simple quant strategy creation and backtesting package."
 authors = [
     {name = "Daniel Green",email = "dangreen07@outlook.com"}
@@ -39,6 +39,7 @@ mkdocs-mermaid2-plugin = "^1.2.1"
 mkdocs-print-site-plugin = "^2.7.3"
 pytest-xdist = "^3.8.0"
 matplotlib = "^3.10.3"
+ipykernel = "^7.2.0"
 
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]

{quantex-0.4.4 → quantex-0.4.6}/src/quantex/backtester/backtester.py

@@ -175,7 +175,12 @@ class SimpleBacktester:
             final_cash=self.PnLRecord[-1],
             PnlRecord=pd.Series(self.PnLRecord, index=index),
             orders=orders,
-            tradeRecord=tradeRecord)
+            tradeRecord=tradeRecord,
+            margin_call_events=[
+                event
+                for broker in self.strategy.positions.values()
+                for event in getattr(broker, "margin_call_events", [])
+            ] or None)
     
     def optimize(
         self,

{quantex-0.4.4 → quantex-0.4.6}/src/quantex/backtester/montecarlo.py

@@ -1,10 +1,11 @@
 """
 Monte Carlo simulation module for quantex backtesting.
 
-This module provides Monte Carlo simulation capabilities to test strategy
-robustness through two approaches:
-1. Trade Order Randomization - shuffles the sequence of executed trades
-2. Price Path Resampling (Bootstrap) - resamples historical returns to create synthetic paths
+    This module provides Monte Carlo simulation capabilities to test strategy
+    robustness through three approaches:
+    1. Trade Order Randomization - shuffles the sequence of executed trades
+    2. Trade Shuffle With Replacement - resamples trade returns with replacement
+    3. Price Path Resampling (Bootstrap) - resamples historical returns to create synthetic paths
 """
 
 import copy
@@ -12,6 +13,7 @@ import math
 import random
 import numpy as np
 import pandas as pd
+import matplotlib.dates as mdates
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
@@ -33,6 +35,7 @@ class MonteCarloMode(Enum):
         BOTH: Run both analyses and combine results
     """
     TRADE_ORDER = "trade_order"
+    TRADE_SHUFFLE_WITH_REPLACEMENT = "trade_shuffle_with_replacement"
     PRICE_PATH = "price_path"
     BOTH = "both"
 
@@ -62,6 +65,7 @@ class MonteCarloResult:
     simulations: int = 0
     starting_cash: float = 0.0
     drawdown_stats: dict = field(default_factory=dict)
+    plot_max_curves: int = 150
     
     def _compute_statistics(self):
         """Compute summary statistics from equity curves."""
@@ -113,7 +117,7 @@ class MonteCarloResult:
         self,
         target_return: float,
         drawdown_threshold: float,
-        horizon: int | None = None,
+        horizon: int | str | pd.Timedelta | None = None,
         as_percent: bool = True,
     ) -> dict:
         """
@@ -125,8 +129,10 @@ class MonteCarloResult:
                 True, this is treated as a decimal return (e.g. 0.05 for 5%).
             drawdown_threshold (float): Drawdown threshold. If `as_percent` is
                 True, this is treated as a decimal drawdown (e.g. 0.05 for 5%).
-            horizon (int | None, optional): Number of steps to evaluate. Defaults
-                to the full length of the simulated curves.
+            horizon (int | str | pd.Timedelta | None, optional): Evaluation horizon.
+                If an integer is provided, it is treated as a number of steps.
+                If a string or Timedelta is provided, it is treated as a time span
+                relative to the first timestamp in each equity curve.
             as_percent (bool, optional): Whether thresholds are provided as
                 decimal percentages. Defaults to True.
 
@@ -142,8 +148,26 @@ class MonteCarloResult:
                 "drawdown_threshold": drawdown_threshold,
             }
 
-        horizon = horizon or len(self.equity_curves[0])
-        horizon = max(1, min(horizon, len(self.equity_curves[0])))
+        def _resolve_horizon(curve: pd.Series, horizon_value: int | str | pd.Timedelta | None) -> int:
+            if horizon_value is None:
+                return len(curve)
+            if isinstance(horizon_value, (int, np.integer)):
+                return max(1, min(int(horizon_value), len(curve)))
+
+            if not isinstance(curve.index, pd.DatetimeIndex):
+                return max(1, min(len(curve), len(curve)))
+
+            delta = pd.Timedelta(horizon_value)
+            if delta <= pd.Timedelta(0):
+                return 1
+
+            start_time = curve.index[0]
+            end_time = start_time + delta
+            resolved = int(curve.index.searchsorted(end_time, side="right"))
+            return max(1, min(resolved, len(curve)))
+
+        first_curve = self.equity_curves[0]
+        horizon_steps = _resolve_horizon(first_curve, horizon)
 
         if as_percent:
             target_return = float(target_return)
@@ -152,7 +176,7 @@ class MonteCarloResult:
         return_hits = 0
         drawdown_hits = 0
         for curve in self.equity_curves:
-            sampled = curve.iloc[:horizon]
+            sampled = curve.iloc[:horizon_steps]
             start_value = float(sampled.iloc[0])
             end_value = float(sampled.iloc[-1])
             achieved_return = (end_value / start_value) - 1.0 if start_value != 0 else 0.0
@@ -173,7 +197,7 @@ class MonteCarloResult:
         }
     
     def plot(self, figsize: tuple = (12, 8), show_original: bool = True, 
-             show_percentiles: bool = True) -> None:
+             show_percentiles: bool = True, max_curves: int | None = None) -> None:
         """
         Plot all Monte Carlo simulation equity curves.
         
@@ -188,6 +212,8 @@ class MonteCarloResult:
                 curve. Defaults to True.
             show_percentiles (bool, optional): Whether to show percentile bands.
                 Defaults to True.
+            max_curves (int | None, optional): Maximum number of simulation curves
+                to render. Defaults to ``self.plot_max_curves``.
         
         Note:
             This method uses matplotlib to display the plots and requires
@@ -196,11 +222,13 @@ class MonteCarloResult:
         from matplotlib import pyplot as plt
         
         fig, ax = plt.subplots(figsize=figsize)
+
+        max_curves = self.plot_max_curves if max_curves is None else max_curves
         
-        # Plot using a numeric simulation step axis to avoid date conversion
-        # artifacts when equity curves share the same time index.
+        # Plot against the datetime index so the x-axis reflects the actual
+        # backtest timeline instead of a generic simulation step axis.
         if not self.equity_curves:
-            ax.set_xlabel("Step")
+            ax.set_xlabel("Datetime")
             ax.set_ylabel("Portfolio Value")
             ax.set_title(f"Monte Carlo Simulation Results ({self.simulations} simulations)")
             ax.grid(alpha=0.3)
@@ -208,14 +236,35 @@ class MonteCarloResult:
             plt.show()
             return
 
-        step_index = np.arange(len(self.equity_curves[0]), dtype=np.float64)
+        base_index = self.equity_curves[0].index
+        if not isinstance(base_index, pd.DatetimeIndex):
+            base_index = pd.to_datetime(base_index)
+
+        def _plot_x_values(curve: pd.Series) -> pd.Index:
+            if isinstance(curve.index, pd.DatetimeIndex):
+                return curve.index
+            return pd.to_datetime(curve.index)
         
         # Plot all simulation curves with low alpha (transparency)
         # This makes the average path appear lightest due to overlap
-        for curve in self.equity_curves:
-            x_vals = np.arange(len(curve), dtype=np.float64)
+        color_cycle = plt.rcParams["axes.prop_cycle"].by_key().get("color", ["steelblue"])
+        curve_count = len(self.equity_curves)
+        if max_curves is not None and max_curves > 0 and curve_count > max_curves:
+            plot_indices = np.linspace(0, curve_count - 1, max_curves, dtype=int)
+        else:
+            plot_indices = range(curve_count)
+
+        for i in plot_indices:
+            curve = self.equity_curves[i]
+            x_vals = _plot_x_values(curve)
             y_vals = np.asarray(curve.values, dtype=np.float64)
-            ax.plot(x_vals, y_vals, color="steelblue", alpha=0.1, linewidth=0.5)
+            ax.plot(
+                x_vals,
+                y_vals,
+                color=color_cycle[i % len(color_cycle)],
+                alpha=0.08,
+                linewidth=0.5,
+            )
         
         # Compute mean and median curves for highlighting
         if self.equity_curves:
@@ -225,18 +274,20 @@ class MonteCarloResult:
             median_curve = aligned.median(axis=1)
             
             # Plot mean curve (thicker, lighter)
-            x_mean = np.arange(len(mean_curve), dtype=np.float64)
+            x_mean = base_index
             y_mean = np.asarray(mean_curve.values, dtype=np.float64)
             ax.plot(x_mean, y_mean, color="darkblue", alpha=0.8, linewidth=2, label="Mean")
             
             # Plot median curve
-            x_med = np.arange(len(median_curve), dtype=np.float64)
+            x_med = base_index
             y_med = np.asarray(median_curve.values, dtype=np.float64)
             ax.plot(x_med, y_med, color="navy", alpha=0.6, linewidth=1.5, linestyle="--", label="Median")
         
         # Show original equity curve if requested
         if show_original and self.original_equity is not None:
-            x_orig = np.arange(len(self.original_equity), dtype=np.float64)
+            x_orig = self.original_equity.index
+            if not isinstance(x_orig, pd.DatetimeIndex):
+                x_orig = pd.to_datetime(x_orig)
             y_orig = np.asarray(self.original_equity.values, dtype=np.float64)
             ax.plot(x_orig, y_orig, color="red", alpha=0.9, linewidth=2, label="Original Backtest")
         
@@ -245,19 +296,20 @@ class MonteCarloResult:
             aligned = pd.concat(self.equity_curves, axis=1)
             p5 = aligned.quantile(0.05, axis=1)
             p95 = aligned.quantile(0.95, axis=1)
-            x_p5 = np.arange(len(p5), dtype=np.float64)
+            x_p5 = p5.index
+            if not isinstance(x_p5, pd.DatetimeIndex):
+                x_p5 = pd.to_datetime(x_p5)
             y_p5 = np.asarray(p5.values, dtype=np.float64)
             y_p95 = np.asarray(p95.values, dtype=np.float64)
             ax.fill_between(x_p5, y_p5, y_p95, alpha=0.2, color="steelblue", label="5th-95th Percentile")
         
-        ax.set_xlabel("Step")
+        ax.set_xlabel("Datetime")
         ax.set_ylabel("Portfolio Value")
         ax.set_title(f"Monte Carlo Simulation Results ({self.simulations} simulations)")
         ax.legend(loc="best")
         ax.grid(alpha=0.3)
-
-        # Match the more compact spaghetti-plot look by tightening x-limits.
-        ax.set_xlim(step_index[0], step_index[-1])
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m"))
+        fig.autofmt_xdate()
         
         plt.tight_layout()
         plt.show()
@@ -358,6 +410,51 @@ def _run_trade_order_simulation(
     return pd.Series(equity, index=index)
 
 
+def _run_trade_shuffle_with_replacement_simulation(
+    original_orders: list[Order],
+    original_cash: float,
+    original_equity: pd.Series,
+    commission: float,
+    commission_type,
+    lot_size: int,
+    seed: int | None = None,
+) -> pd.Series:
+    """
+    Run a Monte Carlo simulation that samples trade outcomes with replacement.
+
+    This mode reuses the original trade-return sequence as a return pool and
+    reconstructs the curve using a replacement-sampled path. Any remaining
+    steps are kept neutral so the resulting equity curve always spans the same
+    time axis as the original backtest.
+    """
+    if seed is not None:
+        random.seed(seed)
+
+    index = original_equity.index
+    equity = np.full(len(index), original_cash, dtype=np.float64)
+
+    equity_values = np.asarray(original_equity.values, dtype=np.float64)
+    equity_returns = np.zeros_like(equity_values)
+    if len(equity_values) > 1:
+        prev = np.empty_like(equity_values)
+        prev[0] = original_cash
+        prev[1:] = equity_values[:-1]
+        equity_returns[1:] = np.where(prev[1:] > 0, (equity_values[1:] / prev[1:]) - 1.0, 0.0)
+
+    trade_returns = equity_returns[1:].tolist()
+    if not trade_returns:
+        return pd.Series(equity, index=index)
+
+    sampled_returns = [random.choice(trade_returns) for _ in range(len(trade_returns))]
+
+    equity_returns = np.concatenate(([0.0], np.asarray(sampled_returns, dtype=np.float64)))
+
+    for i in range(1, len(equity)):
+        equity[i] = equity[i - 1] * (1.0 + equity_returns[i])
+
+    return pd.Series(equity, index=index)
+
+
 def _run_price_path_simulation(
     strategy: Strategy,
     data_sources: dict[str, DataSource],
@@ -511,7 +608,7 @@ def monte_carlo(
             - "trade_order": Randomize trade execution order
             - "price_path": Resample price returns to create synthetic paths
             - "both": Run both analyses and combine results
-            Defaults to "both".
+            Defaults to "trade_order".
         seed (int | None, optional): Random seed for reproducibility.
             Defaults to None.
         progress_bar (bool, optional): Whether to show progress bar during simulation.
@@ -583,6 +680,21 @@ def monte_carlo(
                 # No trades, just return original equity
                 curve = original_equity.copy()
             equity_curves.append(curve)
+
+        if mode == MonteCarloMode.TRADE_SHUFFLE_WITH_REPLACEMENT:
+            if len(original_orders) > 0:
+                curve = _run_trade_shuffle_with_replacement_simulation(
+                    original_orders,
+                    original_cash,
+                    original_equity,
+                    self.commission,
+                    self.commission_type,
+                    self.lot_size,
+                    seed=iter_seed,
+                )
+            else:
+                curve = original_equity.copy()
+            equity_curves.append(curve)
         
         if mode == MonteCarloMode.PRICE_PATH or mode == MonteCarloMode.BOTH:
             # Price path resampling
@@ -637,6 +749,15 @@ def monte_carlo(
             "trade_order": trade_result.percentile_results,
             "price_path": price_result.percentile_results,
         }
+    elif mode == MonteCarloMode.TRADE_SHUFFLE_WITH_REPLACEMENT:
+        result = MonteCarloResult(
+            mode=mode,
+            equity_curves=equity_curves,
+            original_equity=original_equity,
+            simulations=simulations,
+            starting_cash=original_cash,
+        )
+        result._compute_statistics()
     else:
         # Create result object
         result = MonteCarloResult(

{quantex-0.4.4 → quantex-0.4.6}/src/quantex/backtester/reports.py

@@ -46,16 +46,18 @@ class BacktestReport:
     metrics such as Sharpe ratio and maximum drawdown.
     
     Attributes:
-        starting_cash (np.float64): Initial cash amount at start of backtest.
-        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.
+    starting_cash (np.float64): Initial cash amount at start of backtest.
+    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.
+    margin_call_events (list[dict]): Margin call events triggered during the run.
     """
     starting_cash: np.float64
     final_cash: np.float64
     PnlRecord: pd.Series
     orders: list
     tradeRecord: list[np.float64]
+    margin_call_events: list[dict] | None = None
 
     @property
     def annual_rf(self):
@@ -201,6 +203,7 @@ class BacktestReport:
         tot_return = float(equity.iloc[-1] / equity.iloc[0] - 1.0)
         annualized_return = float((1.0 + tot_return) ** (self.periods_per_year / max(len(returns), 1)) - 1.0)
         tot_orders = len(self.orders)
+        margin_calls = len(self.margin_call_events or [])
 
         return (
             f"Starting Cash: ${self.starting_cash:,.2f}\n"
@@ -215,5 +218,6 @@ class BacktestReport:
         ) + (
             f"\nMax Drawdown: {mdd:.2%}\n"
             f"Kelly Fraction: {self.kelly_criterion:.3}\n"
-            f"Total Trades: {tot_orders:,}"
+            f"Total Trades: {tot_orders:,}\n"
+            f"Margin Calls: {margin_calls:,}"
         )

{quantex-0.4.4 → quantex-0.4.6}/src/quantex/broker/broker.py

@@ -79,6 +79,8 @@ class Broker:
         self.complete_orders = []
         self.active_order: Order | None = None
         self.pending_close_order: Order | None = None
+        self.margin_call_triggered: bool = False
+        self.margin_call_events: list[dict] = []
         self._i = 0
         self.source = source
         self.PnLRecord = np.full(len(self.source.data['Close']), self.cash, dtype=np.float64)
@@ -604,5 +606,12 @@ class Broker:
         equity = self.cash + unrealized
         margin_call = self.margin_call * abs(self.position) * self.source.CClose
         if equity < margin_call and self.position < 0:
+            self.margin_call_triggered = True
+            self.margin_call_events.append({
+                "timestamp": self.source.Index[self._i],
+                "equity": equity,
+                "margin_call_threshold": margin_call,
+                "position": self.position,
+            })
             self.close() ## Close all positions immediately, margin call
         self.PnLRecord[self._i] = equity