<!--
%\VignetteEngine{knitr}
%\VignetteIndexEntry{4. Heatmap Annotations}
-->

Heatmap Annotations
========================================

**Author**: Zuguang Gu ( z.gu@dkfz.de )

**Date**: `r Sys.Date()`

-------------------------------------------------------------

```{r global_settings, echo = FALSE, message = FALSE}
library(markdown)
options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))

library(knitr)
knitr::opts_chunk$set(
    error = FALSE,
    tidy  = FALSE,
    message = FALSE,
    fig.align = "center",
    fig.width = 5,
    fig.height = 5)
options(markdown.HTML.stylesheet = "custom.css")

options(width = 100)
```

The annotation graphics actually are quite general. The only common characteristic for annotations
is that they are aligned to the columns or rows of the heatmap. Here there is a `HeatmapAnnotation` class which is used to 
define annotations on columns or rows.

## Column annotation

### Simple annotation

A simple annotation is defined as a vector which contains discrete classes or continuous values.
Since the simple annotation is represented as a vector, multiple simple annotations can be specified
as a data frame. Colors for the simple annotations can be specified by `col` with a vector or
color mapping functions, depending on whether the simple annotations are discrete or continuous.

In the heatmap, simple annotations will be represented as rows of grids.

There is a `draw()` method for the `HeatmapAnnotation` class. `draw()` is used internally and here
we just use it for demonstration.

```{r heatmap_annotation, fig.width = 7, fig.height = 0.5}
library(ComplexHeatmap)
library(circlize)

df = data.frame(type = c(rep("a", 5), rep("b", 5)))
ha = HeatmapAnnotation(df = df)
ha
draw(ha, 1:10)
```

The color of simple annotation should be specified as a list with names for which names in the color list (here it is `type` in following example)
correspond to the names in the data frame. Each color vector should better has names as well to map to 
the levels of annotations.

```{r heatmap_annotation_col, fig.width = 7, fig.height = 0.5}
ha = HeatmapAnnotation(df = df, col = list(type = c("a" =  "red", "b" = "blue")))
ha
draw(ha, 1:10)
```

For continuous annotation, colors should be a color mapping function.

```{r heatmap_annotation_colfun, fig.width = 7, fig.height = 0.5}
ha = HeatmapAnnotation(df = data.frame(age = sample(1:20, 10)),
    col = list(age = colorRamp2(c(0, 20), c("white", "red"))))
ha
draw(ha, 1:10)
```

Color for `NA` can be set by `na_col`:

```{r, fig.width = 7, fig.height = 1}
df2 = data.frame(type = c(rep("a", 5), rep("b", 5)),
                age = sample(1:20, 10))
df2$type[5] = NA
df2$age[5] = NA
ha = HeatmapAnnotation(df = df2, 
  col = list(type = c("a" =  "red", "b" = "blue"),
             age = colorRamp2(c(0, 20), c("white", "red"))),
  na_col = "grey")
draw(ha, 1:10)
```

Put more than one annotations by a data frame.

```{r heatmap_annotation_mixed, fig.width = 7, fig.height = 1}
df = data.frame(type = c(rep("a", 5), rep("b", 5)),
                age = sample(1:20, 10))
ha = HeatmapAnnotation(df = df,
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red")))
)
ha
draw(ha, 1:10)
```

Also individual annotations can be directly specified as vectors:

```{r heatmap_annotation_vector, fig.width = 7, fig.height = 1}
ha = HeatmapAnnotation(type = c(rep("a", 5), rep("b", 5)),
                       age = sample(1:20, 10),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red")))
)
ha
draw(ha, 1:10)
```

To put column annotation to the heatmap, specify `top_annotation` and `bottom_annotation` in `Heatmap()`.

```{r heatmap_column_annotation}
ha1 = HeatmapAnnotation(df = df,
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red")))
)
ha2 = HeatmapAnnotation(df = data.frame(age = sample(1:20, 10)),
    col = list(age = colorRamp2(c(0, 20), c("white", "red"))))

set.seed(123)
mat = matrix(rnorm(80, 2), 8, 10)
mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))
rownames(mat) = paste0("R", 1:12)
colnames(mat) = paste0("C", 1:10)

Heatmap(mat, top_annotation = ha1, bottom_annotation = ha2)
```

### Complex annotations

