Merge pull request #34 from AKKI0511/add-configurable-transaction-costs-and-slippage

[backtest] Add configurable transaction costs, slippage, and liquidity cap; net performance metrics; CLI and docs updates

Author: AKKI0511

config/backtest_config.yaml

@@ -0,0 +1,17 @@
+execution:
+  transaction_costs:
+    enabled: false
+    mode: bps
+    value: 0
+    apply_on: notional
+  slippage:
+    enabled: false
+    mode: bps
+    value: 0
+    reference_price: close
+  liquidity:
+    enabled: false
+    max_participation: 0.1
+    volume_source: bar_volume
+# sample data path for CLI backtest
+data_path: data/backtest_sample.csv

docs/configuration.md

@@ -4,10 +4,11 @@ Learn how to configure QuantTradeAI for your specific needs.
 
 ## 📁 Configuration Files
 
-The framework uses two main configuration files:
+The framework uses several configuration files:
 
 - **`config/model_config.yaml`** - Model parameters and data settings
 - **`config/features_config.yaml`** - Feature engineering settings
+- **`config/backtest_config.yaml`** - Execution settings for backtests
 
 ## 🔧 Model Configuration
 
@@ -83,6 +84,26 @@ trading:
   transaction_cost: 0.001
 ```
 
+### Backtest Execution
+
+```yaml
+execution:
+  transaction_costs:
+    enabled: true
+    mode: bps         # bps or fixed
+    value: 5          # 5 bps = 0.05%
+    apply_on: notional
+  slippage:
+    enabled: true
+    mode: bps
+    value: 10
+    reference_price: close  # or mid if available
+  liquidity:
+    enabled: false
+    max_participation: 0.1
+    volume_source: bar_volume
+```
+
 ## 🔧 Feature Configuration
 
 ### Price Features

docs/examples/execution-costs.md

@@ -0,0 +1,10 @@
+# Execution Costs Example
+
+Run a simple backtest with and without execution costs and slippage.
+
+```bash
+poetry run quanttradeai backtest --config config/backtest_config.yaml
+poetry run quanttradeai backtest --cost-bps 5 --slippage-bps 10
+```
+
+The second command applies 5 bps transaction costs and 10 bps slippage, producing lower Sharpe ratio and PnL compared to the gross run.

docs/quick-reference.md

@@ -17,6 +17,10 @@ poetry run quanttradeai train
 
 # Evaluate model
 poetry run quanttradeai evaluate -m models/trained/AAPL
+
+# Run backtest
+poetry run quanttradeai backtest --config config/backtest_config.yaml
+poetry run quanttradeai backtest --cost-bps 5 --slippage-bps 10
 ```
 
 ## 📊 Python API Patterns

quanttradeai/backtest/backtester.py

