Skip to contents

Summarize a backtest result

Source: R/backtest.R
summary.ledgr_backtest.Rd

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;

  • total 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, total 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.

Articles

Metrics and accounting: vignette("metrics-and-accounting", package = "ledgr") system.file("doc", "metrics-and-accounting.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
#> ======================
#> 
#> 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:
#>   Total Trades:        0
#>   Win Rate:            N/A (no trades)
#>   Avg Trade:           N/A (no trades)
#> 
#> Exposure:
#>   Time in Market:      75.00%
close(bt)