---
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}
  %\VignetteEncoding{UTF-8}
  \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) as well as the pork
used for stuffing, you might search for the turkey, duck, chicken, and pork
genera:

```{r}
turducken <- c("Meleagris", "Anas", "Gallus", "Sus")
taxa <- tnrs_match_names(turducken, context = "Animals")
taxa
```

We have the OTT ids for each genus, however, if we tried to get the induced
subtree from these results, we would get an error:

```{r, error=TRUE}
tr <- tol_induced_subtree(ott_id(taxa))
```

As the error message suggests, some of the taxa are not found in the synthetic
tree. This occurs for 2 main reasons: either the taxa is invalid, or it is part
of a group that is not monophyletic in the synthetic tree. There are two ways to
get around this issue: (1) removing the taxa that are not part of the Open Tree;
(2) using the complete species name.

#### Removing the taxa missing from the synthetic tree

To help with this situation, `rotl` provides a way to identify the OTT ids that
are not part of the synthetic tree. The function `is_in_tree()` takes the output
of the `ott_id()` function and returns a vector of logical indicating whether
the taxa are part of the synthetic tree. We can then use to only keep the taxa that appear in the synthetic tree:

```{r}
in_tree <- is_in_tree(ott_id(taxa))
in_tree
tr <- tol_induced_subtree(ott_id(taxa)[in_tree])
```

#### Using the full taxonomic names

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", "Sus scrofa")
taxa <- tnrs_match_names(turducken_spp, context = "Animals")
tr <- tol_induced_subtree(ott_id(taxa))
plot(tr)
```
