Interactive Cluster Heat Maps Using 'plotly' and 'ggplot2'

Create interactive cluster 'heatmaps' that can be saved as a stand- alone HTML file, embedded in 'R Markdown' documents or in a 'Shiny' app, and available in the 'RStudio' viewer pane. Hover the mouse pointer over a cell to show details or drag a rectangle to zoom. A 'heatmap' is a popular graphical method for visualizing high-dimensional data, in which a table of numbers are encoded as a grid of colored cells. The rows and columns of the matrix are ordered to highlight patterns and are often accompanied by 'dendrograms'. 'Heatmaps' are used in many fields for visualizing observations, correlations, missing values patterns, and more. Interactive 'heatmaps' allow the inspection of specific value by hovering the mouse over a cell, as well as zooming into a region of the 'heatmap' by dragging a rectangle around the relevant area. This work is based on the 'ggplot2' and 'plotly.js' engine. It produces similar 'heatmaps' to 'heatmap.2' with the advantage of speed ('plotly.js' is able to handle larger size matrix), the ability to zoom from the 'dendrogram' panes, and the placing of factor variables in the sides of the 'heatmap'.

Build Status CRAN_Status_Badge

Table of contents:

Screenshot demo


A heatmap is a popular graphical method for visualizing high-dimensional data, in which a table of numbers are encoded as a grid of colored cells. The rows and columns of the matrix are ordered to highlight patterns and are often accompanied by dendrograms. Heatmaps are used in many fields for visualizing observations, correlations, missing values patterns, and more.

Interactive heatmaps allow the inspection of specific value by hovering the mouse over a cell, as well as zooming into a region of the heatmap by dragging a rectangle around the relevant area.

This work is based on the ggplot2 and plotly.js engine. It produces similar heatmaps as d3heatmap (or the static heatmap.2 from gplots), with the advantage of more features such as speed (plotly.js is able to handle larger size matrix), sidebar annotation, and the ability to zoom from the dendrogram.

Please submit features requests

This package is still under active development. If you have features you would like to have added, please submit your suggestions (and bug-reports) at:

Latest news

You can see the most recent changes to the package in the file

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.


To install the stable version on CRAN:


To install the latest ("cutting-edge") GitHub version run:

# good packages to install for this to work smoothly:
# You'll need devtools
install.packages.2 <- function (pkg) if (!require(pkg)) install.packages(pkg);
# make sure you have Rtools installed first! if not, then run:
#install.packages('installr'); install.Rtools()
devtools::install_github("ropensci/plotly") # you will probably benefit from the latest version of plotly

And then you may load the package using:



Quick example:

heatmaply(mtcars, k_row = 3, k_col = 2)

For more (interactive) examples see the online vignette on CRAN

There are also more complex biological examples of using heatmaply in the R package heatmaplyExamples (hosted on github). Here are direct links for available examples:

Saving your heatmaply into a file

You can save an interactive version of your heatmaply into an HTML file using the following code:

heatmaply(mtcars, file = "folder/heatmaply_plot.html")

Similar code can be used for saving a static file (png/jpeg/pdf)

# Before the first time using this code you may need to first run:
# webshot::install_phantomjs()
heatmaply(mtcars, file = "folder/heatmaply_plot.png")


This package is thanks to the amazing work done by MANY people in the open source community. Beyond the many people working on the pipeline of R, thanks should go to the people working on ggplot2 (Hadley Wickham, etc.) and plotly (Carson Sievert, etc.). Also, many of the design elements were inspired by the work done on heatmap, heatmap.2 and d3heatmap, so special thanks goes to the R core team, Gregory R. Warnes, and Joe Cheng from RStudio. The dendrogram side of the package is based on the work in dendextend, in which special thanks should go to Andrie de Vries for his original work on bringing dendrograms to ggplot2 (which evolved into the richer ggdend objects, as implemented in dendextend).

The work on heatmaply was done by Tal Galili, Alan O'Callaghan, and Jonathan Sidi (mostly on shinyHeatmaply).

Funding: This work was supported in part by the European Union Seventh Framework Programme (FP7/2007-2013) under grant agreement no. 604102 (Human Brain Project).

How to cite the heatmaply package

The methods within the package can be cited as:

