---
title: "Overview of the tidyHeatmap package"
author: "Stefano Mangiola"
date: "`r Sys.Date()`"
package: tidyHeatmap
output: "html_vignette"
params:
  demo_metadata: true
vignette: >
  %\VignetteIndexEntry{Overview of the tidyHeatmap package}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
knit: >
    (function(x, ...){
        proj_root <- rprojroot::find_package_root_file() |> normalizePath()
        rmarkdown::render(
            x,
            output_format = "html_document",
            params = list(
                demo_metadata = TRUE
            )
        )
    })
---

```{r setup, include=FALSE}

knitr::opts_chunk$set(
  dpi = 150,
  fig.retina = 1,
  dev = "png",
  dev.args = list(
    png = list(type = "cairo-png", antialias = "subpixel" )
  )
)

```

<!-- badges: start -->
[![Lifecycle:maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.02472/status.svg)](https://doi.org/10.21105/joss.02472)
<!-- badges: end -->

## 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

`tidyHeatmap` is a package that introduces tidy principles to the creation of information-rich heatmaps. 
This package uses [ComplexHeatmap](https://bioconductor.org/packages/release/bioc/html/ComplexHeatmap.html) as graphical engine.
website: [stemangiola.github.io/tidyHeatmap](https://stemangiola.github.io/tidyHeatmap/)

**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

## Functions/utilities available

Function | Description
------------ | -------------
`heatmap` | Plots base heatmap
`annotation_group` | Adds group annotation strips and grouping to the heatmap (replaces group_by)
`annotation_tile` | Adds tile annotation to the heatmap
`annotation_point` | Adds point annotation to the heatmap
`annotation_bar` | Adds bar annotation to the heatmap
`annotation_numeric` | Adds bar + number annotation to the heatmap
`annotation_line` | Adds line annotation to the heatmap
`layer_text` | Add layer of text on top of 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
`layer_star` | Add layer of symbols on top of the heatmap
`layer_asterisk` | 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
`+` | Integrate heatmaps side-by-side
`as_ComplexHeatmap` | Convert the tidyHeatmap output to ComplexHeatmap for non-standard "drawing"
`wrap_heatmap` | Allows the integration with the `patchwork` package


## Installation

To install the most up-to-date version

```{r install, eval=FALSE}

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)

```{r install2, eval=FALSE}

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](https://github.com/stemangiola/tidyHeatmap/issues)

## 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'.

```{r library, echo=FALSE, include=FALSE}
library(dplyr)
library(tidyr)
library(tidyHeatmap)
library(grid)
```

```{r setup data}
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:

- The rows, cols relative column names (mandatory)
- The value column name (mandatory)
- The annotations column name(s)

mtcars
```{r heatmap, fig.width=10, fig.height=10}
mtcars_heatmap <- 
	mtcars_tidy |> 
	heatmap(`Car name`, Property, Value,	scale = "row"	) |>
	annotation_tile(hp)

mtcars_heatmap
```

## Saving

```{r save, eval=F}
mtcars_heatmap |> save_pdf("mtcars_heatmap.pdf")
```

## Clustering

Choose alternative clustering distance and methods.

```{r distance, fig.width=10, fig.height=10}

tidyHeatmap::pasilla |>
	
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row",
		
		# Arguments passed to ComplexHeatmap 
		clustering_distance_rows = "manhattan",
		clustering_distance_columns = "manhattan",
		clustering_method_rows = "ward.D",
		clustering_method_columns = "ward.D"
	) 
```

## 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

```{r grouping, fig.width=10, fig.height=10}
# Make up more groupings
mtcars_tidy_groupings = 
	mtcars_tidy |>
	mutate(property_group = if_else(Property %in% c("cyl", "disp"), "Engine", "Other"))

mtcars_tidy_groupings |> 
	heatmap(`Car name`, Property, Value, scale = "row") |>
	annotation_group(vs, property_group) |>
	annotation_tile(hp)
```

You can provide colour palettes and other aesthetics to groupings

```{r grouping2, fig.width=10, fig.height=10}
mtcars_tidy_groupings |> 
	heatmap(
		`Car name`, Property, Value ,  
		scale = "row"
	) |>
	annotation_group(
		vs, property_group,
		palette_grouping = list(
			# For first grouping (vs)
			c("#66C2A5", "#FC8D62"), 
			# For second grouping (property_group)
			c("#b58b4c", "#74a6aa")
		),
		group_label_fontsize = 14,
		show_group_name = TRUE,
		group_strip_height = grid::unit(20, "pt")
	) |>
	annotation_tile(hp)
```

We can split based on the cladogram

```{r split, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(`Car name`, Property, Value,	scale = "row"	) |>
	split_rows(2) |>
	split_columns(2)
```

We can split on kmean clustering (using ComplexHeatmap options, it is stochastic)

```{r split2, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row",
		row_km = 2,
		column_km = 2
	) 
```


## Custom palettes

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

```{r custom, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, 
		Property, 
		Value,	
		scale = "row",
		palette_value = c("red", "white", "blue")
	)
```

A better-looking blue-to-red palette

```{r redblue, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, 
		Property, 
		Value,	
		scale = "row",
		palette_value = circlize::colorRamp2(
			seq(-2, 2, length.out = 11), 
			RColorBrewer::brewer.pal(11, "RdBu")
		)
	)

```

Or a grid::colorRamp2 function for higher flexibility

```{r flexible, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, 
		Property, 
		Value,	
		scale = "row",
		palette_value = circlize::colorRamp2(c(-2, -1, 0, 1, 2), viridis::magma(5))
	)
```

We can use custom colors for tile annotation 

```{r customtile, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, 
		Property, 
		Value,	
		scale = "row"
	) |>
	annotation_tile(
		hp, 
		palette = c("red", "white", "blue")
	)
```

We can use grid::colorRamp2 function for tile annotation for specific color scales

```{r customtile2, fig.width=10, fig.height=10}
mtcars_tidy |> 
	heatmap(
		`Car name`, 
		Property, 
		Value,	
		scale = "row"
	) |>
	annotation_tile(
		hp, 
		palette = circlize::colorRamp2(c(0, 100, 200, 300), viridis::magma(4))
	)
```

## Multiple groupings and annotations

```{r multiple, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,  
		scale = "row"
	) |>
	annotation_group(location, type) |>
	annotation_tile(condition) |>
	annotation_tile(activation)
```

Example with custom aesthetics for annotation_group

```{r multiple-aesthetics, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,  
		scale = "row"
	) |>
	annotation_group(
		location, type,
		group_label_fontsize = 12,
		group_strip_height = grid::unit(15, "pt"),
		show_group_name = FALSE
	) |>
	annotation_tile(condition) |>
	annotation_tile(activation)
```

Remove legends, adding aesthetics to annotations in a modular fashion, using `ComplexHeatmap` arguments

```{r nolegend, fig.width=10, fig.height=10}

tidyHeatmap::pasilla |>
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row",
		show_heatmap_legend = FALSE
	) |>
	annotation_tile(condition, show_legend = FALSE) |>
	annotation_tile(activation, show_legend = FALSE)
```

## Annotation types

"tile", "point", "bar", "line" and "numeric" are available

```{r manyannotations, fig.width=10, fig.height=10}
# 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)
```

## Annotation size 

We can customise annotation sizes using the `grid::unit()`, and the size of their names using in-built `ComplexHeatmap` arguments

```{r size, fig.width=10, fig.height=10}
pasilla_plus |>
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row"
	) |>
	annotation_tile(condition, size = unit(0.3, "cm"),	annotation_name_gp= gpar(fontsize = 8)) |>
	annotation_point(activation, size = unit(0.3, "cm"),	annotation_name_gp= gpar(fontsize = 8)) |>
	annotation_tile(activation_2, size = unit(0.3, "cm"),	annotation_name_gp= gpar(fontsize = 8)) |>
	annotation_bar(size, size = unit(0.3, "cm"),	annotation_name_gp= gpar(fontsize = 8)) |>
	annotation_line(age, size = unit(0.3, "cm"),	annotation_name_gp= gpar(fontsize = 8))
```

# Layer symbol

Add a layer on top of the heatmap

```{r layer, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	
	# filter
	filter(symbol %in% head(unique(tidyHeatmap::pasilla$symbol), n = 10)) |>
	
	# Add dynamic size
	mutate(my_size = runif(n(), 1,5)) |> 
	
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row"
	) |> 
	layer_point(
		`count normalised adjusted log` > 6 & sample == "untreated3"
	) |>
	layer_square(
		`count normalised adjusted log` > 6 & sample == "untreated2",
		.size = my_size
	) |>
	layer_arrow_up(
		`count normalised adjusted log` > 6 & sample == "untreated1",
		.size = 4
	)
```

## Complex layer symbol example with colors

Advanced example showing different symbols with custom colors and sizes

```{r layer-complex, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	
	# filter
	filter(symbol %in% head(unique(tidyHeatmap::pasilla$symbol), n = 10)) |>
	
	# Add dynamic color and size columns
	mutate(
		my_color = case_when(
			`count normalised adjusted log` > 7 ~ "#57fb77",
			`count normalised adjusted log` > 6 ~ "darkorange", 
			TRUE ~ "#fb7ef9"
		),
		my_size = runif(n(), 3, 8)
	) |> 
	
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row"
	) |> 
	layer_point(
		`count normalised adjusted log` > 6 & sample == "untreated3",
		.color = "red",
		.size = 5
	) |>
	layer_diamond(
		`count normalised adjusted log` > 6 & sample == "untreated1",
		.color = "green",
		.size = 6
	) |>
	layer_star(
		`count normalised adjusted log` > 7,
		.color = "purple",
		.size = 4
	) |>

	# Dynamically color and size
	layer_square(
		`count normalised adjusted log` > 6 & sample == "untreated2",
		.color = my_color,
		.size = my_size
	)
```


# Layer text

Add a text layer on top of the heatmap

```{r layertext, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	
	# filter
	filter(symbol %in% head(unique(tidyHeatmap::pasilla$symbol), n = 10)) |>
	
	# Add dynamic text
	mutate(my_text = "mt", my_size = 7) |> 
	
	# Plot
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row"
	) |> 
	layer_text(
		`count normalised adjusted log` > 6 & sample == "untreated3", 
		.value = "a", 
		.size = 15
	) |> 
	layer_text(
	`count normalised adjusted log` > 6 & sample == "untreated2", 
	.value = my_text,
	.size = my_size
)
```

## Complex layer text example with colors

Advanced example showing text layers with custom colors, sizes, and dynamic content

```{r layertext-complex, fig.width=10, fig.height=10}
tidyHeatmap::pasilla |>
	
	# filter
	filter(symbol %in% head(unique(tidyHeatmap::pasilla$symbol), n = 10)) |>
	
	# Add dynamic text content and styling
	mutate(
		text_content = case_when(
			`count normalised adjusted log` > 7 ~ "***",
			`count normalised adjusted log` > 6 ~ "**", 
			`count normalised adjusted log` > 5 ~ "*",
			TRUE ~ ""
		),
		text_color = case_when(
			`count normalised adjusted log` > 7 ~ "darkred",
			`count normalised adjusted log` > 6 ~ "darkorange", 
			`count normalised adjusted log` > 5 ~ "darkgreen",
			TRUE ~ "darkgray"
		),
		text_size = case_when(
			`count normalised adjusted log` > 7 ~ 12,
			`count normalised adjusted log` > 6 ~ 10, 
			`count normalised adjusted log` > 5 ~ 8,
			TRUE ~ 6
		)
	) |> 
	
	heatmap(
		.column = sample,
		.row = symbol,
		.value = `count normalised adjusted`,	
		scale = "row"
	) |> 
	layer_text(
		`count normalised adjusted log` > 6 & sample == "untreated3", 
		.value = "HIGH",
		.color = "red",
		.size = 12
	) |> 
	layer_text(
		`count normalised adjusted log` > 5 & sample == "untreated1", 
		.value = "↑",
		.color = "blue",
		.size = 10
	) |>

	# Dynamically set text content, color and size
	layer_text(
		`count normalised adjusted log` > 6 & sample == "untreated2", 
		.value = text_content,
		.color = text_color,
		.size = text_size
	)

```

# Adding heatmap side-by-side

```{r sidebyside, warning=FALSE, fig.width=10, fig.height=6}

p_heatmap = heatmap(mtcars_tidy, `Car name`, Property, Value, scale = "row") 

p_heatmap + p_heatmap 

```

Add more than two heatmaps

> **Note:**
> 
> Due to limitations in R's method dispatch, adding more than two tidyHeatmap heatmaps using the `+` operator (e.g. `p_heatmap + p_heatmap + p_heatmap`) may result in an error or unexpected behavior. 
> 
> To robustly combine more than two heatmaps, convert each to a ComplexHeatmap object first, this will use the `+` functionality of `ComplexHeatmap`. This ensures that all objects are compatible and can be combined using ComplexHeatmap's native addition functionality.

```{r three_ways, warning=FALSE, fig.width=10, fig.height=6}
as_ComplexHeatmap(p_heatmap) +
  as_ComplexHeatmap(p_heatmap) +
  as_ComplexHeatmap(p_heatmap)
```


# Using patchwork to integrate across heatmaps and including ggplots

```{r patchworkintegrate, fig.width=10, fig.height=6}
library(ggplot2)
library(patchwork)

p_heatmap =
	mtcars_tidy |> 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
			show_heatmap_legend = FALSE,
		row_names_gp = gpar(fontsize = 7)
	) 

