ledgr

Backtests you can trust, and reopen later.

ledgr is an R package for systematic trading research. It is built so that the usual ways a backtest fools you fail loudly instead of quietly:

• A strategy sees one decision time at a time. It cannot read tomorrow's price, because tomorrow's price is not in what it receives.
• You can declare which instruments existed and were eligible on each date, so delisted instruments stay in the test instead of silently dropping out.
• A parameter sweep keeps every candidate and comes with diagnostics for selection bias, so its best result can be questioned before you trust it.
• Every run is stored with the hash of its data, its parameters, and its strategy source, so you can reopen it months later and see exactly what ran.

sealed snapshot -> experiment -> run -> event ledger -> results

What ledgr Does, And In What Order

ledgr is deliberately narrow. It does one kind of backtest completely before it adds the next:

• long-only positions in spot instruments, starting with equities;
• end-of-day decisions on daily bars, filled at the next open;
• point-in-time universes, with cash distributions and delistings modelled explicitly.

Long-only is the supported use, but not yet a default every run enforces. An availability-aware run refuses a new short and a fill the account cannot afford. A dense run does neither: a negative target opens a short with no borrow cost, margin or financing, and a fill can take cash below zero. Add ledgr_risk_long_only() to the risk chain to drop short targets in either mode, and size targets from the account's cash and equity when capital matters.

Shorting and leverage, intraday bars, other asset classes, and order types such as limits and stops come later, each only once its accounting is specified and tested. Share-changing corporate actions such as splits and mergers are next; Cash Distributions describes what is modelled today. This release does not claim corporate-action completeness, broker-exact settlement, net cash, tax correctness, or exact recipient exposure. Sub-second trading is not a goal.

If you need any of those today, another backtester will serve you better. If you need daily research you can trust and reopen later, that is what ledgr is built for.

Parallel sweeps trade time for memory because each worker receives prepared run state. In one retained v0.2.2 long-window workload, two workers peaked at 4.46 GiB. Treat that as workload-specific sizing evidence, and use workers = 1L when memory is the tighter constraint; parallel dispatch does not change strategy semantics. The Sweeps article gives the matching single-worker record and context.

Install

ledgr needs R 4.6.0 or later. Install it from GitHub. The install needs network access, so it is not run when this page is built:

if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("blechturm/ledgr")

library(ledgr)
library(dplyr)

A First Backtest

A strategy is a function of the current decision context, ctx, and your parameters, params. It returns the holdings you want after the next fill: a number of shares for every instrument.

above_trend <- function(ctx, params) {
  trend <- ctx$vec$feature("sma_20")
  if (!ledgr_passed_warmup(trend)) return(ctx$flat())
  above <- ctx$vec$close > trend * (1 + params$buffer)
  targets <- ctx$flat()
  targets[above] <- params$qty
  targets
}

This one holds qty shares of every instrument whose close is above its 20-day moving average by at least buffer, and nothing otherwise. ctx$flat() starts from zero shares for every instrument, and ctx$vec holds today's values for all of them at once. For the first 19 bars the average does not exist yet, so the strategy holds nothing until it does.

Run it on the package's demo data. The data is sealed into a snapshot first, so every run records exactly which data it used. The snapshot lives in a temporary store here; a real project passes a persistent path, so the evidence outlives the R session:

bars <- ledgr_demo_bars |>
  filter(
    instrument_id %in% c("DEMO_01", "DEMO_02", "DEMO_03"),
    between(ts_utc, ledgr_utc("2019-01-01"), ledgr_utc("2019-12-31"))
  )

snapshot <- ledgr_snapshot_from_df(
  bars,
  snapshot_id = "readme_demo",
  db_path = ledgr_temp_store()
)

exp <- ledgr_experiment(
  snapshot = snapshot,
  strategy = above_trend,
  features = list(ledgr_ind_sma(20)),
  opening = ledgr_opening(cash = 10000),
  cost_model = ledgr_cost_zero()
)

bt <- ledgr_run(
  exp,
  params = list(qty = 10, buffer = 0),
  run_id = "readme_first_run"
)
bt
#> ledgr Backtest Results
#> ======================
#>
#> Run ID:                            readme_first_run
#> Period:                            2019-01-01 to 2019-12-31
#> Opening Cash:                      $10000.00
#> Final Equity:                      $10344.56
#> Total Return:                      3.45%
#> Max Drawdown:                      -1.34%
#> Closed Trades:                     38
#> Metric Calendar:                   US equity daily (default) (252 days/year * 1 bars/day = 252 bars/year)
#>
#> Economic events: NOT SUPPLIED - returns may omit distributions
#> Price basis: UNDECLARED - distribution double counting cannot be ruled out
#>
#> Use summary(bt) for metrics and evidence

This is the beginning of the README. Read the rest at the original. Read the full README ↗