Save a base list to disk

Save a list or List to a JSON or HDF5 file, with extra files created for any of the more complex list elements (e.g., DataFrames, arrays). This uses the uzuki2 specification to ensure that appropriate types are declared.

# S4 method for class 'list'
saveObject(x, path, list.format = saveBaseListFormat(), ...)

# S4 method for class 'List'
saveObject(x, path, list.format = saveBaseListFormat(), ...)

saveBaseListFormat(list.format)

Arguments

x

An ordinary R list, named or unnamed. Alternatively, a List to be coerced into a list.

path

String containing the path to a directory in which to save x.

list.format

String specifying the format in which to save the list.

...

Further arguments, passed to altSaveObject for complex child objects.

Value

For the saveObject method, x is saved inside dir. NULL is invisibly returned.

For saveBaseListFormat; if list.format is missing, a string containing the current format is returned. If list.format is supplied, it is used to define the current format, and the previous format is returned.

File formats

If list.format="json.gz" (default), the list is saved to a Gzip-compressed JSON file (the default). This is an easily parsed format with low storage overhead.

If list.format="hdf5", x is saved into a HDF5 file instead. This format is most useful for random access and for preserving the precision of numerical data.

Storing scalars

The uzuki2 specification (see https://github.com/ArtifactDB/uzuki2) allows length-1 vectors to be stored as-is or as a scalar. If a list element is of length 1, saveBaseList will store it as a scalar on-disk, effectively “unboxing” it for languages with a concept of scalars. Users can override this behavior by adding the AsIs class to the affected list element, which will force storage as a length-1 vector. This reflects the decisions made by readBaseList and mimics the behavior of packages like jsonlite.

See also

https://github.com/ArtifactDB/uzuki2 for the specification.

readBaseList, to read the list back into the R session.

Author

Aaron Lun

Examples

library(S4Vectors)
ll <- list(A=1, B=LETTERS, C=DataFrame(X=1:5))

tmp <- tempfile()
saveObject(ll, tmp)
list.files(tmp, recursive=TRUE)
#> [1] "OBJECT"                            "_environment.json"                
#> [3] "list_contents.json.gz"             "other_contents/0/OBJECT"          
#> [5] "other_contents/0/basic_columns.h5"