plotHeatmap¶
This tool creates a heatmap for scores associated with genomic regions. The program requires a matrix file generated by the tool computeMatrix
.
usage: plotHeatmap [--matrixFile MATRIXFILE] --outFileName OUTFILENAME
[--outFileSortedRegions FILE] [--outFileNameMatrix FILE]
[--dpi DPI] [--kmeans KMEANS] [--hclust HCLUST] [--help]
[--version] [--sortRegions {descend,ascend,no}]
[--sortUsing {mean,median,max,min,sum,region_length}]
[--sortUsingSamples SORTUSINGSAMPLES [SORTUSINGSAMPLES ...]]
[--averageTypeSummaryPlot {mean,median,min,max,std,sum}]
[--missingDataColor MISSINGDATACOLOR]
[--colorMap COLORMAP [COLORMAP ...]] [--alpha ALPHA]
[--colorList COLORLIST [COLORLIST ...]]
[--colorNumber COLORNUMBER] [--zMin ZMIN [ZMIN ...]]
[--zMax ZMAX [ZMAX ...]] [--heatmapHeight HEATMAPHEIGHT]
[--heatmapWidth HEATMAPWIDTH]
[--whatToShow {plot, heatmap and colorbar,plot and heatmap,heatmap only,heatmap and colorbar}]
[--boxAroundHeatmaps BOXAROUNDHEATMAPS]
[--xAxisLabel XAXISLABEL] [--startLabel STARTLABEL]
[--endLabel ENDLABEL] [--refPointLabel REFPOINTLABEL]
[--regionsLabel REGIONSLABEL [REGIONSLABEL ...]]
[--samplesLabel SAMPLESLABEL [SAMPLESLABEL ...]]
[--plotTitle PLOTTITLE] [--yAxisLabel YAXISLABEL]
[--yMin YMIN [YMIN ...]] [--yMax YMAX [YMAX ...]]
[--legendLocation {best,upper-right,upper-left,upper-center,lower-left,lower-right,lower-center,center,center-left,center-right,none}]
[--perGroup] [--plotFileFormat] [--verbose]
Required arguments¶
–matrixFile, -m | |
Matrix file from the computeMatrix tool. | |
–outFileName, -out | |
File name to save the image to. The file ending will be used to determine the image format. The available options are: “png”, “eps”, “pdf” and “svg”, e.g., MyHeatmap.png. |
Output options¶
–outFileSortedRegions | |
File name into which the regions are saved after skipping zeros or min/max threshold values. The order of the regions in the file follows the sorting order selected. This is useful, for example, to generate other heatmaps while keeping the sorting of the first heatmap. Example: Heatmap1sortedRegions.bed | |
–outFileNameMatrix | |
If this option is given, then the matrix of values underlying the heatmap will be saved using this name, e.g. MyMatrix.tab. | |
–dpi | Set the DPI to save the figure. |
Clustering arguments¶
–kmeans | Number of clusters to compute. When this option is set, the matrix is split into clusters using the k-means algorithm. Only works for data that is not grouped, otherwise only the first group will be clustered. If more specific clustering methods are required, then save the underlying matrix and run the clustering using other software. The plotting of the clustering may fail with an error if a cluster has very few members compared to the total number or regions. |
–hclust | Number of clusters to compute. When this option is set, then the matrix is split into clusters using the hierarchical clustering algorithm, using “ward linkage”. Only works for data that is not grouped, otherwise only the first group will be clustered. –hclust could be very slow if you have >1000 regions. In those cases, you might prefer –kmeans or if more clustering methods are required you can save the underlying matrix and run the clustering using other software. The plotting of the clustering may fail with an error if a cluster has very few members compared to the total number of regions. |
Optional arguments¶
–version | show program’s version number and exit |
–sortRegions | Possible choices: descend, ascend, no Whether the heatmap should present the regions sorted. The default is to sort in descending order based on the mean value per region. |
–sortUsing | Possible choices: mean, median, max, min, sum, region_length Indicate which method should be used for sorting. For each row the method is computed. |
–sortUsingSamples | |
List of sample numbers (order as in matrix), that are used for sorting by –sortUsing, no value uses all samples, example: –sortUsingSamples 1 3 | |
–averageTypeSummaryPlot | |
Possible choices: mean, median, min, max, std, sum Define the type of statistic that should be plotted in the summary image above the heatmap. The options are: “mean”, “median”, “min”, “max”, “sum” and “std”. | |
–missingDataColor | |
If –missingDataAsZero is not set, such cases will be colored in black by default. Using this parameter, a different color can be set. A value between 0 and 1 will be used for a gray scale (black is 0). For a list of possible color names see: http://packages.python.org/ete2/reference/reference_svgcolors.html. Other colors can be specified using the #rrggbb notation. | |
–colorMap | Color map to use for the heatmap. If more than one heatmap is being plotted the color of each heatmap can be enter individually (e.g. –colorMap Reds Blues). Color maps are recycled if the number of color maps is smaller than the number of heatmaps being plotted. Available values can be seen here: http://matplotlib.org/users/colormaps.html The available options are: ‘Spectral’, ‘summer’, ‘coolwarm’, ‘Set1’, ‘Set2’, ‘Set3’, ‘Dark2’, ‘hot’, ‘RdPu’, ‘YlGnBu’, ‘RdYlBu’, ‘gist_stern’, ‘cool’, ‘gray’, ‘GnBu’, ‘gist_ncar’, ‘gist_rainbow’, ‘Wistia’, ‘CMRmap’, ‘bone’, ‘RdYlGn’, ‘spring’, ‘terrain’, ‘PuBu’, ‘spectral’, ‘gist_yarg’, ‘BuGn’, ‘bwr’, ‘cubehelix’, ‘YlOrRd’, ‘Greens’, ‘PRGn’, ‘gist_heat’, ‘Paired’, ‘hsv’, ‘Pastel2’, ‘Pastel1’, ‘BuPu’, ‘copper’, ‘OrRd’, ‘brg’, ‘gnuplot2’, ‘jet’, ‘gist_earth’, ‘Oranges’, ‘PiYG’, ‘YlGn’, ‘Accent’, ‘gist_gray’, ‘flag’, ‘BrBG’, ‘Reds’, ‘RdGy’, ‘PuRd’, ‘Blues’, ‘Greys’, ‘autumn’, ‘pink’, ‘binary’, ‘winter’, ‘gnuplot’, ‘RdBu’, ‘prism’, ‘YlOrBr’, ‘rainbow’, ‘seismic’, ‘Purples’, ‘ocean’, ‘PuOr’, ‘PuBuGn’, ‘nipy_spectral’, ‘afmhot’ |
–alpha | The alpha channel (transparency) to use for the heatmaps. The default is 1.0 and values must be between 0 and 1. |
–colorList | List of colors to use to create a colormap. For example, if –colorList black,yellow,blue is set (colors separated by comas) then a color map that starts with black, continues to yellow and finishes in blue is created. If this option is selected, it overrides the –colorMap chosen. The list of valid color names can be seen here: http://matplotlib.org/examples/color/named_colors.html Hex colors are valid (e.g #34a2b1). If individual colors for different heatmaps need to be specified they need to be separated by space as for example: –colorList “white,#cccccc” “white,darkred” As for –colorMap, the color lists are recycled if their number is smaller thatn the number ofplotted heatmaps. The number of transitions is defined by the –colorNumber option. |
–colorNumber | N.B., –colorList is required for an effect. This controls the number of transitions from one color to the other. If –colorNumber is the number of colors in –colorList then there will be no transitions between the colors. |
–zMin, -min | Minimum value for the heatmap intensities. Multiple values, separated by spaces can be set for each heatmap. If the number of zMin values is smaller thanthe number of heatmaps the values are recycled. |
–zMax, -max | Maximum value for the heatmap intensities. Multiple values, separated by spaces can be set for each heatmap. If the number of zMax values is smaller thanthe number of heatmaps the values are recycled. |
–heatmapHeight | |
Plot height in cm. The default for the heatmap height is 28. The minimum value is 3 and the maximum is 100. | |
–heatmapWidth | Plot width in cm. The default value is 4 The minimum value is 1 and the maximum is 100. |
–whatToShow | Possible choices: plot, heatmap and colorbar, plot and heatmap, heatmap only, heatmap and colorbar The default is to include a summary or profile plot on top of the heatmap and a heatmap colorbar. Other options are: “plot and heatmap”, “heatmap only”, “heatmap and colorbar”, and the default “plot, heatmap and colorbar”. |
–boxAroundHeatmaps | |
By default black boxes are plot around heatmaps. This can be turned off by setting –boxAroundHeatmaps no | |
–xAxisLabel, -x | |
Description for the x-axis label. | |
–startLabel | [only for scale-regions mode] Label shown in the plot for the start of the region. Default is TSS (transcription start site), but could be changed to anything, e.g. “peak start”. Same for the –endLabel option. See below. |
–endLabel | [only for scale-regions mode] Label shown in the plot for the region end. Default is TES (transcription end site). |
–refPointLabel | |
[only for reference-point mode] Label shown in the plot for the reference-point. Default is the same as the reference point selected (e.g. TSS), but could be anything, e.g. “peak start”. | |
–regionsLabel, -z | |
Labels for the regions plotted in the heatmap. If more than one region is being plotted, a list of labels separated by spaces is required. If a label itself contains a space, then quotes are needed. For example, –regionsLabel label_1, “label 2”. | |
–samplesLabel | Labels for the samples plotted. The default is to use the file name of the sample. The sample labels should be separated by spaces and quoted if a label itselfcontains a space E.g. –samplesLabel label-1 “label 2” |
–plotTitle, -T | |
Title of the plot, to be printed on top of the generated image. Leave blank for no title. | |
–yAxisLabel, -y | |
Y-axis label for the top panel. | |
–yMin | Minimum value for the Y-axis. Multiple values, separated by spaces can be set for each profile. If the number of yMin values is smaller thanthe number of plots, the values are recycled. |
–yMax | Maximum value for the Y-axis. Multiple values, separated by spaces can be set for each profile. If the number of yMin values is smaller thanthe number of plots, the values are recycled. |
–legendLocation | |
Possible choices: best, upper-right, upper-left, upper-center, lower-left, lower-right, lower-center, center, center-left, center-right, none Location for the legend in the summary plot. Note that “none” does not work for the profiler. | |
–perGroup | The default is to plot all groups of regions by sample. Using this option instead plots all samples by group of regions. Note that this is only useful if you have multiple groups of regions. by sample rather than group. |
–plotFileFormat | |
Possible choices: png, pdf, svg, eps Image format type. If given, this option overrides the image format based on the plotFile ending. The available options are: “png”, “eps”, “pdf” and “svg” | |
–verbose | If set, warning messages and additional information are given. |
An example usage is: plotHeatmap -m <matrix file>
Details¶
Note
With the release of deepTools 2.3 is is now possible to set the color and scale of each heatmap individually. Also, we added the option to remove the boxes around the heatmaps.
plotHeatmap
does not change the values that computeMatrix
calculated, it simply translates them into heatmaps and summary plots.
It offers a large variety of parameters to explore various visualizations and customize the resulting image (see the commands above).
In addition, you can retrieve all the data tables underlying the various plots including the regions that were used to generate the final plot. The following tables summarizes the kinds of optional outputs that are available with the three tools.
optional output type | command | computeMatrix | plotHeatmap | plotProfile |
values underlying the heatmap | --outFileNameMatrix |
yes | yes | no |
values underlying the profile | --outFileNameData |
no | yes | yes |
sorted and/or filtered regions | --outFileSortedRegions |
yes | yes | yes |
Tip
For more details on the optional output, see the examples for computeMatrix.
Usage examples¶
The following example creates a heatmap over hg19 transcripts for our test ENCODE datasets. Note that the matrix contains multiple groups of regions (in this case, one for each chromosome used).
# run compute matrix to collect the data needed for plotting
$ computeMatrix scale-regions -S H3K27Me3-input.bigWig \
H3K4Me1-Input.bigWig \
H3K4Me3-Input.bigWig \
-R genes19.bed genesX.bed \
--beforeRegionStartLength 3000 \
--regionBodyLength 5000 \
--afterRegionStartLength 3000
--skipZeros -o matrix.mat.gz
$ plotHeatmap -m matrix.mat.gz \
-out ExampleHeatmap1.png \
As mentioned above, plotHeatmap
has many options, including the ability to do k-means clustering and change the color map.
$ plotHeatmap -m matrix_two_groups.gz \
-out ExampleHeatmap2.png \
--colorMap RdBu \
--whatToShow 'heatmap and colorbar' \
--zMin -3 --zMax 3 \
--kmeans 4
Tip
More examples can be found in our Gallery.
Multiple colors for heatmaps¶
Since deepTools version 2.3 it is now possible to adjust the color and scale of each heatmap. There are two ways to adjust the colors, one by specifying each of the colormaps (e.g. –colorMap RdBlGr winter terrain) and the other is by giving each of the colors in the heatmap (e.g. –colorList ‘red,blue’ ‘white,green’, ‘white, blue, red’). For the second example, the number of transitions between the colors is given by the –colorNumber which by default is 256.
The following is an example using the –colorList method is used. Also the scale of each heatmap is modified using –zMin and –zMax.
$ plotHeatmap -m matrix_two_groups.gz \
-out ExampleHeatmap3.png \
--colorList 'black, yellow' 'white,blue' '#ffffff,orange,#000000'
--whatToShow 'heatmap and colorbar' \
--zMin -2 -2 0 --zMax 2 2 3
--kmeans 4
--dpi 100
No box around heatmaps¶
In version 2.3 we also added the option to remove the box around heatmaps. In the following example we combine different colormap colors, different scales and the new –boxAroundHeatmaps option.
$ plotHeatmap -m matrix_two_groups.gz \
-out ExampleHeatmap4.png \
--colorMap Oranges_r Blues_r Greens
--whatToShow 'heatmap and colorbar' \
--zMin -4 -4 0 --zMax 0 0 5
--kmeans 4
--dpi 100
--boxAroundHeatmaps no
Tip
More examples can be found in our Gallery.
deepTools Galaxy. | code @ github. |