Freeze a pulse snapshot for strategy development — ledgr_pulse

ledgr_pulse_snapshot() constructs one strategy context outside execution so that an author can inspect it or call a strategy manually. It is an external development and inspection helper: a strategy never calls it.

Usage

ledgr_pulse_snapshot(
  snapshot,
  universe,
  ts_utc,
  features = list(),
  feature_params = list(),
  cash = 1e+05,
  positions = NULL,
  state_prev = NULL,
  params = NULL
)

Arguments

snapshot: A ledgr_snapshot, or an availability-aware ledgr_experiment for experiment-derived inspection. With an experiment, supply only ts_utc (by name), params and feature_params.
universe: Character vector of instruments (snapshot form only).
ts_utc: Timestamp to freeze at. For an experiment it must name one session close of the declared venue; a Date selects that session's close.
features: List of ledgr_indicator objects to compute.
feature_params: JSON-safe list used to resolve parameterized feature declarations when features (or the experiment's features) is a feature map.
cash: Cash held alongside positions. It is not total account value; pulse equity is cash + sum(positions * current close).
positions: Named numeric vector of positions (NULL = flat).
state_prev: Optional JSON-safe previous strategy state. This supports dense one-pulse strategy checks; availability-aware state normalization is not simulated.
params: JSON-safe strategy parameters used to resolve the experiment's feature factory and risk plan, as in ledgr_run() (experiment form only).

Value

A ledgr_pulse_context object with the accessors and planes of the strategy context (see ?ledgr_strategy_context). The snapshot form makes every instrument a member.

Details

Called with an availability-aware ledgr_experiment, it derives everything from that experiment and its concrete parameters: snapshot, universe, features, history policy, data start and opening state. It returns the context that a run of the experiment starting at ts_utc passes to its strategy on that first pulse, built by the same observe-and-settle and context stages over the same shared preparation. It calls no strategy and creates no fills, events, run rows or other durable state. The context supports ledgr_history_frame().

Called with a ledgr_snapshot, the snapshot-and-universe form builds a dense context from the given universe, features and positions. That form has no causal history: ledgr_history_frame() refuses it.

Examples

bars <- data.frame(
  ts_utc = as.POSIXct("2020-01-01", tz = "UTC") + 86400 * 0:3,
  instrument_id = "AAA",
  open = 100:103,
  high = 101:104,
  low = 99:102,
  close = 100:103,
  volume = 1000
)
snapshot <- ledgr_snapshot_from_df(bars)
pulse <- ledgr_pulse_snapshot(
  snapshot,
  universe = "AAA",
  ts_utc = "2020-01-03T00:00:00Z",
  features = list(ledgr_ind_sma(2)),
  positions = c(AAA = 2),
  state_prev = list(pulses_seen = 1)
)
pulse$close("AAA")
#> [1] 102
pulse$feature("AAA", "sma_2")
#> [1] 101.5
pulse$state_prev
#> $pulses_seen
#> [1] 1
#> 
close(pulse)
ledgr_snapshot_close(snapshot)