03-heatmap_annotations.Rmd

```{r, echo = FALSE}
annotation_width = function(ha) {
    if(identical(ComplexHeatmap:::width(ha), unit(1, "npc"))) {
        6
    } else {
        convertWidth(ComplexHeatmap:::width(ha) + unit(4, "mm"), "inch", valueOnly = TRUE)
    }
}
annotation_height = function(ha) {
    if(identical(ComplexHeatmap:::height(ha), unit(1, "npc"))) {
        6
    } else {
        convertHeight(ComplexHeatmap:::height(ha) + unit(4, "mm"), "inch", valueOnly = TRUE)
    }
}
```

# Heatmap Annotations {#heatmap-annotations}

Heatmap annotations are important components of a heatmap that it shows
additional information that associates with rows or columns in the heatmap.
**ComplexHeatmap** package provides very flexible supports for setting
annotations and defining new annotation graphics. The annotations can be put
on the four sides of the heatmap, by `top_annotation`, `bottom_annotation`,
`left_annotation` and `right_annotation` arguments.

The value for the four arguments should be in the `HeatmapAnnotation` class
and should be constructed by `HeatmapAnnotation()` function, or by
`rowAnnotation()` function if it is a row annotation. (`rowAnnotation()` is
just a helper function which is identical to `HeatmapAnnotation(..., which =
"row")`). A simple usage of heatmap annotations is as follows.

```{r, fig.width = 5.2}
set.seed(123)
mat = matrix(rnorm(100), 10)
rownames(mat) = paste0("R", 1:10)
colnames(mat) = paste0("C", 1:10)
column_ha = HeatmapAnnotation(foo1 = runif(10), bar1 = anno_barplot(runif(10)))
row_ha = rowAnnotation(foo2 = runif(10), bar2 = anno_barplot(runif(10)))
Heatmap(mat, name = "mat", top_annotation = column_ha, right_annotation = row_ha)
```

Or assign as bottom annotation and left annotation.

```{r, fig.width = 5.2}
Heatmap(mat, name = "mat", bottom_annotation = column_ha, left_annotation = row_ha)
```

In above examples, `column_ha` and `row_ha` both have two annotations where
`foo1` and `foo2` are numeric vectors and `bar1` and `bar2` are barplots. The
vector-like annotation is called _"simple annotation"_ here and the barplot
annotation is called _"complex annotation"_. You can already see the
annotations must be defined as name-value pairs (e.g. `foo = ...`).

Heatmap annotations can also be independent of the heatmaps. They can be
concatenated to the heatmap list by `+` if it is horizontal, or `%v%` if it is
vertical. Chapter \@ref(a-list-of-heatmaps) will discuss how to concatenate
heatmaps and annotations.

```{r, eval = FALSE}
# code only for demonstration
Heatmap(...) + rowAnnotation() + ...
Heatmap(...) %v% HeatmapAnnotation(...) %v% ...
```

`HeatmapAnnotation()` returns a `HeatmapAnnotation` class object. The object
is usually composed of several annotations. In the following sections of this
chapter, we first introduce settings for individal annotation, and later we
show how to put them toghether.

You can see the information of the `column_ha` and `row_ha` objects by directly enter the object names:

```{r}
column_ha
row_ha
```

In the following examples in this chapter, we will only show the graphics for the
annotations with no heatmap, unless it is necessary. If you want to try it
with a heatmap, you just assign the `HeatmapAnnotation` object which we always
name as `ha` to `top_annotation`, `bottom_annotation`, `left_annotation` or
`right_annotation` arguments.

Settings are basically the same for column annotations and row annotations. If
there is nothing specicial, we only show the column annotation as examples. If
you want to try row annotation, just add `which = "row"` to
`HeatmapAnnotation()` or directly change to `rowAnnotation()` function.

## Simple annotation {#simple-annotation}

A so-called _"simple annotation"_ is the most used style of annotations which
is heatmap-like or grid-like graphics where colors are used to map to the
annotation values. To generate a simple annotation, you just simply put the
annotation vector in `HeatmapAnnotation()` with a certain name.