p_ggplot = data.frame(value = 1:10) |> ggplot(aes(value)) + geom_density()

wrap_heatmap(p_heatmap) + 
	p_ggplot +
	
	# Add padding for better aesthetics
	wrap_heatmap(
		p_heatmap,
		padding = grid::unit(c(-30, -0, -0, -10), "points" ),
		clip = FALSE
	) + 
	plot_layout(width = c(1, 0.3, 1))

```

# ComplexHeatmap further styling

## Add cell borders

```{r borders, fig.width=10, fig.height=6}
mtcars_tidy |> 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		rect_gp = grid::gpar(col = "#161616", lwd = 0.5)
	) 
```

## Drop row clustering

```{r droprow, fig.width=10, fig.height=6}
mtcars_tidy |> 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		cluster_rows = FALSE
	) 
```

## Reorder rows elements

```{r reorder, fig.width=10, fig.height=6}
library(forcats)
mtcars_tidy |> 
	mutate(`Car name` = forcats::fct_reorder(`Car name`, `Car name`, .desc = TRUE)) %>% 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		cluster_rows = FALSE
	) 
```

## Size of dendrograms

```{r sizedendro, fig.width=10, fig.height=6}
mtcars_tidy |> 
	mutate(`Car name` = forcats::fct_reorder(`Car name`, `Car name`, .desc = TRUE)) %>% 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		column_dend_height = unit(0.2, "cm"), 
		row_dend_width = unit(0.2, "cm")
	) 