Besides simple annotations, there are complex annotations. The complex annotations are always
represented as self-defined graphic functions. Actually, for each column annotation, there will be a viewport
created waiting for graphics. The annotation function here defines how to put the graphics to
this viewport. The only argument of the function is an index of column which is already adjusted by column clustering.

In following example, an annotation of points is created. Please note how we define `xscale` so that positions
of points correspond to middle points of the columns if the annotation is added to the heatmap.

```{r heatmap_annotation_complex, fig.width = 7, fig.height = 1}
value = rnorm(10)
column_anno = function(index) {
    n = length(index)
    # since middle of columns are in 1, 2, ..., n and each column has width 1
    # then the most left should be 1 - 0.5 and the most right should be n + 0.5
    pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = range(value)))
    # since order of columns will be adjusted by clustering, here we also 
    # need to change the order by `[index]`
    grid.points(index, value[index], pch = 16, default.unit = "native")
    # this is very important in order not to mess up the layout
    upViewport() 
}
ha = HeatmapAnnotation(points = column_anno)  # here the name is arbitrary
ha
draw(ha, 1:10)
```

Above code is only for demonstration. You don't realy need to define a points annotation,
there are already several annotation generators provided in the package such as `anno_points()` or `anno_barplot()`
which generate such complex annotation function:

- `anno_points()`
- `anno_barplot()`
- `anno_boxplot()`
- `anno_histogram()`
- `anno_density()`
- `anno_text()`

The input value for these `anno_*` functions is quite straightforward. It should be a numeric vector 
(e.g. for `anno_points()` and `anno_barplot()`), a matrix or list (for `anno_boxplot()`, `anno_histogram()` 
or `anno_density()`), or a character vector (for `anno_text()`).

```{r heatmap_annotation_points, fig.width = 7, fig.height = 1}
ha = HeatmapAnnotation(points = anno_points(value))
draw(ha, 1:10)
```

```{r heatmap_annotation_barplot, fig.width = 7, fig.height = 1}
ha = HeatmapAnnotation(barplot = anno_barplot(value))
draw(ha, 1:10)
```

`anno_boxplot()` generates boxplot for each column in the matrix.

```{r heatmap_annotation_boxplot, fig.width = 7, fig.height = 1}
ha = HeatmapAnnotation(boxplot = anno_boxplot(mat))
draw(ha, 1:10)
```

You can mix simple annotaitons and complex annotations:

```{r heatmap_annotation_mixed_with_complex, fig.width = 7, fig.height = 2}
ha = HeatmapAnnotation(df = df, 
                       points = anno_points(value),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))))
ha
draw(ha, 1:10)
```

Since simple annotations can also be specified as vectors, actually you arrange annotations in any order:

```{r, fig.width = 7, fig.height = 2}
ha = HeatmapAnnotation(type = c(rep("a", 5), rep("b", 5)),
                       points = anno_points(value),
                       age = sample(1:20, 10), 
                       bars = anno_barplot(value),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))))
ha
draw(ha, 1:10)
```

For some of the `anno_*` functions, graphic parameters can be set by `gp` argument.
Also note how we specify `baseline` in `anno_barplot()`.

```{r heatmap_annotation_anno_gp, fig.width = 7, fig.height = 3}
ha = HeatmapAnnotation(barplot1 = anno_barplot(value, baseline = 0, gp = gpar(fill = ifelse(value > 0, "red", "green"))),
                       points = anno_points(value, gp = gpar(col = rep(1:2, 5))),
                       barplot2 = anno_barplot(value, gp = gpar(fill = rep(3:4, 5))))
ha
draw(ha, 1:10)
```

If there are more than one annotations, you can control height of each annotation by `annotation_height`.
The value of `annotation_height` can either be numeric values or `unit` objects.

```{r, fig.width = 7, fig.height = 3}
# set annotation height as relative values
ha = HeatmapAnnotation(df = df, points = anno_points(value), boxplot = anno_boxplot(mat),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))),
    annotation_height = c(1, 2, 3, 4))
draw(ha, 1:10)
```

```{r, fig.width = 7, fig.height = 3}
# set annotation height as absolute units
ha = HeatmapAnnotation(df = df, points = anno_points(value), boxplot = anno_boxplot(mat),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))),
    annotation_height = unit.c((unit(1, "npc") - unit(4, "cm"))*0.5, (unit(1, "npc") - unit(4, "cm"))*0.5, 
        unit(2, "cm"), unit(2, "cm")))
draw(ha, 1:10)
```

