10_ggtree_utilities.Rmd

# (PART\*) Part III: Miscellaneous topics {-}

# ggtree utilities {#chapter10}

## facet utilities

### facet_widths


```{r eval=F}
library(ggplot2)
library(ggstance)
library(ggtree)
library(reshape2)

set.seed(123)
tree <- rtree(30)

p <- ggtree(tree, branch.length = "none") + 
    geom_tiplab() + theme(legend.position='none')

a <- runif(30, 0,1)
b <- 1 - a
df <- data.frame(tree$tip.label, a, b)
df <- melt(df, id = "tree.tip.label")

p2 <- facet_plot(p + xlim_tree(8), panel = 'bar', data = df, geom = geom_barh, 
                 mapping = aes(x = value, fill = as.factor(variable)), 
                 width = 0.8, stat='identity') + xlim_tree(9)

facet_widths(p2, widths = c(1, 2))
```

It also supports using name vector to set the widths of specific panels. The following code will display identical figure to Figure \@ref(fig:facetWidth)A.

```r
facet_widths(p2, c(Tree = .5))
```


The `facet_widths` function also work with other `ggplot` object as demonstrated in Figure \@ref(fig:facetWidth)B.


```{r eval=FALSE}
p <- ggplot(iris, aes(Sepal.Width, Petal.Length)) + 
  geom_point() + facet_grid(.~Species)
facet_widths(p, c(setosa = .5))
```

(ref:facetWidthscap) Adjust relative widths of ggplot facets.

(ref:facetWidthcap) **Adjust relative widths of ggplot facets.** The `facet_widths` function works with `ggtree` (A) as well as `ggplot` (B).

```{r facetWidth, echo=F, fig.width=6, fig.height=7, fig.scap="(ref:facetWidthscap)", fig.cap="(ref:facetWidthcap)"}
library(ggplot2)
library(ggstance)
library(ggtree)
library(reshape2)

set.seed(123)
tree <- rtree(30)

p <- ggtree(tree, branch.length = "none") + 
    geom_tiplab() + theme(legend.position='none')

a <- runif(30, 0,1)
b <- 1 - a
df <- data.frame(tree$tip.label, a, b)
df <- melt(df, id = "tree.tip.label")

p2 <- facet_plot(p + xlim_tree(8), panel = 'bar', data = df, geom = geom_barh, 
                 mapping = aes(x = value, fill = as.factor(variable)), 
                 width = 0.8, stat='identity') + xlim_tree(9)

pp = facet_widths(p2, widths = c(1, 2))

g <- ggplot(iris, aes(Sepal.Width, Petal.Length)) + 
  geom_point() + facet_grid(.~Species)
gg = facet_widths(g, c(setosa = .5))

plot_grid(plot_grid(ggdraw(), pp, rel_widths=c(.04, 1)), 
        gg, ncol=1, labels = LETTERS[1:2], rel_heights=c(1.5, 1))
```


### facet_labeller

The `facet_labeller` function was designed to re-label selected panels, and it currently only works with `ggtree` object (*i.e.* `facet_plot` output).

```{r eval=F}
facet_labeller(p2, c(Tree = "phylogeny", bar = "HELLO"))
```

If you want to combine `facet_widths` with `facet_labeller`, you need to call `facet_labeller` to re-label the panels before using `facet_widths` to set the relative widths of each panels. Otherwise it wont work since the output of `facet_widths` is re-drawn from `grid` object.

```{r eval=F}
facet_labeller(p2, c(Tree = "phylogeny")) %>% facet_widths(c(Tree = .4))
```

(ref:facetLabscap) Rename facet labels.

(ref:facetLabcap) **Rename facet labels.** Rename multiple labels simultaneously (A) or only for specific one (B) are all supported. `facet_labeller` can combine with `facet_widths` to rename facet label and then adjust relative widths (B).


```{r facetLab, echo=FALSE,fig.width=6, fig.height=9, fig.scap="(ref:facetLabscap)", fig.cap="(ref:facetLabcap)"}
pg1 <- facet_labeller(p2, c(Tree = "phylogeny", bar = "HELLO"))
pg2 <- facet_labeller(p2, c(Tree = "phylogeny")) %>% facet_widths(c(Tree = .4))
plot_grid(plot_grid(ggdraw(), pg1, rel_widths=c(.04, 1)), 
        plot_grid(ggdraw(), pg2, rel_widths=c(.04, 1)), 
        ncol=1, labels = c("A", "B"))
```

## layout utilities

