View License

Download apps, toolboxes, and other File Exchange content using Add-On Explorer in MATLAB.

» Watch video

Highlights from
Customizable Heat Maps

4.9 | 33 ratings Rate this file 134 Downloads (last 30 days) File Size: 1.17 MB File ID: #24253 Version:
image thumbnail

Customizable Heat Maps


Ameya Deoras (view profile)


24 May 2009 (Updated )

Visualize data as a heatmap with many customizable options.

| Watch this File

File Information

********** Updated for 2014b *********
HEATMAP displays a matrix as an image whose color intensities reflect the magnitude of its values. In addition, it enables you to specify the following properties:
* X- and Y-axes tick labels:
Display the row/column indices or any other numeric or text labels. X-axis tick labels can even be rotated.
* Text labels:
Overlay the heatmap image with formatted text labels. The text labels can be derived from the original numeric matrix or a different matrix or cell array for displaying another dimension of data. You can control the font size and font color of the labels. The labels update automatically with zooming, panning or resizing the figure.

* Custom color maps:
Use MATLAB's default color maps or specify your own. The function provides two additional color maps - "money" (shown in the example image) and "red" (a color map of red color intensities). Specify Linear or Logarithmic color maps and the number of color levels. You can even use different color maps for different heat maps within a figure.

* Other configurable parameters such as grid lines, color bars.

For detailed examples, see the associated document heatmap_examples.m

NOTE: If using rotated tick labels, HEATMAP will resize the axes to make room for the tick labels. When overwriting existing heatmap plots with a new heatmap, use CLF to first clear the figure. See heatmap_examples for an illustration.


This file inspired An Introduction To Dataset Arrays, Credit Risk Modeling With Matlab, Natural Gas Storage Valuation, Steamgraph, and Scattertext.

Required Products MATLAB
MATLAB release MATLAB 7.8 (R2009a)
MATLAB Search Path
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (49)
22 Dec 2016 Salomon Muller

Notice the row values are flipped [relative to the default HeatMap function]. i.e. row 1 is shown on top rather than at the bottom.

Comment only
09 Aug 2016 Shay Ben-Sasson


03 Aug 2016 Audrey Cheong

Thanks for posting! Very helpful!

06 Jan 2016 Timothy Purwin

02 Sep 2015 cheng joylin

25 Jun 2015 cmo

cmo (view profile)

multi-line titles get cut-off. is there a way to include a multi-line string as a title?

02 Jun 2015 cmo

cmo (view profile)

18 May 2015 cmo

cmo (view profile)

for larger matrices (e.x. 7 x 34), the text does not show up in each cell, even if "textmat" == 1

14 May 2015 cmo

cmo (view profile)

11 May 2015 cmo

cmo (view profile)

GREAT function.
Much better than Matlab's implementation.

A couple of problems I noticed:
1) 'UseFigureColorMap' does not extend to Colorbars. Thus, while I can choose to "hard-code" the heatmap's colors, the corresponding colorbar still follows the general figure's colorbar.

12 Feb 2015 gabs

gabs (view profile)

Someone help; why can't I view any heatmaps when I run the examples?

Comment only
04 Feb 2015 arnold

arnold (view profile)

something else that just caught my eye: Is there a possibility to easily set the colorbar label when one does NOT use labels in the heat map?

Secondly: It would also be very nice to find a replacement for 'xor' Textcolor.

Third: It would be cool if text labels of 'nan' fields could simply be left out instead of saying 'nan'

Comment only
30 Jan 2015 Edward Zhao

04 Nov 2014 Alexander Stepanov

There's also a bug in @getGraphicsObjectsPositions. If there's only one column in a heatmap (i.e. one column label), then "extents" is not a cell array. So you need to add the following check in two corresponding places where it is being used as a cell array:

if iscell(extents)
extents = vertcat(extents{:}); % Collect heights in one matrix

Comment only
03 Nov 2014 Alexander Stepanov

And another small issue: you should not rely on the fact that axes are the current axes. Specifically, all the calls to @colorbar, such as the one below, should specify axes through 'peer' property:

c = colorbar(p.Colorbar{:});
% should be
c = colorbar(p.Colorbar{:}, 'peer', p.hAxes);
% etc

Comment only
03 Nov 2014 Alexander Stepanov

To clarify, I made the following changes:

% in parseInputs():

% in setAxesTickLabels():
if ~isequal(p.YTick, 'NOT_SET')
ytick = p.YTick;
ytick = get(p.hAxes, 'YTick');
% and the same for XTick

Also, adjustAxesToAccommodateTickLabels() throws an exception when you pass empty hXText to it (that happens if you set 'XTick' to []). So I had to add the following to the beginning of this function:

