1 Introduction

The beachmat package provides a C++ API for handling a variety of R matrix types. The aim is to abstract away the specific type of matrix object when writing C++ extensions, thus simplifying the processing of data stored in those objects. Currently, the API supports double-precision, integer, logical and character matrices. Supported classes include base matrix objects, a number of classes from the Matrix package, and disk-backed matrices from the HDF5Array package. This document describes how to link to beachmat from the C++ code of another R package.

2 Prerequisites for linking

The beachmat package currently has several dependencies:

  • The compiler should support the C++11 standard. This usually requires GCC version 4.8.1 or higher. You need to tell the build system to use C++11, by modifying the SystemRequirements field of the DESCRIPTION file:

      SystemRequirements: C++11

  • Rcpp should be installed. You also need to ensure that Rcpp is loaded when your package is loaded. This requires addition of Rcpp to the Imports field of the DESCRIPTION file:

     Imports: Rcpp

    … and a corresponding importFrom specification in the NAMESPACE file:

     importFrom(Rcpp, sourceCpp)

    (The exact function to be imported doesn’t matter, as long as the namespace is loaded. Check out the Rcpp documentation for more details.)

  • DelayedArray and beachmat should be added to the Suggests field, as the API will perform some calls to R functions in those packages to query certain parameters.

      Suggests: beachmat, DelayedArray

3 Linking to the library

beachmat is a header-only library, so linking is as simple as writing:

LinkingTo: Rcpp, beachmat

… in your DESCRIPTION file. Note that the Rcpp headers must also be included.

In C or C++ code files, use standard techniques to include header definitions, e.g., #include "beachmat/numeric_matrix.h" (see here for more details). Header files are available for perusal at the following location (enter in an R session):

system.file(package="beachmat", "include")
## [1] "/tmp/RtmpddqHqW/Rinst3543339c4c6f/beachmat/include"

4 Common problems

  • An undefined symbol error starting with _ZN2H56H5FileC1ERKNSt7_... usually indicates that Rhdf5lib was compiled with a different GCC version than beachmat-dependent libraries like HDF5Array, leading to incompatibilities in the binaries. This can usually be fixed by re-installing Rhdf5lib prior to installing beachmat.

  • An expected unqualified-id before 'using' error. This means that the version of GCC used to compile beachmat is out of date and does not fully support C++11.

Users can ask for help by making a post on the Bioconductor support site, labelled with the beachmat tag. This is the preferred avenue for questions. New users are advised to read the posting guide before creating a post.