Motivation and use of Rtwobitlib

Fred Hutchinson Cancer Research Center, Seattle, WA

1. Motivation

Rtwobitlib is an R package that provides the 2bit C Library from the UCSC Genome Browser. See this page on the UCSC Genome Browser website for a quick overview of the 2bit format.

The Rtwobitlib package is primarily useful to developers of other R packages who wish to use the 2bit C library in their own C code.

2. Using the 2bit C library in the C code of your package

Find the header files

In order for the C/C++ compiler to find the 2bit header files during compilation of your package, you must add Rtwobitlib to the LinkingTo field of its DESCRIPTION file, e.g.,

LinkingTo: Rtwobitlib

Note that as of R 3.0.2 LinkingTo values can include version specifications, e.g., LinkingTo: Rtwobitlib (>= 0.3.6).

In C or C++ code files, use standard techniques, e.g., #include <kent/twoBit.h>. Header files are available for perusal at (enter in an R session)

inc_path <- system.file(package="Rtwobitlib", "include")
list.files(inc_path, recursive=TRUE)

##  [1] "kent/bits.h"     "kent/cheapcgi.h" "kent/common.h"   "kent/dnaseq.h"  
##  [5] "kent/dnautil.h"  "kent/errAbort.h" "kent/hash.h"     "kent/linefile.h"
##  [9] "kent/localmem.h" "kent/obscure.h"  "kent/sig.h"      "kent/twoBit.h"

Compile and link against the library

To compile and link your package successfully against the 2bit library included in Rtwobitlib, you must add a src/Makevars file with the following content:

## This file uses GNU make syntax $(shell ...) so we need to
## have "SystemRequirements: GNU make" in the DESCRIPTION file.

RTWOBITLIB_LIBS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
    'Rtwobitlib::pkgconfig("PKG_LIBS")')
RTWOBITLIB_CPPFLAGS=$(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript" -e \
    'Rtwobitlib::pkgconfig("PKG_CPPFLAGS")')

PKG_LIBS=$(RTWOBITLIB_LIBS)
PKG_CPPFLAGS=$(RTWOBITLIB_CPPFLAGS)

Note that $(shell ...) is GNU make syntax so you should add GNU make to the SystemRequirements field of the DESCRIPTION file of your package, e.g.,

SystemRequirements: GNU make

The reason we use $(shell echo ...) rather than back-ticks (e.g. `echo ...`) is because the latter causes problems when, after evaluation, PKG_LIBS and/or PKG_CPPFLAGS contain paths with whitespaces in them.

If your package needs to add to the $PKG_LIBS variable, do so by adding to the PKG_LIBS=$(RTWOBITLIB_LIBS) line, e.g.,

PKG_LIBS=$(RTWOBITLIB_LIBS) -L/path/to/foolib -lfoo

Notes

Rtwobitlib provides both static and dynamic versions of the 2bit library on Linux, but only the static version on Windows and macOS. The procedure above will link against the static version of the 2bit library on all platforms.

3. R functions defined in Rtwobitlib

Rtwobitlib provides the following R functions: twobit_read, twobit_write, twobit_seqlengths, twobit_seqstats.

These functions are implemented in C on top of the 2bit library bundled in the package.

Please refer to their man pages (e.g. with ?twobit_seqlengths) for more information and some examples.