if isempty(hXText)

Comment only
03 Nov 2014 Alexander Stepanov

Great utility, thanks!

One thing it still does not allow you to do, is set custom ticks on x/y axis. If there are too many ticks, you cannot use 'ShowAllTicks' option, and the ticks Matlab chooses by default may not be the ones you actually want. Essentially I had to modify the function to add two optional key-value parameters: 'XTick' and 'YTick' (the change is trivial, but would be nice to see it in the official version)

And another minor thing: when using it to plot correlations, you generally want your axes to be square, so I always end up adding the following line after using @heatmap:
set(axh, 'DataAspectRatio', [1 1 1]);
Would be nice if @heatmap accepted a flag and did it automatically if requested

03 Oct 2014 Paul

Paul (view profile)

Same comment as arnold. Textcolor 'xor' does not work with R2014b for the 'R2014b graphics ready' version, toolbox nor zip downloads as updated 3 Oct 2014. I note that 'erasemode' 'xor' is still in the code of the zipped package. Otherwise excellent!

05 Sep 2014 arnold

arnold (view profile)


The textcolor 'xor' property does not work for me. It looks odd when rendered but when I try to save the figure as pdf, jpg or some other image format, all the text returns to black thus unreadable if the colormap has very dark values in some areas.

Comment only
25 Jul 2014 Franck Dernoncourt

Great function!

One issue on R2014a :
load heatmapData


Error using hg.axes/set
The name 'TickLabelInterpreter' is not an accessible property for an instance of class 'axes'.


comment out line 331 in heatmap.m:

% set(p.hAxes,'TickLabelInterpreter','none');

25 Jul 2014 Franck Dernoncourt

11 Jun 2014 Andre

Andre (view profile)

Thank you very much for this awesome function!
But I'm actually having a problem with the min/max color value of the ColorBar. When I try the following code:

h = heatmap(x, [], [],'%0.4f', 'Colorbar', true, 'MinColorValue', 0.0, 'MaxColorValue', 1.0, 'Colormap', 'autumn', 'Colorlevels', 10, 'Gridlines', '-', 'FontSize', 15, 'UseFigureColormap', false);

It returns an error:
Subscript indices must either be real positive integers or logicals.

Error in heatmap>plotHeatmap (line 235)
p.cdata = reshape(p.Colormap(p.cdata(:),:),[size(p.cdata) 3]);
Error in heatmap (line 128)
p = plotHeatmap(p, mat); % New properties hImage and cdata added

And plots nothing. Am I doing something wrong?

Comment only
30 Apr 2014 Jong-Hwan Kim

Jong-Hwan Kim (view profile)

Awesome!! better than built-in HeatMap function in Matlab. Thanks.

17 Mar 2014 arnold

arnold (view profile)


nice improvements. I got one big problem with the colorbar:
How do I set a ylabel to the colorbar?

Another idea for NaNs would be to just leave out the text "NaN" as well, simply don't show any text in those fields.

