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.
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
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
… and a corresponding
importFrom specification in the
(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
Linking to the library
beachmat is a header-only library, so linking is as simple as writing:
LinkingTo: Rcpp, beachmat
… in your
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):
##  "/tmp/Rtmpy5yHU3/Rinst362f6e6c84c2/beachmat/include"
undefined symbol error starting with
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.
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.