Draw heatmap of microbiome composition across samples

Heatmap made with ComplexHeatmap::Heatmap(), with optional annotation of taxa prevalence/abundance, and/or other sample data.

Transform your data with tax_transform() prior to plotting (and/or scale with tax_scale()).

See the heatmaps vignette for more examples of use.

Plotting "compositional" data can give an idea of the dominant taxa in each sample. Plotting some form of log or clr transformed (or scaled) microbial features can highlight other patterns.

The data will be ordered via your selected seriation methods and distances on either the transformed data (default) or the original count data (or with any other transformation).

Any cell numbers printed can be transformed independently of the colour scheme, and do not affect ordering.

comp_heatmap(
  data,
  taxa = NA,
  taxa_side = "right",
  tax_anno = NULL,
  taxon_renamer = identity,
  samples = NA,
  sample_side = adjacent_side(taxa_side),
  sample_anno = NULL,
  sample_names_show = FALSE,
  colors = heat_palette(palette = "Rocket", rev = TRUE),
  numbers = NULL,
  sample_seriation = "OLO_ward",
  sample_ser_dist = "euclidean",
  sample_ser_counts = !sample_ser_dist %in% c("euclidean", "maximum", "manhattan",
    "canberra", "binary"),
  sample_ser_trans = NULL,
  tax_seriation = "OLO_ward",
  tax_ser_dist = "euclidean",
  tax_ser_counts = FALSE,
  tax_ser_trans = NULL,
  numbers_trans = NULL,
  numbers_zero_replace = 0,
  numbers_use_counts = TRUE,
  grid_col = "white",
  grid_lwd = 0.5,
  name = "Abd.",
  anno_tax = NULL,
  ...
)

Arguments

data

phyloseq or phyloseq extra

taxa

list of taxa to include, or NA for all

taxa_side

"top"/"right"/"bottom"/"left": controls heatmap orientation and where any annotations specified in tax_anno are placed

tax_anno

NULL or annotation function for taxa: taxAnnotation() output.

taxon_renamer

function to rename taxa before plotting

samples

list of samples to include on plot

sample_side

which side to show any sample annotation on, must be adjacent to taxa_side

sample_anno

NULL or annotation function for samples: sampleAnnotation() output.

sample_names_show

show sample names? (you can control side and rotation of names with other ComplexHeatmap::Heatmap arguments)

colors

output of heat_palette() to set heatmap fill color scheme

numbers

output of heat_numbers() to draw numbers on heatmap cells

sample_seriation

name of method used to order the samples (from seriation::seriate)

sample_ser_dist

name of distance to use with sample_seriation method (if needed)

sample_ser_counts

insist on using count data for sample seriation?

sample_ser_trans

function for transformation of data used for sample seriation (such as a call to tax_transform())

tax_seriation

name of method used to order the taxa (from seriation::seriate)

tax_ser_dist

name of distance to use with tax_seriation method (if needed)

tax_ser_counts

insist on using count data for taxa seriation?

tax_ser_trans

function for transformation of data used for taxa seriation (such as a call to tax_transform())

numbers_trans

name of tax_transform transformation, or a function for transformation of data used for drawing numbers on cells

numbers_zero_replace

zero replacement method used if named transformation given to number_trans

numbers_use_counts

insist on using count data for number drawing? (if TRUE, any numbers_trans transformation would be applied to count data)

grid_col

colour of gridlines, or NA for none

grid_lwd

width of gridlines

name

used as legend title (colourbar)

anno_tax

DEPRECATED: optional annotation of taxa distributions: tax_anno() list output, or a pre-made ComplexHeatmap HeatmapAnnotation

...

Arguments passed on to ComplexHeatmap::Heatmap

row_dend_side: Should the row dendrogram be put on the left or right of the heatmap?
row_dend_width: Width of the row dendrogram, should be a unit object.
show_row_dend: Whether show row dendrogram?
row_dend_gp: Graphic parameters for the dendrogram segments. If users already provide a dendrogram object with edges rendered, this argument will be ignored.
show_row_names: Whether show row names.
row_names_gp: Graphic parameters for row names.
row_names_rot: Rotation of row names.
row_names_centered: Should row names put centered?

Examples

library(dplyr)
#> 
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:stats’:
#> 
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#> 
#>     intersect, setdiff, setequal, union
data("dietswap", package = "microbiome")
# create a couple of numerical variables to use
psq <- dietswap %>%
  ps_mutate(
    weight = recode(bmi_group, obese = 3, overweight = 2, lean = 1),
    female = if_else(sex == "female", true = 1, false = 0),
    african = if_else(nationality == "AFR", true = 1, false = 0)
  )
psq <- tax_filter(psq, min_prevalence = 1 / 10, min_sample_abundance = 1 / 10)
#> Proportional min_prevalence given: 0.1 --> min 23/222 samples.
psq <- tax_agg(psq, "Genus")

# randomly select 20 taxa from the 40 top taxa, and 40 random samples

set.seed(123)
taxa <- sample(tax_top(psq, n = 40), size = 20)
samples <- sample(1:122, size = 40)

comp_heatmap(data = psq, taxa = taxa, samples = samples)


# transforming taxon abundances #

# NOTE: if you plan on transforming taxa (e.g. to compositional data or clr)
# but only want to plot a subset of the taxa (e.g. most abundant)
# you should NOT subset the original phyloseq before transformation!
# Instead, choose the subset of taxa plotted with:

# Note 2, choose a symmetrical palette for clr-transformed data
psq %>%
  tax_transform("clr", zero_replace = "halfmin") %>%
  comp_heatmap(
    taxa = taxa, samples = samples, colors = heat_palette(sym = TRUE)
  )


# Almost all the taxa have high values (>> 0) because they are a highly
# abundant subset taken after clr transformation was calculated on all taxa

# See how just taking the first 30 taxa from the dataset gives more balance
psq %>%
  tax_transform("clr", zero_replace = "halfmin") %>%
  comp_heatmap(
    taxa = 1:30, samples = samples, colors = heat_palette(sym = TRUE)
  )


# annotating taxa #

# Notes:
# - Unlike cor_heatmap, taxa are not annotated by default
# - Detection threshold set to 50 as HITchip example data seems to have background noise

comp_heatmap(
  data = psq, taxa = taxa, samples = samples,
  tax_anno = taxAnnotation(Prev = anno_tax_prev(undetected = 50))
)


# annotating samples #

htmp <- psq %>%
  tax_transform("clr", zero_replace = "halfmin") %>%
  comp_heatmap(
    taxa = taxa, samples = samples, colors = heat_palette(sym = TRUE),
    sample_anno = sampleAnnotation(
      Nation. = anno_sample_cat("nationality", legend_title = "Nation.")
    )
  )
#> Warning: coercing non-character anno_cat annotation data to character
htmp


# legends from `anno_sample_cat()` are stored as an attribute of the Heatmap
ComplexHeatmap::draw(
  object = htmp,
  annotation_legend_list = attr(htmp, "AnnoLegends"), merge_legends = TRUE
)

Draw heatmap of microbiome composition across samples

Arguments

See also

Examples