With the annotation constructed, you can assign to the heatmap either by `top_annotation` or `bottom_annotation`.
Also you can control the size of total column annotations by `top_annotation_height` and `bottom_annotation_height`
if the height of the annotations are relative values.

If the annotation has proper size (high enough), it would be helpful to add axis on it. `anno_points()`, `anno_barplot()` 
and `anno_boxplot()` support axes. Please note we didn't pre-allocate space for axes particularly, 
we only assume there are already empty spaces for showing axes.

```{r add_annotation}
ha = HeatmapAnnotation(df = df, points = anno_points(value),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))))
ha_boxplot = HeatmapAnnotation(boxplot = anno_boxplot(mat, axis = TRUE))
Heatmap(mat, name = "foo", top_annotation = ha, bottom_annotation = ha_boxplot, 
    bottom_annotation_height = unit(3, "cm"))
```

Gaps below each annotation can be specified by `gap` in `HeatmapAnnotation()`. 

```{r}
ha = HeatmapAnnotation(df = df, points = anno_points(value), gap = unit(c(2, 4), "mm"),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))))
Heatmap(mat, name = "foo", top_annotation = ha)
```

You can suppress some of the annotation legend by specifying `show_legend` to `FALSE` when creating the `HeatmapAnnotation` object.

```{r annotation_show}
ha = HeatmapAnnotation(df = df, show_legend = c(FALSE, TRUE),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))))
Heatmap(mat, name = "foo", top_annotation = ha)
```

More types of annotations which show data distribution in corresponding columns are supported
by `anno_histogram()` and `anno_density()`.

```{r annotation_more, fig.height = 10, fig.width = 7}
ha_mix_top = HeatmapAnnotation(histogram = anno_histogram(mat, gp = gpar(fill = rep(2:3, each = 5))),
    density_line = anno_density(mat, type = "line", gp = gpar(col = rep(2:3, each = 5))),
    violin = anno_density(mat, type = "violin", gp = gpar(fill = rep(2:3, each = 5))),
    heatmap = anno_density(mat, type = "heatmap"))
Heatmap(mat, name = "foo", top_annotation = ha_mix_top, top_annotation_height = unit(8, "cm"))
```

Text is also one of the annotaiton graphics. `anno_text()` supports adding text as heatmap annotations. With this annotation
function, it is easy to simulate column names with rotations. 
Note you need to calcualte the space for the text annotations by hand and the package doesn't garentee
that all the rotated text are shown in the plot (In following figure, if row names and legend are not drawn,
'C10C10C10' will show completely, but there are some tricks which can be found in the [**Examples**](s9.examples.html) vignette).

```{r rotated_column_names}
long_cn = do.call("paste0", rep(list(colnames(mat)), 3))  # just to construct long text
ha_rot_cn = HeatmapAnnotation(text = anno_text(long_cn, rot = 45, just = "left", offset = unit(2, "mm")))
Heatmap(mat, name = "foo", top_annotation = ha_rot_cn, top_annotation_height = unit(2, "cm"))
```

## Row annotations

Row annotation is also defined by the `HeatmapAnnotation` class, but with specifying
`which` to `row`.

```{r row_annotation, fig.width = 1, fig.height = 7}
df = data.frame(type = c(rep("a", 6), rep("b", 6)))
ha = HeatmapAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")),
    which = "row", width = unit(1, "cm"))
draw(ha, 1:12)
```

There is a helper function `rowAnnotation()` which is same as `HeatmapAnnotation(..., which = "row")`.

```{r, eval = FALSE}
ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")), width = unit(1, "cm"))
```

`anno_*` functions also works for row annotations, by you need to add `which = "row"` in the function.
E.g:

```{r, eval = FALSE}
ha = rowAnnotation(points = anno_points(runif(10), which = "row"))
```

Similar as `rowAnnotation()`, there are corresponding wrapper `anno_*` functions. There functions
are almost same as the original functions except pre-defined `which` argument to `row`.

- `row_anno_points()`
- `row_anno_barplot()`
- `row_anno_boxplot()`
- `row_anno_histogram()`
- `row_anno_density()`
- `row_anno_text()`

Similar, there can be more than one row annotations. 

```{r, fig.width = 3, fig.height = 7}
ha_combined = rowAnnotation(df = df, boxplot = row_anno_boxplot(mat), 
    col = list(type = c("a" = "red", "b" = "blue")),
    annotation_width = c(1, 3))
draw(ha_combined, 1:12)
```

