Summarize a backtest result

Prints standard performance, risk, trade, and exposure metrics.

Usage

# S3 method for class 'ledgr_backtest'
summary(
  object,
  metrics = "standard",
  metric_context = NULL,
  risk_free_rate = NULL,
  ...
)

Arguments

object

A ledgr_backtest object.

metrics

Only "standard" is supported.

metric_context

Optional metric context override for this summary. When omitted, ledgr uses the metric context stored with the run.

risk_free_rate

Optional scalar annual risk-free-rate override as a decimal. Supply either metric_context or risk_free_rate, not both.

...

Unused.

Value

The input ledgr_backtest object, invisibly. The printed values are descriptive output; use ledgr_compute_metrics() for a named list of the same metric values.

Details

The standard summary displays:

• total return: last public equity row divided by the first public equity row minus 1;

• annualized return: geometric annualized return from the first and last public equity rows using the metric context's annualization calendar;

• max drawdown: maximum peak-to-trough decline, min(equity / cummax(equity) - 1);

• annualized volatility: standard deviation of adjacent equity-row returns multiplied by sqrt(bars_per_year);

• Sharpe ratio: annualized ratio of average period excess return to excess-return standard deviation, using the metric context's scalar annual risk-free rate converted to a per-period return;

• Closed Trades: number of closed trade rows, not number of fill rows;

• win rate: share of closed trade rows with strict realized_pnl > 0;

• average trade: mean realized_pnl across closed trade rows;

• time in market: share of equity rows with absolute positions_value > 1e-6.

If there are no closed trade rows, Closed Trades is zero and win rate and average trade are printed as not available. If registered features cannot become usable because an instrument has fewer bars than the feature contract requires, the summary prints a compact Warmup Diagnostics section naming the feature ID, instrument ID, required bars, and available bars. Availability-aware runs also print their recorded completion evidence: requested and achieved windows, stop reason, last fully valued and executed times, complete or incomplete performance, and affected identifiers. When that evidence says performance is incomplete, the achieved-window block keeps prefix total return and maximum drawdown visible, but withholds annualized return, annualized volatility, and Sharpe ratio with an explicit explanation.

Articles

Metrics and accounting: vignette("metrics-and-accounting", package = "ledgr") system.file("doc", "metrics-and-accounting.html", package = "ledgr") Availability and durable explanations: vignette("survivorship-bias", package = "ledgr") system.file("doc", "survivorship-bias.html", package = "ledgr")

Examples

bars <- data.frame(
  ts_utc = as.POSIXct("2020-01-01", tz = "UTC") + 86400 * 0:3,
  instrument_id = "AAA",
  open = c(100, 101, 102, 103),
  high = c(101, 102, 103, 104),
  low = c(99, 100, 101, 102),
  close = c(100, 101, 102, 103),
  volume = 1000
)
strategy <- function(ctx, params) {
  targets <- ctx$flat()
  targets["AAA"] <- 1
  targets
}
bt <- ledgr_backtest(data = bars, strategy = strategy, initial_cash = 1000, cost_model = ledgr_cost_zero())
summary(bt)
#> ledgr Backtest Summary
#> ======================
#> 
#> Execution Evidence:
#>   Fill Timing:         dense_bar_timestamp
#>   Timing Version:      N/A
#> 
#> Performance Metrics:
#>   Total Return:        0.20%
#>   Annualized Return:   18.27%
#>   Max Drawdown:        0.00%
#> 
#> Risk Metrics:
#>   Risk-Free Rate:      0.00% annual
#>   Annualization:       252 periods/year (US equity daily)
#>   Volatility (annual): 0.92%
#>   Sharpe Ratio:        18.330
#> 
#> Trade Statistics:
#>   Closed Trades:       0
#>   Win Rate:            N/A (no trades)
#>   Avg Trade:           N/A (no trades)
#> 
#> Exposure:
#>   Time in Market:      75.00%
close(bt)