Overview of the tidyHeatmap package

Lifecycle:maturing DOI

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

website: stemangiola.github.io/tidyHeatmap

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

Advantages:

Functions/utilities available

Function | Description ------------ | ------------- heatmap | Plots base heatmap add_tile | Adds tile annotation to the heatmap add_point | Adds point annotation to the heatmap add_bar | Adds bar annotation to the heatmap add_line | Adds line annotation to the heatmap layer_point | Adds layer of symbols on top of the heatmap layer_square | Adds layer of symbols on top of the heatmap layer_diamond | Adds layer of symbols on top of the heatmap layer_arrow_up | Adds layer of symbols on top of the heatmap layer_arrow_down | Add layer of symbols on top of the heatmap split_rows | Splits the rows based on the dendogram split_columns | Splits the columns based on the dendogram save_pdf | Saves the PDF of the heatmap

Installation

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

Input data frame

The heatmaps visualise a multi-element, multi-feature dataset, annotated with independent variables. Each observation is a element-feature pair (e.g., person-physical characteristics).

element | feature | value | independent_variables ------------ | ------------- | ------------- | ------------- chr or fctr | chr or fctr | numeric | ...

Let's transform the mtcars dataset into a tidy "element-feature-independent variables" data frame. Where the independent variables in this case are 'hp' and 'vs'.

library(dplyr)
library(tidyr)
library(tidyHeatmap)
mtcars_tidy <- 
    mtcars %>% 
    as_tibble(rownames="Car name") %>% 

    # Scale
    mutate_at(vars(-`Car name`, -hp, -vs), scale) %>%

    # tidyfy
    pivot_longer(cols = -c(`Car name`, hp, vs), names_to = "Property", values_to = "Value")

mtcars_tidy

Plotting

For plotting, you simply pipe the input data frame into heatmap, specifying:

mtcars

mtcars_heatmap <- 
    mtcars_tidy %>% 
        heatmap(`Car name`, Property, Value ) %>%
        add_tile(hp)

mtcars_heatmap

Saving

mtcars_heatmap %>% save_pdf("mtcars_heatmap.pdf")

Grouping and splitting

We can easily group the data (one group per dimension maximum, at the moment only the vertical dimension is supported) with dplyr, and the heatmap will be grouped accordingly

mtcars_tidy %>% 
    group_by(vs) %>%
    heatmap(`Car name`, Property, Value ) %>%
    add_tile(hp)

We can provide colour palettes to groupings

mtcars_tidy %>% 
    group_by(vs) %>%
    heatmap(
        `Car name`, Property, Value ,
        palette_grouping = list(c("#66C2A5", "#FC8D62"))
    ) %>%
    add_tile(hp)

We can split based on the cladogram

mtcars_tidy %>% 
    heatmap(`Car name`, Property, Value ) %>%
    split_rows(2) %>%
    split_columns(2)

We can Split on kmean clustering (using ComplexHeatmap options, it is stokastic)

mtcars_tidy %>% 
    heatmap(
        `Car name`, Property, Value ,
        row_km = 2,
        column_km = 2
    ) 

Custom palettes

We can easily use custom palette, using strings, hexadecimal color character vector,

mtcars_tidy %>% 
    heatmap(
        `Car name`, 
        Property, 
        Value,
        palette_value = c("red", "white", "blue")
    )

A better-looking blue-to-red palette

mtcars_tidy %>% 
    heatmap(
        `Car name`, 
        Property, 
        Value,
        palette_value = circlize::colorRamp2(
            seq(-2, 2, length.out = 11), 
            RColorBrewer::brewer.pal(11, "RdBu")
        )
    )

Or a grid::colorRamp2 function for higher flexibility

mtcars_tidy %>% 
    heatmap(
        `Car name`, 
        Property, 
        Value,
        palette_value = circlize::colorRamp2(c(-2, -1, 0, 1, 2), viridis::magma(5))
    )

Multiple groupings and annotations

tidyHeatmap::pasilla %>%
    group_by(location, type) %>%
    heatmap(
            .column = sample,
            .row = symbol,
            .value = `count normalised adjusted`
        ) %>%
    add_tile(condition) %>%
    add_tile(activation)

Annotation types

This feature requires >= 0.99.20 version

"tile" (default), "point", "bar" and "line" are available

# Create some more data points
pasilla_plus <- 
    tidyHeatmap::pasilla %>%
        dplyr::mutate(act = 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`
        ) %>%
    add_tile(condition) %>%
    add_point(activation) %>%
    add_tile(act) %>%
    add_bar(size) %>%
    add_line(age)

Layer symbol

Add a layer on top of the heatmap

tidyHeatmap::pasilla %>%

    # filter
    filter(symbol %in% head(unique(tidyHeatmap::pasilla$symbol), n = 10)) %>%

    heatmap(
            .column = sample,
            .row = symbol,
            .value = `count normalised adjusted`
        ) %>% 
    layer_point(
        `count normalised adjusted log` > 6 & sample == "untreated3" 
    )

ComplexHeatmap further styling

Add cell borders

    mtcars_tidy %>% 
        heatmap(
            `Car name`, Property, Value, 
            rect_gp = grid::gpar(col = "#161616", lwd = 0.5)
        ) 

Drop row clustering

    mtcars_tidy %>% 
        heatmap(
            `Car name`, Property, Value, 
            cluster_rows = FALSE
        ) 


Try the tidyHeatmap package in your browser

Any scripts or data that you put into this service are public.

tidyHeatmap documentation built on July 7, 2021, 9:07 a.m.