In jbengler/bro: bro's little helpers

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The goal of bro_plot_heatmap() is to provide a tidyverse-style interface to the powerful heatmap package pheatmap by \@raivokolde. Although heatmaps can be generated via ggplot2::geom_tile(), it is hard to reach the versatility and beauty of a genuine heatmap function like pheatmap::pheatmap().

library(tidyverse)
library(bro)

Data requirements

bro_plot_heatmap() requires tidy data in long format, see tidyverse.

As an example we will use the gene expression data set bro_data_exprs. In the tidyverse lingo the columns of a data frame are called variables. One of these variables named expression contains the numeric values to be color-coded in the heatmap. Furthermore we will use the variables sample for heatmap columns and external_gene_name for heatmap rows.

bro_data_exprs

glimpse(bro_data_exprs)

Basic usage

The basic layout of the heatmap relies on the parameters rows, columns and values. You can think of them like aesthetics in ggplot2::ggplot(), similar to something like aes(x = columns, y = rows, fill = values).

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression
)

Features

Data scaling

With the parameter scale you can activate data scaling for "row" or "column". By default data scaling is turned off scale = "none".

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 scale = "row"
)

Ordering

Rows and columns in the heatmap will appear in the same order as in the tidy data frame used as input. For example, to order rows and columns alphabetically, just use the dplyr::arrange().

bro_data_exprs %>% 
  arrange(external_gene_name, sample) %>% 
  bro_plot_heatmap(rows = external_gene_name,
                   columns = sample,
                   values = expression,
                   scale = "row"
)

Color legend

You can customize the number of colors color_scale_n and also the minimum and maximum values of the color legend, color_scale_min and color_scale_max.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2
)

Of course, you can also replace the color legend altogether.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 scale = "row",
                 color = c("#161523","#1C1E4C","#2D3679","#3B4D98","#49569F","#69549D",
                           "#855097","#9E4F96","#CA5296","#DC5F8E","#E17872","#E58D63",
                           "#EDA962","#F5CA66","#F9E96C","#EEE969")
)

Annotations

Annotations can be added for both rows and columns via ann_row and ann_col, respectively. Just specify the corresponding variables in the tidy data frame. If you want more then one variable for annotation just combine them by c(var1, var2, var3).

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2
)

Customize annotations colors

You can provide a list of named vectors to take control over the annotations colors ann_colors.

ann_colors <- list(
  condition = c(EAE = "#BD79B4", healthy = "#F5CEF2"),
  group = c(Ein = "#C14236", Eip = "#E28946", Hin = "#4978AB", Hip = "#98BB85"),
  sample_type = c(input = "#BDBDBD", IP = "#7D7D7D"),
  direction = c(down = "#5071DC", up = "#C34B6B"),
  is_immune_gene = c(yes = "#B69340", no = "#FFFFFF")
)

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2,
                 ann_colors = ann_colors
)

Gaps

Gaps can be added by specifying data frame variables that should be used to generate the gaps. Only one variable can be chosen for gaps_row and one for gaps_col.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2,
                 ann_colors = ann_colors,
                 gaps_row = direction,
                 gaps_col = group
)

Fix cell dimensions

You can fix the cell dimensions via the cellwidth and cellheight parameters.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2,
                 ann_colors = ann_colors,
                 gaps_row = direction,
                 gaps_col = group,
                 cellwidth = 7,
                 cellheight = 7
)

Write to file

You can use the parameter filename to write the heatmap to file.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 filename = "my_heatmap.pdf"
)

More features

There are even more features like clustering and dendrograms implemented in pheatmap::pheatmap(). All parameters that are not directly evaluated by bro_plot_heatmap() will be automatically passed to pheatmap::pheatmap().

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 scale = "row",
                 color_scale_n = 16,
                 color_scale_min = -2,
                 color_scale_max = 2,
                 ann_colors = ann_colors,
                 cellwidth = 7,
                 cellheight = 7,
                 cluster_rows = TRUE,
                 cluster_cols = TRUE
)

What's under the hood?

bro_plot_heatmap() takes the tidy data frame and the additional arguments and does the data wrangling needed to satisfy pheatmap::pheatmap(). By setting return_data = TRUE you can get a glimpse at the result of the data wrangling.

bro_plot_heatmap(bro_data_exprs,
                 rows = external_gene_name,
                 columns = sample,
                 values = expression,
                 ann_col = c(sample_type, condition, group),
                 ann_row = c(is_immune_gene, direction),
                 gaps_row = direction,
                 gaps_col = group,
                 return_data = TRUE
)

jbengler/bro documentation built on Aug. 1, 2023, 9:09 a.m.