```

## Size of rows/columns titles and names

```{r sizecolumns, fig.width=10, fig.height=10}
mtcars_tidy |> 
	mutate(`Car name` = forcats::fct_reorder(`Car name`, `Car name`, .desc = TRUE)) %>% 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		row_names_gp = gpar(fontsize = 7),
		column_names_gp = gpar(fontsize = 7),
		column_title_gp = gpar(fontsize = 7),
		row_title_gp = gpar(fontsize = 7)
	) 
```

## Remove row and column titles

You can completely remove the row and column titles by setting them to empty strings:

```{r removetitles, fig.width=10, fig.height=10}
mtcars_tidy |> 
	mutate(`Car name` = forcats::fct_reorder(`Car name`, `Car name`, .desc = TRUE)) |> 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row", 
		row_title = "",      # Remove row title
		column_title = ""    # Remove column title
	) 
```

## Align numeric annotation

This can be done only for `annotation_numeric` because of `ComplexHeatmap` requirements (?ComplexHeatmap::anno_numeric)

```{r align_numeric, fig.width=10, fig.height=10}
mtcars_tidy |> 
	mutate(`Car name` = forcats::fct_reorder(`Car name`, `Car name`, .desc = TRUE)) %>% 
	heatmap(
		`Car name`, Property, Value,	
		scale = "row"
	) |> 
  annotation_numeric(hp, align_to="right")
```

## External `ComplexHeatmap` functionalities

ComplexHeatmap has some graphical functionalities that are not included in the standard functional framework. We can use `as_ComplexHeatmap` to convert our output before applying drawing options.

### Chainging side of legends

```{r sidelegend, fig.width=10, fig.height=6}

heatmap(mtcars_tidy, `Car name`, Property, Value, scale = "row"	) %>%
	as_ComplexHeatmap() %>%
	ComplexHeatmap::draw(heatmap_legend_side = "left"	)
```

### Add title using `draw` from `ComplexHeatmap`

```{r title, fig.width=10, fig.height=6}
mtcars_tidy |> 
    heatmap(`Car name`, Property, Value,    scale = "row"   ) |>
    as_ComplexHeatmap() |>
    ComplexHeatmap::draw(
        column_title = "TITLE", 
        column_title_gp = gpar(fontsize = 16)
    )
```




### Add title using `ggtitle` from `ggplot2`

```{r title2, fig.width=10, fig.height=10}
mtcars_tidy |> 
    heatmap(`Car name`, Property, Value,  scale = "row" ) |>
    wrap_heatmap() +
		ggplot2::ggtitle("TITLE")
```


# Session Info

```{r}
sessionInfo()
```

