These constructors normalize point-in-time membership, trading-status,
session-calendar, lifetime, and equity corporate-action evidence before
snapshot creation. Effective intervals are half-open: effective_from is
included and effective_to is excluded. A membership, trading-status or
lifetime row without a knowledge time is accepted and kept in sealed
evidence, but every run, sweep, feature precompute, walk-forward session or
pulse inspection that prepares availability from that snapshot refuses with
ledgr_fact_knowledge_missing until the row has a knowledge time.
knowledge = "assume_effective" fills a missing knowledge time from the
effective time; a supplied knowledge time is always kept.
Date-backed fact clocks are civil labels: ledgr_facts() resolves each to exactly one
declared open session and retains the civil date, UTC instant, venue zone
and calendar identity in sealed evidence. Corporate-action entitlement,
effective, and payment dates resolve to session close; their knowledge
dates resolve to session open. POSIXct values remain exact.
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_equity_corporate_actions(df)
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.
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.
Equity corporate-action rows require subtype, parent_instrument_id,
complete, and provenance_tier. The optional clocks are
entitlement_time, effective_time, knowledge_time, and payment_time.
Optional normalized terms are gross_cash_per_parent_unit,
recipient_instrument_id, and recipient_quantity_per_parent_unit; each
supplied term requires its matching *_validated flag. Incomplete rows
require one lower-snake-case refusal_reason. Provenance is either
snapshot_bound, with no upstream identifiers, or
upstream_vintage_bound, with both upstream_build_id and
bar_vintage_id.
A row with an event clock (the effective time, else the entitlement time)
and no knowledge_time is known when that event becomes effective: a
POSIXct event at its instant, a Date event at the declared open of its venue
session, while the event itself stays at that session's close. Such a
row's knowledge provenance reads assumed, with reason
knowledge_assume_effective, and results of an availability-aware run list
equity_corporate_actions among their assumption-backed families. A supplied
knowledge_time is never replaced and reads evidenced. A row with no event or knowledge clock is
audit-only. A knowable row with neither an entitlement nor effective clock
refuses only once its knowledge cutoff is reached during execution. A
complete ordinary_cash_dividend, cash_acquisition, stock_acquisition,
mixed_acquisition or spin_off row with an effective clock but no
entitlement clock refuses with ledgr_corporate_action_entitlement_missing
at the pulse it would act on, in every execution mode.
Clock order and interval bounds are checked on resolved instants, so a Date
field is compared only after it resolves to its session.
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. A POSIXct open or close must fall on its session_date in
the venue zone (ledgr_session_instant_off_date), and no two open sessions
may share an open or a close instant (ledgr_session_instant_duplicate).
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_fact_invalid_completeness,
ledgr_fact_unvalidated_term, ledgr_session_invalid,
ledgr_session_time_ambiguous, and ledgr_session_time_nonexistent.
Civil dates that do not match exactly one declared open session use
ledgr_fact_civil_date_unresolved.
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)