RcppTskit: R access to the tskit C API

Overview

Tskit enables performant storage, manipulation, and analysis of ancestral recombination graphs (ARGs) using succinct tree sequence encoding. The tree sequence encoding of an ARG is described in Wong et al. (2024) doi:10.1093/genetics/iyae100. See https://tskit.dev for project news, documentation, and tutorials. Tskit provides Python, C, and Rust application programming interfaces (APIs). The Python API can be called from R via the reticulate R package to seamlessly load and analyse a tree sequence, as described at https://tskit.dev/tutorials/RcppTskit.html. RcppTskit provides R access to the tskit C API for use cases where the reticulate option is not optimal. For example, for high-performance and low-level work with tree sequences. Currently, RcppTskit provides a limited number of R functions due to the availability of extensive Python API and the reticulate option.

See more details on the state of the tree sequence ecosystem and aims of RcppTskit in RcppTskit/vignettes/RcppTskit_intro.qmd. The vignette also shows examples on how to use RcppTskit on its own or to develop new R packages.

Status

Contents

• extern - Git submodule for tskit and instructions on obtaining the latest version and copying the tskit C code into RcppTskit directory. extern is saved outside of the RcppTskit directory because R CMD CHECK complains otherwise.

• RcppTskit - R package RcppTskit.

License

• See extern/LICENSE for tskit.

• See RcppTskit/DESCRIPTION and RcppTskit/LICENSE for RcppTskit.

Installation

To install the published release from CRAN use:

# TODO: Publish on CRAN #14
#       https://github.com/HighlanderLab/RcppTskit/issues/14
# install.packages("RcppTskit")

To install a published release or specific branches from Github use the following code. Note that you will have to compile the C/C++ code and will hence require the complete R build toolchain, including compilers. See https://r-pkgs.org/setup.html#setup-tools for introduction to this topic, https://cran.r-project.org/bin/windows/Rtools for Windows tools, and https://mac.r-project.org/tools for macOS tools.

# install.packages("remotes") # If you don't have it already

# Release
# TODO: Tag a release #15
#       https://github.com/HighlanderLab/RcppTskit/issues/15
# remotes::install_github("HighlanderLab/RcppTskit/RcppTskit")

# Main branch
remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@main")

# Development branch
remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@devel")

Development

Code of Conduct

Please note that the RcppTskit project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Clone

First clone the repository and step into the directory:

git clone https://github.com/HighlanderLab/RcppTskit.git
cd RcppTskit

Pre-commit install

We use pre-commit hooks to ensure code quality. Specifically, we use:

• air to format R code,
• jarl to lint R code,
• clang-format to format C/C++ code, and
• clang-tidy to lint C/C++ code.

To install the hooks, run:

pre-commit install

tskit

If you plan to update tskit, follow instructions in extern/README.md.

RcppTskit

Then open RcppTskit package directory in your favourite R IDE (Positron, RStudio, text-editor-of-your-choice, etc.) and implement your changes.

You should routinely check your changes (in R):

# Note that the RcppTskit R package is in the RcppTskit sub-directory
setwd("path/to/RcppTskit/RcppTskit")

# Check
devtools::check()

# Install
devtools::install()

# Test
devtools::test()

# Test coverage
cov <- covr::package_coverage(clean = TRUE)
covr::report(cov)

Alternatively check your changes from the command line:

# Note that the RcppTskit package is in the RcppTskit sub-directory
cd path/to/RcppTskit/RcppTskit

# Check
R CMD build RcppTskit
R CMD check RcppTskit_*.tar.gz

# Install
R CMD INSTALL RcppTskit_*.tar.gz

On Windows, replace tar.gz with zip.

Pre-commit run

Before committing your changes, run the pre-commit hooks to ensure code quality:

# pre-commit autoupdate # to update the hooks
pre-commit run --all-files
# pre-commit run <hook_id>

Continuous integration

We use Github Actions to run continuous integration (CI) checks on each push and pull request. Specifically, we run:

• R CMD check on multiple platforms and
• covr test coverage.