Learn R Programming

rotl: 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.

Installation

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

install.packages("rotl")

If you want to test the development version, you first need to install the remotes package.

install.packages("remotes")

Then you can install rotl using:

remotes::install_github("ropensci/rotl")

Vignettes

There are three vignettes:

  • Start by checking out the “How to use rotl?” by typing: vignette("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 analysis” 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:

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

Now we can get the tree with just those tips:

tr <- tol_induced_subtree(ott_ids = ott_id(resolved_names))
## Warning in collapse_singles(tr, show_progress): Dropping singleton nodes with
## labels: mrcaott83926ott6145147, mrcaott83926ott3607728, mrcaott83926ott3607876,
## mrcaott83926ott3607873, mrcaott83926ott3607687, mrcaott83926ott3607716,
## mrcaott83926ott3607689, mrcaott83926ott3607732, mrcaott770295ott3607719,
## mrcaott770295ott3607692, Ponginae ott1082538, Hylobatidae ott166544
plot(tr)

The code above can be summarized in a single pipe:

library(magrittr)
## or expressed as a pipe:
c("Pongo", "Pan", "Gorilla", "Hoolock", "Homo") %>%
  tnrs_match_names() %>%
  ott_id() %>%
  tol_induced_subtree() %>%
  plot()
## Warning in collapse_singles(tr, show_progress): Dropping singleton nodes with
## labels: mrcaott83926ott6145147, mrcaott83926ott3607728, mrcaott83926ott3607876,
## mrcaott83926ott3607873, mrcaott83926ott3607687, mrcaott83926ott3607716,
## mrcaott83926ott3607689, mrcaott83926ott3607732, mrcaott770295ott3607719,
## mrcaott770295ott3607692, Ponginae ott1082538, Hylobatidae ott166544

Citation and Manuscript

To cite rotl in publications pleases use:

Michonneau, F., Brown, J. W. and Winter, D. J. (2016), rotl: an R package to interact with the Open Tree of Life data. Methods in Ecology and Evolution. 7(12):1476-1481. doi: 10.1111/2041-210X.12593

You may also want to cite the paper for the Open Tree of Life

Hinchliff, C. E., et al. (2015). Synthesis of phylogeny and taxonomy into a comprehensive tree of life. Proceedings of the National Academy of Sciences 112.41 (2015): 12764-12769 doi: 10.1073/pnas.1423041112

The manuscript in Methods in Ecology and Evolution includes additional examples on how to use the package. The manuscript and the code it contains are also hosted on GitHub at: https://github.com/fmichonneau/rotl-ms

Versioning

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.

Copy Link

Version

Install

install.packages('rotl')

Monthly Downloads

3,981

Version

3.1.0

License

BSD_2_clause + file LICENSE

Issues

Pull Requests

Stars

Forks

Last Published

June 15th, 2023

Functions in rotl (3.1.0)

synonyms.match_names

List the synonyms for a given name
study_external_IDs

Get external identifiers for data associated with an Open Tree study
studies_properties

Properties of the Studies
tnrs_contexts

TNRS contexts
taxonomy_taxon_info

Taxon information
tol_subtree

Extract a subtree from the synthetic tree
tnrs_infer_context

Infer the taxonomic context from a list of names
tnrs_match_names

Match names to the Open Tree Taxonomy
tol_induced_subtree

Subtree from the Open Tree of Life
tol_about

Information about the Tree of Life
taxonomy_subtree

Taxonomy subtree
taxonomy_mrca

Taxonomic MRCA
tol_lineage

Node info
tol_mrca

MRCA of taxa from the synthetic tree
get_study

Get all the trees associated with a particular study
rotl

An Interface to the Open Tree of Life API
list_trees

List trees ids in objects returned by studies_find_studies and studies_find_trees.
inspect.match_names

Inspect and Update alternative matches for a name returned by tnrs_match_names
get_study_tree

Study Tree
source_list

List of studies used in the Tree of Life
get_tree_ids

Study Metadata
ott_id.match_names

ott_id and flags for taxonomic names matched by tnrs_match_names
get_study_subtree

Study Subtree
is_in_tree

Check that OTT ids occur in the Synthetic Tree
taxonomy_about

Information about the Open Tree Taxonomy
tax_lineage

Lineage of a taxon
studies_find_studies

Find a Study
tax_rank

Methods for Taxonomy
strip_ott_ids

Strip OTT ids from tip labels
studies_find_trees

Find Trees
taxon_external_IDs

Get external identifiers for data associated with an Open Tree taxon