Source: vignettes/most_probably_asked_questions.Rmd

Most probably asked questions

There is no plot comming out after running Heatmap() function.

In this case, you need to use draw() function explicitly. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#plot-the-heatmap and https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#plot-the-heamtap-list.

Retrieve orders and dendrograms.

For retrieving orders and dendrograms from a single heatmap. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-single-heatmap.html#get-orders-and-dendrograms-from-heatmap.

For retrieving orders and dendrograms from a list of heatmaps. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#get-orders-and-dendrograms-from-a-list-of-heatmaps.

How should I control the height or width of the heatmap annotations?

For complex annotations generated by anno_*() functions, width or height should be set inside the anno_*() function, such as anno_points(..., height = ...). The size of simple annotations is controlled by anno_simple_size. The width/height and annotation_width/annotation_height are used to adjust the size for multiple annotations which are put in one HeatmapAnnotation object. See https://jokergoo.github.io/ComplexHeatmap-reference/book/heatmap-annotations.html#multiple-annotations

How should I control the axes of the annotations?

In the annotation functions anno_*(), the argument axis_param can be used to set the axes. The value should be a list and the default settings for axis can be get by:

default_axis_param("column")
default_axis_param("row")

How to control the style of legends?

The style of legends can be controlled by heatmap_legend_param in Heatmap(), or annotation_legend_param in HeatmapAnnotation(). The parameters for controlling legends are those arguments in Legend() function. See https://jokergoo.github.io/ComplexHeatmap-reference/book/legends.html#heatmap-and-annotation-legends.

Some text are cut by the plotting region.

The layout of the ComplexHeatmap is not perfect that it is still possible some of the text are drawn out of the plotting region. In this case, you can set the padding argument in draw() function to increase the blank areas around the final plot. See https://jokergoo.github.io/ComplexHeatmap-reference/book/a-list-of-heatmaps.html#manually-increase-space-around-the-plot.

Does Heatmap title supports mathematical expression?

Yes, all the text-related elements (e.g. titles, row names, legend titles, legend labels, …) allow methematical expression.

I have many heatmaps and I want to put them into different panels for a big figure for my paper.

You can set newpage = FALSE in draw() function and use grid.layout() to manage the layout of your panels.

pushViewport(viewport(layout = grid.layout(...)))
pushViewport(viewport(layout.pos.row = ..., layout.pos.col = ...))
draw(ht, newpage = FALSE) # or draw(ht_list, newpage = FALSE)
popViewport()
...

But I more suggest to use grid.grabExpr() to directly capture the output of the heatmap and later draw the whole plot as a single graphic element by grid.draw().

ht_grob = grid.grabExpr(draw(ht, ...))

pushViewport(viewport(layout = grid.layout(...)))
pushViewport(viewport(layout.pos.row = ..., layout.pos.col = ...))
grid.draw(ht_grob)
popViewport()
...

I have a matrix with too many rows and I want to simplify the row dendrogram.

You can first group your rows into several groups and make a group-level dendrogram on it. See following example:

m = matrix(rnorm(1000*10), nr = 1000)
hc = hclust(dist(m))
group = cutree(hc, k = 6)
Heatmap(m, cluster_rows = cluster_within_group(t(m), group), 
    row_split = 6, border = TRUE) # it would be better if also set row_split

I have a matrix with huge nunmber of rows or columns, what is the efficient way to visualize it?

Heatmap is used to visualize the global patterns of your matrix while not every single row or column. I suggest to random sample rows or columns into a reasonable small number, and the final heatmap should look the same as if you still insist to use the full matrix.

How to add axes for dendrograms?

You need to use decorate_row_dend() or decorate_column_dend() to manually add the axes. See following examples:

m = matrix(rnorm(100), 10)

ht = Heatmap(m, name = "foo", 
    row_dend_width = unit(4, "cm"),
    column_dend_height = unit(4, "cm")
)
draw(ht, padding = unit(c(15, 2, 2, 2), "mm"))
decorate_column_dend("foo", {
    grid.yaxis()
})
decorate_row_dend("foo", {
    vp = current.viewport()
    xscale = vp$xscale
    grid.xaxis(at = xscale[2] - 0:5, label = 0:5)
})

Note for the left row dendrogram, the x-axis is from right to left, you need to self-define at and label in grid.xaxis() function.

You can also check annotation_axis_grob() function (later use grid.draw() to draw the axes) to draw a nicer axis.

I set row_km/column_km and it gives me different k-means clusterings for different runs.

Yes, this is what it should be expected because k-means uses random start points and it might give different results for different runs. To solve this problem, you do either way as follows:

  1. Always add set.seed(...) before making the heatmap. This makes sure the random seed is always the same for different runs.
  2. Set row_km_repeats/column_km_repeats to run k-means multiple times to get a final consensus k-means clustering. Note you might still get different results, but the chance is much smaller than just running k-means once.

I only want to draw dendrograms plus a list of annotations.

You need to assign the dendrograms to a zero-row/column matrix:

hc = hclust(dist(matrix(rnorm(100), 10)))
Heatmap(matrix(nc = 0, nr = 10), cluster_rows = hc, 
    right_annotation = rowAnnotation(
        foo = anno_points(1:10),
        sth = 1:10,
        bar = anno_barplot(1:10)),
    row_split = 2)

I still have a problem with the package and I am lost in the ocean of the huge vignette.

The vignette (https://jokergoo.github.io/ComplexHeatmap-reference/book/) contains huge number of examples and plots showing different usage of the package. It is sometimes not easy to find the solution you are looking for. In this case, don’t hesitate to write me an email. I am glad to answer all of your questions!