Read causal history from a strategy context

ledgr_history_frame() returns one fresh ledgr_history result for one bar field or one registered feature, read causally at the context's pulse. Every returned value is observed at or before that cutoff, with facts known by it. History is available in availability-aware contexts only: strategy contexts of availability-aware runs, sweeps and walk-forward windows, and ledgr_pulse_snapshot() called with a ledgr_experiment.

Usage

ledgr_history_frame(
  ctx,
  feature = NULL,
  bar = NULL,
  lookback,
  instruments = "admissible",
  min_observations = NULL,
  min_instruments = 1L,
  layout = c("wide", "long")
)

Arguments

ctx: A pulse context.
feature: One active feature alias or registered feature ID.
bar: One bar field: "open", "high", "low", "close" or "volume". Supply exactly one of feature and bar.
lookback: Required. Inf for all history from the data start, or a non-negative whole number of expected venue sessions ending at the cutoff.
instruments: "admissible", "decision_axis", or a character vector of known instrument IDs.
min_observations: Minimum finite treated values required per instrument. NULL requires the finite lookback, or every returned session for lookback = Inf.
min_instruments: Minimum included instruments required for ledgr_passed_warmup() to return TRUE. It does not filter columns.
layout: "wide" (one row per session, ts_utc plus one column per included instrument) or "long" (one row per session and instrument with ts_utc, instrument_id, source, value and the cell evidence).

Value

A ledgr_history data frame. Its "ledgr_history" attribute is structural provenance for the originating read, not authentication of the current numeric cells. It records the data start, returned-window start and cutoff, requested and available lookback, source, policy identity and recorded requirements, the selection table (requested, included and excluded instruments with reasons and carried input counts) and whether any value used observations before the window. Only the explicit long layout contains cell-aligned diagnostic evidence.

Details

The time axis is the declared venue's expected sessions from the data start (the first session of the experiment's snapshot) through the cutoff. A finite lookback keeps the last lookback sessions of that axis and is an exact suffix of the full (Inf) result, including carried values whose source lies before the window. Each instrument has its own expected-session mask on the common axis: a lifetime-inactive session is structural, not a missing observation, and a print inside such an interval stays readable with that structural flag.

Bar history is restated with the cutoff's knowledge. Feature history is a vintage view: each cell keeps the value and the evidence it had at its own pulse, so a fact that becomes known later changes feature cells only from its knowledge pulse on. For example, if an inactive interval at sessions 5 and 6 becomes known at session 7, a read at session 7 shows the bar prints of sessions 5 and 6 as inactive-interval prints, while their feature cells keep the valid values computed at sessions 5 and 6; the session-7 feature cell is computed with the interval known.

Bar values follow the experiment's ledgr_history_policy(): open, high, low and close carry forward within the declared expected-session horizon; volume never carries. The ordinary wide result records compact carried counts per instrument. The explicit long diagnostic layout adds cell evidence from the feature preparation: calculated means the required inputs were admitted, ready that the cell reached its segment's first-valid row, and calculation_valid a ready, finite value. A cell whose own required input was carried is input_carried; a value carried from an earlier valid cell is output_carried, with that cell's source time and age. missing_reason separates not_ready (warm-up or re-warming), calculation_non_finite (ready, but the calculation is not finite), required_input_missing, carried_input_excluded, output_carry_expired, output_carried, outside_calculation and not_expected, so every cell that is not calculation_valid has a reason. used_before_window is TRUE when any returned value used an observation or calculation state before the returned window, including carried values and bounded values whose stable_after reach (window and readiness) extends before the window, for example across inactive sessions.

instruments = "admissible" selects the decision-axis instruments that are admissible at the cutoff, "decision_axis" adds held nonmembers and restricted members, and a character vector requests known instrument IDs explicitly; unknown IDs refuse and known IDs are never dropped for current inadmissibility. min_observations excludes requested instruments with too few finite values after treatment and records the count and reason. Input- and output-carried finite values count. min_instruments records the panel readiness requirement without filtering another instrument. Exclusion is estimation only: it creates no target, zero target, liquidation or fill. The strategy still returns a target for every instrument on its decision axis.

Articles

Reading causal history: vignette("causal-history", package = "ledgr") system.file("doc", "causal-history.html", package = "ledgr")

Examples

if (FALSE) { # \dontrun{
strategy <- function(ctx, params) {
  returns <- ctx |>
    ledgr_history_frame(feature = "return_1", lookback = 20L,
                        min_instruments = 3L)
  x <- ledgr_history_matrix(returns)
  ctx$hold()
}
} # }