Something else I thought of:
the y-labels of the colorbar are always set automatically (or is there a way I don't see?). One tick is close to the top, as it should be, yet there is no label close to the bottom of the colorbar. This is not nice. They should be evenly spread across the colorbar with one close to the top value and one close to the bottom value. :)

Comment only
15 Feb 2014 Ameya Deoras

Ameya Deoras (view profile)

Karin, thanks for catching that oversight. Jonathan, technically "iscellstr" is correct but since the text function allows empty numeric values as the string, I will change it to iscell.

The changes will be in today's update. Thanks!

Comment only
15 Feb 2014 Patrick Anderson

This is an excellent utility and I appreciate the effort of the creator Ameya Deoras.

I had only minor difficulties accessing the 'Xlabel' and similar attributes. Users should be aware that the "colormap" property is critical for proper visualization (as acknowledged by author).

10 Feb 2014 Anna

Anna (view profile)

Thanks Karin for your comment, it works!

09 Feb 2014 Jonathan

great function! very nice options.

small bug: on line 589,

iscellstr(textmat) should be iscell(textmat)

Comment only
24 Jan 2014 Karin

Karin (view profile)

Hi, It is a nice function and precisely what I needed. I also got the same error as Anna, but I think I solved it.

The function 'CreateXTicks' (line 359) needs 5 input arguments. If you look at line 349 these 5 input arguments are used: hXText = createXTicks(p.hAxes, p.TickAngle, xtick, xlab(xtick), p.TickTexInterpreter). However, if you look at line 512 only 4 input argumetents are used: axInfo.hXText = createXTicks(hAxes, p.TickAngle, xticks, xlabels(xticks)). If you put in p.TickTexInterpreter as 5th argument, no more errors!

Comment only
24 Jan 2014 Karin

Karin (view profile)

20 Jan 2014 Anna

Anna (view profile)

Hi, very nice function and useful updates, thank you. I still have a problem with tick labels though. Here is my command:

heatmap(results,window,labelROI,[], 'UseFigureColormap', false, 'NaNColor', [1 1 1], 'MinColorValue', -1, 'MaxColorValue', 1, 'Colorbar', true, 'Gridlines',':', 'ShowAllTicks',1, 'TickAngle', 90)

And this is the error:

Error using heatmap>createXTicks (line 364)
Not enough input arguments.

Error in heatmap>updateLabels (line 512)
axInfo.hXText = createXTicks(hAxes, p.TickAngle, xticks, xlabels(xticks));

Error in heatmap>resize (line 554)
updateLabels(hAxes(i), false);

Error using drawnow
Error while evaluating figure ResizeFcn

Can you help, please?
Thank you.

Comment only
12 Dec 2013 Ameya Deoras

Ameya Deoras (view profile)

Hi everyone. Thanks for the comments/feedback. I have updated the function with fixes and new features:
* It now correctly handles the labels for small matrices with labels.
* There are two options minColorLevel and maxColorLevel that allow you to specify how the data range maps to the color range. This is useful when comparing heatmaps and ensuring the same color-data mapping between heatmaps
* There is now a nanColor option that allows you to specify a special color for missing data elements.

Comment only
20 Sep 2013 Julian

Julian (view profile)

this is an excellent contribution which I am finding most useful. Thanks.

16 Sep 2013 arnold

arnold (view profile)

Hi, nice function.

There seems to be a problem though with the labeling. In case of a small input-matrix (i.e. 5x5), one has to set "ShowAllTicks=1" otherwise the function will give an error when you also provide labels:
Subscript indices must either be real positive integers or logicals.

Error in heatmap2>setAxesLabels (line 280)

Error in heatmap2 (line 111)
[p, xlab, ylab, hXText] = setAxesLabels(p, xlab, ylab);

try it :)

Comment only
10 Sep 2013 Yair A

Yair A (view profile)

23 Aug 2013 Yongqiang Zhou

01 May 2013 Maxim

Maxim (view profile)

Wow! Where I've been all this time! Thanks a lot.

29 Apr 2013 Jonathan W

Excellent script. I have a question. Is there a way to color only certain values? Say, between 0 and 0.001 have one color, between 0.001 and 0.01 a different color, between 0.01 and 0.05 a different color, and everything else appear as white/blank? Thanks for your help.

20 Apr 2013 Yilong Jia

02 Mar 2013 Tung Le

Thanks for the code. It's very helpful.

I have a question. I want to plot two different heat maps but using the same color range so that one can compare them qualitatively. Is there anyway to do that with this code?
Thank you.

10 Jan 2013 Franck Dernoncourt

Just one small detail: if the matrix has a dimension < 7 and that we don't set 'ShowAllTicks', true, it might screw the labels due to (heatmap.m)

if p.ShowAllTicks
xtick = 1:length(xlab);
xtick = get(p.hAxes, 'XTick');

> xtick = get(p.hAxes, 'XTick'); can return a larger array than xlab, thereby exploding at xlab(xtick).

Same for y I guess.

02 Jan 2013 Kevin

Kevin (view profile)

A very nice application of heat maps that can be used to quickly integrate heat maps into a project. Great work and thanks for sharing.

17 Jul 2012 Paul

Paul (view profile)

11 Jul 2012 Jessica Lam

25 May 2012 Shaohan Hu

29 Feb 2012 Sergio

Sergio (view profile)

Very useful tool to give the wow factor for presentations of data. Enables the creation of heat maps very quickly.

25 Feb 2012 Bayes Zhang

29 Dec 2011 Syed Abbas

Great! Very helpful

15 Feb 2010 Gareth Thomas

Very nice:) I found it very useful

Comment only
21 Dec 2011 1.1

Major update. New features include:
* Text labels correctly update when figure is zoomed, panned or resized
* X tick labels can be rotated
* Show all or a subset of tick labels for large matrices

12 Dec 2013 1.2

Bug fixes and a few more optional parameters added

02 Jan 2014 1.3

Added copyright notices

19 Feb 2014 1.4

Minor bug fixes

03 Oct 2014 1.5

Compatible with 2014b. Some new capabilities like controlling the number of ticks, handling NaN's and setting minimum and maximum color levels

01 Sep 2016

Updated license

Contact us