### Mix heatmaps and row annotations

Essentially, row annotations and column annotations are identical graphics, but in practice,
there is some difference. In **ComplexHeatmap** package, row annotations have the same place as the heatmap
while column annotations are just like accessory components of heatmaps. The idea here is that row annotations
can be corresponded to all the heatmaps in the list while column annotations can only be corresponded to its own heatmap. 
For row annotations, similar
as heatmaps, you can append the row annotations to heatmap or heatmap list or even row annotation object itself.
The order of elements in row annotations will be adjusted by the clustering of heatmaps.

```{r heatmap_list_with_row_annotation, fig.width = 9}
ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")),
    width = unit(1, "cm"))
ht1 = Heatmap(mat, name = "ht1")
ht2 = Heatmap(mat, name = "ht2")
ht1 + ha + ht2
```

If `km` or `split` is set in the main heatmap, the row annotations are
splitted as well.

```{r heatmap_list_with_row_annotation_complex}
ht1 = Heatmap(mat, name = "ht1", km = 2)
ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")),
    boxplot = row_anno_boxplot(mat, axis = TRUE), 
    annotation_width = unit(c(1, 5), "cm"))
ha + ht1
```

When row split is applied, graphical parameters for annotation function can be specified as with the same length
as the number of row slices.

```{r heatmap_list_with_row_annotation_graphical_parameter}
ha = rowAnnotation(boxplot = row_anno_boxplot(mat, gp = gpar(fill = c("red", "blue"))), 
    width = unit(2, "cm"))
ha + ht1
```

Since only row clustering and row titles for the main heatmap are kept, they can be adjusted to the most left or right side
of the plot by setting `row_hclust_side` and `row_sub_title_side`:

```{r heatmap_list_hclust_title_side}
draw(ha + ht1, row_dend_side = "left", row_sub_title_side = "right")
```

### Self define row annotations

Self-defining row annotations is same as self-defining column annotations. The only
difference is that x coordinate and y coordinate are switched. If row annotations
are split by rows, the argument `index` will automatically be the index in the 'current' row slice.

```{r}
value = rowMeans(mat)
row_anno = function(index) {
    n = length(index)
    pushViewport(viewport(xscale = range(value), yscale = c(0.5, n + 0.5)))
    grid.rect()
    # recall row order will be adjusted, here we specify `value[index]`
    grid.points(value[index], seq_along(index), pch = 16, default.unit = "native")
    upViewport()
}
ha = rowAnnotation(points = row_anno, width = unit(1, "cm"))
ht1 + ha
```

For the self-defined annotation function, there can be a second argument `k` which gives the index of 'current' row slice.

```{r}
row_anno = function(index, k) {
    n = length(index)
    col = c("blue", "red")[k]
    pushViewport(viewport(xscale = range(value), yscale = c(0.5, n + 0.5)))
    grid.rect()
    grid.points(value[index], seq_along(index), pch = 16, default.unit = "native", gp = gpar(col = col))
    upViewport()
}
ha = rowAnnotation(points = row_anno, width = unit(1, "cm"))
ht1 + ha
```

### Heatmap with zero row

If you only want to visualize meta data of your matrix, you can set the matrix with zero row.
In this case, only one heatmap is allowed.

```{r zero_row_heatmap, fig.height = 2}
ha = HeatmapAnnotation(df = data.frame(value = runif(10), type = rep(letters[1:2], 5)),
    barplot = anno_barplot(runif(10)),
    points = anno_points(runif(10)))
zero_row_mat = matrix(nrow = 0, ncol = 10)
colnames(zero_row_mat) = letters[1:10]
Heatmap(zero_row_mat, top_annotation = ha, column_title = "only annotations")
```

This feature is very useful if you want to compare multiple metrics. Axes and labels in following plot
are added by [heatmap decoration](s6.heatmap_decoration.html). Also notice how we adjust 
paddings of the plotting regions to give enough space for hte axis labels. 