In [session 4.2.2](#tree-layouts), we introduce several layouts that supported by `r Biocpkg("ggtree")`. The `r Biocpkg("ggtree")` package also provide several layout functions that can transfrom from one to another. Note that not all layouts are supported (see \@ref(tab:layoutLayerTab)).

```{r layoutLayerTab, echo=FALSE}
layout.df = tibble::tribble(~Layout, ~Description,
    "layout_circular",      "transform rectangular layout to circular layout",
    "layout_dendrogram",    "transform rectangular layout to dendrogram layout",
    "layout_fan",           "transform rectangular/circular layout to fan layout",
    "layout_rectangular",   "transform circular/fan layout to rectangular layout")
knitr::kable(layout.df, caption = "Layout layers.", booktabs = T)
```


```{r eval=FALSE}
set.seed(2019)
x <- rtree(20)
p <- ggtree(x)
p + layout_dendrogram()
ggtree(x, layout = "circular") + layout_rectangular()
p + layout_circular()
p + layout_fan(angle=90)
```


(ref:layoutLayerscap) Layout layers for transforming among different layouts.

(ref:layoutLayercap) **Layout layers for transforming among different layouts**. Default rectangular layout (A); transform rectangular to dendrogram layout (B); transform circular to rectangular layout (C); transform rectangular to circular layout (D); transform rectangular to fan layout (E).


```{r layoutLayer, echo=FALSE, fig.width=7.2, fig.height=6, message=FALSE, fig.cap="(ref:layoutLayercap)", fig.scap="(ref:layoutLayerscap)"}
set.seed(2019)
x <- rtree(20)
p <- ggtree(x)

pp1 <- cowplot::plot_grid(
    p,
    p + layout_dendrogram(),
    p + layout_circular() + layout_rectangular(),
    ncol=3, labels = LETTERS[1:3])

pp2 <- cowplot::plot_grid(
    p + layout_circular(), 
    p + layout_fan(angle=90),
    ncol=2, labels = LETTERS[4:5])

cowplot::plot_grid(pp1, pp2, ncol=1, rel_heights=c(2, 3))
```


## legend utilities


## scale utilities

### xlim_expand {#xlim_expand}

Sometimes we need to set `xlim` for specific panel (*e.g.* allocate more space for [long tip labels](#faq-label-truncated) at `Tree` panel). However, the `ggplot2::xlim()` function applies to all the panels. `r Biocpkg("ggtree")` provides `xlim_expand()` to adjust `xlim` for user specific panel. It accepts two parameters, `xlim` and `panel`, and can adjust all individual panels as demonstrated in Figure \@ref(fig:xlimExpand)A. If you only want to adjust `xlim` of the `Tree` panel, you can use `xlim_tree()` as a shortcut.


```{r eval=FALSE}
set.seed(2019-05-02)
x <- rtree(30)
p <- ggtree(x) + geom_tiplab()
d <- data.frame(label = x$tip.label, 
                value = rnorm(30))
p2 <- facet_plot(p, panel = "Dot", data = d, 
            geom = geom_point, mapping = aes(x = value))
p2 + xlim_tree(6) + xlim_expand(c(-10, 10), 'Dot')
```



The `xlim_expand()` function also works with `ggplot2::facet_grid()`. As demonstrating in Figure \@ref(fig:xlimExpand)B, only the `xlim` of *virginica* panel was adjusted by `xlim_expand()`.


```{r eval=FALSE}
g <- ggplot(iris, aes(Sepal.Length, Sepal.Width)) + 
    geom_point() + facet_grid(. ~ Species, scales = "free_x") 
g + xlim_expand(c(0, 15), 'virginica')
```    

(ref:xlimExpandscap) Setting xlim for user specific panel.

(ref:xlimExpandcap) **Setting xlim for user specific panel.** xlim for `ggtree::facet_plot` (A, Tree and Dot panels), and `ggplot2::facet_grid` (B, virginica panel).


```{r xlimExpand, echo=FALSE, fig.cap="(ref:xlimExpandcap)", fig.scap="(ref:xlimExpandscap)", fig.width=12, fig.height = 5}
set.seed(2019-05-02)
x <- rtree(30)
p <- ggtree(x) + geom_tiplab()
d <- data.frame(label = x$tip.label, 
                value = rnorm(30))
p2 <- facet_plot(p, panel = "Dot", data = d, 
            geom = geom_point, mapping = aes(x = value))
p2 <- p2 + xlim_expand(c(0, 6), 'Tree') + xlim_expand(c(-10, 10), 'Dot')            
g <- ggplot(iris, aes(Sepal.Length, Sepal.Width)) + 
    geom_point() + facet_grid(. ~ Species, scales = "free_x") 

plot_grid(plot_grid(ggdraw(), p2, rel_widths=c(.04, 1)),
    g + theme_grey() + xlim_expand(c(0, 15), 'virginica'),
    ncol=2, labels=c("A", "B"))
```