Run a backtest (v0.1.2)

Thin wrapper around the canonical engine path.

Usage

ledgr_backtest(
  snapshot = NULL,
  strategy,
  universe = NULL,
  start = NULL,
  end = NULL,
  initial_cash = 1e+05,
  strategy_params = list(),
  features = list(),
  timing_model = ledgr_timing_next_open(),
  cost_model,
  risk_chain = ledgr_risk_none(),
  execution_mode = "audit_log",
  checkpoint_every = 10000L,
  db_path = NULL,
  control = list(),
  run_id = NULL,
  data = NULL,
  corporate_action_policy = ledgr_corporate_actions_research()
)

Arguments

snapshot

A ledgr_snapshot object, or a data frame for the data-first convenience path.

strategy

Strategy function using function(ctx, params), or a configured strategy list.

universe

Character vector of instrument IDs. If NULL, it is inferred from the snapshot or data frame.

start

Start timestamp (NULL = snapshot start).

end

End timestamp (NULL = snapshot end).

initial_cash

Starting capital. Must be a finite numeric scalar > 0.

strategy_params

JSON-safe list passed to function(ctx, params) strategies and stored as part of run provenance.

features

List of ledgr indicator or indicator-bundle definitions (optional). Bundles flatten into ordinary indicators before runtime.

timing_model

Timing model object. Defaults to ledgr_timing_next_open().

cost_model

Required ledgr cost model object. Use ledgr_cost_zero() for explicit zero-cost execution.

risk_chain

Target-risk chain object. Defaults to ledgr_risk_none() for explicit no-risk execution.

execution_mode

Execution mode ("db_live" or "audit_log").

checkpoint_every

Flush interval for audit_log mode.

db_path

Database path for the run ledger (NULL = snapshot DB).

control

Optional list of engine overrides (e.g., execution_mode).

run_id

Optional run identifier to resume or reuse.

data

Optional data frame/tibble or ledgr_snapshot. Exactly one of snapshot and data may be supplied.

corporate_action_policy

Corporate-action settlement policy. Defaults to ledgr_corporate_actions_research().

Value

A ledgr_backtest object.

Details

v0.1.7 introduces the experiment-first public workflow: ledgr_experiment() plus ledgr_run(). ledgr_backtest() remains available as a compatibility wrapper around the same canonical runner path.

Strategies return target holdings. The default timing model is next_open: a target decided at pulse t is filled at the next available bar. Targets on the final pulse therefore cannot be filled unless another bar exists after end.

Cost models are explicit. Use ledgr_cost_zero() for no-cost execution. ledgr_cost_spread_bps() treats spread_bps as a quoted bid/ask spread: buys cross half the spread above the reference price and sells cross half the spread below it, so a round trip crosses approximately spread_bps basis points before explicit fees.

v0.1.x does not provide a supported broker-style short-selling contract. Strategy authors should treat negative target quantities as outside the supported public workflow until explicit shorting semantics are specified.

Articles

Strategy authoring: vignette("strategy-development", package = "ledgr") system.file("doc", "strategy-development.html", package = "ledgr")

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"] <- if (ctx$close("AAA") > 100) 1 else 0
  targets
}
bt <- ledgr_backtest(
  data = bars,
  strategy = strategy,
  initial_cash = 1000,
  cost_model = ledgr_cost_zero()
)
print(bt)
#> ledgr Backtest Results
#> ======================
#> 
#> Run ID:                            run_1e28016bc2e22313
#> Period:                            2020-01-01 to 2020-01-04
#> Opening Cash:                      $1000.00
#> Final Equity:                      $1001.00
#> Total Return:                      0.10%
#> Max Drawdown:                      0.00%
#> Closed Trades:                     0
#> 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
close(bt)