Define a reusable ledgr experiment — ledgr

ledgr_experiment() bundles a sealed snapshot, strategy, features, opening state, and execution options into the experiment-first public object used by the v0.1.7 workflow. The constructor validates shape only; it does not run a strategy or write run artifacts.

Usage

ledgr_experiment(
  snapshot,
  strategy,
  features = list(),
  opening = ledgr_opening(cash = 1e+05),
  universe = NULL,
  timing_model = ledgr_timing_next_open(),
  cost_model,
  risk_chain = ledgr_risk_none(),
  fill_model = NULL,
  persist_features = TRUE,
  execution_mode = "audit_log",
  metric_context = NULL,
  risk_free_rate = NULL
)

Arguments

snapshot: A sealed ledgr_snapshot.
strategy: A function with signature function(ctx, params).
features: List of ledgr_indicator/ledgr_indicator_bundle objects, a single indicator or bundle, or a ledgr_feature_map. Compatibility note: function(params) feature factories remain supported for old flat-grid and advanced exact-ID workflows, but new parameterized feature sweeps should use ledgr_feature_map() with ledgr_param(), ledgr_feature_grid(), ledgr_strategy_grid(), and ledgr_grid_cross().
opening: A ledgr_opening object.
universe: Character vector of instrument IDs, or NULL for all instruments in the snapshot.
timing_model: Timing model object. Defaults to ledgr_timing_next_open(). The timing model proposes fills; cost models resolve fill prices and explicit fees.
cost_model: Required ledgr cost model object. Use ledgr_cost_zero() for explicit zero-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.
risk_chain: Target-risk chain object. Defaults to ledgr_risk_none() for explicit no-risk execution.
fill_model: Legacy v0.1.8 fill model argument. Supplying it now fails with ledgr_legacy_fill_model_shape; use timing_model plus cost_model.
persist_features: Logical scalar.
execution_mode: Execution mode ("audit_log" or "db_live").
metric_context: Optional ledgr_metric_context object or scalar annual risk-free rate shorthand. NULL uses the default metric context.
risk_free_rate: Optional shorthand for the annual risk-free rate. Supply either metric_context or risk_free_rate, not both.

Value

A ledgr_experiment object.

Articles

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

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

Reproducibility model: vignette("reproducibility", package = "ledgr") system.file("doc", "reproducibility.html", package = "ledgr")

Examples

bars <- data.frame(
  ts_utc = as.POSIXct("2020-01-01", tz = "UTC") + 86400 * 0:2,
  instrument_id = "AAA",
  open = c(100, 101, 102),
  high = c(101, 102, 103),
  low = c(99, 100, 101),
  close = c(100, 101, 102),
  volume = 1000
)
snapshot <- ledgr_snapshot_from_df(bars)
strategy <- function(ctx, params) {
  stats::setNames(rep(0, length(ctx$universe)), ctx$universe)
}
exp <- ledgr_experiment(snapshot, strategy, cost_model = ledgr_cost_zero())
inherits(exp, "ledgr_experiment")
#> [1] TRUE
ledgr_snapshot_close(snapshot)