Repository navigation
Expand file tree
/
Copy pathmetrics.py
More file actions
137 lines (111 loc) · 5.36 KB
/
Copy pathmetrics.py
File metadata and controls
137 lines (111 loc) · 5.36 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
"""Performance metrics and the accounting reconciliation.
Conventions, fixed so numbers are comparable across runs: risk-free rate is
zero, standard deviations use ``ddof=1``, and annualisation is by
``sqrt(periods_per_year)`` for volatility and ``periods_per_year`` for means.
Drawdowns are negative numbers.
``reconcile_pnl`` is the honesty check: it rebuilds the equity curve two
independent ways and asserts both agree with the engine's own curve.
"""
from __future__ import annotations
from typing import Dict, Optional
import numpy as np
import pandas as pd
# Canonical order for compute_metrics / compare_costs output.
METRIC_KEYS = ["total_return", "cagr", "sharpe", "ann_vol", "max_drawdown",
"win_rate", "n_trades", "ann_turnover_x", "final_equity"]
def infer_periods_per_year(index: pd.DatetimeIndex) -> float:
"""Guess the bar frequency from the median spacing of ``index``.
Returns 252 for daily bars (business-day gaps of 1-3 days), 52 weekly,
12 monthly, 4 quarterly, 1 annual.
"""
if len(index) < 3:
return 252.0
spacing = np.median(np.diff(np.asarray(index, dtype="datetime64[s]"))
.astype("timedelta64[s]").astype(float)) / 86400.0
if spacing <= 4.0:
return 252.0
if spacing <= 10.0:
return 52.0
if spacing <= 45.0:
return 12.0
if spacing <= 130.0:
return 4.0
return 1.0
def sharpe_ratio(returns, periods_per_year: float = 252.0) -> float:
"""Annualised Sharpe with rf = 0 and a sample (``ddof=1``) standard deviation."""
r = np.asarray(returns, dtype=float)
r = r[np.isfinite(r)]
if r.size < 2:
return float("nan")
sd = r.std(ddof=1)
if sd <= 0.0:
return float("nan")
return float(r.mean() / sd * np.sqrt(periods_per_year))
def max_drawdown(equity) -> float:
"""Deepest peak-to-trough fraction of an equity curve, as a negative number."""
e = pd.Series(equity, dtype=float)
if e.empty:
return float("nan")
return float((e / e.cummax() - 1.0).min())
def annualised_turnover(result, periods_per_year: float = 252.0) -> float:
"""Traded notional per unit of equity, per year.
Expressed as a multiple: 46x means the book traded roughly 46 times its own
size each year. Measured against mean equity over the whole run, so it is
one number describing the period rather than a per-bar quantity.
"""
n = len(result.equity)
if n == 0 or not result.fills:
return 0.0
mean_equity = float(result.equity.mean())
if mean_equity <= 0.0:
return float("nan")
return float(result.total_traded_notional / mean_equity * periods_per_year / n)
def compute_metrics(result, periods_per_year: Optional[float] = None) -> Dict[str, float]:
"""Summarise a :class:`BacktestResult` as a dict keyed by :data:`METRIC_KEYS`."""
ppy = periods_per_year or infer_periods_per_year(result.equity.index)
equity = result.equity
rets = result.returns.to_numpy(dtype=float)
n = len(equity)
start = float(result.initial_cash)
final = float(equity.iloc[-1])
total_return = final / start - 1.0
years = n / ppy
cagr = (final / start) ** (1.0 / years) - 1.0 if years > 0 and final > 0 else float("nan")
trades = result.trades
wins = sum(1 for t in trades if t.pnl > 0)
return {
"total_return": float(total_return),
"cagr": float(cagr),
"sharpe": sharpe_ratio(rets, ppy),
"ann_vol": float(rets.std(ddof=1) * np.sqrt(ppy)) if n > 1 else float("nan"),
"max_drawdown": max_drawdown(equity),
"win_rate": float(wins / len(trades)) if trades else float("nan"),
"n_trades": float(len(trades)),
"ann_turnover_x": annualised_turnover(result, ppy),
"final_equity": final,
}
def reconcile_pnl(result, verbose: bool = True) -> Dict[str, float]:
"""Rebuild the equity curve two independent ways and check both against zero.
``cash_residual`` re-derives every bar's equity from the cash ledger and the
marked position, which is the identity the engine maintains bar by bar.
``trade_residual`` ignores the curve entirely and rebuilds the *final* equity
from realised trade PnL plus the unrealised mark on whatever is still open --
a path that shares no arithmetic with the first. If frictions were being
dropped or double-counted anywhere, these two disagree.
"""
closes = result.prices["Close"].astype(float)
rebuilt = result.cash + result.position * closes
cash_residual = float(np.abs(result.equity.to_numpy() - rebuilt.to_numpy()).max())
realised = float(sum(t.pnl for t in result.trades))
final_position = float(result.meta.get("final_position", 0.0))
final_avg_cost = float(result.meta.get("final_avg_cost", 0.0))
# Works for both signs: a short has negative units and a cost basis that is
# net *proceeds*, so the same expression books its gain when price falls.
unrealised = final_position * (float(closes.iloc[-1]) - final_avg_cost)
expected_final = float(result.initial_cash) + realised + unrealised
trade_residual = float(result.equity.iloc[-1] - expected_final)
out = {"cash_residual": cash_residual, "trade_residual": trade_residual}
if verbose:
print(f"Accounting reconciliation residuals (should be ~0): {out}")
print(f"Fills: {len(result.fills)} Closed round-trip trades: {len(result.trades)}")
return out