<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/treeio-phylogenetic-data-integration/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="https://ropensci.org/blog/2018/05/17/treeio/"> rOpenSci - open tools for open science</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>Phylogenetic trees are commonly used to present evolutionary relationships of species. <a rel="nofollow" href="http://evolution.genetics.washington.edu/phylip/newicktree.html" target="_blank">Newick</a> is the <em>de facto</em> format in phylogenetic for representing tree(s). <a rel="nofollow" href="http://wiki.christophchamp.com/index.php?title=NEXUS_file_format" target="_blank">Nexus</a> format incorporates Newick tree text with related information organized into separated units known as blocks. For the R community, we have <a rel="nofollow" href="https://cran.r-project.org/package=ape" target="_blank">ape</a> and <a rel="nofollow" href="https://cran.r-project.org/package=phylobase" target="_blank">phylobase</a> packages to import trees from Newick and Nexus formats. However, analysis results (tree + analysis findings) from widely used software packages in this field are not well supported. Some of them are extended from Newick and Nexus (<em>e.g.</em> <a rel="nofollow" href="https://revbayes.github.io/intro.html" target="_blank">RevBayes</a> and <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a> outputs), while some of the others are just log files (<em>e.g.</em> <a rel="nofollow" href="http://ginger.ucdavis.edu/r8s" target="_blank">r8s</a> and <a rel="nofollow" href="http://abacus.gene.ucl.ac.uk/software/paml.html" target="_blank">PAML</a> outputs). Parsing these output files is important for interpreting analysis findings.</p>
<p>Information associated with taxon species/strains can be meta-data (<em>e.g.</em> isolation host, time and location, <em>etc.</em>), phenotypic or experimental data. These data as well as analysis finding may be further analyzed in the evolutionary context for downstream integrative and comparative studies. Unfortunately, taxon-associated data are mostly stored in separate files and often in inconsistent formats. To fill this gap, I developed the <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> package for phylogenetic tree data integration.</p>
<p>Currently, <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> is able to read the following file formats: Newick, Nexus, New Hampshire eXtended format (NHX), jplace and Phylip as well as the data outputs from the following analysis programs: <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a>, <a rel="nofollow" href="http://sco.h-its.org/exelixis/web/software/epa/index.html" target="_blank">EPA</a>, <a rel="nofollow" href="https://veg.github.io/hyphy-site/" target="_blank">HyPhy</a>, <a rel="nofollow" href="http://nbisweden.github.io/MrBayes/" target="_blank">MrBayes</a>, <a rel="nofollow" href="http://abacus.gene.ucl.ac.uk/software/paml.html" target="_blank">PAML</a>, <a rel="nofollow" href="https://pbil.univ-lyon1.fr/software/phyldog/" target="_blank">PHYLDOG</a>, <a rel="nofollow" href="http://matsen.fhcrc.org/pplacer/" target="_blank">pplacer</a>, <a rel="nofollow" href="http://ginger.ucdavis.edu/r8s" target="_blank">r8s</a>, <a rel="nofollow" href="http://evomics.org/learning/phylogenetics/raxml/" target="_blank">RAxML</a> and <a rel="nofollow" href="https://revbayes.github.io/intro.html" target="_blank">RevBayes</a>.</p>
<h3>Installation</h3>
<p>The <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> package is released within Bioconductor project.</p>
<p>To get the released version from Bioconductor:</p>
<pre><code>## try http:// if https:// URLs are not supported
source(&quot;https://bioconductor.org/biocLite.R&quot;)
biocLite(&quot;treeio&quot;)
</code></pre>
<p>Or the development version from github:</p>
<pre><code>## install.packages(&quot;devtools&quot;)
devtools::install_github(&quot;GuangchuangYu/treeio&quot;)
</code></pre>
<h2>Importing trees with data</h2>
<h3>Importing tree data from software outputs</h3>
<p>The <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> package provides several parser functions as illustrated in the following table:</p>
<table>
<thead>
<tr>
<th align="left">Parser function</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">read.beast</td>
<td align="left">parsing output of BEAST</td>
</tr>
<tr>
<td align="left">read.codeml</td>
<td align="left">parsing output of CodeML (rst and mlc files)</td>
</tr>
<tr>
<td align="left">read.codeml_mlc</td>
<td align="left">parsing mlc file (output of CodeML)</td>
</tr>
<tr>
<td align="left">read.hyphy</td>
<td align="left">parsing output of HYPHY</td>
</tr>
<tr>
<td align="left">read.jplace</td>
<td align="left">parsing jplace file including output of EPA and pplacer</td>
</tr>
<tr>
<td align="left">read.mrbayes</td>
<td align="left">parsing output of MrBayes</td>
</tr>
<tr>
<td align="left">read.newick</td>
<td align="left">parsing newick string, with ability to parse node label as support values</td>
</tr>
<tr>
<td align="left">read.nhx</td>
<td align="left">parsing NHX file including output of PHYLDOG and RevBayes</td>
</tr>
<tr>
<td align="left">read.paml_rst</td>
<td align="left">parsing rst file (output of BaseML or CodeML)</td>
</tr>
<tr>
<td align="left">read.phylip</td>
<td align="left">parsing phylip file (phylip alignment + newick string)</td>
</tr>
<tr>
<td align="left">read.r8s</td>
<td align="left">parsing output of r8s</td>
</tr>
<tr>
<td align="left">read.raxml</td>
<td align="left">parsing output of RAxML</td>
</tr>
</tbody>
</table>
<p>For example, users can parse <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a> output using <code>read.beast</code> function. All the information inferred by by <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a> will be stored in the output object.</p>
<pre><code>file &lt;- system.file(&quot;extdata/BEAST&quot;, &quot;beast_mcc.tree&quot;, package=&quot;treeio&quot;)
beast &lt;- read.beast(file)
beast
</code></pre>
<pre><code>## 'treedata' S4 object that stored information of
##  '/Library/R/library/treeio/extdata/BEAST/beast_mcc.tree'.
## 
## ...@ phylo: 
## Phylogenetic tree with 15 tips and 14 internal nodes.
## 
## Tip labels:
##  A_1995, B_1996, C_1995, D_1987, E_1996, F_1997, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##  'height',   'height_0.95_HPD',  'height_median',    'height_range', 'length',
##  'length_0.95_HPD',  'length_median',    'length_range', 'posterior',    'rate',
##  'rate_0.95_HPD',    'rate_median',  'rate_range'.
</code></pre>
<h3>Linking external data to phylogeny</h3>
<p>In addition to analysis findings that are associated with the tree as we showed above, there is a wide range of heterogeneous data, including phenotypic data, experimental data and clinical data <em>etc.</em>, that need to be integrated and linked to phylogeny. For example, in the study of viral evolution, tree nodes may be associated with epidemiological information, such as location, age and subtype. To facilitate data integration, <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> provides <code>full_join</code> method to link external data to phylogeny as demonstrated below:</p>
<pre><code>x &lt;- data_frame(label = as.phylo(beast)$tip.label, trait = rnorm(Ntip(beast)))
full_join(beast, x, by=&quot;label&quot;)
</code></pre>
<pre><code>## 'treedata' S4 object that stored information of
##  '/Library/R/library/treeio/extdata/BEAST/beast_mcc.tree'.
## 
## ...@ phylo: 
## Phylogenetic tree with 15 tips and 14 internal nodes.
## 
## Tip labels:
##  A_1995, B_1996, C_1995, D_1987, E_1996, F_1997, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##  'height',   'height_0.95_HPD',  'height_median',    'height_range', 'length',
##  'length_0.95_HPD',  'length_median',    'length_range', 'posterior',    'rate',
##  'rate_0.95_HPD',    'rate_median',  'rate_range',   'trait'.
</code></pre>
<pre><code>N &lt;- Nnode2(beast)
y &lt;- data_frame(node = 1:N, fake_trait = rnorm(N), another_trait = runif(N))
full_join(beast, y, by=&quot;node&quot;)
</code></pre>
<pre><code>## 'treedata' S4 object that stored information of
##  '/Library/R/library/treeio/extdata/BEAST/beast_mcc.tree'.
## 
## ...@ phylo: 
## Phylogenetic tree with 15 tips and 14 internal nodes.
## 
## Tip labels:
##  A_1995, B_1996, C_1995, D_1987, E_1996, F_1997, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##  'height',   'height_0.95_HPD',  'height_median',    'height_range', 'length',
##  'length_0.95_HPD',  'length_median',    'length_range', 'posterior',    'rate',
##  'rate_0.95_HPD',    'rate_median',  'rate_range',   'fake_trait',
##  'another_trait'.
</code></pre>
<h3>Combining tree data</h3>
<p>To allow comparative study, <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> supports combining multiple phylogenetic trees into one with their node/branch-specific attribute data.</p>
<p>The following example merges a tree analyzed by <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a> and <a rel="nofollow" href="http://abacus.gene.ucl.ac.uk/software/paml.html" target="_blank">CODEML</a>.</p>
<pre><code>beast_file &lt;- system.file(&quot;examples/MCC_FluA_H3.tree&quot;, package=&quot;ggtree&quot;)
rst_file &lt;- system.file(&quot;examples/rst&quot;, package=&quot;ggtree&quot;)
mlc_file &lt;- system.file(&quot;examples/mlc&quot;, package=&quot;ggtree&quot;)
beast_tree &lt;- read.beast(beast_file)
codeml_tree &lt;- read.codeml(rst_file, mlc_file)

merged_tree &lt;- merge_tree(beast_tree, codeml_tree)
merged_tree
</code></pre>
<pre><code>## 'treedata' S4 object that stored information of
##  '/Library/R/library/ggtree/examples/MCC_FluA_H3.tree',
##  '/Library/R/library/ggtree/examples/rst',
##  '/Library/R/library/ggtree/examples/mlc'.
## 
## ...@ phylo: 
## Phylogenetic tree with 76 tips and 75 internal nodes.
## 
## Tip labels:
##  A/Hokkaido/30-1-a/2013, A/New_York/334/2004, A/New_York/463/2005, A/New_York/452/1999, A/New_York/238/2005, A/New_York/523/1998, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##  'height',   'height_0.95_HPD',  'height_median',    'height_range', 'length',
##  'length_0.95_HPD',  'length_median',    'length_range', 'posterior',    'rate',
##  'rate_0.95_HPD',    'rate_median',  'rate_range',   'subs', 'AA_subs',  't',    'N',
##  'S',    'dN_vs_dS', 'dN',   'dS',   'N_x_dN',   'S_x_dS'.
</code></pre>
<p>After merging, the <code>merged_tree</code> object contains the whole set of node/branch attributes from both <code>beast_tree</code> and <code>codeml_tree</code>. The tree object can be converted to tidy data frame using <a rel="nofollow" href="https://cran.r-project.org/package=tidytree" target="_blank">tidytree</a> package and visualized as hexbin scatterplot of <em>d<sub>N</sub>/d<sub>S</sub></em>, <em>d<sub>N</sub></em> and <em>d<sub>S</sub></em> inferred by <a rel="nofollow" href="http://abacus.gene.ucl.ac.uk/software/paml.html" target="_blank">CODEML</a> versus <em>rate</em> (substitution rate in unit of substitutions/site/year) inferred by <a rel="nofollow" href="http://beast2.org/" target="_blank">BEAST</a> on the same branches, as an example to demonstrate comparison of node attributes inferred by different software.</p>
<pre><code>library(tidytree)
library(ggplot2)

as_data_frame(merged_tree) %>%
    dplyr::select(dN_vs_dS, dN, dS, rate) %>%
    subset(dN_vs_dS >=0 &amp; dN_vs_dS &lt;= 1.5) %>%
    tidyr::gather(type, value, dN_vs_dS:dS) %>%
    ggplot(aes(rate, value)) + geom_hex() +
    facet_wrap(~factor(type, levels = c('dN_vs_dS', 'dN', 'dS')),
               scale='free_y') +
    ylab(NULL)
</code></pre>
<p><img alt="hexbin scatter plot: correlation of dN/dS with substitution rate" src="https://i1.wp.com/ropensci.org/img/blog-images/2018-05-01-treeio/hexbin-scatterplot.png?w=456&ssl=1" data-recalc-dims="1"></p>
<p>With this feature, users are able to compare/integrate evolutionary inferences obtained from different software packages/models.</p>
<h2>Further readings</h2>
<p>For more details of importing trees with data, please refer to the <a rel="nofollow" href="http://bioconductor.org/packages/devel/bioc/vignettes/treeio/inst/doc/Importer.html" target="_blank">vignette</a>. In addition, <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> also supports exporting tree data to BEAST Nexus format, which allows software output format conversion and also enables combining external data with tree into a single file.</p>
<p>The following screenshot shows an example of exporting <a rel="nofollow" href="http://abacus.gene.ucl.ac.uk/software/paml.html" target="_blank">CODEML</a> output to BEAST Nexus file. The tree was visualized using FigTree and colored by <em>d<sub>N</sub></em>. For more details, please refer to the vignette, <a rel="nofollow" href="http://bioconductor.org/packages/devel/bioc/vignettes/treeio/inst/doc/Exporter.html" target="_blank">exporting trees with data</a>.</p>
<p><img alt="" src="https://i2.wp.com/raw.githubusercontent.com/GuangchuangYu/treeio/master/vignettes/figures/codeml.png?w=456&ssl=1" data-recalc-dims="1"></p>
<p>All the data parsed/merged by <a rel="nofollow" href="https://bioconductor.org/packages/treeio/" target="_blank">treeio</a> can be converted to tidy data frame using <a rel="nofollow" href="https://cran.r-project.org/package=tidytree" target="_blank">tidytree</a> and can be used to visualize and annotate the tree using <a rel="nofollow" href="https://bioconductor.org/packages/ggtree/" target="_blank">ggtree</a>.</p>
<p>For more details, please refer to the online vignettes:</p>
<ul>
<li><a rel="nofollow" href="https://cran.r-project.org/web/packages/tidytree/vignettes/tidytree.html" target="_blank">A Tidy Tool for Phylogenetic Tree Data Manipulation</a></li>
<li><a rel="nofollow" href="https://ropensci.org/blog/2018/05/17/treeio/treeVisualization.html" target="_blank">Tree Visualization</a></li>
<li><a rel="nofollow" href="https://ropensci.org/blog/2018/05/17/treeio/treeManipulation.html" target="_blank">Tree Manipulation</a></li>
<li><a rel="nofollow" href="https://ropensci.org/blog/2018/05/17/treeio/treeAnnotation.html" target="_blank">Tree Annotation</a></li>
<li><a rel="nofollow" href="https://cran.r-project.org/web/packages/emojifont/vignettes/phylomoji.html" target="_blank">Phylomoji</a></li>
<li><a rel="nofollow" href="https://guangchuangyu.github.io/software/ggtree/vignettes/ggtree-ggimage.html" target="_blank">Annotating phylogenetic tree with images</a></li>
<li><a rel="nofollow" href="https://guangchuangyu.github.io/software/ggtree/vignettes/ggtree-inset.html" target="_blank">Annotate a phylogenetic tree with insets</a></li>
</ul>
	<p>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="https://ropensci.org/blog/2018/05/17/treeio/"> rOpenSci - open tools for open science</a></strong>.</div>
<hr>
<a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="https://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a rel="nofollow" href="https://www.r-project.org/" title="The R Project for Statistical Computing">R</a> news and <a rel="nofollow" href="https://www.r-bloggers.com/search/tutorial" title="R tutorials">tutorials</a> on topics such as: <a rel="nofollow" href="https://www.r-bloggers.com/search/data%20science" title="Data science">Data science</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Big%20Data" title="Big Data">Big Data, <a rel="nofollow" href="https://www.r-users.com/" title="R jobs">R jobs</a>, visualization (<a rel="nofollow" href="https://www.r-bloggers.com/search/ggplot2" title="ggplot and ggplot2 tutorials">ggplot2</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/boxplot" title="Boxplots using lattice and ggplot2 tutorials">Boxplots</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/map" title="Maps and gis">maps</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/animation" title="Animation in R">animation</a>), programming (<a rel="nofollow" href="https://www.r-bloggers.com/search/RStudio" title="RStudio IDE for R">RStudio</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/sweave" title="Sweave and literate programming">Sweave</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/LaTeX" title="LaTeX in R">LaTeX</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/SQL" title="SQL and databases">SQL</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/eclipse" title="Eclipse IDE for R">Eclipse</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/git" title="git and github, Version Control System">git</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/hadoop" title="Large data in R using Hadoop">hadoop</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Web+Scraping" title="Web Scraping of google, facebook, yahoo, twitter and more using R">Web Scraping</a>) statistics (<a rel="nofollow" href="https://www.r-bloggers.com/search/regression" title="Regressions and ANOVA analysis tutorials">regression</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/PCA" title="principal component analysis tutorial">PCA</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/time+series" title="Time series">time series</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/trading" title="finance trading">trading</a>) and more...
<img width="1" alt="" src="http://feeds.feedburner.com/~r/RBloggers/~4/nnsuWyk0_wY" height="1"></a></div>