Write the provenance record of a data capsule

Pins a local CSV: writes data_provenance.json next to it with the file's name, SHA-256, size in bytes and number of data rows, where it came from and when. That record is what morie_capsule_verify() (and rmoriebricklayer::vrfcps(), and the rmbl-action GitHub Action) checks the data against later.

Usage

morie_capsule_write(
  dir,
  data_file,
  url = NULL,
  name = NULL,
  retrieved = format(Sys.Date()),
  provenance_file = "data_provenance.json",
  table = NULL,
  script_file = NULL
)

Arguments

dir

The capsule directory, a single string.

data_file

The CSV, relative to dir.

url

Where the data were downloaded from (source$url), or NULL.

name

The capsule's name. NULL (the default): the data file's name without .csv.

retrieved

The retrieval date, YYYY-MM-DD. Default: today.

provenance_file

The record's file name, relative to dir.

table

NULL, or a list stored as the record's table (the column schema the verification's schema_valid row reads).

script_file

NULL, or an analysis script relative to dir, pinned as script$filename and script$sha256.

Value

The provenance (a list), invisibly, with the file written as attribute "path".

Details

The record written is

{"name": ..., "source": {"url", "retrieved"}, "resource": {"filename",
 "sha256", "size_bytes", "row_count_data_rows"}, "table": ..., "script": {"filename",
 "sha256"}}

in that order, the order of the rmbl-action examples and of morie.capsule.write() in Python, so the three writers agree byte for byte. source$url is left out when url is NULL, table and script when not given. The row count is what utils::read.csv() reads, header excluded, which is how the verification counts them. An existing provenance file is overwritten.

Errors: dir not an existing directory; data_file or provenance_file not a relative path inside dir; a data_file that is not a .csv file in dir or cannot be read; url, name or retrieved not one string; table not a list; script_file not a file inside dir.

See also

Other capsule: morie_capsule_bundle(), morie_capsule_compare(), morie_capsule_drift(), morie_capsule_manifest(), morie_capsule_sign(), morie_capsule_verify()

Examples

dir <- file.path(tempdir(), "capsule-write")
dir.create(dir, showWarnings = FALSE)
write.csv(data.frame(id = 1:3, value = c(2.5, 3.1, 4.0)),
          file.path(dir, "data.csv"), row.names = FALSE)
prov <- morie_capsule_write(dir, "data.csv",
                            url = "https://example.org/data.csv",
                            retrieved = "2026-10-20")
str(prov$resource)
#> List of 4
#>  $ filename           : chr "data.csv"
#>  $ sha256             : chr "9ecd4bbb8d421da594889ff894d91b92d40155b2784f8afc552147d7e940d197"
#>  $ size_bytes         : num 29
#>  $ row_count_data_rows: int 3
morie_capsule_verify(dir)$ok
#> [1] TRUE

# a path out of the capsule is refused
try(morie_capsule_write(dir, "../data.csv"))
#> Error : `data_file` must be a path relative to `dir`, inside it: ../data.csv
unlink(dir, recursive = TRUE)