Learn R Programming

The tidyHeatmap package

Stefano Mangiola 2025-01-26

tidyHeatmap is a package that introduces tidy principles to the creation of information-rich heatmaps. This package uses ComplexHeatmap as graphical engine.

Citation

Mangiola et al., (2020). tidyHeatmap: an R package for modular heatmap production based on tidy principles. Journal of Open Source Software, 5(52), 2472, https://doi.org/10.21105/joss.02472

Full documentation here

# Create some more data points
pasilla_plus <- 
	tidyHeatmap::pasilla |>
	dplyr::mutate(activation_2 = activation, activation_3 = activation) |> 
	tidyr::nest(data = -sample) |>
	dplyr::mutate(size = rnorm(n(), 4,0.5)) |>
	dplyr::mutate(age = runif(n(), 50, 200)) |>
	tidyr::unnest(data) 

# Plot
pasilla_plus |>
    heatmap(
        .column = sample,
        .row = symbol,
        .value = `count normalised adjusted`,   
        scale = "row"
    ) |>
    annotation_group(location) |>
    annotation_tile(condition, show_legend = FALSE) |>
    annotation_point(activation) |>
    annotation_numeric(activation_3) |>
    annotation_tile(activation_2) |>
    annotation_bar(size) |>
    annotation_line(age)

Advantages:

  • Modular annotation with just specifying column names
  • Custom grouping of rows/columns is easy to specify with annotation_group, e.g. heatmap(...) |> annotation_group(...)
  • Labels size adjusted by row and column total number
  • Default use of Brewer and Viridis palettes

Retrieve heatmap data and dendrograms

After creating a heatmap, you can extract the matrix and dendrograms exactly as they appear in the plot:

# Create heatmap
hm <- tidyHeatmap::N52 |>
  tidyHeatmap::heatmap(
    .row = symbol_ct,
    .column = UBR,
    .value = `read count normalised log`
  )

# Extract heatmap data as plotted
result <- hm |> get_heatmap_data()
ordered_matrix <- result$matrix        # Matrix with rows/columns in heatmap order
row_dendrogram <- result$row_dend      # Row dendrogram object
column_dendrogram <- result$column_dend # Column dendrogram object

# All have consistent row and column names
print(rownames(ordered_matrix))
print(labels(row_dendrogram))

Functions/utilities available

FunctionDescription
heatmapPlots base heatmap
annotation_groupAdds group annotation strips and grouping to the heatmap
annotation_tileAdds tile annotation to the heatmap
annotation_pointAdds point annotation to the heatmap
annotation_barAdds bar annotation to the heatmap
annotation_numericAdds bar + number annotation to the heatmap
annotation_lineAdds line annotation to the heatmap
layer_textAdd layer of text on top of the heatmap
layer_pointAdds layer of symbols on top of the heatmap
layer_squareAdds layer of symbols on top of the heatmap
layer_diamondAdds layer of symbols on top of the heatmap
layer_arrow_upAdds layer of symbols on top of the heatmap
layer_arrow_downAdd layer of symbols on top of the heatmap
layer_starAdd layer of symbols on top of the heatmap
layer_asteriskAdd layer of symbols on top of the heatmap
split_rowsSplits the rows based on the dendogram
split_columnsSplits the columns based on the dendogram
get_heatmap_dataRetrieves matrix and dendrograms exactly as plotted
save_pdfSaves the PDF of the heatmap
+Integrate heatmaps side-by-side
as_ComplexHeatmapConvert the tidyHeatmap output to ComplexHeatmap for non-standard "drawing"
wrap_heatmapAllows the integration with the patchwork package

Installation

To install the most up-to-date version

devtools::install_github("stemangiola/tidyHeatmap")

To install the most stable version (however please keep in mind that this package is under a maturing lifecycle stage)

install.packages("tidyHeatmap")

Contribution

If you want to contribute to the software, report issues or problems with the software or seek support please open an issue here

Copy Link

Version

Install

install.packages('tidyHeatmap')

Monthly Downloads

1,476

Version

1.12.2

License

GPL-3

Issues

1

Pull Requests

1

Stars

345

Forks

25

Maintainer

Stefano Mangiola

Last Published

July 22nd, 2025

Functions in tidyHeatmap (1.12.2)

get_sample_counts

Get column names either from user or from attributes
annotation_bar

Adds a bar annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
drop_class

Remove class to abject
error_if_log_transformed

Check whether a numeric vector has been log transformed
get_x_y_annotation_columns

get_x_y_annotation_columns
heatmap

Creates a `InputHeatmap` object from `tbl_df` on evaluation creates a `ComplexHeatmap`
parse_formula

.formula parser
scale_robust

Scale counts in a robust way against sd == 0
wrap_heatmap

Wrap tidyHeatmap (ComplexHeatmap) in a patchwork-compliant patch
get_elements_features_abundance

Get column names either from user or from attributes
layer_text

Adds a layers of texts above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
save_pdf

Save plot on PDF file
get_elements_features

Get column names either from user or from attributes
save_pdf,Heatmap-method

save_pdf
save_pdf,InputHeatmap-method

save_pdf
split_rows

Split the heatmap row-wise depending on the biggest branches in the cladogram.
get_sample_transcript_counts

Get column names either from user or from attributes
get_sample_transcript

Get column names either from user or from attributes
select_closest_pairs

Sub function of remove_redundancy_elements_though_reduced_dimensions
input_heatmap

input_heatmap
layer_arrow_down

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
ifelse_pipe

This is a generalisation of ifelse that accepts an object and return an objects
layer_point

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
layer_diamond

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
prepend

From rlang deprecated
quo_names

Convert array of quosure (e.g. c(col_a, col_b)) into character vector
+.InputHeatmap

Add two tidyHeatmap objects together
layer_arrow_up

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
layer_asterisk

Adds a layer of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
pasilla

Example data set Pasilla
layer_square

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
layer_star

Adds a layer of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
add_class

Add class to abject
annotation_point

Adds a point annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
annotation_line

Adds a line annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
annotation_numeric

Adds a numeric annotation layer to an `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
N52

Example data set N52
annot_to_list

annot_to_list
add_annotation

add_annotation
annotation_group

Add group annotation strips to a tidyHeatmap
add_attr

Add attribute to abject
get_abundance_norm_if_exists

Get column names either from user or from attributes
as_ComplexHeatmap

Creates a `ComplexHeatmap` object for less standard plot manipulation (e.g. changing legend position)
check_if_wrong_input

Check whether there are NA counts
annotation_tile

Adds a tile annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
get_elements

Get column names either from user or from attributes
check_if_duplicated_genes

Check whether there are duplicated genes/transcripts
as_matrix

Get matrix from tibble
check_if_counts_is_na

Check whether there are NA counts
get_heatmap_data

Retrieve heatmap data and dendrograms as plotted
ifelse2_pipe

This is a generalisation of ifelse that accepts an object and return an objects