"""Per-run performance figures computed from a saved run's report view.
Pure functions with no Desktop or persistence access. The Desktop result page, the
batch API and evaluation reports all use these definitions (docs/user-guide/results.md).
"""
from __future__ import annotations
from typing import Any, Dict, List, Optional, Tuple
# A detached session view (see research.views).
View = Dict[str, Any]
[docs]
def fill_rows(view: View) -> List[Dict[str, Any]]:
"""Published fills joined with their order's side, for tables and chart marks."""
account = view.get('account') or {}
sides = {o['order_id']: o['side'] for o in account.get('orders', [])}
symbols = {o['order_id']: o.get('symbol') for o in account.get('orders', [])}
fills = view.get('fills')
if fills is None:
fills = [e for e in view.get('events') or [] if e['kind'] == 'fill']
return [
dict(
time_ns=e['time_ns'],
side=sides.get(e['data']['order_id']),
symbol=symbols.get(e['data']['order_id']),
quantity=e['data']['quantity'],
price=e['data']['price'],
fee=e['data']['fee'],
)
for e in fills
]
# Trading days per year used to annualise the Sharpe ratio of daily returns.
TRADING_DAYS_PER_YEAR = 252
# Fewer daily returns than this make a Sharpe ratio too noisy to rely on; the result
# page says so next to the figure.
RELIABLE_SHARPE_RETURNS = 20
[docs]
def round_trips(rows: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Pair fills into round trips with the ledger's own average-cost rule.
A round trip opens with the fill that takes the position away from zero shares,
long or short, and closes with the fill that brings it back to zero; a fill that
crosses zero closes one trip and opens the next. P&L follows domain.ledger.actions
exactly: a long's cost includes buy fees and a partial sale takes
``cost * shares // held``; a short's cost is its proceeds after fees, released in
proportion as it is covered. So the trips' P&L adds up to the ledger's realized P&L.
Returns ``trips`` (closed: open_ns, close_ns, pnl), ``realized_pnl`` (every
realization, including those inside a trip still open at the end) and ``open``.
"""
book = dict(held=0, cost=0, realized=0, opened=0, trip=0)
trips: List[Dict[str, int]] = []
def realize(pnl: int, time_ns: int) -> None:
book['realized'] += pnl
book['trip'] += pnl
if book['held'] == 0:
trips.append(dict(open_ns=book['opened'], close_ns=time_ns, pnl=book['trip']))
def open_if_flat(time_ns: int) -> None:
if book['held'] == 0:
book['opened'], book['trip'] = time_ns, 0
for row in sorted(rows, key=lambda r: r['time_ns']):
price, quantity, fee, stamp = row['price'], row['quantity'], row['fee'], row['time_ns']
held = book['held']
if row['side'] == 'buy' and held < 0:
covering = min(quantity, -held)
fee_cover = fee * covering // quantity
cost = book['cost']
released = -cost if covering == -held else -cost * covering // -held
book['held'], book['cost'] = held + covering, cost + released
realize(released - covering * price - fee_cover, stamp)
if quantity > covering:
open_if_flat(stamp)
book['held'] += quantity - covering
book['cost'] += (quantity - covering) * price + fee - fee_cover
elif row['side'] == 'buy':
open_if_flat(stamp)
book['held'], book['cost'] = held + quantity, book['cost'] + quantity * price + fee
elif quantity <= held:
cost = book['cost']
allocated = cost if quantity == held else cost * quantity // held
book['held'], book['cost'] = held - quantity, cost - allocated
realize(quantity * price - fee - allocated, stamp)
else:
closing = max(0, held)
fee_close = fee * closing // quantity
if closing:
cost = book['cost']
book['held'], book['cost'] = 0, 0
realize(closing * price - fee_close - cost, stamp)
open_if_flat(stamp)
opening = quantity - closing
book['held'] -= opening
book['cost'] -= opening * price - (fee - fee_close)
return dict(trips=trips, realized_pnl=book['realized'], open=book['held'] != 0)
[docs]
def daily_returns(
initial_cash: int, rows: List[Dict[str, Any]], closes: List[List[int]]
) -> Optional[List[float]]:
"""Daily equity returns of a one-symbol account, or None once equity is not positive.
Equity at each day's last trade price (``closes``: [day, time_ns, price]) is cash
plus shares held. The first return is measured from the starting cash.
"""
cash, held, index, previous = initial_cash, 0, 0, initial_cash
ordered = sorted(rows, key=lambda r: r['time_ns'])
returns: List[float] = []
for _, time_ns, price in closes:
while index < len(ordered) and ordered[index]['time_ns'] <= time_ns:
row = ordered[index]
notional = row['quantity'] * row['price']
sign = 1 if row['side'] == 'buy' else -1
cash -= sign * notional + row['fee']
held += sign * row['quantity']
index += 1
equity = cash + held * price
if previous <= 0:
return None
returns.append(equity / previous - 1)
previous = equity
return returns
[docs]
def sharpe_ratio(returns: Optional[List[float]]) -> Optional[float]:
"""Annualised Sharpe ratio of daily returns, or None with fewer than two or no spread.
Risk-free rate zero, sample standard deviation, scaled by the square root of 252.
"""
from statistics import mean, stdev
if returns is None or len(returns) < 2 or stdev(returns) == 0:
return None
return mean(returns) / stdev(returns) * TRADING_DAYS_PER_YEAR**0.5
[docs]
def sortino_ratio(returns: Optional[List[float]]) -> Optional[float]:
"""Annualised Sortino ratio of daily returns, or None with fewer than two or no loss.
Mean return over the downside deviation: the root mean square of every return's
shortfall below zero (gains count as zero), over all returns. Target and risk-free
rate zero, scaled by the square root of 252.
"""
from statistics import mean
if returns is None or len(returns) < 2:
return None
downside = (sum(min(r, 0.0) ** 2 for r in returns) / len(returns)) ** 0.5
if downside == 0:
return None
return mean(returns) / downside * TRADING_DAYS_PER_YEAR**0.5
[docs]
def daily_sharpe(
initial_cash: int, rows: List[Dict[str, Any]], closes: List[List[int]]
) -> Optional[float]:
"""Annualised Sharpe ratio of a one-symbol account's daily returns (daily_returns)."""
return sharpe_ratio(daily_returns(initial_cash, rows, closes))
def _apply_fill(row: Dict[str, Any], cash: int, held: Dict[Any, int]) -> int:
"""Apply one fill to cash and the per-symbol holdings; return the new cash."""
sign = 1 if row['side'] == 'buy' else -1
held[row.get('symbol')] = held.get(row.get('symbol'), 0) + sign * row['quantity']
return cash - sign * row['quantity'] * row['price'] - row['fee']
[docs]
def portfolio_daily_returns(
initial_cash: int, rows: List[Dict[str, Any]], closes: Dict[str, List[List[int]]]
) -> Tuple[int, Optional[List[float]]]:
"""(days counted, daily returns or None) of an account trading several symbols.
Each day the account is cash plus every holding at its symbol's close that day; a
symbol with no close that day keeps its last close. Fills up to the day's latest close
count. The first return is measured from the starting cash. Returns are None when a
held symbol has no close yet or equity is not positive.
"""
by_day: Dict[int, Dict[str, List[int]]] = {}
for symbol, values in closes.items():
for day, time_ns, price in values:
by_day.setdefault(day, {})[symbol] = [time_ns, price]
ordered = sorted(rows, key=lambda r: r['time_ns'])
cash, index, previous = initial_cash, 0, initial_cash
held: Dict[Any, int] = {}
last: Dict[str, int] = {}
returns: List[float] = []
for day in sorted(by_day):
cutoff = max(time_ns for time_ns, _ in by_day[day].values())
last.update({symbol: price for symbol, (_, price) in by_day[day].items()})
while index < len(ordered) and ordered[index]['time_ns'] <= cutoff:
cash = _apply_fill(ordered[index], cash, held)
index += 1
if any(quantity and symbol not in last for symbol, quantity in held.items()):
return len(returns), None
equity = cash + sum(q * last[s] for s, q in held.items() if q)
if previous <= 0:
return len(returns), None
returns.append(equity / previous - 1)
previous = equity
return len(returns), returns
[docs]
def portfolio_daily_sharpe(
initial_cash: int, rows: List[Dict[str, Any]], closes: Dict[str, List[List[int]]]
) -> Tuple[int, Optional[float]]:
"""(daily returns, annualised Sharpe ratio) of an account trading several symbols."""
days, returns = portfolio_daily_returns(initial_cash, rows, closes)
return days, sharpe_ratio(returns)
[docs]
def trade_statistics(view: View, rows: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Sharpe and Sortino ratios, win rate, turnover and average holding time of a run.
Defined in docs/user-guide/results.md. Each value is None when it cannot be
computed: a run that started with shares held, no closed round trip, or fewer than
two daily returns. ``realized_pnl`` is recomputed from the fills as a check.
"""
initial = (view.get('run') or {}).get('initial_snapshot') or {}
empty = dict(
sharpe_ratio=None,
sortino_ratio=None,
sharpe_returns=0,
sharpe_reliable=False,
win_rate=None,
round_trips=0,
winning_trips=0,
turnover=None,
average_holding_ns=None,
realized_pnl=None,
)
if not initial or initial['positions'] or any(r['side'] not in ('buy', 'sell') for r in rows):
return empty
# Each symbol is its own position; round trips are paired per symbol and added up.
by_symbol: Dict[Any, List[Dict[str, Any]]] = {}
for row in rows:
by_symbol.setdefault(row.get('symbol'), []).append(row)
paired = [round_trips(group) for group in by_symbol.values()]
trips = [trip for result in paired for trip in result['trips']]
wins = sum(1 for t in trips if t['pnl'] > 0)
traded = sum(r['quantity'] * r['price'] for r in rows)
markets = view.get('markets') or {}
daily: Optional[List[float]]
if markets:
closes = {s: m.get('daily_closes') or [] for s, m in markets.items()}
days, daily = portfolio_daily_returns(initial['cash'], rows, closes)
else:
# Older runs on several symbols saved one symbol's closes: no Sharpe for them.
several = len(by_symbol) > 1
days = 0 if several else len(view.get('daily_closes') or [])
daily = (
None
if several
else daily_returns(initial['cash'], rows, view.get('daily_closes') or [])
)
# One return per recorded day; the first is measured from the starting cash.
returns = days
return dict(
sharpe_returns=returns,
sharpe_reliable=returns >= RELIABLE_SHARPE_RETURNS,
sharpe_ratio=sharpe_ratio(daily),
sortino_ratio=sortino_ratio(daily),
win_rate=wins / len(trips) if trips else None,
round_trips=len(trips),
winning_trips=wins,
turnover=traded / initial['cash'] if initial['cash'] > 0 else None,
average_holding_ns=(
sum(t['close_ns'] - t['open_ns'] for t in trips) // len(trips) if trips else None
),
realized_pnl=sum(result['realized_pnl'] for result in paired),
)
def _curve_figures(
initial_cash: int, series: List[List[int]], rows: List[Dict[str, Any]]
) -> Dict[str, Any]:
"""Drawdown, total return and exposure of an equity curve built from ``rows``.
Total return is the last point's equity over the starting cash, minus one. Exposure
is the share of the curve's points after the first at which any position is open,
counting the fills before that point (every fill at the last point), as the curve does.
"""
ordered = sorted(rows, key=lambda r: r['time_ns'])
held: Dict[Any, int] = {}
index, exposed = 0, 0
points = series[1:]
for position, (stamp, _) in enumerate(points):
last = position == len(points) - 1
while index < len(ordered) and (last or ordered[index]['time_ns'] < stamp):
_apply_fill(ordered[index], 0, held)
index += 1
exposed += any(held.values())
return dict(
_drawdown(series),
total_return=series[-1][1] / initial_cash - 1 if initial_cash > 0 else None,
exposure=exposed / len(points) if points else None,
)
def _drawdown(series: List[List[int]]) -> Dict[str, Any]:
"""The series with its largest fall from a previous peak, in money and as a ratio."""
peak, drawdown, ratio = series[0][1], 0, 0.0
for _, equity in series:
peak = max(peak, equity)
if peak - equity > drawdown:
drawdown, ratio = peak - equity, (peak - equity) / peak if peak else 0.0
return dict(series=series, max_drawdown=drawdown, max_drawdown_ratio=ratio)
[docs]
def portfolio_series(
initial_cash: int, rows: List[Dict[str, Any]], bars: Dict[str, List[Dict[str, Any]]]
) -> Optional[List[List[int]]]:
"""[time_ns, equity] of an account on several symbols over their archived bars.
The curve starts when every symbol has a bar, at the latest first bar's open. At
each bar's end, equity is cash plus every holding at its symbol's latest close (a
symbol keeps its last close until its next bar ends). Fills before that time count.
None when a symbol has no archived bar.
"""
if not bars or any(not values for values in bars.values()):
return None
def end(bar: Dict[str, Any]) -> int:
return int(bar['end_ns'] if bar.get('complete', True) else bar['observed_through_ns'])
first = max(values[0]['start_ns'] for values in bars.values())
price = {}
for symbol, values in bars.items():
started = [b for b in values if b['start_ns'] <= first]
price[symbol] = (
started[-1]['open'] if started[-1]['start_ns'] == first else started[-1]['close']
)
events = sorted(
(end(b), symbol, b['close'])
for symbol, values in bars.items()
for b in values
if end(b) > first
)
ordered = sorted(rows, key=lambda r: r['time_ns'])
cash, index = initial_cash, 0
held: Dict[Any, int] = {}
def apply(until: Optional[int]) -> None:
nonlocal cash, index
while index < len(ordered) and (until is None or ordered[index]['time_ns'] < until):
cash = _apply_fill(ordered[index], cash, held)
index += 1
def equity() -> int:
return cash + sum(q * price[s] for s, q in held.items() if q and s in price)
apply(first)
series = [[first, equity()]]
for position, (stamp, symbol, close) in enumerate(events):
apply(None if position == len(events) - 1 else stamp)
price[symbol] = close
if series[-1][0] == stamp:
series[-1][1] = equity()
else:
series.append([stamp, equity()])
return series