% \VignetteIndexEntry{Circular phylogenetic tree}
% \VignetteDepends{circlize}
% \VignetteKeywords{circos R}
% \VignetteKeywords{Phylogenetic tree}
% \VignetteKeywords{circlize}
% \VignettePackage{circlize}
%\VignetteCompiler{knitr}
%\VignetteEngine{knitr::knitr}

<<echo = FALSE>>=
library(knitr)
opts_chunk$set(fig.pos = "")

library(circlize)
circos.initialize = function(...) {
    circos.par(unit.circle.segments = 300)
    circlize::circos.initialize(...)
}
@

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage[sc]{mathpazo}
\renewcommand{\sfdefault}{lmss}
\renewcommand{\ttdefault}{lmtt}

\title{How to draw a phylogenetic tree}

\author{Zuguang Gu {\tt <z.gu@dkfz.de>}}
\usepackage[margin=1in, a4paper]{geometry}

\usepackage{hyperref}


\begin{document}

\maketitle 

In this short vignette, we will show how to customize the circular style of 
phylogenetic tree through \textbf{circlize} package. Basically, a phylogenetic tree is 
a dendrogram which is a combination of lines. In R, there are several classes that 
describe such type of tree such as {\tt hclust}, {\tt dendrogram} and {\tt phylo}. 
In this example, we will demonstrate how to draw the tree from the {\tt dendrogram} class. 
Nevertheless, other classes can be converted to {\tt dendrogram} without too much difficulty.

The {\tt bird.orders} data we are using here is from \textbf{ape} package. This data set is 
related to species of birds. We split the tree into six sub trees by {\tt cutree}
and convert the data into a {\tt dendrogram} object.

<<eval = FALSE>>=
library(ape)
data(bird.orders)
hc = as.hclust(bird.orders)
@

<<echo = FALSE>>=
load(paste0(system.file(package = "circlize"), "/extdata/bird.orders.RData"))
@

<<>>=
labels = hc$labels  # name of birds
ct = cutree(hc, 6)  # cut tree into 6 pieces
n = length(labels)  # number of bird species
dend = as.dendrogram(hc)
@

As we mentioned in the main vignette, the x-value for the phylogenetic tree is in fact index. 
Thus, the x-lim is just the minimum and maximum index of labels in the tree. Since there is 
only one phylogenetic tree, we only need one ``big" sector. In the first track, 
we plot the name of each bird, with different colors to represent different sub trees. 

{\tt max\_height} is the maximum height of tree and is used to calculate the height of the track.

<<phylogenetic_tree_part1, eval = FALSE>>=
library(circlize)
circos.par(cell.padding = c(0, 0, 0, 0))
circos.initialize(factors = "a", xlim = c(0, n)) # only one sector
max_height = attr(dend, "height")  # maximum height of the trees
circos.trackPlotRegion(ylim = c(0, 1), bg.border = NA, track.height = 0.3, 
    panel.fun = function(x, y) {
        for(i in seq_len(n)) {
            circos.text(i-0.5, 0, labels[i], adj = c(0, 0.5), 
                facing = "clockwise", niceFacing = TRUE,
                col = ct[labels[i]], cex = 0.7)
        }
})
@

In the above code, set {\tt xlim} to {\tt c(0, n)} is very important because the leaves of 
the dendrogram are drawn at {\tt x = seq(0.5, n - 0.5)}.

In the second track, we plot the circular dendrogram by {\tt circos.dendrogram}. You can
render the dendrogram by \textbf{dendextend} package (figure \ref{fig:phylogenetic_tree} A).

<<phylogenetic_tree_part2, eval = FALSE, message = FALSE, text = FALSE>>=
suppressPackageStartupMessages(library(dendextend))
dend = color_branches(dend, k = 6, col = 1:6)
circos.trackPlotRegion(ylim = c(0, max_height), bg.border = NA, 
    track.height = 0.4, panel.fun = function(x, y) {
        circos.dendrogram(dend, max_height = max_height)
})
circos.clear()
@

By default, dendrograms are facing outside of the circle. You can set {\tt facing}
argument to {\tt inside} to make them facing inside. but of course you need to
adjust the name track to the inside of the dendrogram track (figure \ref{fig:phylogenetic_tree} B).

<<eval = FALSE>>=
circos.dendrogram(dend, max_height = max_height, facing = "inside")
@

<<phylogenetic_tree_part3, eval = FALSE, message = FALSE>>=
circos.par(cell.padding = c(0, 0, 0, 0))
circos.initialize(factors = "a", xlim = c(0, n)) # only one sector
circos.trackPlotRegion(ylim = c(0, max_height), bg.border = NA, 
    track.height = 0.4, panel.fun = function(x, y) {
        circos.dendrogram(dend, max_height = max_height, facing = "inside")
})
circos.trackPlotRegion(ylim = c(0, 1), bg.border = NA, track.height = 0.3, 
    panel.fun = function(x, y) {
        for(i in seq_len(n)) {
            circos.text(i-0.5, 1, labels[i], adj = c(1, 0.5), 
                facing = "clockwise", niceFacing = TRUE,
                col = ct[labels[i]], cex = 0.7)
        }
})
circos.clear()
@

With the flexibility of {\bf circlize} package, it would be easy add more tracks if you want to add more corresponded information for the dendrogram to the plot.

Figure \ref{fig:phylogenetic_tree} C is the normal dendrogram.

<<phylogenetic_tree, echo = FALSE, fig.align = "center", out.width = "\\textwidth", out.height = "\\textwidth", fig.width = 10, fig.height = 10, fig.cap = "A simple phylogenetic tree. A: circular style; B) dendrogram is facing inside of the circle; C: normal style.">>=
par(mfrow = c(2, 2))
<<phylogenetic_tree_part1>>
<<phylogenetic_tree_part2>>
text(-0.9, 0.9, "A", cex = 1.5)
<<phylogenetic_tree_part3>>
text(-0.9, 0.9, "B", cex = 1.5)

par(mar = c(8, 4, 4, 1))
plot(dend, main = "C")
@


\end{document}