Tal Galili, Alan O'Callaghan, Jonathan Sidi, Carson Sievert; heatmaply: an R package for creating
interactive cluster heatmaps for online publishing, Bioinformatics, , btx657,

A BibTeX entry for LaTeX users is

  author = {{Galili} and {Tal} and {O'Callaghan} and {Alan} and {Sidi} and {Jonathan} and {Sievert} and {Carson}},
  title = {heatmaply: an R package for creating interactive cluster heatmaps for online publishing},
  journal = {Bioinformatics},
  year = {2017},
  doi = {10.1093/bioinformatics/btx657},
  url = {},
  eprint = {},

This free open-source software implements academic research by the authors and co-workers. If you use it, please support the project by citing the appropriate journal articles.


You are welcome to:


heatmaply 0.16.0 (2019-05-10)


  • heatmaply
    • The boolean argument dend_hoverinfo can control whether hoverinfo is shown for the row and column dendrograms.


  • heatmaply
    • Supplying label_names could cause incorrect orientation of side colors
    • Using plot_method="plotly" could cause incorrect interpretation of colour strings.
    • custom_hovertext did not work when plot_method="plotly"
    • Remove collaborate option internally (would cause warnings to be issued)


  • heatmaply
    • Use plotly::orca for saving to file, rather than plotly::export
  • Alan O'Callaghan is now recognized in the DESCRIPTION as a co-author of the package, in recognition to his significant (continuous) contribution to the package and the community. Thanks for everything Alan!

heatmaply 0.15.2 (2018-07-06)


  • heatmaply
    • labels did not show (only numbers)

heatmaply 0.15.0 (2018-06-23)


  • heatmaply
    • Side colour plot legends will now have the title of the column when there is only one column used.


  • heatmaply
    • heatmaply would scramble rownames when manually supplied via labrow or labcol
    • Minor bugfixes relating to the use of the node_size_mat argument.
    • handle cases with row/col names are not all unique. fix #155
    • resolve some test errors.

heatmaply 0.14.1 (2018-02-01)


  • heatmaply
    • hover text didn't show sometimes.
    • If custom_hovertext is not a matrix - it is turned into a matrix (important if inserting a data.frame). Fix issue #151

heatmaply 0.14.0 (2018-01-20)


  • heatmaply
    • Add custom_hovertext argument, adding custom hovertext option
    • Add label_format_fun argument, which formats text before adding to hovertext
    • Row and column annotation legends are now ordered according to factor levels, or by default, are sorted (the previous default behavior).
    • Add node_type argument, which allows users to plot the heatmap with discs rather than squares. See also thepoint_size_mat` argument.
    • Add point_size_mat argument, which is mapped to point size when node_type="scatter". Also adds point_size_name argument, which is the name of this parameter in the heatmap hovertext.


  • heatmaply
    • Fixed a bug where column/row annotation legend labels would overlap when only two levels were present.


  • Using stylr to improve the readability of the R code.
  • Using devtools::spell_check() to spell check the doc.

heatmaply 0.13.0 (2017-11-11)


  • heatmaply
    • Add File size arguments (#114) - width / height
    • Allows use of Pearson, Spearman or Kendall correlation coefficient as a distance measure, by specifying distfun="pearson", distfun="spearman" or distfun="kendall". This corresponds to the use of distfun=function(x) as.dist(1 - cor(x))).


  • heatmaply
    • Scale before clustering #112 (fixes: Allow the dendrogram to use scaled data #111 )
    • stops heatmaply from crashing when using RGui (#121)
    • draw_cellnote = TRUE fails for matrix with NA (#123)

heatmaply 0.12.1 (2017-10-25)


  • heatmaply

    • removing tick labels with showticklabels now removes the ticks as well as the tick labels.
    • Prevent grid_gap warning (#105)
    • Add cellnote_size argument, controlling the font size of the cellnote.
  • ggplot_heatmap

    • now handles data.frame input


  • Added citation to the bioinformatics article! (

heatmaply 0.11.1 (2017-09-27)


  • heatmaply
    • side_color_layers argument, which allows the user to pass in ggplot functions which will be added to the side color plots.
    • row_side_palette and col_side_palette can now be named vectors of colors.
    • Improved test coverage.
    • Side color plots have better defaults colors, courtesy of RColorBrewer's qualitative color palettes.
    • file argument can now work with static file extensions such as png/jpeg/pdf (thanks to the webshot package). It is also now vectorized, allowing to pass things like: heatmaply(x, file = c("heatmaply_plot.html", "heatmaply_plot.png"))
    • added labRow, labCol - to stay backward compatible with gplots::heatmap.2


  • heatmaply
    • Improved side color plots when plot_method = "plotly", including improved positioning of legends.
    • grid_gap works when plot_method = "plotly"
    • file argument will now deal with names that includes folder names before the file name.
    • heatmaply.heatmapr() previously ignored row_side_colors and col_side_colors when passed to heatmapr() (issue #94)
    • Fix the scale of cexRow/cexCol to that of fontsize_row/col

heatmaply 0.10.1 (2017-05-27)


  • cool_warm - a new divergent color pallette (from blue to red) based on Kenneth Moreland's proposal in (Diverging color maps for scientific visualization." Advances in Visual Computing (2009)), provided by the user YAK in (, and which relies on code from the Rgnuplot package.


  • heatmaply
    • Add "auto" cellnote colouring, which predicts the luminosity of cells and switches between black and white text as appropriate, for readability
    • Add cellnote_textposition argument, which controls the justification of cellnote within a cell. See the plotly documentation for more details.
    • dendrogram parameter can now accept TRUE/FALSE as synonyms for "both"/"none".
      • showticklabels = c(TRUE, TRUE) - a 2d parameter to allow turning off of tick labels in the rows/columns - thus making the rendering of the plot much faster for larger matrix.
  • heatmaply_cor now uses cool_warm instead of RdBu.
  • Added a warning for when not using the latest ggplot version.


  • heatmaply
    • cellnote would previously not work with character matrices. This is now fixed.
    • heatmaply would formerly ignore colour functions when plot_method = "plotly"

heatmaply 0.9.2 (2017-05-05)


  • heatmaply
    • Fix subplot_width/subplot_height

heatmaply 0.9.1 (2017-04-14)

This release adds unit testing and code coverage to the heatmaply package. Users should not be affected, but this will hopefully accelerate development and reduce the occurrence of bugs.


  • heatmaply_na, heatmaply_cor - wrappers for heatmaply for exploring missing values patterns, and for correlation matrix.


  • heatmaply -
    • Use slightly more sensible default for heights (in line with widths in any case), and add subplot_widths and subplot_heights arguments for user customisation.
    • plot_method argument ("plotly" or "ggplot") which controls the underlying plot method used for dendrograms and the main heatmap. Currently there is some disparity between the features available in both methods but it is hoped this can be addressed. plotly will likely give higher performance for large matrices.
    • Row names of matrix are now shown when plot_method = "plotly". This functionality should also be added to the function whenplot_method = "ggplot"`, once changes are made to the plotly R package.
    • Add colorbar_len argument, which controls the fraction of the total height which the colorbar/color legend will take up.
    • Add colorbar_xpos, colorbar_ypos, to change the x and y position of the colorbar, in case the defaults are not suitable.
    • Add colorbar_xanchor, colorbar_yanchor arguments which control the anchoring points of the colorbar, relative to which the x and y position is applied ("left", "middle" and "right" for colorbar_xanchor, and "top", "middle" or "bottom" for colorbar_yanchor).
    • Allow for colorbar and side color legends to be displayed simultaneously when plot_method = "plotly"
    • Add long_data argumnet, which allows the user to use data in "long" format (eg,
    • Add label_names argument, which allows the user to specify names to replace "row" and "column" as the names of the mouseover co-ordinates.
    • Add "cellnote" functionality, allowing the display of text overlaid on the cells of the heatmap. Controlled by the draw_cellnote argument. Cellnote color can be controlled by the cellnote_color argument. It is hoped that with future versions of plotly, an outline can be added, in order to make text readable on any background.
    • Add fontsize_row and fontsize_col arguments to heatmaply, which control font size for row and column labels. cexRow and cexCol are aliases (in order to keep compatability with gplots::heatmap.2).
    • Add grid_gap argument. Default is 0, higher numbers influence the gap between cells, helping the user to identify distinct values/cells within the matrix.
  • heatmapr
    • Removed some unused arguments and code.
  • is.plotly - new function to check if an object is of class plotly or not.


  • heatmaply
    • Fix the cexRow and cexCol arguments, which were previously non-functional.
    • Fix a mistake in an object's check in ggplot_heatmap. Props to Hannes Becker ( The following no longer crashes heatmaply: library(heatmaply) df <- data.frame(1) heatmaply(mtcars)
    • Make sure limits work when NA are present.
    • Fix the error: "argument * matches multiple formal arguments" by adding an explicit "col" argument to heatmaply.


  • heatmaply
    • Added scale and na.rm arguments to the document.
    • Added seriate.
  • Cross-ref percentize and normalize.
  • Vignette
    • Re-organize sections
    • Adding a section on data transformation.
    • Fixing typos

heatmaply 0.8.2 (2017-03-20)


  • Remove temp files.
  • Fix missing import and two typos.

heatmaply 0.8.0 (2017-03-18)


  • heatmaply - * file parameter - allows to save a heatmaply plot as an HTML file. * Allow Rowv/Colv to also work for hclust (by turning them into a dendrogram). * Add examples to heatmaply's Rd and the vignette on using Rowv/Colv. * Added the parameters hclust_method, dist_method to allow a more refined control over dist and hclust functions which are creating the dendrograms. A user wanting an even more refined control should just supply dendrograms directly to Rowv and Colv. * Added the parameters: distfun_row, hclustfun_row, distfun_col, hclustfun_col. They allow a more refine control over the dendrograms of the rows/columns (without the user needing to create the dendrograms from scratch) * clean the modeBarButtons from irrelevent icons
    • RColorBrewer_colors - added colors to be available for the heatmap. The sequential palettes names are (less important since we have viridis): Blues BuGn BuPu GnBu Greens Greys Oranges OrRd PuBu PuBuGn PuRd Purples RdPu Reds YlGn YlGnBu YlOrBr YlOrRd The diverging palettes are: BrBG PiYG PRGn PuOr RdBu RdGy RdYlBu RdYlGn Spectral


  • heatmaply -
    • make row_side_colors/col_side_colors work for vectors as well (by turning them to a data.frame). Fixes: Error in if (dim(row_side_colors)[1] != dim(x)[1]) stop("row_side_colors and x have different numbers of rows") : argument is of length zero

heatmaply 0.7.0 (2017-01-21)


  • heatmaply - * Non numeric columns are now added to row_side_colors, making heatmaply reasonably robust to heterogeneous data.frames. * main - a new parameter for setting the title of the plot. * the margins parameter now accepts 4 elements (previously it was only 2), for bottom, left, top (relevant for the plot's title) and right margins.
  • heatmapr - * Allow k_row and k_col to accept NA. This will pick the number of clusters using dendextend::find_k


  • percentize - a pre-processing function for performing the Empirical Percentile Transformation on a vector or data.frame.
  • normalize - a pre-processing function for adjusing the range of the variables to be from 0 to 1.
  • is.na10 - Indicates which elements are missing (either 1 and 0)

heatmaply 0.6.1 (2016-11-11)


  • Allow dendrogram parameter to work again.

heatmaply 0.6.0 (2016-11-05)


  • heatmaply - * added row_side_colors to allow non-numeric values in the sidebar of the heatmap, similar to RowSideColors in gplots::heatmap.2 (RowSideColors also works in heatmaply). Props goes to Alanocallaghan for his work on this. * added a proper margins parameter. * grid_color now works (thanks to a hack of using geom_hline and geom_vline instead of heom_tile(..., color) in ggplot_heatmap ) * added branches_lwd - to control the width of the dendrograms' width.

heatmaply 0.5.0 (2016-08-04)


  • is.heatmapr
  • ggheatmap - first try. (not working well enough yet. The proportions of the elements are not good)
  • heatmaply
    • key.title - a parameter to control the main title of the color key. (feature request by John Rizk)

heatmaply 0.4.0 (2016-07-15)


  • heatmaply
    • grid_color - control the color of the heatmap grid. This is currently not working until this feature will be added by plotly.
    • hover over dendrogram now returns the height.
    • colors can now also accept a function (and will use it to produce 256 colors)
  • heatmapr
    • seriate - character indicating the method of matrix sorting (default: "OLO"). This uses the seriation package.
    • srtRow, srtCol - add legacy support for these parameters (they are passed to row_text_angle and column_text_angle)
    • hide_colorbar - controls if the color bar should be hidden.
    • xlab, ylab - add titles to the x and y axis.

heatmaply 0.3.2 (2016-05-26)


  • heatmaply 0.3.2 - first CRAN release!


  • http -> https

heatmaply 0.3.1 (2016-05-26)


  • fix minor typos.

heatmaply 0.3.0 (2016-05-25)


  • heatmaply
    • Now works with Rowv=F and Colv=F (by introducing a new un-exported function: heatmap_subplot_from_ggplotly)
    • Remove space between the heatmap and dendrograms (via: coord_cartesian(expand = FALSE) and coord_flip(expand = FALSE))
    • Added the margin parameter (to control the distance between the heatmap and the dendrograms.)
    • Added row_text_angle and column_text_angle (with srtRow and srtCol for backward compatibility with gplots::heatmap.2). Fix #3


  • fix #2 : Error: Don't know how to add scale_fill_gradient_fun to a plot by moving "scale_fill_gradient_fun" after "..." (I may change this parameter's name later)


  • heatmaply now has a basic vignette.

heatmaply 0.2.1 (2016-05-23)


  • fix various import issues that caused warnings with devtools::check()

heatmaply 0.2.0 (2016-05-23)


  • More control over colors in heatmaply via the new parameters: colours, limits, na.value, and scale_colour_gradient_fun.
  • first attempts at row_dend_left (although this is not yet working.)


  • dendrograms are now presented without axes text.
  • passing scale (= "row" or "column") works again.

heatmaply 0.1.0 (2016-05-14)

  • First (very rough) version. It has a minimal working example, as well as MANY things to fix/tweak/adjust.


  • remove unneeded code from d3heatmap

  • add many options for controlling the heatmap "as it should be"

  • implement all relevant options streight to heatmaply.

  • ggheatmap?

  • Expose widths and heights from heatmap_subplot_from_ggplotly to heatmaply

  • write example for using seriation+dendextend for heatmaps.

  • Show the following example for using seriation:

require(seriation) require(dendextend)

"GW", "OLO"

d <- dist(USArrests[1:15,]) dend <- as.dendrogram(hclust(d, method = "ave")) par(mfrow = c(1,2)) plot(dend, main = "default")

seriate(cophenetic(dend), method = "OLO", control = list(hclust = as.hclust(dend)))

the downside in using cophenetic is that seriate has to go through running hclust all over again

but we'll just have to accept it...

o <- seriate(d, method = "GW", control = list(hclust = as.hclust(dend)) ) get_order(o) labels(cophenetic(dend))[get_order(o)] d2 <- rotate(dend, order = rev(labels(d)[get_order(o)])) plot(d2, main = "GW")

o <- seriate(d, method = "OLO", control = list(hclust = as.hclust(dend)) ) d3 <- rotate(dend, order = rev(labels(d)[get_order(o)]))

require(heatmaply) heatmaply(USArrests[1:15,], Rowv = d2) heatmaply(USArrests[1:15,], Rowv = d3) heatmaply(USArrests[1:15,], Rowv = dend)


identical(seriate(d, method = "OLO"), seriate(d, method = "OLO", control = list(hclust = as.hclust(dend)) )) get_order(seriate(d, method = "OLO")) get_order(seriate(d, method = "OLO", control = list(hclust = hclust(d, method = "sing")) )) # this works :)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.3.0 by Tal Galili, 10 days ago,,,

Report a bug at

Browse source code at

Authors: Tal Galili [aut, cre, cph] ( , Alan O'Callaghan [aut] ( , Jonathan Sidi [ctb] ( , Jaehyun Joo [ctb] ( , Yoav Benjamini [ths]

Documentation:   PDF Manual  

GPL-2 | GPL-3 license

Imports ggplot2, dendextend, magrittr, reshape2, scales, seriation, utils, stats, grDevices, methods, colorspace, RColorBrewer, htmlwidgets, webshot, assertthat, egg

Depends on plotly, viridis

Suggests knitr, covr, gplots, tidyselect, rmarkdown, testthat

Imported by BayesianNetwork, CALANGO, latentcor, neatmaps, pagoo, wilson.

Depended on by shinyHeatmaply.

Suggested by CNVScope, dendextend, protti.

See at CRAN