@@ -18,7 +18,6 @@
 """
 
 import pandas as pd
-
 from quanttradeai.utils.metrics import sharpe_ratio, max_drawdown
 from quanttradeai.trading.risk import apply_stop_loss_take_profit
 from quanttradeai.trading.portfolio import PortfolioManager
@@ -28,24 +27,125 @@ def _simulate_single(
     df: pd.DataFrame,
     stop_loss_pct: float | None = None,
     take_profit_pct: float | None = None,
-    transaction_cost: float = 0.0,
-    slippage: float = 0.0,
+    execution: dict | None = None,
 ) -> pd.DataFrame:
-    """Simulate trades for a single symbol."""
+    """Simulate trades for a single symbol with execution effects."""
     data = df.copy()
     if stop_loss_pct is not None or take_profit_pct is not None:
         data = apply_stop_loss_take_profit(data, stop_loss_pct, take_profit_pct)
-    data["price_return"] = data["Close"].pct_change()
-    data["strategy_return"] = data["price_return"].shift(-1) * data["label"]
-    data["strategy_return"] = data["strategy_return"].fillna(0.0)
-
-    trade_cost = transaction_cost + slippage
-    if trade_cost > 0:
-        trades = data["label"].diff().abs()
-        trades.iloc[0] = abs(data["label"].iloc[0])
-        data["strategy_return"] -= trades * trade_cost
 
+    exec_cfg = execution or {}
+    tc = exec_cfg.get("transaction_costs", {})
+    sl = exec_cfg.get("slippage", {})
+    liq = exec_cfg.get("liquidity", {})
+
+    ref_col = "Close"
+    if sl.get("reference_price", "close") == "mid" and "Mid" in data.columns:
+        ref_col = "Mid"
+    prices = data[ref_col].astype(float)
+    volumes = data.get("Volume", pd.Series(float("inf"), index=data.index))
+
+    position = 0.0
+    carry = 0.0
+    entry_price: float | None = None
+    gross_returns: list[float] = [0.0] * len(data)
+    net_returns: list[float] = [0.0] * len(data)
+    ledger: list[dict] = []
+
+    for i in range(len(data)):
+        price = prices.iloc[i]
+        volume = volumes.iloc[i] if i < len(volumes) else float("inf")
+        desired = data["label"].iloc[i] + carry
+
+        diff = desired - position
+        side = 1 if diff > 0 else -1 if diff < 0 else 0
+        qty = abs(diff)
+        total_cost = 0.0
+
+        if side != 0 and qty > 0:
+            if liq.get("enabled", False):
+                max_part = liq.get("max_participation", 0.0)
+                max_qty = max_part * float(volume)
+                exec_qty = min(qty, max_qty)
+                carry = qty - exec_qty
+            else:
+                exec_qty = qty
+                carry = 0.0
+
+            if exec_qty > 0:
+                slip_amt = 0.0
+                slip_bps = 0.0
+                if sl.get("enabled", False) and sl.get("value", 0) > 0:
+                    if sl.get("mode", "bps") == "bps":
+                        slip_bps = sl["value"]
+                        slip_amt = price * slip_bps / 10000
+                    else:
+                        slip_amt = sl["value"]
+                        slip_bps = slip_amt / price * 10000
+                fill_price = price + slip_amt if side > 0 else price - slip_amt
+
+                t_cost = 0.0
+                if tc.get("enabled", False) and tc.get("value", 0) > 0:
+                    if tc.get("mode", "bps") == "bps":
+                        t_cost = price * exec_qty * tc["value"] / 10000
+                    else:
+                        if tc.get("apply_on", "notional") == "shares":
+                            t_cost = tc["value"] * exec_qty
+                        else:
+                            t_cost = tc["value"]
+
+                sl_cost = abs(slip_amt) * exec_qty
+                total_cost = t_cost + sl_cost
+
+                gross_pnl = 0.0
+                if position != 0 and side != (1 if position > 0 else -1):
+                    close_qty = min(abs(position), exec_qty)
+                    if position > 0:
+                        gross_pnl = (fill_price - entry_price) * close_qty
+                    else:
+                        gross_pnl = (entry_price - fill_price) * close_qty
+                    if exec_qty > close_qty:
+                        entry_price = fill_price
+                elif position == 0:
+                    entry_price = fill_price
+                elif side == (1 if position > 0 else -1):
+                    entry_price = (
+                        entry_price * abs(position) + fill_price * exec_qty
+                    ) / (abs(position) + exec_qty)
+
+                position += side * exec_qty
+                if position == 0:
+                    entry_price = None
+
+                ledger.append(
+                    {
+                        "timestamp": data.index[i],
+                        "side": "buy" if side > 0 else "sell",
+                        "qty": exec_qty,
+                        "reference_price": price,
+                        "fill_price": fill_price,
+                        "gross_pnl_contrib": gross_pnl,
+                        "transaction_cost": t_cost,
+                        "slippage_cost": sl_cost,
+                        "costs": total_cost,
+                        "slippage_bps_applied": slip_bps,
+                        "net_pnl_contrib": gross_pnl - total_cost,
+                    }
+                )
+
+        if i < len(data) - 1:
+            price_next = prices.iloc[i + 1]
+            gross_ret = (price_next - price) / price * position
+            cost_return = total_cost / price if price else 0.0
+            gross_returns[i] = gross_ret
+            net_returns[i] = gross_ret - cost_return
+    gross_returns[-1] = 0.0
+    net_returns[-1] = 0.0
+    data["gross_return"] = pd.Series(gross_returns, index=data.index)
+    data["strategy_return"] = pd.Series(net_returns, index=data.index)
+    data["gross_equity_curve"] = (1 + data["gross_return"]).cumprod()
     data["equity_curve"] = (1 + data["strategy_return"]).cumprod()
+    data.attrs["ledger"] = pd.DataFrame(ledger)
     return data
 
 
@@ -55,6 +155,7 @@ def simulate_trades(
     take_profit_pct: float | None = None,
     transaction_cost: float = 0.0,
     slippage: float = 0.0,
+    execution: dict | None = None,
     portfolio: PortfolioManager | None = None,
 ) -> pd.DataFrame | dict[str, pd.DataFrame]:
     """Simulate trades using label signals.
