ComplexHeatmap in R

To check the github repo for the ComplexHeatmap package click here.
Complete reference is available here.
The complete reference book contains all the details about this package but can be overwhelming due to the amount of information. I write this tutorial to get you started on using ComplexHeatmap by making simple heatmap and adding some features to it.


ComplexHeatmap package needs to be installed and loaded:


# Load package
library(ComplexHeatmap)  # directly load the package if it is installed already

Load dataset

Your dataset needs to be loaded in the form of a matrix.

# Loaded the dataset in matrix named mat
mat <- as.matrix(read.csv ("PATH/TO/file.csv", sep = ',', row.names = 1, header=T))
# Other file formats can also be loaded as matrix
# mat[1:5,1:3]   #to view the matrix
If the dataset has non-numeric entries, the matrix might be loaded as character type and can lead to heatmap not displaying properly. If this is a problem, get rid of the non-numeric characters and convert the matrix type to numeric (see below).
According to the complete reference documentation: "NA is allowed in the matrix. You can control the color of NA by na_col argument (by default it is grey for NA). A matrix that contains NA can be clustered by Heatmap() as long as there is no NA distances between any of the rows or columns respectively."

# after loading the data as.matrix, check matrix type in the environment panel in RStudio or by using:
# If matrix type is character,  it returns "character". You need to replace any characters with numbers.

mat[mat == "None"] <- 0    # replaces the word "None" anywhere in mat with 0

# Once the matrix contains only numerals, change it's type:
mat <- type.convert(mat, = TRUE)

Now, typeof(mat) returns "double" then matrix is numeric. You can also use
which should return TRUE

For this tutorial, I will make a random matrix to use as an example.

# Generate random matrix
mat <- matrix(rnorm(50, 20), nrow=10)
is.numeric(mat) # check if numeric
mat[1:5,1:3] # view selected rows and columns
# The output is shown below


Generate simple heatmap

This command generates a heatmap with default settings without additional commands:

Heatmap(mat)  # mat is the dataset name loaded earlier as matrix


The commands in R are case sensitive, so heatmap and Heatmap are commands from two different packages.

Customize your heatmap

There are countless ways to customize your heatmap with R. Here are a few of the ways to make a great heatmap.

Select different colors

Use RColorBrewer package to get a variety of color palettes. Always select colorblind accessible color combinations. You can input colors using palettes directly from RColorBrewer or using the hex codes to specify exact hues.



# col_fun <- colorRamp2(c(18, 20, 23), brewer.pal(3, "Blues"))
# OR
col_fun <- colorRamp2(c(18, 20, 23), c("#FFFFB2", "#f4a582", "#BD0026"))
# The `colorRamp2` function is used for color interpolation. 

Heatmap(mat, name = "mat", col = col_fun)


Draw heatmap with custom labels on legend

        heatmap_legend_param = list(
          title = "Legend title", at = c(18, 20, 23),
          labels = c("label1", "2", "three")
# Numbers in parameter at=c() appear on legend unless labels=c() is included.


Customize legend

You can specify title, annotation, and position of legend.

Legend_details <- list(title = "Map Legend",
                       at = c(18, 20, 23)
map1 <- Heatmap(mat, heatmap_legend_param = Legend_details)
draw(map1, heatmap_legend_side = "left")   # Can be “right”, “left”, “bottom”, “top”


Draw independent legend for more flexibility

Note that this legend is independent of the plot, so you need to select the same colors carefully for representing the corresponding plot.

col_fun <- colorRamp2(c(18, 20, 23), 
                      c("#d1e5f0", "#f4a582", "#d6604d"))
# create a function to represent color, which can be used for both legend and heatmap to avoid selecting different colors for both

lgd = Legend(col_fun = col_fun, title = "Legend title")
lgd1 = draw(lgd, x= unit(0.9, "npc"), y=unit(0.2, "npc")) 

The numbers 0.9 and 0.2 in the last line of code represent the position of legend on x and y axis of the entire plot and can be changed according to your need. This gives you more flexibility with the positioning of the legend.

Add more annotations to the plot

ComplexHeatmap package allows you to modify the plot in lots of ways. Here is an example of a complex heatmap with additional annotations.

mat <- matrix(rnorm(50, 20), nrow=10)
rownames(mat) = paste0("R", 1:10)
labels <- data.frame(Rowlabels = c("These", "are", "given", "row", "labels", "These", "are", "given", "row", "labels"))

### Define annotations

ha_row = rowAnnotation(df= labels,
                       gp = gpar(col = "black"),
                       annotation_legend_param = list(title = "Legend1 title", 
                                                      ncol = 1)

col_fun <- colorRamp2(c(18, 20, 23), 
                      c("Blue", "#f4a582", "#d6604d"))

### Make the heatmap
map <- Heatmap(mat, show_heatmap_legend = TRUE, col=col_fun,
               heatmap_legend_param = list(title = "Legend2 title", ncol = 1),
               column_title = "Title",
               left_annotation = ha_row,
               column_title_gp = gpar(fontsize = 18, fontface = "bold"),
               row_names_gp = grid::gpar(fontsize = 10)

draw(map, align_heatmap_legend = "heatmap_top", merge_legends = TRUE)


There are lots of additional features in this package like drawing histograms, boxplots, and violin plots around the heatmap. Check out the complete reference documentation for more information.

Further Reading

Homepage Section Index Previous Next