```{r, fig.height = 5}
ha = HeatmapAnnotation(df = data.frame(value = runif(10), type = rep(letters[1:2], 5)),
    barplot = anno_barplot(runif(10), axis = TRUE),
    points = anno_points(runif(10), axis = TRUE),
    annotation_height = unit(c(0.5, 0.5, 4, 4), "cm"))
zero_row_mat = matrix(nrow = 0, ncol = 10)
colnames(zero_row_mat) = letters[1:10]
ht = Heatmap(zero_row_mat, top_annotation = ha, column_title = "only annotations")
draw(ht, padding = unit(c(2, 20, 2, 2), "mm"))
decorate_annotation("value", {grid.text("value", unit(-2, "mm"), just = "right")})
decorate_annotation("type", {grid.text("type", unit(-2, "mm"), just = "right")})
decorate_annotation("barplot", {
    grid.text("barplot", unit(-10, "mm"), just = "bottom", rot = 90)
    grid.lines(c(0, 1), unit(c(0.2, 0.2), "native"), gp = gpar(lty = 2, col = "blue"))
})
decorate_annotation("points", {
    grid.text("points", unit(-10, "mm"), just = "bottom", rot = 90)
})
```

### Heatmap with zero column

If no heatmap is needed to draw and users only want to arrange a list of row annotations, an empty
matrix with no column can be added to the heatmap list. Within the zero-column matrix, you can either
split row annotaitons:

```{r all_row_annotations, fig.width = 4}
ha_boxplot = rowAnnotation(boxplot = row_anno_boxplot(mat), width = unit(3, "cm"))
ha = rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")), width = unit(2, "cm"))
text = paste0("row", seq_len(nrow(mat)))
ha_text = rowAnnotation(text = row_anno_text(text), width = max_text_width(text))
nr = nrow(mat)
Heatmap(matrix(nrow = nr, ncol = 0), split = sample(c("A", "B"), nr, replace = TRUE)) + 
    ha_boxplot + ha + ha_text
```

or add dendrograms to the row annotations:

```{r no_heatmap_but_with_cluster, fig.width = 4}
dend = hclust(dist(mat))
Heatmap(matrix(nrow = nr, ncol = 0), cluster_rows = dend) + 
    ha_boxplot + ha + ha_text
```

Remember it is not allowed to only concantenate row annotations because row annotations don't provide
information of number of rows.

### Use heatmap instead of simple row annotations

Finally, if your row annotations are simple annotations, I recommand to use heatmap instead.
Following two methods generate similar figures.

```{r}
df = data.frame(type = c(rep("a", 6), rep("b", 6)))
Heatmap(mat) + rowAnnotation(df = df, col = list(type = c("a" = "red", "b" = "blue")), 
    width = unit(1, "cm"))
Heatmap(mat) + Heatmap(df, name = "type", col = c("a" = "red", "b" = "blue"), 
    width = unit(1, "cm"))
```

## Axes for annotations

Axes for complex annotations are important to show range and direction of the data. `anno_*` functions
provide `axis` and `axis_side` arguments to control the axes.

```{r}
ha1 = HeatmapAnnotation(b1 = anno_boxplot(mat, axis = TRUE),
    p1 = anno_points(colMeans(mat), axis = TRUE))
ha2 = rowAnnotation(b2 = row_anno_boxplot(mat, axis = TRUE),
    p2 = row_anno_points(rowMeans(mat), axis = TRUE), width = unit(2, "cm"))
Heatmap(mat, top_annotation = ha1, top_annotation_height = unit(2, "cm")) + ha2
```

For row annotations, by default direction of the data is from left to right. But it may confuse people
if the row annotation is placed on the left of the heatmap. You can change axis directions for row annotations
by `axis_direction`. Compare following two plots:

```{r, fig.width = 10}
pushViewport(viewport(layout = grid.layout(nr = 1, nc = 2)))
pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 1))
ha = rowAnnotation(boxplot = row_anno_boxplot(mat, axis = TRUE), width = unit(3, "cm"))
ht_list = ha + Heatmap(mat)
draw(ht_list, column_title = "normal axis direction", newpage = FALSE)
upViewport()

pushViewport(viewport(layout.pos.row = 1, layout.pos.col = 2))
ha = rowAnnotation(boxplot = row_anno_boxplot(mat, axis = TRUE, axis_direction = "reverse"), 
    width = unit(3, "cm"))
ht_list = ha + Heatmap(mat)
draw(ht_list, column_title = "reverse axis direction", newpage = FALSE)
upViewport(2)
```

## Stacked barplots

