---
title: "Working With multiPhylo Objects in treedata.table"
author: "Josef Uyeda, Cristian Roman-Palacios, April Wright"
date: "08/08/2020"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Working With multiPhylo Objects in treedata.table}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## Working with multiphylo objects

`treedata.table` further allows the matching of multiple phylogenies (`multiPhylo`) against a single dataset (`data.frame`). Below, we modified the anole dataset to explain the extended functionality of `treedata.table` with `multiPhylo` objects. Note that all the trees in the `multiPhylo` must have exactly the same taxa.

We first load the sample dataset.

```{r}
library(ape)
library(treedata.table)

# Load example data
data(anolis)
#Create treedata.table object with as.treedata.table
td <- as.treedata.table(tree = anolis$phy, data = anolis$dat)
```


We then create a `multiPhylo` object including only two `phylo` objects. Users can provide any number of `phylo` objects within the `multiPhylo` object. However, trees can only differ in their topology. In other words, all trees must have the same tip labels. 

We also note that both the provided `multiPhylo` and `data.frame` should partially overlap

```{r}
trees<-list(anolis$phy,anolis$phy)
class(trees) <- "multiPhylo"
trees
```

Now, we create our treedata.table object by combining the trait data (`data.frame`) and the newly generated `multiPhylo` object. Note that there is only a single character matrix.

```{r}
td <- as.treedata.table(tree=trees, data=anolis$dat)
```

The resulting `td` object now returns a `multiPhylo` object under `phy`. This objectcontains only the overlapping taxa between the multiphylo objects and the input dataset.

```{r}
class(td$phy);td$phy
```

Please note that all the basic `treedata.table` functions highlighted above for `phylo` objects are still functional when `treedata.table` objects include `multiPhylo` objects.

```{r}
td[, head(.SD, 1), by = "ecomorph"]
```

Functions can also be run on any `treedata.table` object with `multiphylo` data. For instance, the following line will fit a phenogram for `SVL` on each of the trees we provided in the `multiPhylo` object.

```{r}
tdt(td, geiger::fitContinuous(phy, extractVector(td, 'SVL'), model="BM", ncores=1))
```

The output is an object of class `list` with each element corresponding to the output function of each tree in the provided `multiPhylo` object.