sim_platform.research.metrics¶
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).
- sim_platform.research.metrics.fill_rows(view)[source]¶
Published fills joined with their order’s side, for tables and chart marks.
- Parameters:
view (Dict[str, Any])
- Return type:
List[Dict[str, Any]]
- sim_platform.research.metrics.round_trips(rows)[source]¶
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) andopen.- Parameters:
rows (List[Dict[str, Any]])
- Return type:
Dict[str, Any]
- sim_platform.research.metrics.daily_returns(initial_cash, rows, closes)[source]¶
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.- Parameters:
initial_cash (int)
rows (List[Dict[str, Any]])
closes (List[List[int]])
- Return type:
List[float] | None
- sim_platform.research.metrics.sharpe_ratio(returns)[source]¶
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.
- Parameters:
returns (List[float] | None)
- Return type:
float | None
- sim_platform.research.metrics.sortino_ratio(returns)[source]¶
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.
- Parameters:
returns (List[float] | None)
- Return type:
float | None
- sim_platform.research.metrics.daily_sharpe(initial_cash, rows, closes)[source]¶
Annualised Sharpe ratio of a one-symbol account’s daily returns (daily_returns).
- Parameters:
initial_cash (int)
rows (List[Dict[str, Any]])
closes (List[List[int]])
- Return type:
float | None
- sim_platform.research.metrics.portfolio_daily_returns(initial_cash, rows, closes)[source]¶
(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.
- Parameters:
initial_cash (int)
rows (List[Dict[str, Any]])
closes (Dict[str, List[List[int]]])
- Return type:
Tuple[int, List[float] | None]
- sim_platform.research.metrics.portfolio_daily_sharpe(initial_cash, rows, closes)[source]¶
(daily returns, annualised Sharpe ratio) of an account trading several symbols.
- Parameters:
initial_cash (int)
rows (List[Dict[str, Any]])
closes (Dict[str, List[List[int]]])
- Return type:
Tuple[int, float | None]
- sim_platform.research.metrics.trade_statistics(view, rows)[source]¶
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_pnlis recomputed from the fills as a check.- Parameters:
view (Dict[str, Any])
rows (List[Dict[str, Any]])
- Return type:
Dict[str, Any]
- sim_platform.research.metrics.performance(view)[source]¶
Describe a saved run from its complete fills and archived bars.
Equity is cash plus the position marked at each archived bar’s close. It is a display estimate over the archived window, not a ledger or a liquidation value. Live views publish only recent events, so they receive fills without a curve.
- Parameters:
view (Dict[str, Any])
- Return type:
Dict[str, Any]
- sim_platform.research.metrics.portfolio_series(initial_cash, rows, bars)[source]¶
[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.
- Parameters:
initial_cash (int)
rows (List[Dict[str, Any]])
bars (Dict[str, List[Dict[str, Any]]])
- Return type:
List[List[int]] | None