quantex 0.4.1__tar.gz → 0.4.3__tar.gz

{quantex-0.4.1 → quantex-0.4.3}/PKG-INFO

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

{quantex-0.4.1 → quantex-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantex"
-version = "0.4.1"
+version = "0.4.3"
 description = "A simple quant strategy creation and backtesting package."
 authors = [
     {name = "Daniel Green",email = "dangreen07@outlook.com"}

{quantex-0.4.1 → quantex-0.4.3}/src/quantex/backtester/montecarlo.py

@@ -8,6 +8,7 @@ robustness through two approaches:
 """
 
 import copy
+import math
 import random
 import numpy as np
 import pandas as pd
@@ -60,6 +61,7 @@ class MonteCarloResult:
     original_equity: pd.Series | None = None
     simulations: int = 0
     starting_cash: float = 0.0
+    drawdown_stats: dict = field(default_factory=dict)
     
     def _compute_statistics(self):
         """Compute summary statistics from equity curves."""
@@ -86,6 +88,89 @@ class MonteCarloResult:
             "p75": np.percentile(final_values, 75),
             "p95": np.percentile(final_values, 95),
         }
+
+        drawdowns = []
+        for curve in self.equity_curves:
+            running_max = curve.cummax()
+            dd = (curve / running_max) - 1.0
+            drawdowns.append(float(dd.min()))
+
+        drawdown_values = np.asarray(drawdowns, dtype=np.float64)
+        self.drawdown_stats = {
+            "mean": float(np.mean(drawdown_values)),
+            "std": float(np.std(drawdown_values)),
+            "min": float(np.min(drawdown_values)),
+            "max": float(np.max(drawdown_values)),
+            "median": float(np.median(drawdown_values)),
+            "p5": float(np.percentile(drawdown_values, 5)),
+            "p25": float(np.percentile(drawdown_values, 25)),
+            "p50": float(np.percentile(drawdown_values, 50)),
+            "p75": float(np.percentile(drawdown_values, 75)),
+            "p95": float(np.percentile(drawdown_values, 95)),
+        }
+
+    def probabilities(
+        self,
+        target_return: float,
+        drawdown_threshold: float,
+        horizon: int | None = None,
+        as_percent: bool = True,
+    ) -> dict:
+        """
+        Calculate the probability of reaching a target return and exceeding
+        a drawdown threshold within a given time horizon.
+
+        Args:
+            target_return (float): Target return threshold. If `as_percent` is
+                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.
+            as_percent (bool, optional): Whether thresholds are provided as
+                decimal percentages. Defaults to True.
+
+        Returns:
+            dict: Probability summary containing return and drawdown metrics.
+        """
+        if not self.equity_curves:
+            return {
+                "return_probability": 0.0,
+                "drawdown_probability": 0.0,
+                "horizon": horizon,
+                "target_return": target_return,
+                "drawdown_threshold": drawdown_threshold,
+            }
+
+        horizon = horizon or len(self.equity_curves[0])
+        horizon = max(1, min(horizon, len(self.equity_curves[0])))
+
+        if as_percent:
+            target_return = float(target_return)
+            drawdown_threshold = float(drawdown_threshold)
+
+        return_hits = 0
+        drawdown_hits = 0
+        for curve in self.equity_curves:
+            sampled = curve.iloc[:horizon]
+            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
+            max_drawdown = float(((sampled / sampled.cummax()) - 1.0).min())
+
+            if achieved_return >= target_return:
+                return_hits += 1
+            if abs(max_drawdown) >= drawdown_threshold:
+                drawdown_hits += 1
+
+        total = len(self.equity_curves)
+        return {
+            "return_probability": return_hits / total,
+            "drawdown_probability": drawdown_hits / total,
+            "horizon": horizon,
+            "target_return": target_return,
+            "drawdown_threshold": drawdown_threshold,
+        }
     
     def plot(self, figsize: tuple = (12, 8), show_original: bool = True, 
              show_percentiles: bool = True) -> None:
@@ -198,6 +283,13 @@ class MonteCarloResult:
             f"  50th: ${self.percentile_results.get('p50', 0):,.2f} (Median)\n"
             f"  75th: ${self.percentile_results.get('p75', 0):,.2f}\n"
             f"  95th: ${self.percentile_results.get('p95', 0):,.2f}\n"
+            f"\nDrawdown Statistics (% of peak):\n"
+            f"  Mean Max DD: {self.drawdown_stats.get('mean', 0):.2%}\n"
+            f"  5th: {self.drawdown_stats.get('p5', 0):.2%}\n"
+            f"  25th: {self.drawdown_stats.get('p25', 0):.2%}\n"
+            f"  50th: {self.drawdown_stats.get('p50', 0):.2%}\n"
+            f"  75th: {self.drawdown_stats.get('p75', 0):.2%}\n"
+            f"  95th: {self.drawdown_stats.get('p95', 0):.2%}\n"
         )
 
 
@@ -231,10 +323,10 @@ def _run_trade_order_simulation(
     """
     if seed is not None:
         random.seed(seed)
-    
-    # Shuffle the orders
-    shuffled_orders = original_orders.copy()
-    random.shuffle(shuffled_orders)
+
+    # Trade-order Monte Carlo must preserve the trade outcomes while changing
+    # only the order in which those outcomes are realized. We therefore shuffle
+    # the per-step percentage returns, not the absolute equity values.
     
     # Get time index from original equity
     index = original_equity.index
@@ -242,22 +334,25 @@ def _run_trade_order_simulation(
     # Initialize equity record
     equity = np.full(len(index), original_cash, dtype=np.float64)
     
-    # Calculate cumulative PnL changes from original equity
-    # Convert to numpy array first to avoid type issues
+    # Use step-wise percentage returns rather than absolute value changes.
+    # This keeps the path dependent on the sequence of returns rather than
+    # collapsing to the same terminal value every time.
     equity_values = np.asarray(original_equity.values, dtype=np.float64)
-    equity_changes = np.diff(equity_values)
-    equity_changes = np.insert(equity_changes, 0, 0)
-    
-    # Shuffle the equity changes to randomize trade order
-    # Convert to list for shuffle, then back to array
-    equity_changes_list = equity_changes.tolist()
-    random.shuffle(equity_changes_list)
-    equity_changes = np.array(equity_changes_list, dtype=np.float64)
+    equity_returns = np.zeros_like(equity_values)
+    if len(equity_values) > 1:
+        prev = np.where(np.arange(len(equity_values)) == 0, original_cash, equity_values[:-1])
+        equity_returns[1:] = np.where(prev > 0, (equity_values[1:] / prev) - 1.0, 0.0)
+
+    # Keep the starting cash anchored at index 0 and randomize the remaining
+    # returns so the path always begins from the actual initial capital.
+    shuffled_returns = equity_returns[1:].tolist()
+    random.shuffle(shuffled_returns)
+    equity_returns = np.concatenate(([0.0], np.asarray(shuffled_returns, dtype=np.float64)))
     
-    # Reconstruct equity curve with shuffled changes
+    # Reconstruct equity curve with shuffled returns
     for i in range(1, len(equity)):
-        equity[i] = equity[i - 1] + equity_changes[i]
-    
+        equity[i] = equity[i - 1] * (1.0 + equity_returns[i])
+
     return pd.Series(equity, index=index)
 
 
@@ -298,32 +393,78 @@ def _run_price_path_simulation(
     synthetic_sources = {}
     
     for symbol, source in data_sources.items():
-        close_prices = source.data['Close'].values
-        
-        # Calculate log returns
+        close_prices = np.asarray(source.data["Close"].values, dtype=np.float64)
+        if len(close_prices) < 2:
+            synthetic_sources[symbol] = DataSource(source.data.copy())
+            continue
+
+        # Use a block-bootstrap on log returns to preserve local serial dependence
+        # and then re-price the path using a geometric Brownian motion style
+        # reconstruction with the sampled return distribution.
         log_returns = np.diff(np.log(close_prices))
-        
-        # Resample with replacement
         n_samples = len(log_returns)
-        resampled_indices = np.random.randint(0, n_samples, size=n_samples)
-        resampled_returns = log_returns[resampled_indices]
-        
-        # Reconstruct price path starting from initial price
-        synthetic_prices = np.zeros(n_samples + 1)
-        synthetic_prices[0] = close_prices[0]
-        synthetic_prices[1:] = close_prices[0] * np.exp(np.cumsum(resampled_returns))
-        
-        # Create synthetic OHLCV data
-        # Use the same pattern but with resampled close prices
-        synthetic_df = source.data.copy()
-        synthetic_df['Close'] = synthetic_prices
-        
-        # Adjust Open, High, Low based on close (simple approximation)
-        # This is a simplification - real implementation would need proper OHLC generation
-        synthetic_df['Open'] = synthetic_prices * (1 + np.random.uniform(-0.001, 0.001, n_samples + 1))
-        synthetic_df['High'] = np.maximum(synthetic_prices, synthetic_df['Open']) * (1 + np.random.uniform(0, 0.002, n_samples + 1))
-        synthetic_df['Low'] = np.minimum(synthetic_prices, synthetic_df['Open']) * (1 - np.random.uniform(0, 0.002, n_samples + 1))
-        
+        block_size = max(2, min(10, int(np.sqrt(n_samples))))
+        synthetic_log_returns = []
+
+        while len(synthetic_log_returns) < n_samples:
+            start = int(np.random.randint(0, n_samples))
+            block = log_returns[start : start + block_size]
+            if len(block) < block_size:
+                wrap = block_size - len(block)
+                block = np.concatenate((block, log_returns[:wrap]))
+            synthetic_log_returns.extend(block.tolist())
+
+        synthetic_log_returns = np.asarray(synthetic_log_returns[:n_samples], dtype=np.float64)
+
+        # Keep the simulated path realistic by matching the original return
+        # center and volatility rather than letting the bootstrap drift too far.
+        original_mean = float(np.mean(log_returns))
+        original_std = float(np.std(log_returns))
+        synthetic_mean = float(np.mean(synthetic_log_returns))
+        synthetic_std = float(np.std(synthetic_log_returns))
+        if synthetic_std > 0 and original_std > 0:
+            synthetic_log_returns = (synthetic_log_returns - synthetic_mean) * (original_std / synthetic_std) + original_mean
+        else:
+            synthetic_log_returns = synthetic_log_returns - synthetic_mean + original_mean
+
+        synthetic_close = np.empty(n_samples + 1, dtype=np.float64)
+        synthetic_close[0] = close_prices[0]
+        synthetic_close[1:] = synthetic_close[0] * np.exp(np.cumsum(synthetic_log_returns))
+        synthetic_close = np.maximum(synthetic_close, np.finfo(np.float64).tiny)
+
+        # Derive intraday range from the historical candle shape so OHLC remains coherent.
+        source_df = source.data.copy()
+        if "Open" in source_df.columns:
+            open_close_gap = np.log(np.asarray(source_df["Open"].values, dtype=np.float64) / close_prices)
+            open_close_gap = np.nan_to_num(open_close_gap, nan=0.0, posinf=0.0, neginf=0.0)
+        else:
+            open_close_gap = np.zeros_like(synthetic_close)
+
+        open_noise = np.random.choice(open_close_gap, size=n_samples + 1, replace=True)
+        synthetic_open = synthetic_close * np.exp(open_noise)
+
+        if {"High", "Low"}.issubset(source_df.columns):
+            high_wick = np.log(np.asarray(source_df["High"].values, dtype=np.float64) / np.maximum(close_prices, np.finfo(np.float64).tiny))
+            low_wick = np.log(np.asarray(source_df["Low"].values, dtype=np.float64) / np.maximum(close_prices, np.finfo(np.float64).tiny))
+            high_wick = np.nan_to_num(high_wick, nan=0.0, posinf=0.0, neginf=0.0)
+            low_wick = np.nan_to_num(low_wick, nan=0.0, posinf=0.0, neginf=0.0)
+            synthetic_high = np.maximum(synthetic_open, synthetic_close) * np.exp(np.abs(np.random.choice(high_wick, size=n_samples + 1, replace=True)))
+            synthetic_low = np.minimum(synthetic_open, synthetic_close) * np.exp(-np.abs(np.random.choice(low_wick, size=n_samples + 1, replace=True)))
+        else:
+            synthetic_high = np.maximum(synthetic_open, synthetic_close)
+            synthetic_low = np.minimum(synthetic_open, synthetic_close)
+
+        synthetic_df = source_df.copy()
+        synthetic_df["Close"] = synthetic_close
+        synthetic_df["Open"] = synthetic_open
+        synthetic_df["High"] = np.maximum.reduce([synthetic_high, synthetic_open, synthetic_close])
+        synthetic_df["Low"] = np.minimum.reduce([synthetic_low, synthetic_open, synthetic_close])
+
+        if "Volume" in synthetic_df.columns:
+            volume = np.asarray(source_df["Volume"].values, dtype=np.float64)
+            if len(volume) == n_samples + 1:
+                synthetic_df["Volume"] = np.maximum(0.0, np.random.choice(volume, size=n_samples + 1, replace=True))
+
         synthetic_sources[symbol] = DataSource(synthetic_df)
     
     # Update strategy with synthetic data sources
@@ -349,8 +490,8 @@ def _run_price_path_simulation(
 
 def monte_carlo(
     self,
-    simulations: int = 100,
-    mode: MonteCarloMode | str = MonteCarloMode.BOTH,
+    simulations: int | None = None,
+    mode: MonteCarloMode | str = MonteCarloMode.TRADE_ORDER,
     seed: int | None = None,
     progress_bar: bool = False,
 ) -> MonteCarloResult:
@@ -361,7 +502,9 @@ def monte_carlo(
     either trade order randomization, price path resampling, or both.
     
     Args:
-        simulations (int, optional): Number of simulations to run. Defaults to 100.
+        simulations (int | None, optional): Number of simulations to run.
+            Defaults to the number of unique permutations of executed trades
+            when mode is "trade_order", otherwise 100.
         mode (MonteCarloMode | str, optional): Simulation mode. Options:
             - "trade_order": Randomize trade execution order
             - "price_path": Resample price returns to create synthetic paths
@@ -402,6 +545,12 @@ def monte_carlo(
     original_equity = original_report.PnlRecord
     original_cash = float(original_report.starting_cash)
     original_orders = original_report.orders
+
+    if simulations is None:
+        if mode == MonteCarloMode.TRADE_ORDER:
+            simulations = math.factorial(len(original_orders)) if original_orders else 0
+        else:
+            simulations = 100
     
     equity_curves = []
     
@@ -446,14 +595,55 @@ def monte_carlo(
             )
             equity_curves.append(curve)
     
-    # Create result object
-    result = MonteCarloResult(
-        mode=mode,
-        equity_curves=equity_curves,
-        original_equity=original_equity,
-        simulations=simulations,
-        starting_cash=original_cash,
-    )
-    result._compute_statistics()
-    
+    # In BOTH mode we ran two distinct simulation families per iteration.
+    # Keep the results and summary statistics separate to avoid pooling
+    # different distributions into a single invalid summary.
+    if mode == MonteCarloMode.BOTH:
+        trade_curves = equity_curves[0::2]
+        price_curves = equity_curves[1::2]
+
+        trade_result = MonteCarloResult(
+            mode=MonteCarloMode.TRADE_ORDER,
+            equity_curves=trade_curves,
+            original_equity=original_equity,
+            simulations=simulations,
+            starting_cash=original_cash,
+        )
+        trade_result._compute_statistics()
+
+        price_result = MonteCarloResult(
+            mode=MonteCarloMode.PRICE_PATH,
+            equity_curves=price_curves,
+            original_equity=original_equity,
+            simulations=simulations,
+            starting_cash=original_cash,
+        )
+        price_result._compute_statistics()
+
+        result = MonteCarloResult(
+            mode=mode,
+            equity_curves=equity_curves,
+            original_equity=original_equity,
+            simulations=simulations,
+            starting_cash=original_cash,
+        )
+        result.summary_stats = {
+            "trade_order": trade_result.summary_stats,
+            "price_path": price_result.summary_stats,
+        }
+        result.percentile_results = {
+            "trade_order": trade_result.percentile_results,
+            "price_path": price_result.percentile_results,
+        }
+    else:
+        # Create result object
+        result = MonteCarloResult(
+            mode=mode,
+            equity_curves=equity_curves,
+            original_equity=original_equity,
+            simulations=simulations,
+            starting_cash=original_cash,
+        )
+        result._compute_statistics()
+
     return result