Author: Aaron Lun

# Using TileDB-backed matrices with beachmat

# Overview

beachmat.tiledb provides a C++ API to extract numeric data from TileDB-backed matrices from the TileDBArray package. This extends the beachmat package to the matrix representations in the tatami_tiledb library. By including this package, users and developers can enable tatami-compatible C++ code to operate natively on file-backed data via the TileDB C library.

# For users

Users can simply load the package in their R session:

    library(beachmat.tiledb)

This will automatically extend beachmat’s functionality to TileDBArray matrices. Any package code based on beachmat will now be able to access TileDB data natively without any further work.

# For developers

Developers should read the beachmat developer guide if they have not done so already.

Developers can import beachmat.tiledb in their packages to guarantee native support for TileDBArray classes. This registers more `initializeCpp()` methods that initializes the appropriate C++ representations for these classes. Of course, this adds some more dependencies to the package, which may or may not be acceptable; some developers may prefer to leave this choice to the user or hide it behind an optional parameter to reduce the installation burden (e.g., if TileDB-backed matrices are not expected to be a common input in the package workflow).

It’s worth noting that beachmat by itself will already work with `TileDBMatrix` objects even without loading beachmat.tiledb. However, this is not as efficient as any package C++ code needs to go back into R to extract the matrix data via `DelayedArray::extract_array()` and friends. Importing beachmat.tiledb provides native support without the need for calls to R functions.

# Session information

    sessionInfo()

    ## R version 4.6.0 (2026-04-24)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.4 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.26.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] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] beachmat.tiledb_1.4.0 knitr_1.51            BiocStyle_2.40.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] Matrix_1.7-5          bit_4.6.0             jsonlite_2.0.0
    ##  [4] compiler_4.6.0        BiocManager_1.30.27   Rcpp_1.1.1-1.1
    ##  [7] nanoarrow_0.8.0       jquerylib_0.1.4       IRanges_2.46.0
    ## [10] yaml_2.3.12           fastmap_1.2.0         lattice_0.22-9
    ## [13] XVector_0.52.0        R6_2.6.1              RcppCCTZ_0.2.14
    ## [16] S4Arrays_1.12.0       generics_0.1.4        tiledb_0.33.0
    ## [19] BiocGenerics_0.58.0   RcppSpdlog_0.0.28     DelayedArray_0.38.0
    ## [22] MatrixGenerics_1.24.0 maketools_1.3.2       TileDBArray_1.20.0
    ## [25] bslib_0.10.0          rlang_1.2.0           cachem_1.1.0
    ## [28] xfun_0.57             sass_0.4.10           sys_3.4.3
    ## [31] bit64_4.8.0           SparseArray_1.12.0    cli_3.6.6
    ## [34] spdl_0.0.5            digest_0.6.39         grid_4.6.0
    ## [37] lifecycle_1.0.5       S4Vectors_0.50.0      evaluate_1.0.5
    ## [40] nanotime_0.3.14       buildtools_1.0.0      zoo_1.8-15
    ## [43] beachmat_2.28.0       abind_1.4-8           stats4_4.6.0
    ## [46] rmarkdown_2.31        matrixStats_1.5.0     tools_4.6.0
    ## [49] htmltools_0.5.9