Skip to contents

Create a snapshot from a CSV file

Source: R/snapshot_adapters.R
ledgr_snapshot_from_csv.Rd

Reads a bars CSV, optionally an instruments CSV, and seals a snapshot. This is the file-input form of ledgr_snapshot_from_df(). Both accept the same columns, the same timestamp forms, and the same point-in-time facts, and both return a sealed ledgr_snapshot.

Usage

ledgr_snapshot_from_csv(
  csv_path,
  instruments_csv_path = NULL,
  db_path = NULL,
  snapshot_id = NULL,
  facts = NULL,
  invalid_observations = c("error", "quarantine"),
  price_basis = NULL
)

Arguments

csv_path

Path to a bars CSV file.

instruments_csv_path

Optional path to an instruments CSV. When NULL, instruments are generated from the instrument ids in the bars.

db_path

Optional DuckDB file path (default: tempfile).

snapshot_id

Optional snapshot id. When NULL, ledgr generates one.

facts

Optional point-in-time facts created by ledgr_facts().

invalid_observations

Either "error" (the default) or the explicit "quarantine" acknowledgement. Quarantine requires declared sessions in facts.

price_basis

Optional declaration of the economic basis of the bars. See ledgr_snapshot_from_df().

Value

A ledgr_snapshot object.

Details

The bars CSV must contain instrument_id, ts_utc, open, high, low, and close; volume is optional. ledgr imports only those canonical bar columns. Other CSV columns are ignored and do not become part of the sealed snapshot or its hash.

ts_utc accepts a date-only value such as 2020-01-01, an ISO 8601 UTC datetime with a trailing Z, and the same datetime without the Z. A date-only value becomes midnight UTC. Timestamps are whole seconds by contract.

ledgr reads the file with DuckDB, as UTF-8, tolerating a byte-order mark. instrument_id, ts_utc and symbol are read as text and price columns as double, so an all-numeric instrument id such as 0001 keeps its leading zeros and a snapshot's identity depends on the data rather than on a reader's column-type inference. A bars CSV and the equivalent data.frame seal to the same snapshot hash.

The instruments CSV must contain instrument_id. symbol, currency, asset_class, multiplier, and tick_size are optional and default to the instrument id, "USD", "EQUITY", 1, and 0.01. Every instrument the bars reference must appear in it.

CSV parse and OHLC validation errors are snapshot creation errors. They are raised before a snapshot can be loaded into ledgr_experiment() or executed with ledgr_run(), and they use the general ledgr argument and timestamp classes ledgr_invalid_args and ledgr_invalid_timestamp. Snapshot creation fails before a usable snapshot artifact is left behind, so fix the CSV and rerun snapshot creation.

Articles

Durable experiment stores: vignette("experiment-store", package = "ledgr") system.file("doc", "experiment-store.html", package = "ledgr") Point-in-time facts and quarantine: vignette("survivorship-bias", package = "ledgr") system.file("doc", "survivorship-bias.html", package = "ledgr")

Examples

csv_path <- tempfile(fileext = ".csv")
utils::write.csv(data.frame(
  ts_utc = c("2020-01-01T00:00:00Z", "2020-01-02T00:00:00Z"),
  instrument_id = "AAA",
  open = c(100, 101),
  high = c(101, 102),
  low = c(99, 100),
  close = c(100, 101),
  volume = 1000
), csv_path, row.names = FALSE)
snapshot <- ledgr_snapshot_from_csv(csv_path)
ledgr_snapshot_info(snapshot)
#> # A tibble: 1 × 14
#>   snapshot_id                  status created_at_utc sealed_at_utc snapshot_hash
#>   <chr>                        <chr>  <chr>          <chr>         <chr>        
#> 1 snapshot_20261027_174439_ce… SEALED 2026-10-27T17… 2026-10-27T1… f425781cd274…
#> # ℹ 9 more variables: hash_rule_version <int>, verified_in_process <lgl>,
#> #   bar_count <int>, instrument_count <int>, off_session_bar_count <int>,
#> #   start_date <chr>, end_date <chr>, meta_json <chr>, error_msg <chr>
ledgr_snapshot_close(snapshot)