```{r}
ha = HeatmapAnnotation(foo = 1:10)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Or a discrete annotation:

```{r}
ha = HeatmapAnnotation(bar = sample(letters[1:3], 10, replace = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

You can use any strings as annotation names except those pre-defined arguments
in `HeatmapAnnotation()`.

If colors are not specified, colors are randomly generated. To set colors for
annotations, `col` needs to be set as a named list where the names should be
the same as annotation names. For continuous values, the color mapping should
be a color mapping function generated by `circlize::colorRamp2()`.

```{r}
library(circlize)
col_fun = colorRamp2(c(0, 5, 10), c("blue", "white", "red"))
ha = HeatmapAnnotation(foo = 1:10, col = list(foo = col_fun))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

And for discrete annotations, the color should be a named vector where names
correspond to the levels in the annotation.

```{r}
ha = HeatmapAnnotation(bar = sample(letters[1:3], 10, replace = TRUE),
    col = list(bar = c("a" = "red", "b" = "green", "c" = "blue")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If you specify more than one vectors, there will be multiple annotations
(`foo` and `bar` in following example). Also you can see how `col` is set when
`foo` and `bar` are all put into a single `HeatmapAnnotation()`. Maybe now you
can understand the names in the color list is actually used to map to the
annotation names. Values in `col` will be used to construct legends for simple
annotations.

```{r}
ha = HeatmapAnnotation(
    foo = 1:10, 
    bar = sample(letters[1:3], 10, replace = TRUE),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    )
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The color for `NA` value is controlled by `na_col` argument.

```{r}
ha = HeatmapAnnotation(
    foo = c(1:4, NA, 6:10), 
    bar = c(NA, sample(letters[1:3], 9, replace = TRUE)),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    ),
    na_col = "black"
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`gp` mainly controls the graphics parameters for the borders of the grids.

```{r}
ha = HeatmapAnnotation(
    foo = 1:10, 
    bar = sample(letters[1:3], 10, replace = TRUE),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    ),
    gp = gpar(col = "black")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The simple annotation can also be a matrix (numeric or character) that all the
columns in the matrix share a same color mapping schema. **Note columns in the
matrix correspond to the rows in the column annotation** (you can imagine a vector is a one-column matrix). Also the column
names of the matrix are used as the annotation names.

```{r}
ha = HeatmapAnnotation(foo = cbind(a = runif(10), b = runif(10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If the matrix has no column name, the name of the annotation is still used, but drawn
in the middle of the annotation.

```{r}
ha = HeatmapAnnotation(foo = cbind(runif(10), runif(10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```


As simple annotations can be in different modes (e.g. numeric, or character),
they can be combined as a data frame and send to `df` argument. Imagine in your
project, you might already have an annotation table, you can directly set it by
`df`.

```{r}
anno_df = data.frame(
    foo = 1:10,
    bar = sample(letters[1:3], 10, replace = TRUE)
)
ha = HeatmapAnnotation(df = anno_df,
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    )
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Single annotations and data frame can be mixed, but single annotations are
inserted after the data frame annotation. In following example, colors for
`foo2` is not specified, random colors will be used.

```{r}
ha = HeatmapAnnotation(df = anno_df,
    foo2 = rnorm(10),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    )
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`border` controls the border of every single annotation.

```{r}
ha = HeatmapAnnotation(
    foo = cbind(1:10, 10:1),
    bar = sample(letters[1:3], 10, replace = TRUE),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    ),
    border = TRUE
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The height of the simple annotation is controlled by `simple_anno_size`
argument. Since all single annotations have same height, the value of
`simple_anno_size` is a single `unit` value. Note there are arguments like
`width`, `height`, `annotation_width` and `annotation_height`, but they are
used to adjust the width/height for the complete heamtap annotations (which
are always mix of several annotations). The adjustment of these four arguments
will be introduced in Section \@ref(multiple-annotations).

```{r}
ha = HeatmapAnnotation(
    foo = cbind(a = 1:10, b = 10:1), 
    bar = sample(letters[1:3], 10, replace = TRUE),
    col = list(foo = col_fun,
               bar = c("a" = "red", "b" = "green", "c" = "blue")
    ),
    simple_anno_size = unit(1, "cm")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

When you have multiple heatmaps and it is better to keep the size of simple
annotations on all heatmaps with the same size. `ht_opt$simple_anno_size` can
be set to control the simple annotation size globally (It will be introduced
in Section \@ref(change-parameters-globally)).

## Simple annotation as an annotation function {#simple-annotation-as-an-annotation-function}

`HeatmapAnnotation()` supports _"complex annotation"_ by setting the
annotation as a function. The annotation function defines how to draw the
graphics at a certain position corresponding to the column or row in the
heatmap. There are quite a lot of annotation functions predefined in
**ComplexHeatmap** package. In the end of this chapter, we will introduce how
to construct your own annotation function by the `AnnotationFunction` class.

For all the annotation functions in forms of `anno_*()`, if it is specified in
`HeatmapAnnotation()` or `rowAnnotation()`, you don't need to do anything
explicitly on `anno_*()` to tell whether it should be drawn on rows or
columns. `anno_*()` automatically detects whether it is a row annotation
environment or a column annotation environment.

The simple annotation shown in previous section is internally constructed by
`anno_simple()` annotation function. Directly using `anno_simple()` **will not
automatically generate legends for the final plot**, but, it can provide more
flexibility for more annotation graphics (note in Chapter
\@ref(legends) we will show, although `anno_simple()` cannot automatically generate the
legends, the legends can be controlled and added to the final plot manually).

For an example in previous section:

```{r, eval = FALSE}
# code only for demonstration
ha = HeatmapAnnotation(foo = 1:10)
```

is actually identical to:

```{r, eval = FALSE}
# code only for demonstration
ha = HeatmapAnnotation(foo = anno_simple(1:10))
```

`anno_simple()` makes heatmap-like annotations (or the simple annotations).
Basically if users only make heatmap-like annotations, they do not need to
directly use `anno_simple()`, but this function allows to add more symbols on
the annotation grids.

`anno_simple()` allows to add "points" or single-letter symbols on top of the
annotation grids. `pch`, `pt_gp` and `pt_size` control the settings of the
points. The value of `pch` can be a vector with possible `NA` values.

```{r}
ha = HeatmapAnnotation(foo = anno_simple(1:10, pch = 1, 
    pt_gp = gpar(col = "red"), pt_size = unit(1:10, "mm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Set `pch` as a vector:

```{r}
ha = HeatmapAnnotation(foo = anno_simple(1:10, pch = 1:10))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Set `pch` as a vector of letters:

```{r}
ha = HeatmapAnnotation(foo = anno_simple(1:10, 
    pch = sample(letters[1:3], 10, replace = TRUE)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Set `pch` as a vector with `NA` values (nothing is drawn for `NA` pch values):

```{r}
ha = HeatmapAnnotation(foo = anno_simple(1:10, pch = c(1:4, NA, 6:8, NA, 10, 11)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`pch` also works if the value for `anno_simple()` is a matrix. The length of
`pch` should be as same as the number of matrix rows or columns or even the
length of the matrix (the length of the matrix is the length of all data
points in the matrix).

Length of `pch` corresponds to matrix columns:

```{r}
ha = HeatmapAnnotation(foo = anno_simple(cbind(1:10, 10:1), pch = 1:2))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Length of `pch` corresponds to matrix rows:

```{r}
ha = HeatmapAnnotation(foo = anno_simple(cbind(1:10, 10:1), pch = 1:10))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`pch` is a matrix:

```{r}
pch = matrix(1:20, nc = 2)
pch[sample(length(pch), 10)] = NA
ha = HeatmapAnnotation(foo = anno_simple(cbind(1:10, 10:1), pch = pch))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Till now, you might wonder how to set the legends of the symbols you've added
to the simple annotations. Here we will only show you a simple example and
this functionality will be discussed in Chapter \@ref(legends). In following
example, we assume the simple annotations are kind of p-values and we add `*`
for p-values less than 0.01.


```{r, fig.width = 5.2}
set.seed(123)
pvalue = 10^-runif(10, min = 0, max = 3)
is_sig = pvalue < 0.01
pch = rep("*", 10)
pch[!is_sig] = NA
# color mapping for -log10(pvalue)
pvalue_col_fun = colorRamp2(c(0, 2, 3), c("green", "white", "red")) 
ha = HeatmapAnnotation(
    pvalue = anno_simple(-log10(pvalue), col = pvalue_col_fun, pch = pch),
    annotation_name_side = "left")
ht = Heatmap(matrix(rnorm(100), 10), name = "mat", top_annotation = ha)
# now we generate two legends, one for the p-value
# see how we define the legend for pvalue
lgd_pvalue = Legend(title = "p-value", col_fun = pvalue_col_fun, at = c(0, 1, 2, 3), 
    labels = c("1", "0.1", "0.01", "0.001"))
# and one for the significant p-values
lgd_sig = Legend(pch = "*", type = "points", labels = "< 0.01")
# these two self-defined legends are added to the plot by `annotation_legend_list`
draw(ht, annotation_legend_list = list(lgd_pvalue, lgd_sig))
```

The height of the simple annotation can be controlled by `height` argument or
`simple_anno_size` inside `anno_simple()`. `simple_anno_size` controls the
size for single-row annotation and `height`/`width` controls the total
height/width of the simple annotations. If `height`/`width` is set,
`simple_anno_size` is ignored.

```{r}
ha = HeatmapAnnotation(foo = anno_simple(1:10, height = unit(2, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
ha = HeatmapAnnotation(foo = anno_simple(cbind(1:10, 10:1), 
    simple_anno_size = unit(2, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

**For all the annotation functions we introduce later, the height or the width
for individual annotations should all be set inside the `anno_*()`
functions.**

```{r, eval = FALSE}
# code only for demonstration
anno_*(..., width = ...)
anno_*(..., height = ...)
```

Again, the `width`, `height`, `annotation_width` and `annotation_height`
arguments in `HeatmapAnnotation()` are used to adjust the size of multiple
annotations.


## Empty annotation {#empty-annotation}

`anno_empty()` is a place holder where nothing is drawn. Later user-defined
graphics can be added by `decorate_annotation()` function.

```{r}
ha = HeatmapAnnotation(foo = anno_empty(border = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, index = 1:10, test = TRUE)
```

In Chapter \@ref(heatmap-decoration), we will introduce the use of the
decoration functions, but here we give a quick example. In gene expression
expression analysis, there are senarios that we split the heatmaps into
several groups and we want to highlight some key genes in each group. In this
case, we simply add the gene names on the right side of the heatmap without
aligning them to the their corresponding rows. (`anno_mark()` can align the
labels correclty to their corresponding rows, but in the example we show here,
it is not necessray).

In following example, since rows are split into four slices, the empty
annotation is also split into four slices. Basically what we do is in each
empty annotation slice, we add a colored segment and text.

```{r, fig.width = 5.2}
random_text = function(n) {
    sapply(1:n, function(i) {
        paste0(sample(letters, sample(4:10, 1)), collapse = "")
    })
}
text_list = list(
    text1 = random_text(4),
    text2 = random_text(4),
    text3 = random_text(4),
    text4 = random_text(4)
)
# note how we set the width of this empty annotation
ha = rowAnnotation(foo = anno_empty(border = FALSE, 
    width = max_text_width(unlist(text_list)) + unit(4, "mm")))
Heatmap(matrix(rnorm(1000), nrow = 100), name = "mat", row_km = 4, right_annotation = ha)
for(i in 1:4) {
    decorate_annotation("foo", slice = i, {
        grid.rect(x = 0, width = unit(2, "mm"), gp = gpar(fill = i, col = NA), just = "left")
        grid.text(paste(text_list[[i]], collapse = "\n"), x = unit(4, "mm"), just = "left")
    })
}
```

Note the previous plot can also be made by `anno_block()` or `anno_textbox()` (Section \@ref(anno-text-box)).

A second use of the empty annotation is to add complex annotation graphics
where the empty annotation pretends to be a virtual plotting region. You can
construct an annotation function by `AnnotationFunction` class for complex
annotation graphics, which allows subsetting and splitting, but still, it can
be a secondary choice to directly draw inside the empty annotation, which is
easier and faster for implementing (but less flexible and does not allow
splitting).

In following we show how to add a "complex version" of points annotation. The
only thing that needs to be careful is the location on x-axis (y-axis if it is
a row annotation) should correspond to the column index after column
reordering.

```{r, fig.width = 5.2}
# Note this example is only for demonstration of `anno_empty()`.
# Actually it can be made easily by `anno_points()`.
ha = HeatmapAnnotation(foo = anno_empty(border = TRUE, height = unit(3, "cm")))
ht = Heatmap(matrix(rnorm(100), nrow = 10), name = "mat", top_annotation = ha)
ht = draw(ht)
co = column_order(ht)
value = runif(10)
decorate_annotation("foo", {
    # value on x-axis is always 1:ncol(mat)
    x = 1:10
    # while values on y-axis is the value after column reordering
    value = value[co]
    pushViewport(viewport(xscale = c(0.5, 10.5), yscale = c(0, 1)))
    grid.lines(c(0.5, 10.5), c(0.5, 0.5), gp = gpar(lty = 2),
        default.units = "native")
    grid.points(x, value, pch = 16, size = unit(2, "mm"),
        gp = gpar(col = ifelse(value > 0.5, "red", "blue")), default.units = "native")
    grid.yaxis(at = c(0, 0.5, 1))
    popViewport()
})
```

## Block annotation {#block-annotation}

There are two uses for block annotation. 1. simply as rectangles (with labels
inside) to mark heatmap slices, 2. as plotting regions to associate subsets of
rows or columns in the heatmap.

### Block for putting labels

In this case, the block annotation is more like a color block which identifies groups when
the rows or columns of the heatmap are split.

```{r, fig.width = 5.2}
Heatmap(matrix(rnorm(100), 10), name = "mat",
    top_annotation = HeatmapAnnotation(foo = anno_block(gp = gpar(fill = 2:4))),
    column_km = 3)
```

Labels can be added to each block.

```{r, fig.width = 5.2}
Heatmap(matrix(rnorm(100), 10), name = "mat",
    top_annotation = HeatmapAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
        labels = c("group1", "group2", "group3"), 
        labels_gp = gpar(col = "white", fontsize = 10))),
    column_km = 3,
    left_annotation = rowAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
        labels = c("group1", "group2", "group3"), 
        labels_gp = gpar(col = "white", fontsize = 10))),
    row_km = 3)
```

Note the length of `labels` or graphics parameters should have the same length
as the number of slices.

`anno_block()` function draws rectangles for row/column slices where one
rectangle only corresponds to one single slice. Then what if we want to draw
the rectangles over several slices to show they belong to certain groups?

Currently, it is difficult to directly support it in `anno_block()`, however,
there is workaround for it. Actually, to draw rectangles across several
slices, we need to know two things: 1. the positions of the slices in the
plot, and 2. space to draw the rectangles. Luckily, the positions can be
obtained by directly go to the correspoding viewport and the space can be
allocated by `anno_empty()` function.

In the following code, we use `anno_empty()` to create an empty annotation:

```{r, fig.width = 5.2}
set.seed(123)
mat2 = matrix(rnorm(50*50), nrow = 50)
split = rep(1:5, each = 10)
ha = HeatmapAnnotation(
    empty = anno_empty(border = FALSE),
    foo = anno_block(gp = gpar(fill = 2:6), labels = LETTERS[1:5])
)
Heatmap(mat2, name = "mat2", column_split = split, top_annotation = ha, 
    column_title = NULL)
```

Let's say, we want to put the first three column slices as a group and the last two
slices as the second group.

The positions of the first and the third slices for annotation `"empty"` can be obtained by:

```{r, eval = FALSE}
seekViewport("annotation_empty_1")
loc1 = deviceLoc(x = unit(0, "npc"), y = unit(0, "npc"))
seekViewport("annotation_empty_3")
loc2 = deviceLoc(x = unit(1, "npc"), y = unit(1, "npc"))
loc2
```

```{r, echo = FALSE, fig.width = 5.2}
pdf(NULL)
ha = HeatmapAnnotation(
    empty = anno_empty(border = FALSE),
    foo = anno_block(gp = gpar(fill = 2:6), labels = LETTERS[1:5])
)
Heatmap(mat2, name = "mat2", column_split = split, top_annotation = ha, 
    column_title = NULL)
seekViewport("annotation_empty_1")
loc1 = deviceLoc(x = unit(0, "npc"), y = unit(0, "npc"))
seekViewport("annotation_empty_3")
loc2 = deviceLoc(x = unit(1, "npc"), y = unit(1, "npc"))
invisible(dev.off())
loc2
```


The viewport name `"annotation_empty_1"` correspond to the first slice for
annotation `empty`, and we take the left bottom of the first "empty"
annotation slice and the top right of the third slice, saved in `loc1` and
`loc2` variables.

Here what is important is the use of `grid::deviceLoc()` function. It directly
converts a location measured in a certain viewport to the position in
the graphics device.

In the end, we go to the `"global"` viewport because the size of `"global"`
viewport is the size of the graphics device, and draw the rectangle and add
label.

```{r, eval = FALSE}
seekViewport("global")
grid.rect(loc1$x, loc1$y, width = loc2$x - loc1$x, height = loc2$y - loc1$y, 
    just = c("left", "bottom"), gp = gpar(fill = "red"))
grid.text("group 1", x = (loc1$x + loc2$x)*0.5, y = (loc1$y + loc2$y)*0.5)
```

```{r, echo = FALSE, fig.width = 5.2}
ha = HeatmapAnnotation(
    empty = anno_empty(border = FALSE),
    foo = anno_block(gp = gpar(fill = 2:6), labels = LETTERS[1:5])
)
Heatmap(mat2, name = "mat2", column_split = split, top_annotation = ha, 
    column_title = NULL)
seekViewport("annotation_empty_1")
loc1 = deviceLoc(x = unit(0, "npc"), y = unit(0, "npc"))
seekViewport("annotation_empty_3")
loc2 = deviceLoc(x = unit(1, "npc"), y = unit(1, "npc"))
seekViewport("global")
grid.rect(loc1$x, loc1$y, width = loc2$x - loc1$x, height = loc2$y - loc1$y, 
    just = c("left", "bottom"), gp = gpar(fill = "red"))
grid.text("group 1", x = (loc1$x + loc2$x)*0.5, y = (loc1$y + loc2$y)*0.5)
```

The viewport names for the annotations are in a fixed format, which is
`annotation_{annotation_name}_{slice_index}`. The full set of viewport names
can be obtained by `list_components()` function.

```{r, eval = FALSE}
list_components()
```

```{r, echo = FALSE, fig.width = 5.2}
pdf(NULL)
ha = HeatmapAnnotation(
    empty = anno_empty(border = FALSE),
    foo = anno_block(gp = gpar(fill = 2:6), labels = LETTERS[1:5])
)
Heatmap(mat2, name = "mat2", column_split = split, top_annotation = ha, 
    column_title = NULL)
list_components()
invisible(dev.off())
```

If more than one group-level rectangles are to be added, we can wrap the code
into a simple function `group_block_anno()`:

```{r, fig.width = 5.2}
ha = HeatmapAnnotation(
    empty = anno_empty(border = FALSE, height = unit(8, "mm")),
    foo = anno_block(gp = gpar(fill = 2:6), labels = LETTERS[1:5])
)
Heatmap(mat2, name = "mat2", column_split = split, top_annotation = ha, 
    column_title = NULL)

library(GetoptLong)  # for the function qq()
group_block_anno = function(group, empty_anno, gp = gpar(), 
    label = NULL, label_gp = gpar()) {

    seekViewport(qq("annotation_@{empty_anno}_@{min(group)}"))
    loc1 = deviceLoc(x = unit(0, "npc"), y = unit(0, "npc"))
    seekViewport(qq("annotation_@{empty_anno}_@{max(group)}"))
    loc2 = deviceLoc(x = unit(1, "npc"), y = unit(1, "npc"))

    seekViewport("global")
    grid.rect(loc1$x, loc1$y, width = loc2$x - loc1$x, height = loc2$y - loc1$y, 
        just = c("left", "bottom"), gp = gp)
    if(!is.null(label)) {
        grid.text(label, x = (loc1$x + loc2$x)*0.5, y = (loc1$y + loc2$y)*0.5, gp = label_gp)
    }
}

group_block_anno(1:3, "empty", gp = gpar(fill = "red"), label = "group 1")
group_block_anno(4:5, "empty", gp = gpar(fill = "blue"), label = "group 2")
```

### Blocks as plotting regions

When heatmap is split, each block in block annotation can be thought as a
virtual plotting region. `anno_block()` allows an argument `panel_fun` which
accepts a self-defined function that draws graphics in each slice. It must
have two arguments: 

1. row/column indices for the current slice (let's call it `index`),
2. a vector of levels from the split variable that correspond to current slice (let's call it `level`). When e.g. `row_km` is 
   only set or `row_split` is only set to one categorical variable, then `level` is a vector of length one. If there are multiple
   categorical variables set with `row_km` and `row_split`, `level` is a vector of which the length is the same as the number 
   of categorical variables.

When `panel_fun` is set, all other graphics parameters in `anno_block()` are ignored. See the following example:

```{r, fig.width = 7}
col = c("1" = "red", "2" = "blue", "A" = "green", "B" = "orange")
Heatmap(matrix(rnorm(100), 10), name = "mat", row_km = 2, 
    row_split = sample(c("A", "B"), 10, replace = TRUE)) + 
rowAnnotation(foo = anno_block(
    panel_fun = function(index, levels) {
        grid.rect(gp = gpar(fill = col[levels[2]], col = "black"))
        txt = paste(levels, collapse = ",")
        txt = paste0(txt, "\n", length(index), " rows")
        grid.text(txt, 0.5, 0.5, rot = 0,
            gp = gpar(col = col[levels[1]]))
    },
    width = unit(3, "cm")
))
```

To make it more general, `anno_block()` accepts an argument `align_to` which defines
a list of indices that blocks will be corresponded to, but you need to make sure 
the indices are continuously adjacent on heatmaps.

```{r, fig.width = 5.2}
split = sample(c("A", "B"), 10, replace = TRUE)
align_to = list("A" = which(split == "A"))
panel_fun = function(index, nm) {
    grid.rect()
    grid.text(paste0(length(index), " rows"), 0.5, 0.5)
}
Heatmap(matrix(rnorm(100), 10), name = "mat", row_split = split) + 
rowAnnotation(foo = anno_block(
    align_to = align_to,
    panel_fun = panel_fun,
    width = unit(3, "cm")
))
```

`anno_block()` normally works with `row_split`, but it is not necessary, see the following example:

```{r, fig.width = 5.2}
align_to = list("A" = 2:4, "B" = 7:9)
Heatmap(matrix(rnorm(100), 10), name = "mat", cluster_rows = FALSE) + 
rowAnnotation(foo = anno_block(
    align_to = align_to,
    panel_fun = panel_fun,
    width = unit(3, "cm")
))
```

## Image annotation {#image-annotation}

Images can be added as annotations. `anno_image()` supports image in `png`,
`svg`, `pdf`, `eps`, `jpeg/jpg`, `tiff` formats. How they are imported as
annotations are as follows:

- `png`, `jpeg/jpg` and `tiff` images are imported by `png::readPNG()`,
  `jpeg::readJPEG()` and `tiff::readTIFF()`, and drawn by
  `grid::grid.raster()`.
- `svg` images are firstly reformatted by `rsvg::rsvg_svg()` and then imported
  by `grImport2::readPicture()` and drawn by `grImport2::grid.picture()`.
- `pdf` and `eps` images are imported by `grImport::PostScriptTrace()` and
  `grImport::readPicture()`, later drawn by `grImport::grid.picture()`.

The free icons for following examples are from
https://github.com/Keyamoon/IcoMoon-Free. A vector of image paths are set as
the first argument of `anno_image()`.

```{r}
image_png = sample(dir("IcoMoon-Free-master/PNG/64px", full.names = TRUE), 10)
image_svg = sample(dir("IcoMoon-Free-master/SVG/", full.names = TRUE), 10)
image_eps = sample(dir("IcoMoon-Free-master/EPS/", full.names = TRUE), 10)
image_pdf = sample(dir("IcoMoon-Free-master/PDF/", full.names = TRUE), 10)

# we only draw the image annotation for PNG images, while the others are the same
ha = HeatmapAnnotation(foo = anno_image(image_png))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Different image formats can be mixed in the input vector.

```{r, eval = FALSE}
# code only for demonstration
ha = HeatmapAnnotation(foo = anno_image(c(image_png[1:3], image_svg[1:3], 
    image_eps[1:3], image_pdf[1:3])))
```

Border and background colors (if the images have transparent background) can
be set by `gp`.

```{r}
ha = HeatmapAnnotation(foo = anno_image(image_png, 
    gp = gpar(fill = 1:10, col = "black")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`border` controls the border of the whole annotation.

```{r}
ha = HeatmapAnnotation(foo = anno_image(image_png, border = "red"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Padding or space around the images is set by `space`.

```{r}
ha = HeatmapAnnotation(foo = anno_image(image_png, space = unit(3, "mm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If only some of the images need to be drawn, the other elements in the `image`
vector can be set to `''` or `NA`.

```{r}
image_png[1:2] = ""
ha = HeatmapAnnotation(foo = anno_image(image_png))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

## Points annotation {#points-annotation}

Points annotation implemented by `anno_points()` shows distribution of a list
of data points. The data points object `x` can be a single vector or a matrix.
If it is a matrix, the graphics settings such as `pch`, `size` and `gp` can
correpspond to matrix columns. Note again, if `x` is a matrix, rows in `x`
correspond to columns in the heatmap matrix.

```{r}
ha = HeatmapAnnotation(foo = anno_points(runif(10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
ha = HeatmapAnnotation(foo = anno_points(matrix(runif(20), nc = 2), 
    pch = 1:2, gp = gpar(col = 2:3)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`ylim` controls the range on "y-axis" or the "data axis" (if it is a row
annotation, the data axis is horizontal), `extend` controls the extended space
on the data axis direction. `axis` controls whether to show the axis and
`axis_param` controls the settings for axis. The default settings for axis are:

```{r}
default_axis_param("column")
```
 
And you can overwrite some of them:

```{r}
ha = HeatmapAnnotation(foo = anno_points(runif(10), ylim = c(0, 1),
    axis_param = list(
        side = "right",
        at = c(0, 0.5, 1), 
        labels = c("zero", "half", "one")
    ))
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

One thing that might be useful is you can control the rotation of the axis
labels.

```{r}
ha = rowAnnotation(foo = anno_points(runif(10), ylim = c(0, 1),
    width = unit(2, "cm"),
    axis_param = list(
        side = "bottom",
        at = c(0, 0.5, 1), 
        labels = c("zero", "half", "one"),
        labels_rot = 45
    ))
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha)*1.2, fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

**The configuration of axis is same for all other annotation functions which have
axes.**

The default size of the points annotation is 5mm. It can be controlled by
`height`/`width` argument in `anno_points()`.

```{r}
ha = HeatmapAnnotation(foo = anno_points(runif(10), height = unit(2, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

## Line annotation {#lines-annotation}

`anno_lines()` connects the data points by a list of segments. Similar as
`anno_points()`, the data variable can be a numeric vector:

```{r}
ha = HeatmapAnnotation(foo = anno_lines(runif(10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Or a matrix:

```{r}
ha = HeatmapAnnotation(foo = anno_lines(cbind(c(1:5, 1:5), c(5:1, 5:1)), 
    gp = gpar(col = 2:3), add_points = TRUE, pt_gp = gpar(col = 5:6), pch = c(1, 16)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

As shown above, points can be added to the lines by setting `add_points = TRUE`.

Smoothed lines (by `loess()`) can be added instead of the original lines by
setting `smooth = TRUE`, but it should be used with caution because the order of
columns in the heatmap is used as "x-value" for the fitting and only if you think
the fitting against the reordered order makes sense.

Smoothing also works when the input data variable is a matrix that the smoothing
is performed for each column separately.

If `smooth` is `TRUE`, `add_points` is set to `TRUE` by default.

```{r}
ha = HeatmapAnnotation(foo = anno_lines(runif(10), smooth = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The default size of the lines annotation is 5mm. It can be controlled by
`height`/`width` argument in `anno_lines()`.

```{r, eval = FALSE}
# code only for demonstration
ha = HeatmapAnnotation(foo = anno_lines(runif(10), height = unit(2, "cm")))
```

## Barplot annotation {#barplot_annotation}

The data points can be represented as barplots. Some of the arguments in
`anno_barplot()` such as `ylim`, `axis`, `axis_param` are the same as
`anno_points()`.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(1:10))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The width of bars is controlled by `bar_width`. It is a relative value to the 
width of the cell in the heatmap.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(1:10, bar_width = 1))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Graphic parameters are controlled by `gp`.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(1:10, gp = gpar(fill = 1:10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

You can choose the baseline of bars by `baseline`.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(seq(-5, 5), baseline = "min"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(seq(-5, 5), baseline = 0))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If the input value is a matrix, it will be stacked barplots.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(matrix(nc = 2, c(1:10, 10:1))))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

And length of parameters in `gp` can be the number of the columns in the matrix:

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(cbind(1:10, 10:1), 
    gp = gpar(fill = 2:3, col = 2:3)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The default size of the barplot annotation is 5mm. It can be controlled by
`height`/`width` argument in `anno_barplot()`.

```{r, eval = FALSE}
# code only for demonstration
ha = HeatmapAnnotation(foo = anno_barplot(runif(10), height = unit(2, "cm")))
```

Following example shows a barplot annotation which visualizes a proportion
matrix (for which row sums are 1).

```{r}
m = matrix(runif(4*10), nc = 4)
m = t(apply(m, 1, function(x) x/sum(x)))
ha = HeatmapAnnotation(foo = anno_barplot(m, gp = gpar(fill = 2:5), 
    bar_width = 1, height = unit(6, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The direction of the axis can be reversed which is useful when the annotation
is put on the left of the heatmap.

```{r, fig.width = 4.5, fig.height = 6}
ha_list = rowAnnotation(axis_reverse = anno_barplot(m, gp = gpar(fill = 2:5), 
    axis_param = list(direction = "reverse"), 
    bar_width = 1, width = unit(4, "cm"))) +
rowAnnotation(axis_normal = anno_barplot(m, gp = gpar(fill = 2:5), 
    bar_width = 1, width = unit(4, "cm")))
draw(ha_list, ht_gap = unit(4, "mm"))
```

`direction = "reverse"` also works for other annotation functions which have
axes, but it is more commonly used for barplot annotations.

Argument `add_numbers` can be set to `TRUE` so that numbers associated to bars are drawn on top of the bars.
For column annotation, texts are by default with 45 degree rotation.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(1:10, add_numbers = TRUE, 
    height = unit(1, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

When the input for `anno_barplot()` is a matrix, argument `beside` can be set to
`TRUE` so that bars for a same heatmap column are positioned by each other:

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(matrix(nc = 2, c(1:10, 10:1)), 
    beside = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Argument `attach` can be set to `TRUE` so that two adjacent bars are attached.

```{r}
ha = HeatmapAnnotation(foo = anno_barplot(matrix(nc = 2, c(1:10, 10:1)), 
    beside = TRUE, attach = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

## Boxplot annotation {#box-annotation}

Boxplot annotation as well as the annotation functions which are introduced
later are more suitable for small matrice. I don't think you want to put
boxplots as column annotation for a matrix with 100 columns.

For `anno_boxplot()`, the input data variable should be a matrix or a list. If
`x` is a matrix and if it is a column annotation, statistics for boxplots are
calculated by columns, and if it is a row annotation, the calculation is done
by rows.

```{r}
set.seed(12345)
m = matrix(rnorm(100), 10)
ha = HeatmapAnnotation(foo = anno_boxplot(m, height = unit(4, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Graphic parameters are controlled by `gp`.

```{r}
ha = HeatmapAnnotation(foo = anno_boxplot(m, height = unit(4, "cm"), 
    gp = gpar(fill = 1:10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Width of the boxes are controlled by `box_width`. `outline` controls whether to
show outlier points.

```{r}
ha = HeatmapAnnotation(foo = anno_boxplot(m, height = unit(4, "cm"), 
    box_width = 0.9, outline = FALSE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`anno_boxplot()` only draws one boxplot for one single row. Section
\@ref(add-multiple-boxplots-for-single-row) demonstrates how to define an annotation function which
draws multiple boxplots for a single row, and Section \@ref(zoom-annotation)
demonstrates how to draw one single boxplot for a group of rows.

## Histogram annotation {#histogram-annotation}

Annotations as histograms are more suitable to put as row annotations. The
setting for the data variable is the same as `anno_boxplot()` which can be a
matrix or a list.


Similar as `anno_boxplot()`, the input data variable should be a matrix or a list. If
`x` is a matrix and if it is a column annotation, histograms are
calculated by columns, and if it is a row annotation, histograms are calculated
by rows.

```{r}
m = matrix(rnorm(1000), nc = 100)
ha = rowAnnotation(foo = anno_histogram(m)) # apply `m` on rows
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Number of breaks for histograms is controlled by `n_breaks`.

```{r}
ha = rowAnnotation(foo = anno_histogram(m, n_breaks = 20))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Colors are controlled by `gp`.

```{r}
ha = rowAnnotation(foo = anno_histogram(m, gp = gpar(fill = 1:10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

## Density annotation {#density-annotation}

Similar as histogram annotations, `anno_density()` shows the distribution
as a fitted curve.

```{r}
ha = rowAnnotation(foo = anno_density(m))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The height of the density peaks can be controlled to make the distribution
look like a ["joyplot"](http://blog.revolutionanalytics.com/2017/07/joyplots.html).

```{r}
ha = rowAnnotation(foo = anno_density(m, joyplot_scale = 2, 
    gp = gpar(fill = "#CCCCCC80")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Or visualize the distribution as violin plot.

```{r}
ha = rowAnnotation(foo = anno_density(m, type = "violin", 
    gp = gpar(fill = 1:10)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

When there are too many rows in the input variable, the space for normal
density peaks might be too small. In this case, we can visualize the
distribution by heatmaps.

```{r}
m2 = matrix(rnorm(50*10), nrow = 50)
ha = rowAnnotation(foo = anno_density(m2, type = "heatmap", width = unit(6, "cm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

THe color schema for heatmap distribution is controlled by `heatmap_colors`.

```{r}
ha = rowAnnotation(foo = anno_density(m2, type = "heatmap", width = unit(6, "cm"), 
    heatmap_colors = c("white", "orange")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

In **ComplexHeatmap** package, there is a `densityHeatmap()` function which
visualizes distribution as a heatmap. It will be introduced in Section
\@ref(density-heatmap).

## Joyplot annotation {#joyplot-annotation}

`anno_joyplot()` is specific for so-called joyplot (http://blog.revolutionanalytics.com/2017/07/joyplots.html).
The input data should be a matrix or a list.

Note `anno_joyplot()` is always applied to columns if the input is a matrix.
Because joyplot visualizes parallel distributions and the matrix is not a
necessary format while a list is already enough for it, if you are not sure
about how to set as a matrix, just convert it to a list for using it.

```{r}
m = matrix(rnorm(1000), nc = 10)
lt = apply(m, 2, function(x) data.frame(density(x)[c("x", "y")]))
ha = rowAnnotation(foo = anno_joyplot(lt, width = unit(4, "cm"), 
    gp = gpar(fill = 1:10), transparency = 0.75))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Or only show the lines (`scale` argument controls the relative height of the
curves).

```{r}
m = matrix(rnorm(5000), nc = 50)
lt = apply(m, 2, function(x) data.frame(density(x)[c("x", "y")]))
ha = rowAnnotation(foo = anno_joyplot(lt, width = unit(4, "cm"), gp = gpar(fill = NA), 
    scale = 4))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The format of the input variable is special. It can be one of the following
two:

1. a matrix (remember `anno_joyplot()` is always applied to columns of the
   matrix) where x coordinate corresponds to `1:nrow(matrix)` and each column
   in the matrix corresponds to one distribution in the joyplot.
2. a list of data frames where each data frame has two columns which
   correspond to x coordinate and y coordinate.

## Horizon chart annotation {#horizon-chart-annotation}

[Horizon
chart](https://flowingdata.com/2015/07/02/changing-price-of-food-items-and-horizon-graphs/)
as annotation can only be added as row annotation. The format of the input
variable for `anno_horizon()` is the same as `anno_joyplot()` which is
introduced in previous section.

The default style of horizon chart annotation is:

```{r}
lt = lapply(1:20, function(x) cumprod(1 + runif(1000, -x/100, x/100)) - 1)
ha = rowAnnotation(foo = anno_horizon(lt))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Values in each track are normalized by `x/max(abs(x))`.

Colors for positive values and negative values are controlled by `pos_fill`
and `neg_fill` in `gpar()`.

```{r}
ha = rowAnnotation(foo = anno_horizon(lt, 
    gp = gpar(pos_fill = "orange", neg_fill = "darkgreen")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`pos_fill` and `neg_fill` can be assigned as a vector.

```{r}
ha = rowAnnotation(foo = anno_horizon(lt, 
    gp = gpar(pos_fill = rep(c("orange", "red"), each = 10),
              neg_fill = rep(c("darkgreen", "blue"), each = 10))))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Whether the peaks for negative values start from the bottom or from the top.

```{r}
ha = rowAnnotation(foo = anno_horizon(lt, negative_from_top = TRUE))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

The space between every two neighbouring charts.

```{r}
ha = rowAnnotation(foo = anno_horizon(lt, gap = unit(1, "mm")))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

## Text annotation {#text-annotation}

Text can be used as annotations by `anno_text()`. Graphics parameters are controlled
by `gp`.

```{r}
ha = rowAnnotation(foo = anno_text(month.name, gp = gpar(fontsize = 1:12+4)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Locationsn are controlled by `location` and `just`. Rotation is controlled by `rot`.

```{r}
ha = rowAnnotation(foo = anno_text(month.name, location = 1, rot = 30, 
    just = "right", gp = gpar(fontsize = 1:12+4)))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
ha = rowAnnotation(foo = anno_text(month.name, location = 0.5, just = "center"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`location` and `just` are automatically calculated according the the position
of the annotations put to the heatmap (e.g. text are aligned to the left if it
is a right annotation to the heatmap and are aligned to the right it it is a
left annotation).

The width/height are automatically calculated based on all the text. Normally
you don't need to manually set the width/height of it.

Background colors can be set by `gp`. Here `fill` controls the filled
background color, `col` controls the color of text and the non-standard
`border` controls the background border color.

You can see we explicitly set `width` as 1.2 times the width of the longest
text.

```{r}
ha = rowAnnotation(foo = anno_text(month.name, location = 0.5, just = "center",
    gp = gpar(fill = rep(2:4, each = 4), col = "white", border = "black"),
    width = max_text_width(month.name)*1.2))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

More complicated texts can be drawn by integrating with the **gridtext**
package (Section \@ref(gridtext-annotations)). A quick example is as follows:

```{r}
text = sapply(LETTERS[1:10], function(x) {
    qq("<span style='color:red'>**@{x}**<sub>@{x}</sub></span>_@{x}_<sup>@{x}</sup>")
})
ha = rowAnnotation(
    foo = anno_text(gt_render(text, align_widths = TRUE, 
                        r = unit(2, "pt"),
                        padding = unit(c(2, 2, 2, 2), "pt")), 
                    gp = gpar(box_col = "blue", box_lwd = 2), 
                    just = "right", 
                    location = unit(1, "npc")
    ))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Unlike other annotations, by default there is no annotation title for text annotation. The title
can be added by setting `show_name = TRUE` in `anno_text()`:

```{r}
m = matrix(rnorm(100), 10)
Heatmap(m) + rowAnnotation(month = anno_text(month.name[1:10], just = "center", 
        location = unit(0.5, "npc"), show_name = TRUE), 
    annotation_name_rot = 0)
```

## Numeric labels annotation {#anno-numeric}

There is a special text annotation for numeric labels. To emphasize the visual effect,
we also want to add bars to show the absolute values of the numbers. This can be 
done with `anno_numeric()` function. Note currently it only supports row annotation.

```{r}
x = round(runif(10), 3)
ha = rowAnnotation(numeric = anno_numeric(x), annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```

Background colors can by controlled by `bg_gp`.

```{r}
ha = rowAnnotation(numeric = anno_numeric(x, 
        bg_gp = gpar(fill = "orange", col = "black")),
    annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```

`align_to` can be set to `"right"` or `"left"`:

```{r}
ha = rowAnnotation(numeric = anno_numeric(x, 
        bg_gp = gpar(fill = "orange", col = "black"),
        align_to = "right"),
    annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```

Format of labels on the plot can be controlled by `labels_format`:

```{r}
ha = rowAnnotation(numeric = anno_numeric(x,
        labels_format = function(x) paste0(sprintf("%.2f", x*100), "%")),
    annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```

It is also possible to show a numeric vector with both negative and positive values.
In this case, all graphics parameters should have length of two where the first one
controls negative values and the second controls positive values.

```{r}
x = round(runif(10, -1, 1), 3)
ha = rowAnnotation(numeric = anno_numeric(x, 
        bg_gp = gpar(fill = c("green", "red"))), 
    annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```

Another example is to visualize a vector of p-values. Here we should apply `-log10()`
on p-values for mapping to bar heights with `x_convert` argument:

```{r}
x = 10^(-runif(10, 1, 6))
ha = rowAnnotation(pvalue = anno_numeric(x, 
        rg = c(min(x), 1),
        x_convert = function(x) -log10(x), 
        labels_format = function(x) sprintf("%.2e", x)),
    annotation_name_rot = 0)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, 1:10, test = TRUE)
```


## Completely customized annotation


For most annotation functions implemented in **ComplexHeatmap**, they only
draw one same type of annotation graphics, e.g. `anno_points()` only draws
points or `anno_image()` only draws images. From **ComplexHeatmap** version 2.9.4, we added a new annotation
function `anno_customize()`, with which you can completely freely define
graphics for every annotation cell.

The input for `anno_customize()` should be a categorical vector.

```{r}
x = c("a", "a", "a", "b", "b", "b", "c", "c", "d", "d")
```

For each level, you need to define a graphics function for it. 

```{r}
graphics = list(
    "a" = function(x, y, w, h) {
        grid.rect(x, y, w*0.8, h*0.33, gp = gpar(fill = "red"))
    },
    "b" = function(x, y, w, h) {
        grid.text("A", x, y, gp = gpar(col = "darkgreen"))
    },
    "c" = function(x, y, w, h) {
        grid.points(x, y, gp = gpar(col = "orange"), pch = 16)
    },
    "d" = function(x, y, w, h) {
        img = png::readPNG(system.file("extdata", "Rlogo.png", package = "circlize"))
        grid.raster(img, x, y, width = unit(0.8, "snpc"), 
            height = unit(0.8, "snpc")*nrow(img)/ncol(img))
    }
)
```

When adding graphics, each annotation cell is an independent viewport, thus, the self-defined graphics function accepts four arguments: `x` and `y`: the center
of the viewport of the annotation cell, `w` and `h`: the width and height of the viewport. In the example above, we set a horizontal bar for `"a"`, a text for `"b"`,
a point for `"c"` and an image for `"d"`.

Then we add this new annotation to both row and column of the heatmap, just in the same way as normal annotations.

```{r}
m = matrix(rnorm(100), 10)
Heatmap(m, 
    top_annotation = HeatmapAnnotation(foo = anno_customize(x, graphics = graphics)),
    right_annotation = rowAnnotation(bar = anno_customize(x, graphics = graphics)))
```

Reordering and splitting are automatically adjusted.

```{r}
Heatmap(m, 
    top_annotation = HeatmapAnnotation(foo = anno_customize(x, graphics = graphics)),
    right_annotation = rowAnnotation(bar = anno_customize(x, graphics = graphics)),
    column_split = x, row_split = x)
```

`Legend()` function also accepts a `graphics` argument, so it is easy to add
legends for the "customized annotations". How to use `Legend()` function will
be introduced in Chapter \@ref(legends).

```{r}
m = matrix(rnorm(100), 10)
ht = Heatmap(m, 
    top_annotation = HeatmapAnnotation(foo = anno_customize(x, graphics = graphics)))
lgd = Legend(title = "foo", at = names(graphics), graphics = graphics)
draw(ht, annotation_legend_list = lgd)
```

## Mark annotation {#mark-annotation}

Sometimes there are many rows or columns in the heatmap and we want to mark
some of them. `anno_mark()` is used to mark subset of rows or columns and
connect to labels with lines.

`anno_mark()` at least needs two arguments where `at` are the indices to the
original matrix and `labels` are the corresponding text.

```{r, eval = FALSE}
m = matrix(rnorm(1000), nrow = 100)
rownames(m) = 1:100
ha = rowAnnotation(foo = anno_mark(at = c(1:4, 20, 60, 97:100), 
    labels = month.name[1:10]))
Heatmap(m, name = "mat", cluster_rows = FALSE, right_annotation = ha,
    row_names_side = "left", row_names_gp = gpar(fontsize = 4))
Heatmap(m, name = "mat", cluster_rows = FALSE, right_annotation = ha,
    row_names_side = "left", row_names_gp = gpar(fontsize = 4), row_km = 4)
```

```{r, echo = FALSE}
m = matrix(rnorm(1000), nrow = 100)
rownames(m) = 1:100
ha = rowAnnotation(foo = anno_mark(at = c(1:4, 20, 60, 97:100), labels = month.name[1:10]))
ht1 = Heatmap(m, name = "mat", cluster_rows = FALSE, right_annotation = ha,
    row_names_side = "left", row_names_gp = gpar(fontsize = 4))

ht2 = Heatmap(m, name = "mat", cluster_rows = FALSE, right_annotation = ha,
    row_names_side = "left", row_names_gp = gpar(fontsize = 4), row_km = 4)
grid.newpage()
pushViewport(viewport(x = 0.25, width = 0.5))
draw(ht1, newpage = FALSE)
popViewport()
pushViewport(viewport(x = 0.75, width = 0.5))
draw(ht2, newpage = FALSE)
popViewport()
```

The calculation of positions of texts depends on the absolute size of the graphics
device. If you resize the current interactive device or you use `grid.grabExpr()` 
to capture the current plot, you might see the positions of texts are all corrupt.
Please refer to Section \@ref(cowplot) for a solution.


## Zoom/link annotation {#zoom-annotation}

`anno_mark()` connects single row or column on the heatmap to a label, the
next annotation function `anno_link()` connects subsets of rows or columns to
plotting regions where more comprehensive graphics can be added there. 
See following example where we make boxplot for every row group.

```{r, fig.width = 5.2}
set.seed(123)
m = matrix(rnorm(100*10), nrow = 100)
subgroup = sample(letters[1:3], 100, replace = TRUE, prob = c(1, 5, 10))
rg = range(m)
panel_fun = function(index, nm) {
    pushViewport(viewport(xscale = rg, yscale = c(0, 2)))
    grid.rect()
    grid.xaxis(gp = gpar(fontsize = 8))
    grid.boxplot(m[index, ], pos = 1, direction = "horizontal")
    popViewport()
}
anno = anno_link(align_to = subgroup, which = "row", panel_fun = panel_fun, 
    size = unit(2, "cm"), gap = unit(1, "cm"), width = unit(4, "cm"))
Heatmap(m, name = "mat", right_annotation = rowAnnotation(foo = anno), 
    row_split = subgroup)
```

The important arguments for `anno_zoom()` are:

1. `align_to`: It defines how the plotting regions (or the boxes) correspond
   to the rows or the columns in the heatmap. If the value is a list of
   indices, each box corresponds to the rows or columns with indices in one
   vector in the list. If the value is a categorical variable (e.g. a factor
   or a character vector) that has the same length as the rows or columns in
   the heatmap, each box corresponds to the rows/columns in each level in the
   categorical variable.
2. `panel_fun`: A self-defined function that defines how to draw graphics in
   the box. The function must have a `index` argument which is the indices for
   the rows/columns that the box corresponds to. It can have a second argument
   `nm` which is the "name" of the selected part in the heatmap. The
   corresponding value for `nm` comes from `align_to` if it is specified as a
   categorical variable or a list with names.
3. `size`: The size of boxes. It can be pure numeric that they are treated as
   relative fractions of the total height/width of the heatmap. The value of
   `size` can also be absolute units.
4. `gap`: Gaps between boxes. It should be a `unit` object.

In previous example, `align_to` is set as a categorical variable. In the next
example, `align_to` is set as a list of indicies and only cover slices "a" and "b".

```{r, fig.width = 5.2}
align_to = split(1:nrow(m), subgroup)
align_to = align_to[c("a", "b")]
anno = anno_link(align_to = align_to, which = "row", panel_fun = panel_fun, 
    size = unit(2, "cm"), gap = unit(1, "cm"), width = unit(4, "cm"))
Heatmap(m, name = "mat", right_annotation = rowAnnotation(foo = anno), 
    row_split = subgroup)
```

`anno_link()` also works for column annotations.

Similar as `anno_mark()`, the positions of the plotting regions also depends
on the absolute size of the graphic device. If you resize the current
interactive device or you use `grid.grabExpr()` to capture the current plot,
you might see the positions of texts are all corrupt. Please refer to Section
\@ref(cowplot) for a solution.

As show in the previous examples, `anno_link()` normally works together with
`row_split`/`column_split` to associate additional graphics to slices. However,
it is not necessary, as long as rows with indices in `align_to` are continuously
adjacent on heatmaps.

```{r, fig.width = 5.2}
align_to = list(1:20)
anno = anno_link(align_to = align_to, which = "row", panel_fun = panel_fun, 
    size = unit(2, "cm"), gap = unit(1, "cm"), width = unit(4, "cm"))
# here row indices 1 to 20 are adjacent since no clustering is applied on rows
Heatmap(m, name = "mat", right_annotation = rowAnnotation(foo = anno), 
    cluster_rows = FALSE)
```

## Text box annotation {#anno-text-box}

From **ComplexHeatmap** 2.11.1, there are supports for drawing text boxes and associating them
to heatmaps.

### Construct the text box

Text box annotation depends on the text box "grob". The text box grob can be
constructed with the function `textbox_grob()`. It accpets a character vector
with words or phrases/sentences. We first demonstrate the use of words.

Following functionn `random_text()` generates a vector of random words or phrases.

```{r}
random_text = function(n, n_words = 1) {
    sapply(1:n, function(i) {
         w = replicate(sample(n_words, 1), 
            paste0(sample(letters, sample(4:10, 1)), collapse = ""))
        if(n_words > 1) {
            paste(w, collapse = " ")
        } else {
            w
        }
    })
}
```

Following code shows how to set graphics parameters:

```{r, fig.height = 1}
set.seed(123)
words = random_text(10)
words
grid.newpage()
gb = textbox_grob(words)
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, gp = gpar(col = 1:10))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, gp = gpar(fontsize = runif(10, 5, 20)))
grid.draw(gb)
```

Following code shows how to set the background:

```{r, fig.height = 1}
grid.newpage()
gb = textbox_grob(words, background_gp = gpar(fill = "#CCCCCC", col = "#808080"))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, background_gp = gpar(fill = "#CCCCCC", col = NA), 
    round_corners = TRUE)
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, background_gp = gpar(fill = "#CCCCCC", col = "#808080"), 
    padding = unit(4, "mm"))
grid.draw(gb)
```

Following code shows how to set spaces between words and lines, and how to set the width
of the text box:

```{r, fig.height = 1}
grid.newpage()
gb = textbox_grob(words, line_space = unit(5, "mm"))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, text_space = unit(5, "mm"))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, max_width = unit(12, "cm"))
grid.draw(gb)
```

Words can be added from the bottom left of the box or from the top left:

```{r, fig.height = 1}
fontsize = sort(runif(10, 5, 20))
grid.newpage()
gb = textbox_grob(words, gp = gpar(fontsize = fontsize))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(words, gp = gpar(fontsize = fontsize), 
    first_text_from = "bottom")
grid.draw(gb)
```

Sentences or phrases are composed of several words, so there are some extra parameters.
If the longest sentence is longer than `max_width`, the width of the longest sentence will
be the width of the text box. Setting `word_wrap = TRUE` can adjust the text
according to the width of the text box.

```{r, fig.height = 1.5}
sentences = random_text(5, 8)
sentences
fontsize = runif(5, 5, 20)
grid.newpage()
gb = textbox_grob(sentences, gp = gpar(col = 1:5, fontsize = fontsize))
grid.draw(gb)
grid.newpage()
gb = textbox_grob(sentences, gp = gpar(col = 1:5, fontsize = fontsize), 
    word_wrap = TRUE)
grid.draw(gb)
```

Also argument `add_new_line` can be set to `TRUE` so each sentence will be in a single line.

```{r, fig.height = 1.5}
grid.newpage()
gb = textbox_grob(sentences, gp = gpar(col = 1:5, fontsize = fontsize), 
    add_new_line = TRUE)
grid.draw(gb)
grid.newpage()
gb = textbox_grob(sentences, gp = gpar(col = 1:5, fontsize = fontsize), 
    add_new_line = TRUE, word_wrap = TRUE)
grid.draw(gb)
```

Finally, the width and height of the text box grob can be obtained by `grobWidth()` and `grobHeight()`.
Also there is a companion function `grid.textbox()` that directly draws text box at a certain position. 

```{r, eval = FALSE}
# code only for demonstration
gb = textbox_grob(words)
grobWidth(gb)
grobHeight(gb)
grid.textbox(words, x, y)
```

### Draw textbox annotation

The function `anno_textbox()` draws several text boxes and associate them to heatmaps.
Note you don't need to directly use `textbox_grob()` function with `anno_textbox()`,
but there are parameters that control texts in `anno_textbox()` that are directly passed to `textbox_grob()`.

Since texts are already wrapped into boxes, the text box annotations are basically 
implemented by `anno_link()` and `anno_block()`. 

By default, the text box annotation is implemented by `anno_link()`. Since heights
of text boxes are not always the same as the height of subsets of rows they correspond to,
there are connections between the heatmap and text boxes. In the following example,
we generated 10 text boxes and each one is linked to a heatmap slice. In this case,
the first parameter for `anno_textbox()` is a categorical variable which also split heatmap rows.
The second parameter `text` is a named list of character vectors where name of the list
should correspond to the levels in `split`.

```{r, fig.width = 7}
mat = matrix(rnorm(100*10), nrow = 100)
split = sample(letters[1:10], 100, replace = TRUE)
text = lapply(unique(split), function(x) {
    random_text(10)
})
names(text) = unique(split)

Heatmap(mat, name = "mat", cluster_rows = FALSE, row_split = split,
    right_annotation = rowAnnotation(textbox = anno_textbox(split, text))
)
```

Or put on the left side of the heatmap:

```{r, fig.width = 7}
Heatmap(mat, name = "mat", cluster_rows = FALSE, row_split = split, row_title = NULL,
    left_annotation = rowAnnotation(textbox = anno_textbox(split, text, side = "left"))
)
```

Parameters for `textbox_grob()` can be directly passed in `anno_textbox()`. E.g.
when the text are sentences, to control word wrap and new lines:

```{r, fig.width = 7}
split = sample(letters[1:5], 100, replace = TRUE)
sentences = lapply(unique(split), function(x) {
    random_text(3, 8)
})
names(sentences) = unique(split)

Heatmap(mat, name = "mat", row_split = split,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(
            split, sentences, 
            word_wrap = TRUE, 
            add_new_line = TRUE)
    )
)
```

The first argument for `anno_textbox()` can also be set as a list of indicies. Note
the indices for rows should be continuously adjacent on heatmaps.

```{r, fig.width = 7}
align_to = split(seq_along(split), split)
Heatmap(mat, name = "mat", row_split = split,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(
            align_to[c("a", "b")], 
            sentences[c("a", "b")], # names should match
            word_wrap = TRUE, 
            add_new_line = TRUE)
    )
)
```

`anno_textbox()` works mainly together with `row_split` to associate more information
to every heatmap slice. But this is not necessary, as long as you can ensure the indices
are continuously adjacent on heatmaps. In the next example, rows are not clustered,
we add two text boxed to correspond to row 1-10 and row 11-30. 


```{r, fig.width = 7}
Heatmap(mat, name = "mat", cluster_rows = FALSE,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(
            list("a" = 1:10, "b" = 11:30), 
            sentences[c("a", "b")], 
            word_wrap = TRUE, 
            add_new_line = TRUE)
    )
)
```

There are some cases that users want to put the text boxes exactly at the positions
of the corresponding heatmap slices. In this case, the `by` argument should be
set to `"anno_block"`. And now `anno_block()` is internally used to implement text
box annotations.

```{r, fig.width = 7}
split = rep(letters[1:10], 10)
text = lapply(unique(split), function(x) {
    random_text(10)
})
names(text) = unique(split)

Heatmap(mat, name = "mat", row_split = split,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(split, text, by = "anno_block")
    )
)
```

Similarly, the first parameter can be set as a list of indicies:

```{r, fig.width = 7}
align_to = split(seq_along(split), split)
Heatmap(mat, name = "mat", row_split = split,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(
            align_to[c("a", "b")], 
            text[c("a", "b")], # names should match
            by = "anno_block")
    )
)
```


```{r, fig.width = 7}
Heatmap(mat, name = "mat", cluster_rows = FALSE,
    right_annotation = rowAnnotation(
        textbox = anno_textbox(
            list("a" = 1:10, "b" = 50:70), 
            text[c("a", "b")], 
            by = "anno_block"))
)
```

So far, the texts are assigned with random colors. Now the question is how to 
exactly control graphics parameters for texts in the text boxes. In previous examples,
the value of `text` is a list of character vectors. The graphics parameters can
be integrated into `text` by setting `text` as a list of data frames. In each data 
frame, the first column contains texts that will be put into boxes. The data frame 
can also contains the following four columns (`"col"`, `"fontsize"`, `"fontfamily"`
and `"fontface"`) to exactly control the corresponding text.


```{r, fig.width = 7}
split = rep(letters[1:5], 20)
text = lapply(unique(split), function(x) {
    df = data.frame(text = random_text(10))
    df$fontsize = runif(10, 6, 20)
    if(runif(1) > 0.5) {
        df$col = rep(rand_color(1), 10)
    } else {
        df$col = 1:10
    }
    df
})
names(text) = unique(split)
head(text[[1]])

Heatmap(mat, name = "mat", cluster_rows = FALSE, row_split = split,
    right_annotation = rowAnnotation(textbox = anno_textbox(split, text))
)
```

In the [**simplifyEnrichment**](http://www.bioconductor.org/packages/devel/bioc/html/simplifyEnrichment.html) package,
we use `anno_textbox()` to implement a word cloud annotation to visualize 
summaries of biological functions in each GO cluster.

## Summary annotation {#summary-annotation}

There is one special annotation `anno_summary()` which only works with
one-column heatmap or one-row heatmap (we can say the heatmap only contains a
vector). It shows summary statistics for the vector in the heatmap. If the
corresponding vector is discrete, the summary annotation is presented as
barplots and if the vector is continuous, the summary annotation is boxplot.
`anno_summary()` is always used when the heatmap is split so that statistics
can be compared between heatmap slices.

The first example shows the summary annotation for discrete heatmap. The
barplot shows the proportion of each level in each slice. The absolute values
can already be seen by the height of the heatmap slice.

The color schema for the barplots is automatically extracted from the heatmap.

```{r}
ha = HeatmapAnnotation(summary = anno_summary(height = unit(4, "cm")))
v = sample(letters[1:2], 50, replace = TRUE)
split = sample(letters[1:2], 50, replace = TRUE)

Heatmap(v, name = "mat", col = c("a" = "red", "b" = "blue"),
    top_annotation = ha, width = unit(2, "cm"), row_split = split)
```

The second example shows the summary annotation for continuous heatmap. The
graphic parameters should be manually set by `gp`. The legend of the boxplot
can be created and added as introduced in Section \@ref(discrete-legends),
last second paragraph.

```{r}
ha = HeatmapAnnotation(summary = anno_summary(gp = gpar(fill = 2:3), 
    height = unit(4, "cm")))
v = rnorm(50)
Heatmap(v, name = "mat", top_annotation = ha, width = unit(2, "cm"), 
    row_split = split)
```

Normally we don't draw this one-column heatmap along. It is always combined
with other "main heatmaps". E.g. A gene expression matrix with a one-column
heatmap which shows whether the gene is a protein coding gene or a linc-RNA
gene.

In following, we show a simple example of a "main heatmap" with two one-column
heatmaps. The functionality of heatmap concatenation will be introduced in
Chapter \@ref(a-list-of-heatmaps).

```{r, fig.width = 5.2}
m = matrix(rnorm(50*10), nrow = 50)
ht_list = Heatmap(m, name = "main_matrix")

ha = HeatmapAnnotation(summary = anno_summary(height = unit(3, "cm")))
v = sample(letters[1:2], 50, replace = TRUE)
ht_list = ht_list + Heatmap(v, name = "mat1", top_annotation = ha, width = unit(1, "cm"))

ha = HeatmapAnnotation(summary = anno_summary(gp = gpar(fill = 2:3), 
    height = unit(3, "cm")))
v = rnorm(50)
ht_list = ht_list + Heatmap(v, name = "mat2", top_annotation = ha, width = unit(1, "cm"))

split = sample(letters[1:2], 50, replace = TRUE)
lgd_boxplot = Legend(labels = c("group a", "group b"), title = "group",
    legend_gp = gpar(fill = c("red", "blue")))
draw(ht_list, row_split = split, ht_gap = unit(5, "mm"), 
    heatmap_legend_list = list(lgd_boxplot))
```

## Multiple annotations {#multiple-annotations}

### General settings {#heatmap-annotation-general-settings}

As mentioned before, to put multiple annotations in `HeatmapAnnotation()`,
they just need to be specified as name-value pairs. In `HeatmapAnnotation()`,
there are some arguments which controls multiple annotations. For these
arguments, they are specified as a vector which has same length as number of
the annotations, or a named vector with subset of the annotations.

The simple annotations which are specified as vectors, matrices and data
frames will automatically have legends on the heatmap. `show_legend` controls
whether to draw the legends for them. Note here if `show_legend` is a vector,
the value of `show_legend` should be in one of the following formats:

- A logical vector with the same length as the number of simple annotations.
- A logical vector with the same length as the number of totla annotations. The
  values for complex annotations are ignored.
- A named vector to control subset of the simple annotations.

For customization on the annotation legends, please refer to Section \@ref(heatmap-and-annotation-legends).

```{r, fig.width = 5.2}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    show_legend = c("bar" = FALSE)
)
Heatmap(matrix(rnorm(100), 10), name = "mat", top_annotation = ha)
```

`gp` controls graphic parameters (except `fill`) for the simple annotatios,
such as the border of annotation grids.

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    gp = gpar(col = "red")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```


`border` controls the border of every single annotations.
`show_annotation_name` controls whether show annotation names. As mentioned,
the value can be a single value, a vector or a named vector.

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    show_annotation_name = c(bar = FALSE), # only turn off `bar`
    border = c(foo = TRUE) # turn on foo
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`annotation_name_gp`, `annotation_name_offset`, `annotation_name_side` and
`annotation_name_rot` control the style and position of the annotation names.
The latter three can be specified as named vectors. If
`annotation_name_offset` is specified as a named vector, it can be specified
as characters while not `unit` objects: `annotation_name_offset = c(foo = "1cm")`.

`gap` controls the space between every two neighbouring annotations. The value
can be a single unit or a vector of units.

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    gap = unit(2, "mm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    gap = unit(c(2, 10), "mm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

### Size of annotations {#size-of-annotations}

`height`, `width`, `annotation_height` and `annotation_width` control the
height or width of the complete heatmap annotations. Normally you don't need
to set them because all the single annotations have fixed height/width and the
final height/width for the whole heatmap annotation is the sum of them.
Resizing these values will involve rather complicated adjustment depending on
whether it is a simple annotation or complex annotation. The resizing of
heatmap annotations will also happen when adjusting a list of heatmaps. In
following examples, we take column annotations as examples and demonstrate
some scenarios for the resizing adjustment.

First the default height of `ha`:

```{r}
# foo: 1cm, bar: 5mm, pt: 1cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If `height` is set, the size of the simple annotation will not change, while
only the complex annotations are adjusted. If there are multiple complex
annotations, they are adjusted according to the ratio of their original size.

```{r}
# foo: 1cm, bar: 5mm, pt: 4.5cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    height = unit(6, "cm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`simple_anno_size` controls the height of all simple annotations. Recall
`ht_opt$simple_anno_size` can be set to globally control the size of simple
annotations in all heatmaps.

```{r}
# foo: 2cm, bar:1cm, pt: 3cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    simple_anno_size = unit(1, "cm"), height = unit(6, "cm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If `annotation_height` is set as a vector of absolute units, the height of all
three annotations are adjusted accordingly.

```{r}
# foo: 1cm, bar: 2cm, pt: 3cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    annotation_height = unit(1:3, "cm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If `annotation_height` is set as pure numbers which is treated as relative
ratios for annotations, `height` should also be set as an absolute unit and
the size of every single annotation is adjusted by the ratios.

```{r test}
# foo: 1cm, bar: 2cm, pt: 3cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    annotation_height = 1:3, height = unit(6, "cm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`annotation_height` can be mixed with relative units (in `null` unit) and
absolute units.

```{r}
# foo: 1.5cm, bar: 1.5cm, pt: 3cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    annotation_height = unit(c(1, 1, 3), c("null", "null", "cm")), height = unit(6, "cm")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

```{r}
# foo: 2cm, bar: 1cm, pt: 3cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    pt = anno_points(1:10),
    annotation_height = unit(c(2, 1, 3), c("cm", "null", "cm")), height = unit(6, "cm")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

If there are only simple annotations, simply setting `height` won't change the
height.

```{r}
# foo: 1cm, bar: 5mm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    height = unit(6, "cm"))
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

unless `simple_anno_size_adjust` is set to `TRUE`.

```{r}
# foo: 4cm, bar: 2cm
ha = HeatmapAnnotation(foo = cbind(1:10, 10:1), 
    bar = 1:10,
    height = unit(6, "cm"),
    simple_anno_size_adjust = TRUE)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Section \@ref(annotations-as-components-are-adjusted) introduces how the
annotation sizes are adjusted among a list of heatmaps.

### Annotation labels

From version 2.3.3, alternative labels for annotations can be set by `annotation_label` argument:

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    annotation_label = c("Annotation_foo", "Annotation_bar", "Annotation_pt")
)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

Annotation labels can also be set with complex text:

```{r, fig.width = 5.2}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    annotation_label = gt_render(
        c("**Anno**_<span style='color:red'>foo</span>", 
          "**Anno**_<span style='color:blue'>bar</span>", 
          "**Anno**_<span style='color:green'>pt</span>"),
        gp = gpar(box_fill = "grey")
    )
)
Heatmap(matrix(rnorm(100), 10), name = "mat", top_annotation = ha)
```
From version 2.5.6, rotations of annotation names can be configured.

```{r, fig.width = 5.2}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    annotation_name_rot = 45
)
Heatmap(matrix(rnorm(100), 10), name = "mat", top_annotation = ha)
```

Or on the rows:

```{r, fig.width = 5.2}
ha = rowAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10),
    annotation_name_rot = 45
)
Heatmap(matrix(rnorm(100), 10), name = "mat", left_annotation = ha)
```


## Utility functions {#heatmap-annotation-utility-function}

There are some utility functions which make the manipulation of heatmap
annotation easier. Just see following examples.

```{r}
ha = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10))
length(ha)
nobs(ha)
```

Get or set the names of the annotations:

```{r}
names(ha)
names(ha) = c("FOO", "BAR", "PT")
names(ha)
```

You can concatenate two `HeatmapAnnotation` objects if they contain same
number of observations and different annotation names.

```{r}
ha1 = HeatmapAnnotation(foo = 1:10, 
    bar = cbind(1:10, 10:1),
    pt = anno_points(1:10))
ha2 = HeatmapAnnotation(FOO = runif(10), 
    BAR = sample(c("a", "b"), 10, replace = TRUE),
    PT = anno_points(rnorm(10)))
ha = c(ha1, ha2)
names(ha)
```

```{r, echo = FALSE, fig.width = annotation_width(ha), fig.height = annotation_height(ha)}
draw(ha, test = TRUE)
```

`HeatmapAnnotation` object sometimes is subsettable. The row index corresponds
to observations in the annotation and column index corresponds to the
annotations. If the annotations are all simple annotations or the complex
annotation created by `anno_*()` functions in **ComplexHeatmap** package, the
`HeatmapAnnotation` object is always subsettable.

```{r}
ha_subset = ha[1:5, c("foo", "PT")]
ha_subset
```

```{r, echo = FALSE, fig.width = annotation_width(ha_subset), fig.height = annotation_height(ha_subset)}
draw(ha_subset, test = TRUE)
```

The construction of heatmaps and annotations can be separated, later the annotations
can be filled into the heatmap objects by the `attach_annotation()` function.

```{r, eval = FALSE}
# code only for demonstration
ha1 = HeatmapAnnotation(foo = 1:10)
ha2 = rowAnnotation(bar = letters[1:10])
ht = Heatmap(mat)
ht = attach_annotation(ht, ha1, side = "top")
ht = attach_annotation(ht, ha2, side = "left")
```

## Implement new annotation functions {#implement-new-annotation-functions}

All the annotation functions defined in **ComplexHeatmap** are constructed by
the `AnnotationFunction` class. The `AnnotationFunction` class not only stores
the "real R function" which draws the graphics, it also calculates the spaces
produced by the annotation axis. More importantly, it allows splitting the
annotation graphics according to the split of the main heatmap.

As expected, the main part of the `AnnotationFunction` class is a function
which defines how to draw at specific positions which correspond to rows or
columns in the heatmap. The function should have three arguments: `index`, `k`
and `n` (the names of the arguments can be arbitrary) where `k` and `n` are
optional. `index` corresponds to the indices of rows or columns of the
heatmap. The value of `index` is not necessarily to be the whole row indices
or column indices in the heatmap. It can also be a subset of the indices if
the annotation is split into slices according to the split of the heatmap.
`index` is reordered according to the reordering of heatmap rows or columns
(e.g. by clustering). So, `index` actually contains a list of row or column
indices for the current slice after row or column reordering.

As mentioned, annotation can be split into slices. `k` corresponds to the
current slice and `n` corresponds to the total number of slices. The
annotation function draws in every slice repeatedly. The information of `k`
and `n` sometimes can be useful, for example, we want to add axis in the
annotation, and if it is a column annotation and axis is drawn on the very
right of the annotation area, the axis is only drawn when `k == n`.

Since the function only allows `index`, `k` and `n`, the function sometimes
uses several external variables which can not be defined inside the function,
e.g. the data points for the annotation. These variables should be imported
into the `AnnotationFunction` class by `var_import` so that the function can
correctly find these variables.

One important feature for `AnnotationFunction` class is it can be subsettable,
which is the base for splitting. To allow subsetting on the object, users need
to define the rule for the imported variables if there is any. The rules are
simple functions which accpet the variable and indices, and return the subset
of the variable. The subset rule functions implemented in this package are
`subset_gp()`, `subset_matrix_by_row()` and `subset_vector()`. If the
subsetting rule is not provided, it is inferred by the type of the object.

In the following example, we first construct an `AnnotationFunction` object which needs external
variable and supports subsetting. This annotation contains a list of "lolipops" (points plus vertical segments) which
is drawn in a viewport. Y-axis is drawn in the first slices.

The variable `x` is from outside of the function, so it should be added to `var_import`.

```{r}
x = 1:10
anno1 = AnnotationFunction(
    fun = function(index, k, n) {
        n = length(index)
        pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = c(0, 10)))
        grid.rect()
        grid.points(1:n, x[index], default.units = "native")
        grid.segments(1:n, 0, 1:n, x[index], default.units = "native")
        if(k == 1) grid.yaxis()
        popViewport()
    },
    var_import = list(x = x),
    n = 10,
    subsettable = TRUE,
    height = unit(2, "cm")
)
anno1
```

Then we can assign `anno1` in `HeatmapAnnotation()` function. Since `anno1` is
subsettable, you can split columns of the heatmap.

```{r, eval = FALSE}
m = rbind(1:10, 11:20)
Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1))
Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), 
    column_split = rep(c("A", "B"), each = 5))
```

```{r, echo = FALSE, fig.width = 5.2}
m = rbind(1:10, 11:20)
pushViewport(viewport(y = 1, height = 0.5, just = "top"))
draw(Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1)), newpage = FALSE)
upViewport()
pushViewport(viewport(y = 0.5, height = 0.5, just = "top"))
draw(Heatmap(m, top_annotation = HeatmapAnnotation(foo = anno1), 
    column_split = rep(c("A", "B"), each = 5)), newpage = FALSE)
upViewport()
```

The second way is to put all data variables inside the function and no need to
import other variables.

```{r, eval = FALSE}
# code only for demonstration
anno2 = AnnotationFunction(
    fun = function(index) {
        x = 1:10
        n = length(index)
        pushViewport(viewport())
        grid.points(1:n, x[index])
        popViewport()
    },
    n = 10,
    subsettable = TRUE
)
```

The most compact way to only specify the function to the constructor. This allows
reordering, but it does not work when you split heatmap.

```{r, eval = FALSE}
# code only for demonstration
anno3 = AnnotationFunction(
    fun = function(index) {
        x = 1:10
        n = length(index)
        pushViewport(viewport())
        grid.points(1:n, x[index])
        popViewport()
    }
)
```

All the `anno_*()` functions introduced in this section actually are not
really annotation functions, while they are functions generating annotation
functions with specific configurations.

```{r}
anno_points(1:10)
```

In most cases, you don't need to manually construct your `AnnotationFunction`
objects. The annotation function `anno_*()` implemented in **ComplexHeatmap**
are already enough for most of the analysis tasks. On the other hand, users
can also use `anno_empty()` and `decorate_annotation()` to quickly add
self-defined annotation graphics. E.g. we can re-implement previous heatmap
as (of course it is lengthy):

```{r, fig.height = 5/2, fig.width = 5.2}
ht = Heatmap(m, name = "mat",
    top_annotation = HeatmapAnnotation(foo = anno_empty(height = unit(2, "cm"))), 
    column_split = rep(c("A", "B"), each = 5))
ht = draw(ht)
co = column_order(ht)
decorate_annotation("foo", slice = 1, {
    od = co[[1]]
    pushViewport(viewport(xscale = c(0.5, length(od) + 0.5), yscale = c(0, 10)))
    grid.points(seq_along(od), x[od])
    grid.segments(seq_along(od), 0, seq_along(od), x[od], default.units = "native")
    grid.yaxis()
    popViewport()
})
decorate_annotation("foo", slice = 2, {
    od = co[[2]]
    pushViewport(viewport(xscale = c(0.5, length(od) + 0.5), yscale = c(0, 10)))
    grid.points(seq_along(od), x[od])
    grid.segments(seq_along(od), 0, seq_along(od), x[od], default.units = "native")
    popViewport()
})
```

### Construct annotation function by `cell_fun`

To simplify the use of `AnnotationFunction()`, from version 2.9.3, it has a new argument `cell_fun` which accepts
a self-defined function that only draws in a single "annotation cell". 
This would be convenient for annotation only with a few cells.
See the following example which visualizes percent values by text and bars.
Actually this is how `anno_numeric()` (Section \@ref(anno-numeric)) is implemented.

```{r, fig.width = 5, fig.height = 5}
anno_pct = function(x) {

    max_x = max(x)
    text = paste0(sprintf("%.2f", x*100), "%")
    cell_fun_pct = function(i) {
        pushViewport(viewport(xscale = c(0, max_x)))
        grid.roundrect(x = unit(1, "npc"), width = unit(x[i], "native"), 
            height = unit(1, "npc") - unit(4, "pt"), 
            just = "right", gp = gpar(fill = "#0000FF80", col = NA))
        grid.text(text[i], x = unit(1, "npc"), just = "right")
        popViewport()
    }

    AnnotationFunction(
        cell_fun = cell_fun_pct,
        var_import = list(max_x, x, text), 
        which = "row",
        width = max_text_width(text)*1.25
    )
}

x = runif(10)
ha = rowAnnotation(foo = anno_pct(x), annotation_name_rot = 0)

m = matrix(rnorm(100), 10)
rownames(m) = x
ha + Heatmap(m)
```

Note if `cell_fun` is set in `AnnotationFunction`, the returned annotation function
is subsettable, which means it also works when heatmap is split.