Contents

1 Overview

The alabaster.matrix package implements methods to save matrix-like objects to file artifacts and load them back into R. Check out the alabaster.base for more details on the motivation and the alabaster framework.

2 Quick start

Given an array-like object, we can use stageObject() to save it inside a staging directory:

library(Matrix)
y <- rsparsematrix(1000, 100, density=0.05)

library(alabaster.matrix)
tmp <- tempfile()
dir.create(tmp)
meta <- stageObject(y, tmp, "my_sparse_matrix")

library(alabaster.base)
.writeMetadata(meta, tmp)
## $type
## [1] "local"
## 
## $path
## [1] "my_sparse_matrix/matrix.h5"
list.files(tmp, recursive=TRUE)
## [1] "my_sparse_matrix/matrix.h5"      "my_sparse_matrix/matrix.h5.json"

We then load it back into our R session with loadObject(). This creates a HDF5-backed DelayedArray that can be easily coerced into the desired format, e.g., a dgCMatrix.

meta <- acquireMetadata(tmp, "my_sparse_matrix/matrix.h5")
roundtrip <- loadObject(meta, tmp)
class(roundtrip)
## [1] "H5SparseMatrix"
## attr(,"package")
## [1] "HDF5Array"

This process is supported for all base arrays, Matrix objects and DelayedArray objects.

3 Saving delayed operations

For DelayedArrays, we may instead choose to save the delayed operations themselves to file, using the chihaya package. This creates a HDF5 file following the chihaya format, containing the delayed operations rather than the results of their evaluation.

library(DelayedArray)
y <- DelayedArray(rsparsematrix(1000, 100, 0.05))
y <- log1p(abs(y) / 1:100) # adding some delayed ops.

preserveDelayedOperations(TRUE)
meta <- stageObject(y, tmp, "delayed")
.writeMetadata(meta, tmp)
## $type
## [1] "local"
## 
## $path
## [1] "delayed/delayed.h5"
meta <- acquireMetadata(tmp, "delayed/delayed.h5")
roundtrip <- loadObject(meta, tmp)
class(roundtrip)
## [1] "DelayedMatrix"
## attr(,"package")
## [1] "DelayedArray"

However, it is probably best to avoid preserving delayed operations for file-backed DelayedArrays if you want the artifacts to be re-usable on different filesystems. For example, HDF5Arrays will be saved with a reference to an absolute file path, which will not be portable.

Session information

sessionInfo()
## R version 4.3.0 RC (2023-04-13 r84257)
## Platform: x86_64-apple-darwin20 (64-bit)
## Running under: macOS Monterey 12.6.4
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: America/New_York
## tzcode source: internal
## 
## attached base packages:
## [1] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] DelayedArray_0.26.2    S4Arrays_1.0.1         IRanges_2.34.0        
##  [4] S4Vectors_0.38.1       MatrixGenerics_1.12.0  matrixStats_0.63.0    
##  [7] BiocGenerics_0.46.0    alabaster.base_1.0.0   alabaster.matrix_1.0.0
## [10] Matrix_1.5-4           BiocStyle_2.28.0      
## 
## loaded via a namespace (and not attached):
##  [1] crayon_1.5.2            cli_3.6.1               knitr_1.42             
##  [4] rlang_1.1.1             xfun_0.39               chihaya_1.0.0          
##  [7] jsonlite_1.8.4          V8_4.3.0                htmltools_0.5.5        
## [10] sass_0.4.6              rmarkdown_2.21          grid_4.3.0             
## [13] evaluate_0.21           jquerylib_0.1.4         fastmap_1.1.1          
## [16] alabaster.schemas_1.0.1 Rhdf5lib_1.22.0         yaml_2.3.7             
## [19] bookdown_0.34           jsonvalidate_1.3.2      BiocManager_1.30.20    
## [22] compiler_4.3.0          Rcpp_1.0.10             rhdf5filters_1.12.1    
## [25] rhdf5_2.44.0            lattice_0.21-8          digest_0.6.31          
## [28] R6_2.5.1                curl_5.0.0              HDF5Array_1.28.1       
## [31] bslib_0.4.2             tools_4.3.0             cachem_1.0.8