plotMultiHeatmap {CATALYST} | R Documentation

## Multi-panel expression & frequency heatmaps

### Description

Combines expression and frequency heatmaps from `plotExprHeatmap` and `plotFreqHeatmap`, respectively, into a `HeatmapList`.

### Usage

    plotMultiHeatmap(
      x,
      hm1 = "type",
      hm2 = "abundances",
      k = "meta20",
      m = NULL,
      assay = "exprs",
      fun = c("median", "mean", "sum"),
      scale = c("first", ifelse(hm2 == "state", "first", "last")),
      q = c(0.01, ifelse(hm2 == "state", 0.01, 0)),
      normalize = TRUE,
      row_anno = TRUE,
      col_anno = TRUE,
      row_clust = TRUE,
      col_clust = c(TRUE, hm2 == "state"),
      row_dend = TRUE,
      col_dend = c(TRUE, hm2 == "state"),
      bars = FALSE,
      perc = FALSE,
      hm1_pal = rev(brewer.pal(11, "RdYlBu")),
      hm2_pal = if (isTRUE(hm2 == "abundances")) rev(brewer.pal(11, "PuOr")) else hm1_pal,
      k_pal = CATALYST:::.cluster_cols,
      m_pal = k_pal,
      distance = c("euclidean", "maximum", "manhattan", "canberra", "binary", "minkowski"),
      linkage = c("average", "ward.D", "single", "complete", "mcquitty", "median",
        "centroid", "ward.D2")
    )

### Arguments

`x` | a `SingleCellExperiment`.
`hm1` | character string specifying which features to include in the 1st heatmap; valid values are `"type"/"state"` for `type/state_markers(x)` if `rowData(x)$marker_class` have been specified; a subset of `rownames(x)`; NULL to use all features; and FALSE to omit the 1st heatmap altogether.
`hm2` | character string. Specifies the right-hand side heatmap. One of: `"abundances"`: cluster frequencies across samples `"state"`: median state-marker expressions across clusters (analogous to the left-hand side heatmap) a character string/vector corresponding to one/multiple marker(s): median marker expressions across samples and clusters
`k` | character string specifying which; valid values are `names(cluster_codes(x))`.
`m` | character string specifying a metaclustering to include as an annotation when `row_anno = TRUE`.
`assay` | character string specifying which assay data to use; valid values are `assayNames(x)`.
`fun` | character string specifying the function to use as summary statistic.
`scale` | character string specifying the scaling strategy; for expression heatmaps (see `plotExprHeatmap`).
`q` | single numeric in [0,1) determining the quantiles to trim when `scale != "never"`.
`normalize` | logical specifying whether to Z-score normalize cluster frequencies across samples; see `plotFreqHeatmap`.
`row_anno, col_anno` | logical specifying whether to include row/column annotations for cell metadata variables and clustering(s); see `plotExprHeatmap` and `plotFreqHeatmap`.
`row_clust, col_clust` | logical specifying whether rows/columns should be hierarchically clustered and re-ordered accordingly.
`row_dend, col_dend` | logical specifying whether to include the row/column dendrograms.
`bars` | logical specifying whether to include a barplot of cell counts per cluster as a right-hand side row annotation.
`perc` | logical specifying whether to display percentage labels next to bars when `bars = TRUE`.
`hm1_pal, hm2_pal` | character vector of colors to interpolate for each heatmap.
`k_pal, m_pal` | character vector of colors to use for cluster and merging row annotations. If less than `nlevels(cluster_ids(x, k/m))` values are supplied, colors will be interpolated via `colorRampPalette`.
`distance` | character string specifying the distance metric to use in `dist` for hierarchical clustering.
`linkage` | character string specifying the agglomeration method to use in `hclust` for hierarchical clustering.

### Details

In its 1st panel, `plotMultiHeatmap` will display (scaled) type-marker expressions aggregated by cluster (across all samples). Depending on argument `hm2`, the 2nd panel will contain one of:

`hm2 = "abundances"`

  relataive cluster abundances by cluster & sample

`hm2 = "state"`

  aggregated (scaled) state-marker expressions by cluster (across all samples; analogous to panel 1)

`hm2 %in% rownames(x)`

  aggregated (scaled) marker expressions by cluster & sample

### Value

a `HeatmapList-class` object.

### Author(s)

Helena L Crowell helena.crowell@uzh.ch

### References

Nowicka M, Krieg C, Crowell HL, Weber LM et al. CyTOF workflow: Differential discovery in high-throughput high-dimensional cytometry datasets. F1000Research 2017, 6:748 (doi: 10.12688/f1000research.11622.1)

### See Also

`plotMedExprs`, `plotAbundances`, `plotExprHeatmap`, `plotFreqHeatmap`

### Examples

    # construct SCE & run clustering
    data(PBMC_fs, PBMC_panel, PBMC_md)
    sce <- prepData(PBMC_fs, PBMC_panel, PBMC_md)
    sce <- cluster(sce)

    # state-markers + cluster frequencies
    plotMultiHeatmap(sce,
      hm1 = "state", hm2 = "abundances",
      bars = TRUE, perc = TRUE)

    # type-markers + marker of interest
    plotMultiHeatmap(sce, hm2 = "pp38", k = "meta12", m = "meta8")

    # both, type- & state-markers
    plotMultiHeatmap(sce, hm2 = "state")

    # plot markers of interest side-by-side
    # without left-hand side heatmap
    plotMultiHeatmap(sce, k = "meta10",
      hm1 = NULL, hm2 = c("pS6", "pNFkB", "pBtk"),
      row_anno = FALSE, hm2_pal = c("white", "black"))

[Package CATALYST version 1.18.1 Index]