Skip to contents

Overview

This is the R implementation of the SOMA API specification.

Installation

Release packages

TileDB-SOMA releases can be installed from R-universe, which serves macOS binaries and the source package for other Unix-like platforms.

install.packages('tiledbsoma', repos = c('https://tiledb-inc.r-universe.dev',
                                         'https://cloud.r-project.org'))

Installing from source on Unix-like platforms requires cmake, git, and a recent-enough C++ compiler (g++ version 10.* or above).

Alternatively, tiledbsoma can be installed directly from Conda, which serves binaries for multiple architectures.

mamba install -c conda-forge -c tiledb r-tiledbsoma

Note, we’re using mamba here as a drop-in replacement for conda to accelerate the install process.

From source

To install the very latest tiledbsoma development version (our main branch), use remotes::install_github():

remotes::install_github("https://github.com/single-cell-data/TileDB-SOMA", subdir = "apis/r")

A note about the fmt and spdlog packages:

  • If you encounter an install-time error like undefined symbol: _ZTIN3fmt2v912format_errorE then you should uninstall your systemversions of fmt and spdlog. On Linux, this means dpkg -l | egrep "lib(spdlog|fmt)" should now come up empty.
  • If you encounter an install-time error like fatal error: spdlog/spdlog.h: No such file or directory you should additionally recursively remove /usr/local/lib/cmake/spdlog, since the system uninstall of spdlog fails to remove this properly.

Requirements

  • Source installation requires the tiledb R package – which in turn depends on either a local installation of TileDB Core library or the provided build artifacts.
  • In general, source installation of TileDB Core and its packages requires cmake and git to be installed; these are common tools each operating system provides readily.
  • All other R package dependencies are listed in the DESCRIPTION file and can be installed via e.g. remotes::install_deps(".", dependencies=TRUE) which will also install suggested packages. In order to build vignettes, knitr and rmarkdown are required (and will be installed), as is testthat for testing. If testthat is invoked directly then pkgbuild is also needed (but is not installed as not listed in DESCRIPTION).
  • In addition, this R package also depends on the libtiledbsoma library from this repository. It is either installed with the package (as described in the next section), or can be used as a system library (if one is found). A system installation can be provided by following the steps in the libtiledbsoma directory.

Development setup

To set up and install from a local clone of this git repository:

  • Clone this repository: git clone https://github.com/single-cell-data/TileDB-SOMA.git.
  • Change into the R API package directory: cd TileDB-SOMA/apis/r.
  • Optionally, clean the files in the repo: ./cleanup (this is not needed the first time).
  • Optionally, add on optional package with more more test data: install.packages("pbmc3k.tiledb", repos="https://ghrr.github.io/drat").
  • If you have edited any src/*.cpp files and changed any function signatures, then running Rscript -e 'Rcpp::compileAttributes()' will update the Rcpp-generated glue code.
  • If you have changed any C++ function header documentation, run Rscript -e 'roxygen2::roxygenise()' to update the corresponding R files.
  • Build the R package source tarball from the repository sources: R CMD build . (which will also include the libtiledbsoma source via a repository soft-link); other dependencies are required as described in the previous section).
  • Optionally, check and test the package from the tarball skipping vignettes and manuals (which need texlive or equivalent): R CMD check --no-vignettes --no-manual tiledbsoma_*.tar.gz.
  • Finally, install the package from the tarball: R CMD INSTALL tiledbsoma_*.tar.gz. During this installation presence of the two C++ libraries (TileDB Core, TileDB-SOMA) is tested for. TileDB Core builds can be downloaded as needed, and the TileDB-SOMA library is built if needed. (We plan to provide a downloadable artifact for it too.)

Once installed successfully, the package sources can be edited and re-installed iteratively. The optional clean step ensures a full rebuild, and the optional copy of libtiledbsoma ensures it is updated too.

Status

Please see https://github.com/single-cell-data/TileDB-SOMA/issues.

Information for developers

Please see the TileDB-SOMA wiki.

This main branch implements the updated specification. Please also see the main-old branch for an implementation of the original specification.