Saving BumpyMatrices to file

Overview

The BumpyMatrix class provides a representation of complex ragged data structures - see the BumpyMatrix package for more information. This is used to coerce immune repertoire, spatial transcriptomics and drug response data into a familiar 2D array for easy manipulation. The alabaster.bumpy package allows users to save a BumpyMatrix to file within the alabaster framework.

Saving a BumpyMatrix

Let’s make a BumpyMatrix to demonstrate:

library(BumpyMatrix)
library(S4Vectors)
df <- DataFrame(x=runif(100), y=runif(100))
f <- factor(sample(letters[1:20], nrow(df), replace=TRUE), letters[1:20])
mat <- BumpyMatrix(split(df, f), c(5, 4))

Saving it to file involves calling saveObject:

library(alabaster.bumpy)
tmp <- tempfile()
saveObject(mat, tmp)
list.files(tmp, recursive=TRUE)
## [1] "_environment.json"             "concatenated/basic_columns.h5"
## [3] "concatenated/OBJECT"           "OBJECT"                       
## [5] "partitions.h5"

Loading a BumpyMatrix

The loading procedure is even simpler as the metadata of the saved BumpyMatrix remembers how it was saved. We can just use alabaster.base::readObject() or related functions, and the R interface will automatically do the rest.

readObject(tmp)
## 5 x 4 BumpyDataFrameMatrix
## rownames: NULL 
## colnames: NULL 
## preview [1,1]:
##   DataFrame with 4 rows and 2 columns
##             x         y
##     <numeric> <numeric>
##   1 0.8791670 0.0580927
##   2 0.0688957 0.5392207
##   3 0.3994276 0.6338596
##   4 0.1818329 0.9569926

Session info

sessionInfo()
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
## [1] alabaster.bumpy_1.12.0 alabaster.base_1.12.1  S4Vectors_0.50.1      
## [4] BiocGenerics_0.58.1    generics_0.1.4         BumpyMatrix_1.20.0    
## [7] BiocStyle_2.40.0      
## 
## loaded via a namespace (and not attached):
##  [1] cli_3.6.6                knitr_1.51               rlang_1.2.0             
##  [4] xfun_0.59                otel_0.2.0               jsonlite_2.0.0          
##  [7] buildtools_1.0.0         htmltools_0.5.9          maketools_1.3.2         
## [10] sys_3.4.3                sass_0.4.10              rmarkdown_2.31          
## [13] grid_4.6.1               evaluate_1.0.5           jquerylib_0.1.4         
## [16] fastmap_1.2.0            Rhdf5lib_2.0.0           alabaster.schemas_1.12.0
## [19] yaml_2.3.12              IRanges_2.46.0           lifecycle_1.0.5         
## [22] BiocManager_1.30.27      compiler_4.6.1           Rcpp_1.1.1-1.1          
## [25] rhdf5filters_1.24.0      rhdf5_2.56.0             lattice_0.22-9          
## [28] digest_0.6.39            R6_2.6.1                 Matrix_1.7-5            
## [31] bslib_0.11.0             tools_4.6.1              cachem_1.1.0