- Setting the plot type for heatmap
- Choosing markers / channels for display in the heatmap
- The heatmap visual depends on the selected statistic
- Setting the heatmap coloring range
- Data scaling for the heatmap visualization and statistics: raw vs transformed
- Mousing over a heatmap square shows the underlying data
- Exporting heatmap image to PowerPoint or PDF
- Troubleshooting heatmaps
- Heatmap clustering and dendrograms
(To turn your illustration into a heatmap, select the heatmap option from the plot controls)
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)
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
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.
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)
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)
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)
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)
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.