Stats summarises a finished run into returns, risk-adjusted ratios, drawdowns, trade statistics,
fee statistics, and return distributions. It reads the equity curve and trades the portfolio
recorded over the backtest.
Producing a Stats
Callcalculate_stats on a completed strategy, or build one directly:
risk_free_rate defaults to 0.0. pulses_per_year defaults to
None, which reads strategy.pulse_index.pulses_per_year so the annualization matches the actual
cadence of the simulation.
What is on a Stats
The fields below all exist onStats and are populated from the equity curve and trades.
Returns
Risk-adjusted ratios
Sharpe penalises all variability, up and down alike. Sortino only counts the downside, so it suits a
strategy whose upside is choppy but whose losses are what you actually care about (e.g. an option
seller). Calmar ignores volatility entirely and asks how much annual growth you earned per unit of
worst-case loss, which is the framing a drawdown-sensitive allocator uses.
Drawdown
max_drawdown is the worst single hole; avg_drawdown describes the typical hole and is less driven
by one bad event. Time-underwater answers “how long was I stuck below my high-water mark”, which is
the metric an investor feels even when the depth is modest.
Trade statistics
trade_stats is a TradeStats aggregated at the position level (legs opened together count as one
position). Key fields:
Win rate alone is misleading: a strategy can win 90% of the time and still lose money if the rare
losers are huge. Profit factor and expectancy weight by size, so read them together with win rate.
Fee statistics
fee_stats is a FeeStats (total_fees, fee_drag_pct, avg_fee_per_trade,
fees_pct_of_gross_pnl, max_pulse_fees, max_pulse_fees_datetime). See Fees for how
they are charged and read back.
Return distributions
Stats also carries daily, monthly, and yearly breakdowns: daily_mean, daily_vol, daily_skew,
daily_kurt; monthly_returns, monthly_mean, monthly_vol, best_month, worst_month, mtd,
three_month, six_month, pos_month_perc, avg_up_month, avg_down_month; yearly_returns,
ytd, one_year, three_year, five_year, ten_year, yearly_mean, yearly_vol, best_year,
worst_year, win_year_perc, twelve_month_win_perc.
Returns are read off equity, which is net of feesAll the return and ratio fields derive from
equity_history, so they already reflect any fees
charged. To see the gross-vs-net gap explicitly, compare against pulse_total_pnl_history. See
Portfolio, equity and PnL.Greeks PnL decomposition
pnl_decomposition splits the PnL of a group of trades (usually strategy.trades, or any subset of
it) into what delta, gamma, vega and theta explain, pulse by pulse, plus the residual they leave:
delta * dS,
0.5 * gamma * dS**2, vega * d_iv * 100 and theta * calendar_days, times the units held and the
price format multiplier. actual_pnl is the engine’s gross per-pulse PnL, so the residual collects
what a second-order expansion misses: cross terms such as vanna, a fill-price haircut on a trade’s
first mark after open, and noise in the vendor greeks. Pass by_trade=True for one row per trade per pulse,
with trade_id, instrument and tags to group by. Calendar-spread option roots quote a normal vol
and are not supported yet.
Related: Portfolio, equity and PnL · Fees · Greeks ·
Architecture and the pulse loop
