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

Please have a look also to

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_tile(condition) |>
	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 is easy to specify providing a grouped tbl. For example df |> group_by(...)
  • Labels size adjusted by row and column total number
  • Default use of Brewer and Viridis palettes

Functions/utilities available

FunctionDescription
heatmapPlots base heatmap
group_bydplyr function - groups heatpmap rows/columns
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
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,611

Version

1.11.6

License

GPL-3

Issues

8

Pull Requests

0

Stars

338

Forks

25

Maintainer

Stefano Mangiola

Last Published

February 8th, 2025

Functions in tidyHeatmap (1.11.6)

check_if_wrong_input

Check whether there are NA counts
get_sample_transcript_counts

Get column names either from user or from attributes
check_if_counts_is_na

Check whether there are NA counts
check_if_duplicated_genes

Check whether there are duplicated genes/transcripts
get_abundance_norm_if_exists

Get column names either from user or from attributes
layer_square

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

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

input_heatmap
ifelse_pipe

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

Get column names either from user or from attributes
get_sample_counts

Get column names either from user or from attributes
get_elements_features

Get column names either from user or from attributes
annotation_tile

Adds a tile annotation layer 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`
get_elements

Get column names either from user or from attributes
layer_diamond

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

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

Example data set Pasilla
prepend

From rlang deprecated
drop_class

Remove class to abject
save_pdf

Save plot on PDF file
save_pdf,InputHeatmap-method

save_pdf
scale_robust

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

Sub function of remove_redundancy_elements_though_reduced_dimensions
split_rows

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

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

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

get_x_y_annotation_columns
heatmap

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

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

Adds a layers of symbols above the heatmap tiles to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
save_pdf,Heatmap-method

save_pdf
layer_asterisk

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

.formula parser
layer_text

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

Add attribute to abject
add_line

DEPRECATED. Adds a line annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
annot_to_list

annot_to_list
add_tile

DEPRECATED. Adds a tile annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
N52

Example data set N52
add_bar

DEPRECATED. Adds a bar annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
add_point

DEPRECATED. Adds a point annotation layer to a `InputHeatmap`, that on evaluation creates a `ComplexHeatmap`
add_class

Add class to abject
add_annotation

add_annotation
as_matrix

Get matrix from tibble
annotation_bar

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

Get column names either from user or from attributes
annotation_numeric

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

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

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

Check whether a numeric vector has been log transformed
annotation_point

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