Merge pull request #18 from AKKI0511/codex/create-backtester-script-with-metrics

Add simple backtesting utilities

Author: AKKI0511

README.md

@@ -137,6 +137,20 @@ python -m src.main evaluate -m models/trained/MY_MODEL           # evaluate
 the full training pipeline. `evaluate` loads an existing model directory and
 generates evaluation metrics.
 
+## Backtesting
+
+Use the backtester to evaluate label-based trading signals:
+
+```python
+from backtest.backtester import simulate_trades, compute_metrics
+import pandas as pd
+
+df = pd.read_parquet("data/processed/AAPL.parquet")
+df = simulate_trades(df)
+metrics = compute_metrics(df)
+print(metrics)
+```
+
 ## Competition Evaluation Metrics
 
 ### Trade-Level Analytics

src/backtest/backtester.py

@@ -0,0 +1,55 @@
+import pandas as pd
+
+from utils.metrics import sharpe_ratio, max_drawdown
+
+
+def simulate_trades(df: pd.DataFrame) -> pd.DataFrame:
+    """Simulate trades using label signals.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame containing ``Close`` prices and a ``label`` column where
+        1 indicates a long position, -1 a short position and 0 no position.
+
+    Returns
+    -------
+    pd.DataFrame
+        Input DataFrame with additional ``strategy_return`` and
+        ``equity_curve`` columns.
+    """
+    data = df.copy()
+    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)
+    data["equity_curve"] = (1 + data["strategy_return"]).cumprod()
+    return data
+
+
+def compute_metrics(data: pd.DataFrame, risk_free_rate: float = 0.0) -> dict:
+    """Calculate basic performance metrics for a strategy.
+
+    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,
+    }

tests/backtest/test_backtester.py

@@ -0,0 +1,43 @@
+import unittest
+import os
+import sys
+import pandas as pd
+
+# add src to path
+sys.path.insert(
+    0,
+    os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "src")),
+)
+
+from backtest.backtester import simulate_trades, compute_metrics  # noqa: E402
+
+
+class TestBacktester(unittest.TestCase):
+    def setUp(self):
+        close = [10, 11, 10, 12, 11]
+        labels = [1, 0, -1, 1, -1]
+        self.df = pd.DataFrame({"Close": close, "label": labels})
+
+    def test_simulate_trades(self):
+        result = simulate_trades(self.df)
+        expected_returns = pd.Series(
+            [0.1, 0.0, -0.2, -0.083333, 0.0],
+            name="strategy_return",
+        )
+        pd.testing.assert_series_equal(
+            result["strategy_return"].round(6).reset_index(drop=True),
+            expected_returns.round(6),
+            check_names=False,
+        )
+        self.assertIn("equity_curve", result.columns)
+
+    def test_compute_metrics(self):
+        result = simulate_trades(self.df)
+        metrics = compute_metrics(result)
+        self.assertAlmostEqual(metrics["cumulative_return"], -0.193333, places=6)
+        self.assertIn("sharpe_ratio", metrics)
+        self.assertIn("max_drawdown", metrics)
+
+
+if __name__ == "__main__":
+    unittest.main()