A phylogenetic meta-analysis
To demonstrate the use of rotl in a comparative analysis, we will partially reproduce the results of Rutkowska et al 2014. Very briefly, this study is a meta-analysis summarising the results of multiple studies testing for systematic differences in the size of eggs which contain male and female offspring. Such a difference might mean that birds invest more heavily in one sex than the other.
Because this study involves data from 51 different species, Rutkowska et al used a phylogenetic comparative approach to account for the shared evolutionary history among some of the studied-species.
Gather the data
If we are going to reproduce this analysis, we will first need to gather the data. Thankfully, the data is available as supplementary material from the publisher’s website. We can collect the data from using fulltext (with the papers DOI as input) and read it into memory with gdata:
library(rotl)
library(fulltext)
if (require(readxl)) {
doi <- "10.1111/jeb.12282"
xl_file <- ft_get_si(doi, 1, save.name="egg.xls")
egg_data <- read_excel(xl_file)
} else {
egg_data <- read.csv(system.file("extdata", "egg.csv", package = "rotl"))
}
## Loading required package: readxl
## # A tibble: 6 × 14
## animal Spp Lndim Measure Neggs
## <chr> <chr> <dbl> <chr> <dbl>
## 1 Zonotrichia_leucophrys White-crowned sparrow 0.000000000 volume 294
## 2 Passer_domesticus House sparrow 0.009407469 volume 149
## 3 Serinus_canaria Canary 0.000000000 volume 52
## 4 Turdus_merula European blackbird 0.021189299 volume 82
## 5 Agelaius_phoeniceus Red-winged blackbird 0.218316086 volume 394
## 6 Quiscalus_mexicanus Great-tailed grackle 0.281894985 mass 822
## # ... with 9 more variables: Nclutches <dbl>, ESr <dbl>, Type <chr>,
## # StudyID <chr>, Year <dbl>, D <dbl>, EN <dbl>, Zr <dbl>, VZr <dbl>
The most important variable in this dataset is Zr, which is a normalized effect size for difference in size between eggs that contain males and females. Values close to zero come from studies that found the sex of an egg’s inhabitant had little effect in its size, while large positive or negative values correspond to studies with substantial sex biases (towards males and females respectively). Since this is a meta-analysis we should produce the classic funnel plot with effects-size on the y-axis and precision (the inverse of the sample standard error) on the x-axis. Here we calculate precision from the sample variance (Vzr):
plot(1/sqrt(egg_data$VZr), egg_data$Zr, pch=16,
ylab="Effect size (Zr)",
xlab="Precision (1/SE)",
main="Effect sizes for sex bias in egg size among 51 brid species" )
In order to use this data later on we need to first convert it to a standard data.frame. We can also convert the animal column (the species names) to lower case which will make it easier to match names later on:
egg_data <- as.data.frame(egg_data)
egg_data$animal <- tolower(egg_data$animal)
Find the species in OTT
We can use the OTL synthesis tree to relate these species. To do so we first need to find Open Tree Taxonomy (OTT) IDs for each species. We can do that with the Taxonomic Name Resolution Service function tnrs_match_names:
taxa <- tnrs_match_names(unique(egg_data$animal), context="Animals")
head(taxa)
## search_string unique_name approximate_match ott_id
## 1 zonotrichia_leucophrys Zonotrichia leucophrys TRUE 265553
## 2 passer_domesticus Passer domesticus TRUE 745175
## 3 serinus_canaria Serinus canaria TRUE 464865
## 4 turdus_merula Turdus merula TRUE 568572
## 5 agelaius_phoeniceus Agelaius phoeniceus TRUE 226605
## 6 quiscalus_mexicanus Quiscalus mexicanus TRUE 743411
## is_synonym flags number_matches
## 1 FALSE 1
## 2 FALSE 1
## 3 FALSE SIBLING_HIGHER 2
## 4 FALSE 1
## 5 FALSE 2
## 6 FALSE 1
All of these species are in OTT, but a few of them go by different names in the Open Tree than we have in our data set. Because the tree rotl fetches will have Open Tree names, we need to create a named vector that maps the names we have for each species to the names Open Tree uses for them:
taxon_map <- structure(taxa$search_string, names=taxa$unique_name)
Now we can use this map to retrieve “data set names” from “OTT names”:
taxon_map["Anser caerulescens"]
## Anser caerulescens
## "chen_caerulescens"
Get a tree
Now we can get the tree. There are really too many tips here to show nicely, so we will leave them out of this plot
tr <- tol_induced_subtree(taxa$ott_id)
plot(tr, show.tip.label=FALSE)
There are a few things to note here. First, the tree has not branch lengths. At present this is true for the whole of the Open Tree synthetic tree. Some comparative methods require either branch lengths or an ultrametric tree. Before you can use one of those methods you will need to get a tree with branch lengths. You could try looking for published trees made available by the Open Tree with studies_find_trees. Alternatively, you could estimate branch lengths from the toplogy of a phylogeny returned by tol_induced_subtree, perhaps by downloading DNA sequences from the NCBI with rentrez or “hanging” the tree on nodes of known-age using penalized likelihood method in ape::chronos. In this case, we will use only the topology of the tree as input to our comparative analysis, so we can skip these steps.
Second, the tip labels contain OTT IDs, which means they will not perfectly match the species names in our dataset or the taxon map that we created earlier:
## [1] "Sturnus_vulgaris_ott565813" "Sturnus_unicolor_ott366470"
## [3] "Luscinia_svecica_ott274225" "Ficedula_albicollis_ott107840"
Finally, the tree contains node labels for those nodes that match a higher taxonomic group, and empty character vectors ("") for all other nodes. Some comparative methods either do no expect node labels at all, or require all labeled nodes to have a unique name (meaning multiple “empty” labels will cause and error).
We can deal with all these details easily. rotl provides the convenience function strip_ott_ids to remove the extra information from the tip labels. With the IDs removed, we can use our taxon map to replace the tip labels in the tree with the species names from dataset.
otl_tips <- strip_ott_ids(tr$tip.label, remove_underscores=TRUE)
tr$tip.label <- taxon_map[ otl_tips ]
Finally, we can remove the node labels by setting the node.label attribute of the tree to NULL.
Perform the meta-analysis
Now we have data and a tree, and we know the names in the tree match the ones in the data. It’s time to do the comparative analysis. Rutkowska et al. used MCMCglmm, a Bayesian MCMC approach to fitting multi-level models,to perform their meta-analysis, and we will do the same. Of course, to properly analyse these data you would take some care in deciding on the appropriate priors to use and inspect the results carefully. In this case, we are really interested in using this as a demonstration, so we will just run a simple model.
Specifically we sill fit a model where the only variable that might explain the values of Zr is the random factor animal, which corresponds to the phylogenetic relationships among species. We also provide Zvr as the measurement error variance, effectively adding extra weight to the results of more powerful studies. Here’s how we specify and fit that model with MCMCglmm:
library(MCMCglmm, quiet=TRUE)
##
## Attaching package: 'ape'
## The following object is masked from 'package:phylobase':
##
## edges
set.seed(123)
pr<-list(R=list(V=1,nu=0.002),
G=list(G1=list(V=1,nu=0.002))
)
model <- MCMCglmm(Zr~1,random=~animal,
pedigree=tr,
mev=egg_data$VZr,
prior=pr,
data=egg_data,
verbose=FALSE)
## Warning in inverseA(pedigree = pedigree, scale = scale, nodes = nodes): no
## branch lengths: compute.brlen from ape has been used
Now that we have a result we can find out how much phylogenetic signal exists for sex-biased differences in egg-size. In a multi-level model we can use variance components to look at this, specifically the proportion of the total variance that can be explained by phylogeny is called the phylogenetic reliability, H. Let’s calculate the H for this model:
var_comps <- colMeans(model$VCV )
var_comps["animal"] / sum(var_comps)
## animal
## 0.002809591
It appears there is almost no phylogenetic signal to the data. The relationships among species explain much less that one percent of the total variance in the data. If you were wondering, Rutkowska et al. report a similar result, even after adding more predictors to their model most of the variance in Zr was left unexplained.
Demonstration of a basic workflow
The most common use for rotl is probably to start from a list of species and get the relevant parts of the tree for these species. This is a two step process:
- the species names need to be matched to their
ott_id (the Open Tree Taxonomy identifiers) using the Taxonomic name resolution services (TNRS)
- these
ott_id will then be used to retrieve the relevant parts of the Tree of Life.
Step 1: Matching taxonomy to the ott_id
Let’s start by doing a search on a diverse group of taxa: a tree frog (genus Hyla), a fish (genus Salmo), a sea urchin (genus Diadema), and a nautilus (genus Nautilus).
library(rotl)
taxa <- c("Hyla", "Salmo", "Diadema", "Nautilus")
resolved_names <- tnrs_match_names(taxa)
It’s always a good idea to check that the resolved names match what you intended:
| hyla |
Hyla |
FALSE |
1062216 |
FALSE |
|
1 |
| salmo |
Salmo |
FALSE |
982359 |
FALSE |
|
1 |
| diadema |
Diadema (genus in Holozoa) |
FALSE |
631176 |
FALSE |
|
3 |
| nautilus |
Nautilus |
FALSE |
616358 |
FALSE |
|
1 |
The column unique_name sometimes indicates the higher taxonomic level associated with the name. The column number_matches indicates the number of ott_id that corresponds to a given name. In this example, our search on Diadema returns 2 matches, and the one returned by default is indeed the sea urchin that we want for our query. The argument context_name allows you to limit the taxonomic scope of your search. Diadema is also the genus name of a fungus. To ensure that our search is limited to animal names, we could do:
resolved_names <- tnrs_match_names(taxa, context_name = "Animals")
If you are trying to build a tree with deeply divergent taxa that the argument context_name cannot fix, see “How to change the ott ids assigned to my taxa?” in the FAQ below.
Step 2: Getting the tree corresponding to our taxa
Now that we have the correct ott_id for our taxa, we can ask for the tree using the tol_induced_subtree() function. By default, the object returned by tol_induced_subtree is a phylo object (from the ape package), so we can plot it directly.
my_tree <- tol_induced_subtree(ott_ids = resolved_names$ott_id)
plot(my_tree, no.margin=TRUE)
FAQ
How to change the ott ids assigned to my taxa?
If you realize that tnrs_match_names assigns the incorrect taxonomic group to your name (e.g., because of synonymy) and changing the context_name does not help, you can use the function inspect. This function takes the object resulting from tnrs_match_names(), and either the row number, the taxon name (you used in your search in lowercase), or the ott_id returned by the initial query.
To illustrate this, let’s re-use the previous query but this time pretending that we are interested in the fungus Diadema and not the sea urchin:
taxa <- c("Hyla", "Salmo", "Diadema", "Nautilus")
resolved_names <- tnrs_match_names(taxa)
resolved_names
## search_string unique_name approximate_match ott_id
## 1 hyla Hyla FALSE 1062216
## 2 salmo Salmo FALSE 982359
## 3 diadema Diadema (genus in Holozoa) FALSE 631176
## 4 nautilus Nautilus FALSE 616358
## is_synonym flags number_matches
## 1 FALSE 1
## 2 FALSE 1
## 3 FALSE 3
## 4 FALSE 1
inspect(resolved_names, taxon_name = "diadema")
## search_string unique_name approximate_match ott_id
## 1 diadema Diadema (genus in Holozoa) FALSE 631176
## 2 diadema Diadema (genus in Nucletmycea) FALSE 4930522
## 3 diadema Hypolimnas FALSE 643831
## is_synonym flags number_matches
## 1 FALSE 3
## 2 FALSE 3
## 3 TRUE 3
In our case, we want the second row in this data frame to replace the information that initially matched for Diadema. We can now use the update() function, to change to the correct taxa (the fungus not the sea urchin):
resolved_names <- update(resolved_names, taxon_name = "diadema",
new_row_number = 2)
## we could also have used the ott_id to replace this taxon:
## resolved_names <- update(resolved_names, taxon_name = "diadema",
## new_ott_id = 4930522)
And now our resolved_names data frame includes the taxon we want:
| hyla |
Hyla |
FALSE |
1062216 |
FALSE |
|
1 |
| salmo |
Salmo |
FALSE |
982359 |
FALSE |
|
1 |
| diadema |
Diadema (genus in Nucletmycea) |
FALSE |
4930522 |
FALSE |
|
3 |
| nautilus |
Nautilus |
FALSE |
616358 |
FALSE |
|
1 |
How do I know that the taxa I’m asking for is the correct one?
The function taxonomy_taxon_info() takes ott_ids as arguments and returns taxonomic information about the taxa. This output can be passed to some helpers functions to extract the relevant information. Let’s illustrate this with our Diadema example
diadema_info <- taxonomy_taxon_info(631176)
tax_rank(diadema_info)
## $`Diadema (genus in Holozoa)`
## [1] "genus"
##
## attr(,"class")
## [1] "otl_rank" "list"
## $`Diadema (genus in Holozoa)`
## [1] "Diamema" "Centrechinus (Diadema)"
## [3] "Cidaris (Diadema)" "Centrechinus"
##
## attr(,"class")
## [1] "otl_synonyms" "list"
## $`Diadema (genus in Holozoa)`
## [1] "Diadema"
##
## attr(,"class")
## [1] "otl_name" "list"
In some cases, it might also be useful to investigate the taxonomic tree descending from an ott_id to check that it’s the correct taxon and to determine the species included in the Open Tree Taxonomy:
diadema_tax_tree <- taxonomy_subtree(631176)
diadema_tax_tree
## $tip_label
## [1] "Diadema_principeana_ott5725746"
## [2] "Diadema_vetus_ott5725747"
## [3] "Diadema_sp._CS-2014_ott5502179"
## [4] "Diadema_ascensionis_ott4950423"
## [5] "Diadema_africanum_ott4147369"
## [6] "Diadema_antillarum_antillarum_ott4147370"
## [7] "Diadema_antillarum_scensionis_ott220009"
## [8] "Diadema_palmeri_ott836860"
## [9] "Diadema_sp._DSM6_ott771059"
## [10] "Diadema_mexicanum_ott639130"
## [11] "Diadema_setosum_ott631175"
## [12] "Diadema_sp._SETO15_ott587479"
## [13] "Diadema_sp._seto17_ott587478"
## [14] "Diadema_sp._DSM7_ott587487"
## [15] "Diadema_sp._DSM8_ott587486"
## [16] "Diadema_sp._seto9_ott587485"
## [17] "Diadema_sp._seto10_ott587484"
## [18] "Diadema_sp._DSM2_ott587483"
## [19] "Diadema_sp._DSM3_ott587482"
## [20] "Diadema_sp._DSM4_ott587481"
## [21] "Diadema_sp._dsm5_ott587480"
## [22] "Diadema_savignyi_ott395692"
## [23] "Diadema_paucispinum_ott312263"
## [24] "Diadema_sp._seto16_ott312262"
## [25] "Diadema_sp._DSM1_ott219999"
## [26] "Diadema_sp._DJN9_ott66626"
## [27] "Diadema_sp._seto19_ott66624"
## [28] "Diadema_sp._seto38_ott66625"
## [29] "Diadema_sp._seto18_ott66623"
## [30] "Diadema_sp._seto35_ott66618"
##
## $edge_label
## [1] "Diadema_antillarum_ott1022356" "Diadema_ott631176"
By default, this function return all taxa (including self, and internal) descending from this ott_id but it also possible to return phylo object.
How do I get the tree for a particular taxonomic group?
If you are looking to get the tree for a particular taxonomic group, you need to first identify it by its node id or ott id, and then use the tol_subtree() function:
mono_id <- tnrs_match_names("Monotremata")
mono_tree <- tol_subtree(ott_id = ott_id(mono_id))
plot(mono_tree)
How do I find trees from studies focused on my favourite taxa?
The function studies_find_trees() allows the user to search for studies matching a specific criteria. The function studies_properties() returns the list of properties that can be used in the search.
furry_studies <- studies_find_studies(property="ot:focalCladeOTTTaxonName", value="Mammalia")
furry_ids <- furry_studies$study_ids
Now that we know the study_id, we can ask for the meta data information associated with this study:
furry_meta <- get_study_meta("pg_2550")
get_publication(furry_meta) ## The citation for the source of the study
## [1] "O'Leary, Maureen A., Marc Allard, Michael J. Novacek, Jin Meng, and John Gatesy. 2004. \"Building the mammalian sector of the tree of life: Combining different data and a discussion of divergence times for placental mammals.\" In: Cracraft J., & Donoghue M., eds. Assembling the Tree of Life. pp. 490-516. Oxford, United Kingdom, Oxford University Press."
## attr(,"DOI")
## [1] ""
get_tree_ids(furry_meta) ## This study has 10 trees associated with it
## [1] "tree5513" "tree5515" "tree5516" "tree5517" "tree5518" "tree5519"
## [7] "tree5520" "tree5521" "tree5522" "tree5523"
candidate_for_synth(furry_meta) ## None of these trees are yet included in the OTL
## NULL
Using get_study("pg_2550") would returns a multiPhylo object (default) with all the trees associated with this particular study, while get_study_tree("pg_2550", "tree5513") would return one of these trees.
The tree returned by the API has duplicated tip labels, how can I work around it?
You may encounter the following error message:
Error in rncl(file = file, ...) : Taxon number 39 (coded by the token Pratia
angulata) has already been encountered in this tree. Duplication of taxa in a
tree is prohibited.
This message occurs as duplicate labels are not allowed in the NEXUS format and it is stricly enforced by the part of the code used by rotl to import the trees in memory.
If you use a version of rotl more recent than 0.4.1, this should not happen by default for the function get_study_tree. If it happens with another function, please let us know.
The easiest way to work around this is to save the tree in a file, and use APE to read it in memory:
get_study_tree(study_id="pg_710", tree_id="tree1277",
tip_label='ott_taxon_name', file = "/tmp/tree.tre",
file_format = "newick")
tr <- ape::read.tree(file = "/tmp/tree.tre")
How do I get the higher taxonomy for a given taxa?
If you encounter a taxon name you are not familiar with, it might be useful to obtain its higher taxonomy to see where it fits in the tree of life. We can combine several taxonomy methods to extract this information easily.
giant_squid <- tnrs_match_names("Architeuthis")
tax_lineage(taxonomy_taxon_info(ott_id(giant_squid), include_lineage = TRUE))
## $`5295401`
## rank name unique_name ott_id
## 1 family Architeuthidae Architeuthidae 564393
## 2 suborder Oegopsina Oegopsina 43352
## 3 order Teuthida Teuthida 380472
## 4 superorder Decapodiformes Decapodiformes 854107
## 5 infraclass Neocoleoidea Neocoleoidea 329546
## 6 subclass Coleoidea Coleoidea 7371
## 7 class Cephalopoda Cephalopoda 7368
## 8 phylum Mollusca Mollusca 802117
## 9 no rank Lophotrochozoa Lophotrochozoa 155737
## 10 no rank Protostomia Protostomia 189832
## 11 no rank Bilateria Bilateria 117569
## 12 no rank Eumetazoa Eumetazoa 641038
## 13 kingdom Metazoa Metazoa 691846
## 14 no rank Holozoa Holozoa 5246131
## 15 no rank Opisthokonta Opisthokonta 332573
## 16 domain Eukaryota Eukaryota 304358
## 17 no rank cellular organisms cellular organisms 93302
## 18 no rank life life 805080
Why are OTT IDs discovered with rotl missing from an induced subtree?
Some taxonomic names that can be retrieved through the taxonomic name resolution service are not part of the Open Tree’s synthesis tree. These are usually traditional higher-level taxa that have been found to be paraphyletic.
For instance, if you wanted to fetch a tree relating the three birds that go into a Turkducken you might search for the turkey, duck, and chicken genera:
turducken <- c("Meleagris", "Anas", "Gallus")
taxa <- tnrs_match_names(turducken, context="Animals")
taxa
## search_string unique_name approximate_match ott_id is_synonym flags
## 1 meleagris Meleagris FALSE 446481 FALSE
## 2 anas Anas FALSE 765185 FALSE
## 3 gallus Gallus FALSE 153562 FALSE
## number_matches
## 1 2
## 2 1
## 3 4
So, we have IDs for each genus but those messages in the flag column look concerning. BARREN means these taxa have no descendants and MAJOR_RANK_CONFLICT refers to inconsitancies between the rank of these taxa and some of their relatives. For thtese reasons, Meleagris and Anas are not included in the synthetic tree.
If we tried to press on ahead with the IDs that we have, we’d get an error (because there are too few good IDs) or a tree with fewer tips that we had anticipated.
tr <- tol_induced_subtree(taxa$ott_id)
The best way to avoid these problems is to specify complete species names (species being the lowest level of classification in the Open Tree taxonomy they are guaranteed to be monophyletic):
turducken_spp <- c("Meleagris gallopavo", "Anas platyrhynchos", "Gallus gallus")
taxa <- tnrs_match_names(turducken_spp, context="Animals")
tr <- tol_induced_subtree(taxa$ott_id)
plot(tr)
rotl/inst/doc/how-to-use-rotl.Rmd 0000644 0001762 0000144 00000024362 12770044341 016416 0 ustar ligges users ---
title: "How to use rotl?"
author: "François Michonneau"
date: "`r Sys.Date()`"
output:
rmarkdown::html_vignette:
css: vignette.css
vignette: >
%\VignetteIndexEntry{How to use rotl?}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---
`rotl` provides an interface to the Open Tree of Life (OTL) API and allows users
to query the API, retrieve parts of the Tree of Life and integrate these parts
with other R packages.
The OTL API provides services to access:
* the **Tree of Life** a.k.a. TOL (the synthetic tree): a single draft tree that is
a combination of **the OTL taxonomy** and the **source trees** (studies)
* the **Taxonomic name resolution services** a.k.a. TNRS: the methods for
resolving taxonomic names to the internal identifiers used by the TOL and the
GOL (the `ott ids`).
* the **Taxonomy** a.k.a. OTT (for Open Tree Taxonomy): which represents the
synthesis of the different taxonomies used as a backbone of the TOL when no
studies are available.
* the **Studies** containing the source trees used to build the TOL, and
extracted from the scientific literature.
In `rotl`, each of these services correspond to functions with different
prefixes:
| Service | `rotl` prefix |
|---------------|---------------|
| Tree of Life | `tol_` |
| TNRS | `tnrs_` |
| Taxonomy | `taxonomy_` |
| Studies | `studies_` |
`rotl` also provides a few other functions and methods that can be used to
extract relevant information from the objects returned by these functions.
## Demonstration of a basic workflow
The most common use for `rotl` is probably to start from a list of species and
get the relevant parts of the tree for these species. This is a two step
process:
1. the species names need to be matched to their `ott_id` (the Open Tree
Taxonomy identifiers) using the Taxonomic name resolution services (TNRS)
1. these `ott_id` will then be used to retrieve the relevant parts of the Tree
of Life.
### Step 1: Matching taxonomy to the `ott_id`
Let's start by doing a search on a diverse group of taxa: a tree frog (genus
_Hyla_), a fish (genus _Salmo_), a sea urchin (genus _Diadema_), and a nautilus
(genus _Nautilus_).
```{r}
library(rotl)
taxa <- c("Hyla", "Salmo", "Diadema", "Nautilus")
resolved_names <- tnrs_match_names(taxa)
```
It's always a good idea to check that the resolved names match what you
intended:
`r knitr::kable(resolved_names)`
The column `unique_name` sometimes indicates the higher taxonomic level
associated with the name. The column `number_matches` indicates the number of
`ott_id` that corresponds to a given name. In this example, our search on
_Diadema_ returns 2 matches, and the one returned by default is indeed the sea
urchin that we want for our query. The argument `context_name` allows you to
limit the taxonomic scope of your search. _Diadema_ is also the genus name of a
fungus. To ensure that our search is limited to animal names, we could do:
```{r}
resolved_names <- tnrs_match_names(taxa, context_name = "Animals")
```
If you are trying to build a tree with deeply divergent taxa that the argument
`context_name` cannot fix, see "How to change the ott ids assigned to my taxa?"
in the FAQ below.
### Step 2: Getting the tree corresponding to our taxa
Now that we have the correct `ott_id` for our taxa, we can ask for the tree
using the `tol_induced_subtree()` function. By default, the object returned by
`tol_induced_subtree` is a phylo object (from the
[ape](https://cran.r-project.org/package=ape) package), so we can plot it
directly.
```{r, fig.width=7, fig.height=4}
my_tree <- tol_induced_subtree(ott_ids = resolved_names$ott_id)
plot(my_tree, no.margin=TRUE)
```
## FAQ
### How to change the ott ids assigned to my taxa?
If you realize that `tnrs_match_names` assigns the incorrect taxonomic group to
your name (e.g., because of synonymy) and changing the `context_name` does not
help, you can use the function `inspect`. This function takes the object
resulting from `tnrs_match_names()`, and either the row number, the taxon name
(you used in your search in lowercase), or the `ott_id` returned by the initial
query.
To illustrate this, let's re-use the previous query but this time pretending that
we are interested in the fungus _Diadema_ and not the sea urchin:
```{r}
taxa <- c("Hyla", "Salmo", "Diadema", "Nautilus")
resolved_names <- tnrs_match_names(taxa)
resolved_names
inspect(resolved_names, taxon_name = "diadema")
```
In our case, we want the second row in this data frame to replace the
information that initially matched for _Diadema_. We can now use the `update()`
function, to change to the correct taxa (the fungus not the sea urchin):
```{r}
resolved_names <- update(resolved_names, taxon_name = "diadema",
new_row_number = 2)
## we could also have used the ott_id to replace this taxon:
## resolved_names <- update(resolved_names, taxon_name = "diadema",
## new_ott_id = 4930522)
```
And now our `resolved_names` data frame includes the taxon we want:
`r knitr::kable(resolved_names)`
### How do I know that the taxa I'm asking for is the correct one?
The function `taxonomy_taxon_info()` takes `ott_ids` as arguments and returns
taxonomic information about the taxa. This output can be passed to some helpers
functions to extract the relevant information. Let's illustrate this with our
_Diadema_ example
```{r}
diadema_info <- taxonomy_taxon_info(631176)
tax_rank(diadema_info)
synonyms(diadema_info)
tax_name(diadema_info)
```
In some cases, it might also be useful to investigate the taxonomic tree
descending from an `ott_id` to check that it's the correct taxon and to
determine the species included in the Open Tree Taxonomy:
```{r}
diadema_tax_tree <- taxonomy_subtree(631176)
diadema_tax_tree
```
By default, this function return all taxa (including self, and internal)
descending from this `ott_id` but it also possible to return `phylo` object.
### How do I get the tree for a particular taxonomic group?
If you are looking to get the tree for a particular taxonomic group, you need to
first identify it by its node id or ott id, and then use the `tol_subtree()`
function:
```{r, fig.width=7, fig.height=4}
mono_id <- tnrs_match_names("Monotremata")
mono_tree <- tol_subtree(ott_id = ott_id(mono_id))
plot(mono_tree)
```
### How do I find trees from studies focused on my favourite taxa?
The function `studies_find_trees()` allows the user to search for studies
matching a specific criteria. The function `studies_properties()` returns the
list of properties that can be used in the search.
```{r}
furry_studies <- studies_find_studies(property="ot:focalCladeOTTTaxonName", value="Mammalia")
furry_ids <- furry_studies$study_ids
```
Now that we know the `study_id`, we can ask for the meta data information
associated with this study:
```{r}
furry_meta <- get_study_meta("pg_2550")
get_publication(furry_meta) ## The citation for the source of the study
get_tree_ids(furry_meta) ## This study has 10 trees associated with it
candidate_for_synth(furry_meta) ## None of these trees are yet included in the OTL
```
Using `get_study("pg_2550")` would returns a `multiPhylo` object (default) with
all the trees associated with this particular study, while
`get_study_tree("pg_2550", "tree5513")` would return one of these trees.
### The tree returned by the API has duplicated tip labels, how can I work around it?
You may encounter the following error message:
```
Error in rncl(file = file, ...) : Taxon number 39 (coded by the token Pratia
angulata) has already been encountered in this tree. Duplication of taxa in a
tree is prohibited.
```
This message occurs as duplicate labels are not allowed in the NEXUS format and
it is stricly enforced by the part of the code used by `rotl` to import the
trees in memory.
If you use a version of `rotl` more recent than 0.4.1, this should not happen by
default for the function `get_study_tree`. If it happens with another function,
please [let us know](https://github.com/ropensci/rotl/issues).
The easiest way to work around this is to save the tree in a file, and use APE
to read it in memory:
```{r, eval=FALSE}
get_study_tree(study_id="pg_710", tree_id="tree1277",
tip_label='ott_taxon_name', file = "/tmp/tree.tre",
file_format = "newick")
tr <- ape::read.tree(file = "/tmp/tree.tre")
```
### How do I get the higher taxonomy for a given taxa?
If you encounter a taxon name you are not familiar with, it might be useful to
obtain its higher taxonomy to see where it fits in the tree of life. We can
combine several taxonomy methods to extract this information easily.
```{r}
giant_squid <- tnrs_match_names("Architeuthis")
tax_lineage(taxonomy_taxon_info(ott_id(giant_squid), include_lineage = TRUE))
```
### Why are OTT IDs discovered with `rotl` missing from an induced subtree?
Some taxonomic names that can be retrieved through the taxonomic name
resolution service are not part of the Open Tree's synthesis tree. These are
usually traditional higher-level taxa that have been found to be paraphyletic.
For instance, if you wanted to fetch a tree relating the three birds that go
into a [Turkducken](https://en.wikipedia.org/wiki/Turducken) you might search
for the turkey, duck, and chicken genera:
```{r}
turducken <- c("Meleagris", "Anas", "Gallus")
taxa <- tnrs_match_names(turducken, context="Animals")
taxa
```
So, we have IDs for each genus but those messages in the `flag` column look
concerning. `BARREN` means these taxa have no descendants and
`MAJOR_RANK_CONFLICT` refers to inconsitancies between the rank of these taxa
and some of their relatives. For thtese reasons, _Meleagris_ and _Anas_ are not
included in the synthetic tree.
If we tried to press on ahead with the IDs that we have, we'd get an
error (because there are too few good IDs) or a tree with fewer tips that we had
anticipated.
```{r, eval=FALSE}
tr <- tol_induced_subtree(taxa$ott_id)
```
The best way to avoid these problems is to specify complete species names
(species being the lowest level of classification in the Open Tree taxonomy they
are guaranteed to be monophyletic):
```{r, fig.width=7, fig.height=4}
turducken_spp <- c("Meleagris gallopavo", "Anas platyrhynchos", "Gallus gallus")
taxa <- tnrs_match_names(turducken_spp, context="Animals")
tr <- tol_induced_subtree(taxa$ott_id)
plot(tr)
```
rotl/inst/doc/data_mashups.html 0000644 0001762 0000144 00000165365 12770044341 016335 0 ustar ligges users
Get Open Tree IDs to match your data.
Let’s say you have a dataset where each row represents a measurement taken from one species, and your goal is to put these measurements in some phylogenetic context. Here’s a small example: the best estimate of the mutation rate for a set of unicellular Eukaryotes along with some other property of those species which might explain the mutation rate:
csv_path <- system.file("extdata", "protist_mutation_rates.csv", package = "rotl")
mu <- read.csv(csv_path, stringsAsFactors=FALSE)
mu
## species mu pop.size genome.size
## 1 Tetrahymena thermophila 7.61e-12 1.12e+08 1.04e+08
## 2 Paramecium tetraurelia 1.94e-11 1.24e+08 7.20e+07
## 3 Chlamydomonas reinhardtii 2.08e-10 1.00e+08 1.12e+08
## 4 Dictyostelium discoideum 2.90e-11 7.40e+06 3.40e+07
## 5 Saccharomyces cerevisiae 3.30e-10 1.00e+08 1.25e+08
## 6 Saccharomyces pombe 2.00e-10 1.00e+07 1.25e+08
If we want to get a tree for these species we need to start by finding the unique ID for each of these species in the Open Tree database. We can use the Taxonomic Name Resolution Service (tnrs) functions to do this. Before we do that we should see if any of the taxonomic contexts, which can be used to narrow a search and avoid conflicts between different codes, apply to our group of species:
library(rotl)
tnrs_contexts()
## Possible contexts:
## Animals
## Birds, Tetrapods, Mammals, Amphibians, Vertebrates
## Arthropods, Molluscs, Nematodes, Platyhelminthes, Annelids
## Cnidarians, Arachnides, Insects
## Bacteria
## SAR group, Archaea, Excavata, Amoebae, Centrohelida
## Haptophyta, Apusozoa, Diatoms, Ciliates, Forams
## Fungi
## Basidiomycetes, Ascomycetes
## Land plants
## Hornworts, Mosses, Liverworts, Vascular plants, Club mosses
## Ferns, Seed plants, Flowering plants, Monocots, Eudicots
## Rosids, Asterids, Asterales, Asteraceae, Aster
## Symphyotrichum, Campanulaceae, Lobelia
## All life
Hmm, none of those groups contain all of our species. In this case we can search using the All life context and the function tnrs_match_names:
taxon_search <- tnrs_match_names(names=mu$species, context_name="All life")
knitr::kable(taxon_search)
| tetrahymena thermophila |
Tetrahymena thermophila |
FALSE |
180195 |
FALSE |
SIBLING_HIGHER |
1 |
| paramecium tetraurelia |
Paramecium tetraurelia |
FALSE |
568130 |
FALSE |
|
1 |
| chlamydomonas reinhardtii |
Chlamydomonas reinhardtii |
FALSE |
33153 |
FALSE |
|
1 |
| dictyostelium discoideum |
Dictyostelium discoideum |
FALSE |
160850 |
FALSE |
|
1 |
| saccharomyces cerevisiae |
Saccharomyces cerevisiae |
FALSE |
908549 |
FALSE |
|
1 |
| saccharomyces pombe |
Schizosaccharomyces pombe |
FALSE |
990004 |
TRUE |
|
1 |
Good, all of our species are known to Open Tree. Note, though, that one of the names is a synonym. Saccharomyces pombe is older name for what is now called Schizosaccharomyces pombe. As the name suggests, the Taxonomic Name Resolution Service is designed to deal with these problems (and similar ones like misspellings), but it is always a good idea to check the results of tnrs_match_names closely to ensure the results are what you expect.
In this case we have a good ID for each of our species so we can move on. Before we do that, let’s ensure we can match up our original data to the Open Tree names and IDs by adding them to our data.frame:
mu$ott_name <- taxon_search$unique_name
mu$ott_id <- taxon_search$ott_id
Find a tree with your taxa
Now let’s find a tree. There are two possible options here: we can search for published studies that include our taxa or we can use the ‘synthetic tree’ from Open Tree. We can try both approaches.
Published trees
Before we can search for published studies or trees, we should check out the list of properties we can use to perform such searches:
## $tree_properties
## [1] "ot:treebaseOTUId" "ot:nodeLabelMode"
## [3] "ot:originalLabel" "oti_tree_id"
## [5] "ot:ottTaxonName" "ot:inferenceMethod"
## [7] "ot:tag" "ot:treebaseTreeId"
## [9] "ot:comment" "ot:branchLengthDescription"
## [11] "ot:treeModified" "ot:studyId"
## [13] "ot:branchLengthTimeUnits" "ot:ottId"
## [15] "is_deprecated" "ot:branchLengthMode"
## [17] "ot:treeLastEdited" "ot:nodeLabelDescription"
##
## $study_properties
## [1] "ot:studyModified" "ot:focalClade"
## [3] "ot:focalCladeOTTTaxonName" "ot:focalCladeOTTId"
## [5] "ot:studyPublication" "ot:studyLastEditor"
## [7] "ot:tag" "ot:focalCladeTaxonName"
## [9] "ot:studyLabel" "ot:comment"
## [11] "ot:authorContributed" "ot:studyPublicationReference"
## [13] "ot:studyId" "ot:curatorName"
## [15] "ot:studyUploaded" "ot:studyYear"
## [17] "is_deprecated" "ot:dataDeposit"
## [19] "ot:candidateTreeForSynthesis"
We have ottIds for our taxa, so let’s use those IDs to search for trees that contain them. Starting with our first species Tetrahymena thermophila we can use studies_find_trees to do this search.
studies_find_trees(property="ot:ottId", value="180195")
## [1] study_ids dat n_matched_trees
## <0 rows> (or 0-length row.names)
Well… that’s not very promising. We can repeat that process for all of the IDs to see if the other species are better represented.
hits <- lapply(mu$ott_id, studies_find_trees, property="ot:ottId", detailed = FALSE)
sapply(hits, function(x) sum(x[["n_matched_trees"]]))
## [1] 0 0 2 0 32 3
OK, most of our species are not in any of the published trees available. You can help fix this sort of problem by making sure you submit your published trees to Open Tree.
A part of the synthesis tree
Thankfully, we can still use the complete Tree of Life made from the combined results of all of the published trees and taxonomies that go into Open Tree. The function tol_induced_subtree will fetch a tree relating a set of IDs.
Using the default arguments you can get a tree object into your R session:
tr <- tol_induced_subtree(ott_ids=mu$ott_id)
plot(tr)
Connect your data to the tips of your tree
Now we have a tree for of our species, how can we use the tree and the data together?
The package phylobase provide an object class called phylo4d, which is designed to represent a phylogeny and data associated with its tips. In oder to get our tree and data into one of these objects we have to make sure the labels in the tree and in our data match exactly. That’s not quite the case at the moment (tree labels have underscores and IDs appended):
## [1] "Tetrahymena thermophila"
## [1] "Chlamydomonas_reinhardtii_ott33153"
rotl provides a convienence function strip_ott_ids to deal with these.
tr$tip.label <- strip_ott_ids(tr$tip.label, remove_underscores=TRUE)
tr$tip.label %in% mu$ott_name
## [1] TRUE TRUE TRUE TRUE TRUE TRUE
Ok, now the tips are together we can make a new dataset. The phylo4d() functions matches tip labels to the row names of a data.frame, so let’s make a new dataset that contains just the relevant data and has row names to match the tree
library(phylobase)
mu_numeric <- mu[,c("mu", "pop.size", "genome.size")]
rownames(mu_numeric) <- mu$ott_name
tree_data <- phylo4d(tr, mu_numeric)
And now we can plot the data and the tree together
Find external data associated with studies, trees and taxa from Open Tree
In the above example we looked for a tree that related species in another dataset. Now we will go the other way, and try to find data associated with Open Tree records in other databases.
Get external data from a study
Let’s imagine you were interested in extending or reproducing the results of a published study. If that study is included in Open Tree you can find it via studies_find_studies or studies_find_trees and retrieve the published trees with get_study. rotl will also help you find external. The function study_external_IDs retrieves the DOI for a given study, and uses that to gather some more data:
extra_data <- study_external_IDs("pg_1980")
extra_data
## External data identifiers for study
## $doi: 10.1016/j.ympev.2006.04.016
## $pubmed_id: 16762568
## $nucleotide_ids: vector of 58 IDs
## $external_data_url http://purl.org/phylo/treebase/phylows/study/TB2:S1575
Here the returned object contains an external_data_url (in this case a link to the study in Treebase), a pubmed ID for the paper and a vector IDs for the NCBI’s nuleotide database. The packages treebase and rentrez provide functions to make use of these IDs within R.
As an example, let’s use rentrez to download the first two DNA seqences and print them.
library(rentrez)
seqs <- entrez_fetch(db="nucleotide", id=extra_data$nucleotide_ids[1:2], rettype="fasta")
cat(seqs)
## >gi|111606994|emb|AM181011.1| Plectroninia neocaledoniense partial 28S rRNA gene, specimen voucher G316300 (Queensland Museum)
## GCTAGCAAGCGCGTCGGTGGTTCAGCCGGCTGGTCTCGTCGAGTTGTCGGTGTGCGGATCCGAACGGACC
## GCGGCCGATGGCGTCGGCGGGCAAGCTGTGGTGCACTCTGTCGGCGTGCGCGTCAGCGTCGGTTTCGGCC
## GGACGACGAGGCGCTCGGGGAAGGTAGCTGGACCGGTCTTCGGTGCAGTGTTATAGCCCTGGGCCGCTGG
## GTTCGGCGTTTGGGACCGAGGAGAGAGATGATCGCTGCAGCGCCTGTCTCCCTCTCGAGGGGGGCTAGCC
## AGCCGCTGTTTGGGTGGCGTCACTGGCGGAGGACTGCACGCAGTGCTTCGCCGGTGGTCGTGTCCAGGCG
## GGCGGTGTGGGTATAGAGGCGCTTAGGACGCTGGCGTCCAAATGGCCGTGCGCGACCCGTCTTGAAACAC
## GGACCAAGGAGTCTAGCATGTGCGCGAGTCTTAGGGTGTGGAAGCCCTCGGGCGCAATGAAAGTGAAGGG
## CCGTCGTCTCTCGGGGCTGCGGTGTGAGGTGAGAGCCGTCGCCGTCGGGTGGCGGTGCATCATCGGCCGG
## TCCATCCTGCTCTCAGGAGGATCTGCGCAAGAGCGTGTTTGCTGGGACCCGAAAGATGGTGAACTATGCC
## TGAATAGGGTGAAGCCAGAGGAAACTCTGGTGGAGGCTCGTAGCGGTTCTGACGTGCAAATCGATCGTCA
## AATTTGGGTATAGGGGCGAAAGACTAATCGAACCATCTAGTAGCTGGTTCCCTCCGAAGTTTCCCTCAGG
## ATAGCTGGAACTCGTCTTGACACAGTTTTATCAGGTAAAGCGAATGATTAGAGGTCTTGGGGGTGAAACA
## CCCTCAACCTATTCTCAAACTTTAAATAGGTAAGAAGCGCGACTTGCTCAATTGAAGTGGCGCGCAGTGA
## ATGTGAGTTCCAAGTGGGCCATTTTTGGTAAGCAGAACTGGCGATGCGGGATGAACCGAACGCTCGGTTA
## AGGTGCCCAAGTCGACGCTCATCAGACCCCAGAAAAGGTGTTGGTCGATATAGACAGCAGGACGGTGGCC
## ATGGAAGTCGGAATCCGCTAAGGAGTGTGTAACAACTCACCTGCCGAATCAACTAGCCCTGAAAATGGAT
## GGCGCTCAAGCGTCGCACCTATACCGAGCCGTCGTGGTAAATGCCAGGCCACGACGAGTAGGAGGGCGCG
## GTGGTCGTGACGCAGCCCTTGGCGCGAGCCTGGGCGAAACGGCCTCCGGTGCAGATCTTGGTGGTAGTAG
## CAAATATTCAAATGAGAGCTTTGAAGACCGAAGTGGAGAAAGGTTCCATGTGAACAGCAGTTGGACATGG
## GTTAGTCGATCCTAAGAGATAGGGAAGTTCCGTGTGAAAGTGCGCAATGCGCTTCTGTGCTGCGCGCCTC
## CTATCGAAAGGGAATCGGGTTAATATTCCCGAACCGGAAGGCGGATATCTCTGGCTCTCGGGTCAGGAGC
## GGCAACGCAAGCGTACTGCGAGACGTCGGCGGGGGCTCCGGGAAGAGTTGTCTTTTCTTTTTAACGCAGT
## CGCCATCCCTGGAATCGGTTTGCCCGGAGATAGGGTTGGCTGGCTCGGTAAAGCAGCACACTTCATGTGC
## TGTCCGGTGCGCTCTCGACGGCCCTTGAAAATCGCAGGTGTGCATCGATTCTCGCATCCGGTCGTACTCA
## TAACCGCATCAGGTCTCCAAGGT
##
## >gi|111606993|emb|AM181010.1| Eilhardia schulzei partial 28S rRNA gene, specimen voucher G316071 (Queensland Museum)
## GCTAGTAATGTACGTTGGTGGTTCAGCCGGCTAGTCTTGTCGAGTCGTCGTGTGGTGGATCCGACTGGAC
## CGTCCGCGGTGGTGTCGGCGGGCGAGCTGTGGTGCACTCTACGGACGTGCGCGTCAGCGTCGGTTCTCGA
## TGGGCGATAAGGTGCGTGGGGGAAGGTGGCTCGGTCCTTGGGAACTGAGTGTTACAGACCCTGGTGCTGG
## GCTCGTCGTGGGACCGAGGAGAGAGAGAGATGATCGCTGCGGCACCTGCCCCGTTGTCATTTTTCGGGGC
## TAGCCAGCCGTTTGTCAGGTGTGCGTCGGACGTTGAGGACTGCACGCAGTGCTGGACGTGGAGGCGTGAT
## CTGATGGCGGTGTGGGCATTAGAGGTGCCTAGGACGCTGGCGTCCAAATGGCCGTGCGCGACCCGTCTTG
## AAACACGGACCAAGGAGTCTAACATGTGCGCGAGTCTTAGGGTGTGCAAGCCCTCGGGCGCAATGAAAGT
## GAAGGCTCGGCGGCGCTAGTCGAGCTGAGGTGAGAGCCGTGGCCGTTGCATGTGGCGGCGGCGGCGCATC
## ATCGGCCGGTCCATCCTGCTCTCAGGGGGATCCGAGCAAGAGCGTATTTGTTGGGACCCGAAAGATGGTG
## AACTATGCCTGAATAGGGTGAAGCCAGAGGAAACTCTGGTGGAGGCTCGTAGCGATTCTGACGTGCAAAT
## CGATCGTCAAATTTGGGTATAGGGGCGAAAGACTAATCGAACCATCTAGTAGCTGGTTCCCTCCGAAGTT
## TCCCTCAGGATAGCTGGAGCTCTTGGACACAGTTTTATCAGGTAAAGCGAATGATCAGAGGTCTTGGGGG
## TGAAACACCCTCAACCTATTCTCAAACTTTAAATCGGTAAGAAGCGCGACTTGCTGAATTGAAGCCGCGC
## GCAAGCAATGTGAGTTCCAAGTGGGCCATTTTTGGTAAGCAGAACTGGCGATGCGGGATGAACCGAACGC
## TGGGTTAAGGTGCCAAAGTCGACGCTCATCAGACCCCAGAAAAGGTGTTGGTTGATATAGACAGCAGGAC
## GATGGCCATGGAAGTCGGAATCCGCTAAGGAGTGTGTAACAACTCACCTGCCGAATCAACTAGCCCTGAA
## AATGGATGGCGCTCAAGCGTCGCACCTATACCGGGCCGTCGTCGCAAATGCCAGGCGACGACGAGTAGGA
## GGGCGCAGTGGTCGTCATGCAGCCCTTGGCGTGAGCCTGGGTCAAACGGCCTCTGGTGCAGATCTTGGTG
## GTAGTAGCAAATATTCAAATGAGAGCTTTGAAGACCGAAGTGGAGAAAGGTTCCATGTGAACAGCAGTTG
## GACATGGGTTAGTCGATCCTAAGTGATAGGGGAGCTCCGTATGAAAGTGCGCAATCGGCCCTGCTTGTGT
## CGCCTTGCGCCACCTATCGAAAGGGAATCGGGTTAATATTCCCGAACCGGAAGGCGGATTTTCTCTGGCT
## CTCGGGTCAGGAGCGGCAACGCTAGCGAACCGCGAGACGTCGGCGGGGGCTCCGGGAAGAGTTGTCTTTT
## CTTTTTAACGCAGTCGCCATCCCTGGAATCGGTTTGCCCGGAGATAGGGTTGGCTGGCTCGGTAAAGCAG
## CACACTTCATGTGCTGTCCGGTGCGCTCTCGACGGCCCTTGAAAATCGCGGCGAGTGTAGTCTGATTTTC
## GCATCCGTTCGTACTCATAACCGCATCAGGTCTCCAAGGT
You could further process these sequences in R with the function read.dna from ape or save them to disk by specifying a file name with cat.
Find a OTT taxon in another taxonomic database
It is also possible map an Open Tree taxon to a record in another taxonomic database. For instance, if we wanted to search for data about one of the tips of the sub-tree we fetched in the example above we could do so using taxon_external_IDs:
Tt_ids <- taxon_external_IDs(mu$ott_id[2])
Tt_ids
## source id
## 1 silva AY102613
## 2 ncbi 5888
## 3 gbif 5839866
A user could then use rgbif to find locality records using the gbif ID or rentrez to get genetic or bibliometric data about from the NCBI’s databases.