@@ -72,9 +173,14 @@ def simulate_trades(
         Take profit percentage applied to each trade. ``None`` disables take
         profits.
     transaction_cost : float, optional
-        Fixed cost applied every time a position is opened or closed.
+        Legacy cost per trade (as fraction of notional). Converted to execution
+        config if provided.
     slippage : float, optional
-        Additional cost applied on each trade to model slippage.
+        Legacy slippage per trade (as fraction of notional). Converted to
+        execution config if provided.
+    execution : dict, optional
+        Execution configuration controlling transaction costs, slippage and
+        liquidity limits.
     portfolio : PortfolioManager or None, optional
         Portfolio manager used to allocate capital when backtesting multiple
         symbols. Required if ``df`` is a dictionary.
@@ -87,6 +193,18 @@ def simulate_trades(
         dictionary, returns a dictionary with per-symbol results as well as an
         aggregated ``"portfolio"`` entry containing the combined equity curve.
     """
+    exec_cfg = execution.copy() if execution else {}
+    if transaction_cost:
+        exec_cfg.setdefault("transaction_costs", {})
+        exec_cfg["transaction_costs"].update(
+            {"enabled": True, "mode": "bps", "value": transaction_cost * 10000}
+        )
+    if slippage:
+        exec_cfg.setdefault("slippage", {})
+        exec_cfg["slippage"].update(
+            {"enabled": True, "mode": "bps", "value": slippage * 10000}
+        )
+
     if isinstance(df, dict):
         if portfolio is None:
             raise ValueError("portfolio manager required for multiple symbols")
@@ -97,8 +215,7 @@ def simulate_trades(
                 data,
                 stop_loss_pct=stop_loss_pct,
                 take_profit_pct=take_profit_pct,
-                transaction_cost=transaction_cost,
-                slippage=slippage,
+                execution=exec_cfg,
             )
             results[symbol] = res
             qty = portfolio.open_position(symbol, data["Close"].iloc[0], stop_loss_pct)
@@ -120,35 +237,12 @@ def simulate_trades(
             df,
             stop_loss_pct=stop_loss_pct,
             take_profit_pct=take_profit_pct,
-            transaction_cost=transaction_cost,
-            slippage=slippage,
+            execution=exec_cfg,
         )
 
 
 def compute_metrics(data: pd.DataFrame, risk_free_rate: float = 0.0) -> dict:
-    """Calculate basic performance metrics for a strategy.
+    """Return gross and net performance summary."""
+    from quanttradeai.utils.metrics import compute_performance
 
-    Parameters
-    ----------
-    data : pd.DataFrame
-        Output from :func:`simulate_trades` containing ``strategy_return`` and
-        ``equity_curve`` columns.
-    risk_free_rate : float, optional
-        Annual risk free rate used in Sharpe ratio, by default 0.0.
-
-    Returns
-    -------
-    dict
-        Dictionary with ``cumulative_return``, ``sharpe_ratio`` and
-        ``max_drawdown`` keys.
-    """
-    returns = data["strategy_return"]
-    equity = data["equity_curve"]
-    cumulative_return = equity.iloc[-1] - 1
-    sharpe = sharpe_ratio(returns, risk_free_rate)
-    mdd = max_drawdown(equity)
-    return {
-        "cumulative_return": cumulative_return,
-        "sharpe_ratio": sharpe,
-        "max_drawdown": mdd,
-    }
+    return compute_performance(data, risk_free_rate)

quanttradeai/main.py

@@ -15,6 +15,7 @@
 from quanttradeai.data.processor import DataProcessor
 from quanttradeai.data.datasource import WebSocketDataSource
 import pandas as pd
+from quanttradeai.backtest.backtester import simulate_trades, compute_metrics
 from quanttradeai.models.classifier import MomentumClassifier
 from sklearn.model_selection import train_test_split
 import yaml
@@ -188,6 +189,25 @@ def main():
         "-m", "--model-path", required=True, help="Directory containing saved model"
     )
 
+    backtest_parser = subparsers.add_parser("backtest", help="Run backtest")
+    backtest_parser.add_argument(
+        "-c",
+        "--config",
+        default="config/backtest_config.yaml",
+        help="Path to backtest config",
+    )
+    grp_cost = backtest_parser.add_mutually_exclusive_group()
+    grp_cost.add_argument("--cost-bps", type=float, help="Transaction cost in bps")
+    grp_cost.add_argument("--cost-fixed", type=float, help="Fixed transaction cost")
+    grp_slip = backtest_parser.add_mutually_exclusive_group()
+    grp_slip.add_argument("--slippage-bps", type=float, help="Slippage in bps")
+    grp_slip.add_argument("--slippage-fixed", type=float, help="Fixed slippage amount")
+    backtest_parser.add_argument(
+        "--liquidity-max-participation",
+        type=float,
+        help="Override liquidity max participation",
+    )
+
     live_parser = subparsers.add_parser(
         "live-trade", help="Run real-time trading pipeline"
     )
@@ -206,6 +226,39 @@ def main():
         run_pipeline(args.config)
     elif args.command == "evaluate":
         evaluate_model(args.config, args.model_path)
+    elif args.command == "backtest":
+        with open(args.config, "r") as f:
+            cfg = yaml.safe_load(f)
+        exec_cfg = cfg.get("execution", {})
+        if args.cost_bps is not None:
+            exec_cfg.setdefault("transaction_costs", {})
+            exec_cfg["transaction_costs"].update(
+                {"enabled": True, "mode": "bps", "value": args.cost_bps}
+            )
+        if args.cost_fixed is not None:
+            exec_cfg.setdefault("transaction_costs", {})
+            exec_cfg["transaction_costs"].update(
+                {"enabled": True, "mode": "fixed", "value": args.cost_fixed}
+            )
+        if args.slippage_bps is not None:
+            exec_cfg.setdefault("slippage", {})
+            exec_cfg["slippage"].update(
+                {"enabled": True, "mode": "bps", "value": args.slippage_bps}
+            )
+        if args.slippage_fixed is not None:
+            exec_cfg.setdefault("slippage", {})
+            exec_cfg["slippage"].update(
+                {"enabled": True, "mode": "fixed", "value": args.slippage_fixed}
+            )
+        if args.liquidity_max_participation is not None:
+            exec_cfg.setdefault("liquidity", {})
+            exec_cfg["liquidity"].update(
+                {"enabled": True, "max_participation": args.liquidity_max_participation}
+            )
+        df = pd.read_csv(cfg["data_path"])
+        result = simulate_trades(df, execution=exec_cfg)
+        metrics = compute_metrics(result)
+        print(metrics)
     elif args.command == "live-trade":
         import asyncio