Barplot annotation can be stacked barplots if the input (let's say `x`) is a matrix with columns larger than one.
In this case, if graphic parameters are specified as a vector, the length can only be one or
the number of columns in `x`. Since barplots are stacked, each row can only have all positive values
or all negative values.

Note the drawback is there is no legend for the stacked barplots, you need to generate it manually (check [this section](s5.legend.html#toc_3))

```{r}
foo1 = matrix(abs(rnorm(20)), ncol = 2)
foo1[1, ] = -foo1[1, ]
column_ha = HeatmapAnnotation(foo1 = anno_barplot(foo1, axis = TRUE))
foo2 = matrix(abs(rnorm(24)), ncol = 2)
row_ha = rowAnnotation(foo2 = row_anno_barplot(foo2, axis = TRUE, axis_side = "top",
    gp = gpar(fill = c("red", "blue"))), width = unit(2, "cm"))
Heatmap(mat, top_annotation = column_ha, top_annotation_height = unit(2, "cm"), km = 2) + row_ha
```

## Add annotation names

From version 1.11.5, `HeatmapAnnotation()` supports adding annotation names directly to the annotations.
However, due to the design of the package, sometimes the names will be positioned outside of the plot
or overlap to other heatmap compoments, thus, by default it is turned off.

```{r}
df = data.frame(type = c(rep("a", 5), rep("b", 5)),
                age = sample(1:20, 10))
value = rnorm(10)
ha = HeatmapAnnotation(df = df, points = anno_points(value, axis = TRUE),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))),
    annotation_height = unit(c(0.5, 0.5, 2), "cm"),
    show_annotation_name = TRUE,
    annotation_name_offset = unit(2, "mm"),
    annotation_name_rot = c(0, 0, 90))
Heatmap(mat, name = "foo", top_annotation = ha)
```

Or the row annotation names: Note we manually adjust `padding` to fully show the text of "points".

```{r}
df = data.frame(type = c(rep("a", 6), rep("b", 6)),
                age = sample(1:20, 12))
value = rnorm(12)
ha = rowAnnotation(df = df, points = row_anno_points(value, axis = TRUE),
    col = list(type = c("a" = "red", "b" = "blue"),
               age = colorRamp2(c(0, 20), c("white", "red"))),
    annotation_width = unit(c(0.5, 0.5, 2), "cm"),
    show_annotation_name = c(TRUE, FALSE, TRUE),
    annotation_name_offset = unit(c(2, 2, 8), "mm"),
    annotation_name_rot = c(90, 90, 0))
ht = Heatmap(mat, name = "foo") + ha
draw(ht, padding = unit(c(4, 2, 2, 2), "mm"))
```

## Adjust positions of column names

In the layout of the heatmap components, column names are put directly below the heatmap body. This will cause
problems when annotations are put at the bottom of the heatmap as well:

```{r}
ha = HeatmapAnnotation(type = df$type,
    col = list(type = c("a" = "red", "b" = "blue")))
Heatmap(mat, bottom_annotation = ha)
```

To solve this problem, we can replace column names with text annotations, which is, we suppress columns
when making the heamtap and create a text annotation which is formed by column names.

```{r}
ha = HeatmapAnnotation(type = df$type, 
    colname = anno_text(colnames(mat), rot = 90, just = "right", offset = unit(1, "npc") - unit(2, "mm")),
    col = list(type = c("a" = "red", "b" = "blue")),
    annotation_height = unit.c(unit(5, "mm"), max_text_width(colnames(mat)) + unit(2, "mm")))
Heatmap(mat, show_column_names = FALSE, bottom_annotation = ha)
```

When add a text annotation, the maximum width of the text should be calculated and set as the height of the 
text annotation viewport so that all text can be completely shown in the plot. Sometimes, you also need to 
set `rot`, `just` and `offset` to align the text to the correct anchor positions.

## Mark some of the rows/columns

From version 1.8.0, a new annotation function `anno_link()` was added which connects labels and subset of the rows
by links. It is helpful when there are many rows/columns and we want to mark some of the rows (e.g. in a gene expression
matrix, we want to mark some important genes of interest.)

```{r}
mat = matrix(rnorm(10000), nr = 1000)
rownames(mat) = sprintf("%.2f", rowMeans(mat))
subset = sample(1000, 20)
labels = rownames(mat)[subset]
Heatmap(mat, show_row_names = FALSE, show_row_dend = FALSE, show_column_dend = FALSE) + 
rowAnnotation(link = row_anno_link(at = subset, labels = labels),
  width = unit(1, "cm") + max_text_width(labels))
# here unit(1, "cm") is width of segments
```

There are also two shortcut functions: `row_anno_link()` and `column_anno_link()`.

## Session info

```{r}
sessionInfo()
```