rotl

An R package to interact with the Open Tree of Life data APIs.
https://github.com/ropensci/rotl

Category: Biosphere
Sub Category: Biodiversity Data Access and Management

Keywords

peer-reviewed phylogeny r r-package rstats taxonomy

Keywords from Contributors

biodiversity biology routes taxize nomenclature darwincore cycle ecology spocc climate

Last synced: about 6 hours ago
JSON representation

Repository metadata

Interface to Open Tree of Life API

• Host: GitHub
• URL: https://github.com/ropensci/rotl
• Owner: ropensci
• License: other
• Created: 2014-09-16T02:46:12.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2023-06-16T12:51:36.000Z (over 2 years ago)
• Last Synced: 2025-10-26T03:02:18.901Z (about 2 months ago)
• Topics: peer-reviewed, phylogeny, r, r-package, rstats, taxonomy
• Language: R
• Homepage: https://docs.ropensci.org/rotl
• Size: 1.74 MB
• Stars: 45
• Watchers: 8
• Forks: 18
• Open Issues: 22
• Releases: 16
• Metadata Files:
  • Readme: README.Rmd
  • License: LICENSE

README.Rmd

          ---
output: github_document
---

```{r setup, eval=TRUE, echo=FALSE}
library(knitr)
# opts_knit$set(upload.fun = image_uri)
opts_knit$set(upload.fun = imgur_upload)
```


[![R-CMD-check](https://github.com/ropensci/rotl/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rotl/actions/workflows/R-CMD-check.yaml)
[![codecov.io](https://app.codecov.io/github/ropensci/rotl?branch=master)](https://app.codecov.io/github/ropensci/rotl?branch=master)
[![](https://www.r-pkg.org/badges/version/rotl)](https://www.r-pkg.org/pkg/rotl)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/rotl)](https://www.r-pkg.org/pkg/rotl)
[![](https://badges.ropensci.org/17_status.svg)](https://github.com/ropensci/software-review/issues/17)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)



# 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](https://github.com/OpenTreeOfLife/pyopentree)
and [Ruby](https://github.com/SpeciesFileGroup/bark).


## Installation

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

```{r, eval=FALSE}
install.packages("rotl")
```

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

```{r, eval=FALSE}
install.packages("remotes")
```

Then you can install `rotl` using:

```{r, eval=FALSE}
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`?](https://cran.r-project.org/package=rotl/vignettes/rotl.html),
[Data mashups](https://cran.r-project.org/package=rotl/vignettes/data_mashups.html),
and
[Using the Open Tree synthesis in a comparative analysis](https://cran.r-project.org/package=rotl/vignettes/meta-analysis.html).

## 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:

```{r resolve}
library(rotl)
apes <- c("Pongo", "Pan", "Gorilla", "Hoolock", "Homo")
(resolved_names <- tnrs_match_names(apes))
```

Now we can get the tree with just those tips:

```{r get_tr}
tr <- tol_induced_subtree(ott_ids = ott_id(resolved_names))
plot(tr)
```

The code above can be summarized in a single pipe:

```{r pipe, plot=FALSE}
library(magrittr)
## or expressed as a pipe:
c("Pongo", "Pan", "Gorilla", "Hoolock", "Homo") %>%
  tnrs_match_names() %>%
  ott_id() %>%
  tol_induced_subtree() %>%
  plot()
```

## 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](https://doi.org/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](https://doi.org/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:

```{r versioning, eval=FALSE}
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](https://github.com/ropensci/rotl/blob/master/CONDUCT.md). By participating in this project you
agree to abide by its terms.

[![](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org/)

        

---

Owner metadata

• Name: rOpenSci
• Login: ropensci
• Email: info@ropensci.org
• Kind: organization
• Description:
• Website: https://ropensci.org/
• Location: Berkeley, CA
• Twitter: rOpenSci
• Company:
• Icon url: https://avatars.githubusercontent.com/u/1200269?v=4
• Repositories: 307
• Last ynced at: 2023-03-10T20:30:59.242Z
• Profile URL: https://github.com/ropensci

---

GitHub Events

Total

• Watch event: 5
• Pull request event: 1

Last Year

• Watch event: 5
• Pull request event: 1

---

Committers metadata

Last synced: 2 months ago

Name	Email	Commits
Francois Michonneau	f****u@g****m	610
David Winter	d****r@g****m	115
josephwb	p****b@g****m	95
Emily Jane McTavish	e****h@g****m	3
Jeroen Van Goey	j****y@g****m	2
Daijiang Li	d****1@u****u	2
Scott Chamberlain	m****s@g****m	1
Patrick Hausmann	p****n@c****e	1
Maëlle Salmon	m****n@y****e	1
Karthik Ram	k****m@g****m	1
Brian O'Meara	o****n@g****m	1
rOpenSci Bot	m****t@g****m	1

Committer domains:

• covimo.de: 1
• ufl.edu: 1

---

Issue and Pull Request metadata

Last synced: about 2 months ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ropensci/rotl

---

---

---

Package metadata

• Total packages: 3
• Total downloads:
  • cran: 13,825 last-month
• Total docker downloads: 200,502
• Total dependent packages: 5 (may contain duplicates)
• Total dependent repositories: 16 (may contain duplicates)
• Total versions: 39
• Total maintainers: 1

---

Dependencies

Score: 18.96504871248696