Written and maintained by CASRAI Editorial Board
Published
On this page
A gene expression heatmap is a grid in which each row is a gene, each column is a sample, and the colour of each cell shows that gene’s expression level in that sample. In R, the usual route for RNA-seq data is to transform the DESeq2 count matrix with vst(), pick a set of genes, and pass the matrix to pheatmap(); setting scale="row" makes the colours show each gene relative to its own average. This guide walks through that workflow, including the heatmap gene expression settings that most often change how a figure reads.
What a gene expression heatmap is used for in research
Researchers use gene expression heatmaps to see patterns across many genes and samples at once: whether replicates group together, whether a treatment separates from a control, and which genes rise or fall together. The DESeq2 vignette uses heatmaps for two jobs: showing the transformed counts of selected genes, and showing sample-to-sample distances as a quality check. A heatmap is a display of values, not a test. Differential expression itself is tested on raw counts, and the vignette states that “for visualization or clustering” it can be useful to work with transformed versions of the count data (Love, Huber and Anders, 2014).
For a volcano-style view of which genes changed, see the CASRAI guide to the volcano plot for RNA-seq. For a general introduction to the plotting function, see heatmap in R; this page covers the expression-specific steps that guide does not.
How to install or access pheatmap and DESeq2
DESeq2 is a Bioconductor package; its official page and vignette are on bioconductor.org. pheatmap is a CRAN package, and its reference manual is on the R project site. In an R session, install them with:
install.packages("BiocManager")BiocManager::install("DESeq2")install.packages("pheatmap")
Then load them with library("DESeq2") and library("pheatmap"). The rest of this guide assumes you already have a DESeqDataSet object named dds, built from raw, un-normalised counts and a sample table that includes columns such as condition and type, as in the vignette’s worked example. Both packages are free to use.
How to make a gene expression heatmap step by step
Step 1: transform the counts
Raw counts are not suitable for clustering or colouring, because their variance depends on their mean. The DESeq2 vignette describes the variance stabilising transformation (VST) and the regularised logarithm (rlog), both of which “remove the dependence of the variance on the mean” and return values on a log2 scale normalised for library size. Run:
vsd = vst(dds, blind=FALSE)mat = assay(vsd)(the transformed matrix, genes in rows, samples in columns)
The vignette also shows rld = rlog(dds, blind=FALSE); it notes that rlog can be slow and that vst is the faster choice, especially with many samples. Its example timing is roughly 30 seconds for rlog versus under a second for vst on about 20 samples.
Step 2: decide between blind=TRUE and blind=FALSE
With the default blind=TRUE, dispersions are re-estimated using only an intercept, so samples are compared without regard to the experimental design; the vignette recommends this for unbiased sample quality assessment. When the transformed data are for downstream use and many genes differ by design, the vignette recommends blind=FALSE. For a gene heatmap of a finished analysis, blind=FALSE is the vignette’s own choice.
Step 3: choose which genes to show
A heatmap of every gene is unreadable, so you must select a subset. The DESeq2 vignette’s example selects the 20 genes with the highest mean normalised count:
select = order(rowMeans(counts(dds, normalized=TRUE)), decreasing=TRUE)[1:20]
That is one choice among several. Other common selections are the genes with the smallest adjusted p-values from your results table, or the most variable genes across samples; the choice should be stated in the figure legend because it determines what the picture can show.
Step 4: draw the heatmap
df = as.data.frame(colData(dds)[, c("condition","type")])pheatmap(mat[select, ], scale="row", show_rownames=FALSE, annotation_col=df)
The vignette’s own call uses cluster_rows=FALSE, cluster_cols=FALSE and show_rownames=FALSE, so its figure shows the genes in order of mean count with no dendrograms. The version above leaves clustering on (the pheatmap default) and adds scale="row", which is not in the vignette. Whether to scale is a design decision: the pheatmap default for scale is "none", so without it the colours reflect absolute transformed values and highly expressed genes dominate the colour range.
Step 5: add a sample-distance heatmap as a quality check
The vignette also builds a sample-to-sample distance heatmap from the transformed data. It computes sampleDists = dist(t(assay(vsd))), turns it into a matrix, and passes the distances to pheatmap() through clustering_distance_rows and clustering_distance_cols. It explains that the clustering must be supplied explicitly, because otherwise the function would calculate a clustering from the distances between the rows and columns of the distance matrix itself. plotPCA(vsd, intgroup=c("condition","type")) gives the companion principal component view.
How to read the output
Each cell is one gene in one sample. With scale="row", pheatmap centres and scales every row, so a colour tells you whether a sample is above or below that gene’s own average, not how highly the gene is expressed overall. Two genes with very different counts can therefore look identical. With scale="none", colours are the transformed values themselves and can be compared across rows, but a few high-count genes can use up most of the colour range.
The dendrograms show hierarchical clustering. By default pheatmap clusters rows with Euclidean distance and the "complete" linkage method; clustering_distance_rows="correlation" uses Pearson correlation instead, which groups genes by shape of expression profile rather than by magnitude. The default colour scale is a reversed seven-colour RdYlBu palette in 100 steps, so blue is low and red is high. Annotation bars from annotation_col show metadata such as condition above each column; if samples of one condition sit together in the dendrogram, that supports a consistent signal, and if they do not, check batch and library effects before interpreting the genes. A clustered heatmap is descriptive: it does not give p-values.
For deeper treatment of the clustering step, see the CASRAI guide to clustering analysis in R.
A worked example of row scaling
This example uses illustrative numbers, not data from a real experiment. Suppose a highly expressed gene A has vst values 10.0, 10.5 and 11.0 across three samples, and a low-expressed gene B has 4.0, 4.5 and 5.0. Both rise by the same amount across the samples. Gene A has a mean of 10.5 and a standard deviation of 0.5, so centring on the mean and dividing by the standard deviation gives -1, 0 and 1. Gene B has a mean of 4.5 and the same standard deviation, so it also gives -1, 0 and 1. With scale="row" the two rows are coloured identically, which is what you want when the question is “which samples have more of each gene”. With scale="none", gene A would sit at the red end of the palette and gene B at the blue end in every sample, and the shared pattern would be hard to see.
The reverse also holds: scaling discards absolute level. If your claim is that gene A is much more abundant than gene B, an unscaled heatmap, or a table of normalised counts, is the right display.
Common mistakes with expression heatmaps
- Plotting raw counts. The vignette tests differential expression on raw counts but recommends transformed values for visualisation and clustering. Heatmaps of raw counts are dominated by the most highly expressed genes.
- Using the blind transformation for a final figure.
blind=TRUEignores the design and suits quality assessment; the vignette points toblind=FALSEwhen the transformed data are used downstream. - Not saying how genes were chosen. Top-expressed, top-variable and top-significant selections answer different questions, and a reader cannot tell which one you used from the colours alone.
- Treating clustering as evidence. Hierarchical clustering always produces a tree. Statistical claims about genes belong in the differential expression results, with the heatmap as a visual summary.
- Mismatched annotation names. Annotation rows must match matrix column names, so check
all(rownames(df) == colnames(mat))before plotting.
Troubleshooting pheatmap for expression data
Column annotations are missing or raise an error
The row names of the annotation_col data frame must match the column names of the matrix. If samples are named differently in colData and in the matrix, the annotation will not line up.
The plot is one colour with a few bright rows
The values are probably unscaled. Check that you passed the vst or rlog matrix rather than raw counts, then consider scale="row". You can also set breaks, a numeric sequence covering the data range that must be one element longer than the colour vector; values beyond its ends receive the extreme colours.
Gene names are unreadable
Row names are shown by default. Use show_rownames=FALSE for large selections, or reduce fontsize_row, which defaults to the base fontsize (10 by default).
The sample-distance heatmap shows the wrong clustering
Pass the dist object to both clustering_distance_rows and clustering_distance_cols, as in Step 5. Unrecognised values for that argument are treated as a precomputed distance matrix.
You want gene clusters
cutree_rows sets the number of row clusters by cutting the row dendrogram; it is ignored if rows are not clustered.
Free alternatives to pheatmap
ComplexHeatmap is the other widely used R package for expression heatmaps, and CASRAI also covers a Python route.
| Tool | Language | What the sources say |
|---|---|---|
| pheatmap | R (CRAN) | Single function; scale argument with values “row”, “column”, “none” (default “none”) |
| ComplexHeatmap | R (Bioconductor) | No scale argument, so scale the matrix yourself; row splitting with row_km or row_split; colorRamp2() recommended for colours |
| seaborn | Python | Heatmaps in Python; see the linked CASRAI guide |
The data table below sets out how the two R packages handle scaling, colours, row names and row grouping, so you can port a figure from one to the other without changing what it shows. If you move to ComplexHeatmap, centre and scale the matrix yourself first, otherwise the blue-white-red default colours will reflect raw values.
Sources
- Bioconductor: Analyzing RNA-seq data with DESeq2 (vignette), checked 2026-11-16
- Love MI, Huber W, Anders S (2014), Genome Biology 15:550: Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2, checked 2026-11-16
- R project (CRAN): pheatmap reference manual, checked 2026-11-16
- Gu Z: ComplexHeatmap Complete Reference, A single heatmap, checked 2026-11-16
Data: Scaling, colour, row-name and row-grouping settings in pheatmap and ComplexHeatmap
Compiled from the pheatmap reference manual on CRAN and the ComplexHeatmap Complete Reference chapter 'A single heatmap', both read on 2026-11-16. Each row names a heatmap task and gives the argument or behaviour in each package, so a figure can be reproduced in either package.
| Task | pheatmap (CRAN) | ComplexHeatmap (Bioconductor) |
|---|---|---|
| Scale rows or columns | scale argument: "row", "column" or "none" (default "none") | No scale argument; scale the matrix yourself before plotting |
| Colours | color vector; default is a 100-step gradient from the reversed 7-class RdYlBu palette | Default blue-white-red mapping; colorRamp2() recommended |
| Hide gene names | show_rownames=FALSE | show_row_names=FALSE |
| Split rows into groups | cutree_rows = number of row clusters cut from the dendrogram | row_km = k for k-means split; row_split with a categorical vector, data frame or number |
| Row clustering method | clustering_method default "complete", same values as hclust | clustering_method_rows accepts hclust methods |
Sources
- pheatmap reference manual (accessed 2026-11-16)
- ComplexHeatmap Complete Reference: A single heatmap (accessed 2026-11-16)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







