How to create and configure a Heatmap

This article provides instruction and discussion on using heatmaps (sometimes written "heat maps"). 
  1. Setting the plot type for heatmap
  2. Choosing markers / channels for display in the heatmap
  3. The heatmap visual depends on the selected statistic
  4. Setting the heatmap coloring range
  5. Data scaling for the heatmap visualization and statistics: raw vs transformed
    1. Background on data scaling and heatmaps
    2. Practical example of data scaling and heatmaps
  6. Mousing over a heatmap square shows the underlying data
  7. Exporting heatmap image to PowerPoint or PDF
  8. Troubleshooting heatmaps
  9. Heatmap clustering and dendrograms
Setting the plot type for heatmap
On the Working Illustration page, under "Plot Controls" under the illustration tab, select "Plot Type" -- "Heatmap". Make sure to select the appropriate channels for your heatmap in the "Channels" dimension. Click "Update Illlustration." Adjust the other dimensions as needed and click on "Update Illustration".

(To turn your illustration into a heatmap, select the heatmap option from the plot controls)


Choosing channels for display in the heatmap

A typical scenario when building a heatmap is to display samples or gated populations as rows and different markers of interest from within the data as columns. This figure allows the underlying expression profile of certain populations or samples to be explored:

(example of getting a multi-channel expression "fingerprint" from populations gated in viSNE)

In order to create a heatmap with multiple channels, use the channels figure dimension box within the Working Illustration. Make sure to set the X axis illustration setting to Panel/Channel Values. This setting defers control of the x axis to the channels figure dimension box and allows for figures with many channels. A common mistake is to not set this axis setting correctly, resulting in every square of the heatmap having the same data value. See visual below for all important settings:

(example of how to create a heatmap with many channels. Note that scaling is transformed values)


Heatmap visual depends on selected statistic

The desired statistic and equation (e.g. fold) can be chosen using the illustration controls panel on the left side of the working illustration. Heatmaps can be made with any statistic, such as event counts, percent in gate, medians, as well as ratios of these statistics compared between samples (e.g. fold change of event counts). When using a comparison equation, make sure to set the control appropriately.


(specify the statistic and equation for the heatmap)


Once rendered, a heatmap will appear in the illustration tab. The corresponding table of statistics will also be present under the heatmap. The table of statistics can be exported as tab-delimited data. Read more about statistics and equations in the Working Illustration


Setting the heatmap coloring range: global, individual, and custom

The heatmap coloring range is the range of the color bar below the heatmap. Consider the images below with four different configurations of the same heatmap illustration, which has two heatmaps displaying data for different channels. The important configuration differences between the four heatmaps are indicated, and show the different ways to scale the coloring range across heatmaps. This experiment is publicly available on your Cytobank with the name "PBMC (fluorescence)". Clone it to follow along.

Global: The coloring range is the same across heatmaps.


Individual: The coloring range is calculated per heatmap.


Custom range without inflection: The coloring range is user-defined and global.


Custom range with inflection: The coloring range is user-defined and global with an inflection point. Currently it is forced to use both sides of the color scale for this configuration.



Heatmap data scaling: raw versus transformed

1) Background on data scaling and heatmaps

An important concept in data visualization is the use of raw versus transformed data values. By default, heatmaps display statistical values and color themselves according to raw, unscaled data values. In order to visualize a heatmap with coloring and statistics according to transformed data values, the transformed ratio equation must be used (see section above). A control of table's minimum is usually appropriate to visualize an entire heatmap in scaled mode. When using a single heatmap with many channels, however, a control that normalizes each channel to itself is likely desired. Controls using column or row would be indicated for this, depending on how channels are arranged.

Consider the following example with a synthetic file. The file has four populations that are visualized in the heatmap. Their median values are 7.5, 75, 750, and 7500. When visualized in a raw fashion, the heatmap coloring is not very useful:

(heatmap visualized with raw data - the data values in columns 2 and 3 are washed out by the value of column 4)


In order to view the data in the biologically more useful transformed space, the transformed ratio should be used. In this example, the scales are set to Log10 and thus the Log10 ratio is used automatically. The transformed ratio automatically uses the correct ratio according to the scale settings of the channel being analyzed. Read more about statistics and comparative equations in the Working Illustration.

(the same heatmap as above visualized with transformed data values - the patterns in the data are now visible)


2) Practical example of data scaling and heatmaps

Below is a practical example of the theory discussed directly above. The figure shows a heatmap that plots numerous gated populations against a variety of channels in the dataset in order to see an "expression fingerprint" of the gated populations. The left side of the figure shows the heatmap with raw values. The right shows the heatmap with transformed values based on the transformed ratio of the minimum value in the heatmap compared to each datapoint within the heatmap. There is currently no option to use the transformed value of a data point in the absence of a comparative equation with a baseline (i.e., transformed ratio).


(a practical example of the difference that data scaling can make on the interpretation of data visualized in a heatmap. The data seen above are identical except for how they are scaled)


Mousing over a heatmap square shows underlying data

Hovering the mouse over any square on a heatmap will display the underlying data for that sample.



For the plot that pops up upon mouseover, the type of plot and its axes can be set using the settings for viewthrough plot indicated below:


(configure the viewthrough plot settings for mousing over a heatmap square)


Exporting Heatmap Image to PowerPoint or PDF

Heatmaps can be drag and dropped out of your browser to save or open in a different program, but only from the Illustration Print View. Besides that, normal guidelines for exporting images of figures apply.


(drag and drop a heatmap from the illustration print view to PowerPoint)


Troubleshooting Heatmap Errors

The L: Technically speaking, "L" stands for Layers, meaning that there is more than one FCS file assigned to that spot, and Cytobank doesn't know which to show. Use the layout placeholders tab to troubleshoot the current layout of your figure. Heatmaps won't render correctly unless each FCS file occupies its own square in layout placeholders. You may need to activate more Figure Dimensions, or add/remove/adjust Sample Tags until each file has its own square.

The Red Diagonal line: When a red diagonal line appears in a heatmap it means there is no sample in the expected heatmap location. Use the layout placeholders tab to troubleshoot the current layout of your figure, and then make sure you have a file assigned to the correct intersection of Sample Tags.


(example of the L and the red diagonal line. See Layout Placeholders below)


(layout placeholders view of the heatmap above. The files missing from the LPS row are accidentally categorized in the unstim row. Fixing the Sample Tags will fix this figure)
Heatmap Clustering and Dendrograms
Cytobank does not currently support any downstream operations on heatmaps including clustering and dendrogram production. To complete this workflow, heatmap data can be exported from Cytobank and fed into a different software package. Data can be exported directly from the illustration or using the Export Statistics Tool. For tips on recommended software packages for completing this workflow, or to request this feature, get in touch by making a support request.

Have more questions? Submit a request