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", risk_free_rate = 0, ...)

Arguments

object

A ledgr_backtest object.

metrics

Only "standard" is supported in v0.1.7.

risk_free_rate

Scalar annual risk-free rate as a decimal. The default is 0.

...

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 detected bar frequency;

  • 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 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)
summary(bt)
#> ledgr Backtest Summary
#> ======================
#> 
#> Performance Metrics:
#>   Total Return:        0.20%
#>   Annualized Return:   18.27%
#>   Max Drawdown:        0.00%
#> 
#> Risk Metrics:
#>   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)