Point-in-time availability facts — ledgr

These constructors normalize point-in-time membership, trading-status, session-calendar, and lifetime evidence before snapshot creation. Effective intervals are half-open: effective_from is included and effective_to is excluded. Missing knowledge time remains audit-only unless knowledge = "assume_effective" is declared.

Usage

ledgr_facts_membership_intervals(
  df,
  universe_id,
  knowledge = c("evidenced", "assume_effective")
)

ledgr_facts_membership_snapshots(
  df,
  universe_id,
  complete = TRUE,
  knowledge = c("evidenced", "assume_effective")
)

ledgr_facts_trading_status(df, knowledge = c("evidenced", "assume_effective"))

ledgr_facts_lifetime(df, knowledge = c("evidenced", "assume_effective"))

ledgr_facts_sessions(
  df,
  venue_id,
  knowledge = c("evidenced", "assume_effective"),
  timezone = "UTC"
)

ledgr_facts(...)

Arguments

df: A data frame containing one fact row per assertion. See Details.
universe_id: A non-empty identifier for the membership universe.
knowledge: Either "evidenced" or "assume_effective".
complete: Logical scalar or one value per input row. Complete membership snapshots establish omitted instruments as non-members; partial snapshots leave omission unknown. Values must agree within each dated snapshot group.
venue_id: A non-empty venue identifier.
timezone: An IANA timezone used to interpret session dates and times.
...: Fact-family objects returned by these constructors.

Value

A classed fact-family object, or a ledgr_facts bundle.

Details

Membership intervals require instrument_id, effective_from, and member; effective_to and knowledge_time are optional. Membership snapshots require effective_from plus either row-wise instrument_id or a members list-column. character(0) records an empty set without a dummy instrument; the two input shapes cannot be mixed. An NA row-wise instrument_id records an empty set header. Trading-status rows require instrument_id, effective_from, status, and source. Status is one of active, halted, or quotation_only; optional columns are effective_to, knowledge_time, precedence, fact_id, revision_id, and supersedes_fact_id. Lifetime rows require instrument_id, effective_from, and assertion, where assertion is known_active, known_inactive, or unknown.

Session rows require session_date, status, session_open, and session_close; knowledge_time is required under evidenced knowledge and may be omitted only with knowledge = "assume_effective". Every civil date in the declared range appears exactly once. Open-session times may be POSIXct timestamps or local HH:MM:SS strings; closed rows have missing open and close times.

Errors

Structural input failures inherit from ledgr_invalid_args. The primary classes are ledgr_fact_invalid_shape, ledgr_fact_invalid_interval, ledgr_fact_identity_conflict, ledgr_fact_structural_conflict, ledgr_fact_invalid_supersession, ledgr_session_invalid, ledgr_session_time_ambiguous, and ledgr_session_time_nonexistent.

Articles

Point-in-time universe workflow: vignette("survivorship-bias", package = "ledgr") system.file("doc", "survivorship-bias.html", package = "ledgr")

Examples

membership <- ledgr_facts_membership_snapshots(
  data.frame(
    effective_from = as.POSIXct("2020-01-02", tz = "UTC"),
    knowledge_time = as.POSIXct("2020-01-01", tz = "UTC"),
    instrument_id = "AAA"
  ),
  universe_id = "example"
)
facts <- ledgr_facts(membership)
facts
#> ledgr facts
#> Families: 1
#> - membership [example]: 1 row(s)