An introduction to the gapmap package

This document explains basic functions of the gapmap package to draw a gapped cluster heatmap. The plot is generated using the ggplot2 package. Let’s load the library first.

library(gapmap)

We will simulate a simple dataset.

set.seed(1234)
x <- rnorm(10, mean=rep(1:5, each=2), sd=0.4)
y <- rnorm(10, mean=rep(c(1,2), each=5), sd=0.4)
dataFrame <- data.frame(x=x, y=y, row.names=c(1:10))
#calculate distance matrix. default is Euclidean distance
distxy <- dist(dataFrame)
#perform hierarchical clustering. default is complete linkage.
hc <- hclust(distxy)
dend <- as.dendrogram(hc)

To make a gapped cluster heatmap, you need to pass a matrix object for heatmap, and dendrogram class objects for drawing dendrograms and ordering.

grey_scale =c("#333333", "#5C5C5C", "#757575", "#8A8A8A", "#9B9B9B", "#AAAAAA", "#B8B8B8", "#C5C5C5", "#D0D0D0", "#DBDBDB", "#E6E6E6")
gapmap(m = as.matrix(distxy), d_row= rev(dend), d_col=dend, col = grey_scale)

## Warning: The `panel.margin` argument of `theme()` is deprecated as of ggplot2 2.2.0.
## ℹ Please use the `panel.spacing` argument instead.
## ℹ The deprecated feature was likely used in the gapmap package.
##   Please report the issue at
##   <https://github.com/evanbiederstedt/gapmap/issues>.
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.

The default of gapmap function is in the quantitative mode and uses exponential mapping. First, you can choose either modes: quantitative or threshold.

• quantitative: the size of gap is quantitatively mapped to the distance/height at which two nodes merges in hierarchical clustering. For mapping the distance, you have 2 options: linear or exponential mapping.
  • linear: The distance and the size of a gap is linearly mapped.
  • exponential: The distance and the size of a gap is linearly mapped. The scale log base can be set with scale attribute. The default scale is set to 0.5.
• threshold: the gaps are introduced based on the “cutting the tree” method. By setting threshold attributes, or alternatively row_threshold and col_threshold, you can divide into clusters and introduce the gaps between clusters.

The following example uses the linear mapping. This mapping generate more gaps, whereas the previous example of exponential mapping emphasize on the large gaps.

gapmap(m = as.matrix(distxy), d_row= rev(dend), d_col=dend,  mode = "quantitative", mapping="linear", col = grey_scale)

The following example illustrate the difference of two mapping schemes. For the exponential mapping, the scale log base is set to 0.5.

## Warning: A numeric `legend.position` argument in `theme()` was deprecated in ggplot2
## 3.5.0.
## ℹ Please use the `legend.position.inside` argument of `theme()` instead.
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.

The variation of scale log base settings is illustrated in the following plot. The value of scale is annotated on the plot.

Besides the quantitative mode, there is linear mode to introduce gap by a threshold. In the following example, the dendrograms for rows and columns are cut at the threshold distance of 2 and gaps of the same size are introduced between clusters.

gapmap(m = as.matrix(distxy), d_row= rev(dend), d_col=dend,  mode = "threshold", row_threshold = 2, col_threshold = 2, col = grey_scale)

In addition, this package works well with our dendrogram sorting package, called dendsort. For the details on dendsort, please check our paper.

library(dendsort);
gapmap(m = as.matrix(distxy), d_row= rev(dendsort(dend)), d_col=dendsort(dend),  mode = "quantitative", col = grey_scale)