Interface to Open Tree of Life API
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore prepare for 3.0.0 CRAN release Apr 26, 2016
NAMESPACE Merge branch 'master' into tree_data Apr 21, 2016

Build Status Build status CRAN RStudio mirror downloads Research software impact

An R interface to Open Tree API

rotl is an R package to interact with the Open Tree of Life data APIs. It was initially developed as part of the NESCENT/OpenTree/Arbor hackathon.

Client libraries to interact with the Open Tree of Life API also exists for Python and Ruby.


The current stable version is available from CRAN, and can be installed by typing the following at the prompt in R:


If you want to test the development version, you first need to install ghit (ghit is a more lightweight version of devtools if your sole purpose is to install packages that are hosted on GitHub).


Then you can install rotl using:

library(ghit) # or library(devtools)


There are three vignettes:

  • Start by checking out the "How to use rotl?" by typing: vignette("how-to-use-rotl", package="rotl") after installing the package.

  • Then explore how you can use rotl with other packages to combine your data with trees from the Open Tree of Life project by typing: vignette("data_mashups", package="rotl").

  • The vignette "Using the Open Tree Synthesis in a comparative analsysis" demonstrates how you can reproduce an analysis of a published paper by downloading the tree they used, and data from the supplementary material: vignette("meta-analysis", package="rotl").

The vignettes are also available from CRAN: How to use rotl?, Data mashups, and Using the Open Tree synthesis in a comparative analysis.

Quick start

Get a little bit of the big Open Tree tree

Taxonomic names are represented in the Open Tree by numeric identifiers, the ott_ids (Open Tree Taxonomy identifiers). To extract a portion of a tree from the Open Tree, you first need to find ott_ids for a set of names using the tnrs_match_names function:

apes <- c("Pan", "Pongo", "Pan", "Gorilla", "Hoolock", "Homo")
(resolved_names <- tnrs_match_names(apes))
##   search_string unique_name approximate_match ott_id is_synonym flags
## 1           pan         Pan             FALSE 417957      FALSE      
## 2         pongo       Pongo             FALSE 417949      FALSE      
## 3           pan         Pan             FALSE 417957      FALSE      
## 4       gorilla     Gorilla             FALSE 417969      FALSE      
## 5       hoolock     Hoolock             FALSE 712902      FALSE      
## 6          homo        Homo             FALSE 770309      FALSE      
##   number_matches
## 1              1
## 2              1
## 3              1
## 4              1
## 5              1
## 6              1

Now we can get the tree with just those tips:

tr <- tol_induced_subtree(ott_ids=ott_id(resolved_names))

plot of chunk get_tr

The code above can be summarized in a single pipe:

## or expressed as a pipe:
c("Pan", "Pongo", "Pan", "Gorilla", "Hoolock", "Homo") %>%
    tnrs_match_names %>%
    ott_id %>%
    tol_induced_subtree %>%

plot of chunk pipe


Starting with v3.0.0 of the package, the major and minor version numbers (the first 2 digits of the version number) will be matched to those of the API. The patch number (the 3rd digit of the version number) will be used to reflect bug fixes and other changes that are independent from changes to the API.

rotl can be used to access other versions of the API (if they are available) but most likely the high level functions will not work. Instead, you will need to parse the output yourself using the "raw" returns from the unexported low-level functions (all prefixed with a .). For instance to use the tnrs/match_names endpoint for v2 of the API:

rotl:::.tnrs_match_names(c("pan", "pango", "gorilla", "hoolock", "homo"), otl_v="v2")

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.