Saving the metadata

WARNING: this function is deprecated as newer versions of alabaster do not need to write metadata. Helper function to write metadata from a named list to a JSON file. This is commonly used inside stageObject methods to create the metadata file for a child object.

writeMetadata(meta, dir, ignore.null = TRUE)

Arguments

meta

A named list containing metadata. This should contain at least the "$schema" and "path" elements.

dir

String containing a path to the staging directory.

ignore.null

Logical scalar indicating whether NULL values should be ignored during coercion to JSON.

Value

A JSON file containing the metadata is created at path. A list of resource metadata is returned, e.g., for inclusion as the "resource" property in parent schemas.

Details

Any NULL values in meta are pruned out prior to writing when ignore.null=TRUE. This is done recursively so any NULL values in sub-lists of meta are also ignored.

Any scalars are automatically unboxed so array values should be explicitly specified as such with I().

Any starting "./" in meta$path will be automatically removed. This allows staging methods to save in the current directory by setting path=".", without the need to pollute the paths with a "./" prefix.

The JSON-formatted metadata is validated against the schema in meta[["$schema"]] using jsonvalidate. The location of the schema is taken from the package attribute in that string, if one exists; otherwise, it is assumed to be in the alabaster.schemas package. (All schemas are assumed to live in the inst/schemas subdirectory of their indicated packages.)

We also use the schema to determine whether meta refers to an actual artifact or is a metadata-only document. If it refers to an actual file, we compute its MD5 sum and store it in the metadata for saving. We also save its associated metadata into a JSON file at a location obtained by appending ".json" to meta$path.

For artifacts, the MD5 sum calculation will be skipped if the meta already contains a md5sum field. This can be useful on some occasions, e.g., to improve efficiency when the MD5 sum was already computed during staging, or if the artifact does not actually exist in its full form on the file system.

Author

Aaron Lun

Examples

library(S4Vectors)
df <- DataFrame(A=1:10, B=LETTERS[1:10])

tmp <- tempfile()
dir.create(tmp)
info <- stageObject(df, tmp, path="coldata")
writeMetadata(info, tmp)
#> $type
#> [1] "local"
#> 
#> $path
#> [1] "coldata/simple.csv.gz"
#> 
cat(readLines(file.path(tmp, "coldata/simple.csv.gz.json")), sep="\n")
#> {
#>   "$schema": "csv_data_frame/v1.json",
#>   "path": "coldata/simple.csv.gz",
#>   "is_child": false,
#>   "data_frame": {
#>     "columns": [
#>       {
#>         "name": "A",
#>         "type": "integer"
#>       },
#>       {
#>         "name": "B",
#>         "type": "string"
#>       }
#>     ],
#>     "row_names": false,
#>     "dimensions": [10, 2],
#>     "version": 2
#>   },
#>   "csv_data_frame": {
#>     "compression": "gzip"
#>   },
#>   "md5sum": "042b00e066dfa96577b5d6ac3c3ee700"
#> }