Compare completed runs in a ledgr experiment store

Reads stored run metadata, provenance, telemetry, and result artifacts from a durable DuckDB experiment store. Strategies are not rerun, recovered source is not evaluated, and the database is not mutated.

Usage

ledgr_compare_runs(
  snapshot,
  run_ids = NULL,
  include_archived = FALSE,
  metrics = c("standard")
)

Arguments

snapshot: A sealed ledgr_snapshot object. Use ledgr_snapshot_load(db_path, snapshot_id) to resume from a durable DuckDB file in a new R session.
run_ids: Optional character vector of run IDs. If supplied, output preserves this order, including duplicates, and may include archived completed runs. If NULL, compares all non-archived completed runs.
include_archived: Logical scalar. Used only when run_ids = NULL.
metrics: Metrics set. Only "standard" is supported in v0.1.7.

Value

A ledgr_comparison object, which is a classed tibble with one row per completed run. Metric columns are raw numeric values for ranking and filtering; formatted percentages are a print-only concern. n_trades counts closed trade rows, not open-only fill rows; win_rate and avg_trade are computed over those closed trade rows. sharpe_ratio uses the default risk-free rate of 0; use ledgr_compute_metrics() directly when comparing a run with a non-zero risk-free rate.

Articles

Durable experiment stores: vignette("experiment-store", package = "ledgr") system.file("doc", "experiment-store.html", package = "ledgr")

Metrics and accounting: vignette("metrics-and-accounting", package = "ledgr") system.file("doc", "metrics-and-accounting.html", package = "ledgr")

Examples

bars <- subset(ledgr_demo_bars, instrument_id == "DEMO_01")
snapshot <- ledgr_snapshot_from_df(utils::head(bars, 30))
strategy <- function(ctx, params) {
  targets <- ctx$flat()
  targets["DEMO_01"] <- params$qty
  targets
}
exp <- ledgr_experiment(snapshot, strategy, opening = ledgr_opening(cash = 1000))
bt_a <- ledgr_run(exp, params = list(qty = 1), run_id = "qty-1")
on.exit(close(bt_a), add = TRUE)
bt_b <- ledgr_run(exp, params = list(qty = 2), run_id = "qty-2")
on.exit(close(bt_b), add = TRUE)
ledgr_compare_runs(snapshot, run_ids = c("qty-1", "qty-2"))
#> # ledgr comparison
#> # A tibble: 2 × 9
#>   run_id label final_equity total_return sharpe_ratio max_drawdown n_trades
#>   <chr>  <chr>        <dbl> <chr>               <dbl> <chr>           <int>
#> 1 qty-1  NA            998. -0.2%               -1.57 -0.3%               0
#> 2 qty-2  NA            997. -0.3%               -1.56 -0.6%               0
#> # ℹ 2 more variables: win_rate <chr>, reproducibility_level <chr>
#> 
#> # i Full identity and telemetry columns remain available on this tibble.
#> # i Inspect one run with ledgr_run_info(snapshot, run_id).
ledgr_snapshot_close(snapshot)