Package 'SummarizedHeatmap'

Title: Heatmaps for SummarizedExperiment Objects
Description: Represents a heatmap as a SummarizedExperiment-derived object, holding a single assay together with its row and column annotations and any hierarchical clustering. Assay values, annotations, display order, and dendrograms stay synchronized as the object is subsetted or reclustered, so a heatmap's components cannot drift out of step with each other. Each visual component (the main heatmap, annotation strips, dendrograms) is returned as an ordinary ggplot2 plot, and these can be composed, laid out, and customized using patchwork.
Authors: Bradley Blaser [aut, cre] (ORCID: <https://orcid.org/0000-0002-3168-5423>)
Maintainer: Bradley Blaser <[email protected]>
License: MIT + file LICENSE
Version: 0.99.0
Built: 2026-10-13 19:42:19 UTC
Source: https://github.com/bioc/SummarizedHeatmap

Help Index

SummarizedHeatmap

Description

A SummarizedExperiment-derived representation of clustered assays and their feature and sample annotations. Plotting functions return ordinary ggplot2 and patchwork objects that remain open to standard customization.

Author(s)

Maintainer: Bradley Blaser [email protected] (ORCID)

Authors:

See Also

SummarizedHeatmap(), plotHeatmap(), SummarizedExperiment::SummarizedExperiment()

Subset a SummarizedHeatmap

Description

Subsetting follows SummarizedExperiment semantics. If row membership or order changes, the row dendrogram is cleared and row order resets to the natural order of the subset. The same rule applies independently to columns. Clustering for an unchanged dimension is preserved. Subsetting never reclusters implicitly; call clusterRows(), clusterCols(), or clusterHeatmap() when new clustering is desired.

Usage

## S4 method for signature 'SummarizedHeatmap,ANY,ANY,ANY'
x[i, j, ..., drop = FALSE]

Arguments

x

A SummarizedHeatmap object.
i

Row indices, names, or logical selector.
j

Column indices, names, or logical selector.
...

Additional subsetting arguments.
drop

Whether to drop dimensions. Defaults to FALSE to preserve the SummarizedHeatmap class.

Value

A valid SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(20), 5, dimnames = list(letters[1:5], LETTERS[1:4]))
x <- SummarizedHeatmap(mat)
x[1:3, 1:2]

Replace the assay of a SummarizedHeatmap

Description

Assay replacement follows SummarizedExperiment semantics: dimensions and dimnames must be preserved. Because a stored dendrogram and its implied order are only valid for the assay values they were computed from, replacing the assay never silently reclusters. Instead, whenever a dendrogram is currently stored for an axis, it is cleared and that axis's order resets to its natural order; when no dendrogram is stored (e.g. a manually-supplied or default order), the existing order is left untouched. The same rule is applied independently to rows and columns. Call clusterRows(), clusterCols(), or clusterHeatmap() afterwards to recompute clustering against the new values.

Usage

## S4 replacement method for signature 'SummarizedHeatmap,missing'
assay(x, i, withDimnames = TRUE, ...) <- value

## S4 replacement method for signature 'SummarizedHeatmap,numeric'
assay(x, i, withDimnames = TRUE, ...) <- value

## S4 replacement method for signature 'SummarizedHeatmap,character'
assay(x, i, withDimnames = TRUE, ...) <- value

Arguments

x

A SummarizedHeatmap object.
i

Optional name or index of the assay to replace. Since a SummarizedHeatmap always holds exactly one assay, this must (when supplied) identify that single assay.
withDimnames

A logical value indicating whether value's dimnames must be respected. Passed through to the SummarizedExperiment method.
...

Additional arguments passed to the SummarizedExperiment method.
value

A numeric, non-complex matrix with the same dimensions and dimnames as the current assay.

Value

An updated, valid SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
x <- SummarizedHeatmap(mat)
assay(x) <- mat * 2
rowDendro(x)

Replace the assays of a SummarizedHeatmap

Description

Assay replacement follows SummarizedExperiment semantics: dimensions and dimnames must be preserved. Because a stored dendrogram and its implied order are only valid for the assay values they were computed from, replacing the assay never silently reclusters. Instead, whenever a dendrogram is currently stored for an axis, it is cleared and that axis's order resets to its natural order; when no dendrogram is stored (e.g. a manually-supplied or default order), the existing order is left untouched. The same rule is applied independently to rows and columns. Call clusterRows(), clusterCols(), or clusterHeatmap() afterwards to recompute clustering against the new values.

Usage

## S4 replacement method for signature 'SummarizedHeatmap,list'
assays(x, withDimnames = TRUE, ...) <- value

## S4 replacement method for signature 'SummarizedHeatmap,SimpleList'
assays(x, withDimnames = TRUE, ...) <- value

Arguments

x

A SummarizedHeatmap object.
withDimnames

A logical value indicating whether value's dimnames must be respected. Passed through to the SummarizedExperiment method.
...

Additional arguments passed to the SummarizedExperiment method.
value

A list or SimpleList of exactly one assay, with the same dimensions and dimnames as the current assay.

Value

An updated, valid SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
x <- SummarizedHeatmap(mat)
assays(x) <- list(matrix = mat * 2)
rowDendro(x)

Cluster columns

Description

Compute a hierarchical clustering across assay columns and update the stored column dendrogram and display order.

Usage

clusterCols(x, distMethod = "euclidean", hclustMethod = "average")

Arguments

x

A SummarizedHeatmap object.
distMethod

Distance method passed to stats::dist().
hclustMethod

Linkage method passed to stats::hclust().

Value

The updated SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
clusterCols(SummarizedHeatmap(mat))

Cluster rows and columns

Description

Cluster rows and columns

Usage

clusterHeatmap(x, distMethod = "euclidean", hclustMethod = "average")

Arguments

x

A SummarizedHeatmap object.
distMethod

Distance method passed to stats::dist().
hclustMethod

Linkage method passed to stats::hclust().

Value

The updated SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
clusterHeatmap(SummarizedHeatmap(mat))

Cluster rows

Description

Compute a hierarchical clustering across assay rows and update the stored row dendrogram and display order. Clustering is deterministic for a fixed assay and set of methods.

Usage

clusterRows(x, distMethod = "euclidean", hclustMethod = "average")

Arguments

x

A SummarizedHeatmap object.
distMethod

Distance method passed to stats::dist().
hclustMethod

Linkage method passed to stats::hclust().

Value

The updated SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
clusterRows(SummarizedHeatmap(mat))

Access stored column dendrogram

Description

Access stored column dendrogram

Usage

colDendro(x)

## S4 method for signature 'SummarizedHeatmap'
colDendro(x)

Arguments

x

A SummarizedHeatmap object.

Value

A dendrogram, or NULL if columns are not clustered.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
colDendro(SummarizedHeatmap(mat))

Access column display order

Description

Access column display order

Usage

colOrder(x)

## S4 method for signature 'SummarizedHeatmap'
colOrder(x)

Arguments

x

A SummarizedHeatmap object.

Value

Integer column indices in display order.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
colOrder(SummarizedHeatmap(mat))

Plot column annotations

Description

Each selected column annotation is represented by an independent ggplot, labelled with its variable name as axis text next to the annotation tiles. A single variable returns a ggplot; multiple variables return an (unwrapped) patchwork stacking the independent plots (see plotRowData() for alignment and safe-composition details).

Usage

plotColData(
  x,
  vars = NULL,
  side = "right",
  tileColor = "white",
  palette = NULL,
  showNames = FALSE
)

Arguments

x

A SummarizedHeatmap object.
vars

Character vector of rowData names. A named vector uses its names as displayed labels.
side

Which side of the annotation tiles the variable-name label is drawn on: "left" or "right" for column annotations (the tiles are always laid out with column identifiers on the horizontal axis, matching the heatmap's columns, so the label sits on that axis's left or right edge). "left" places the label where it is more prone to clipping when combined with patchwork::free(type = "space"); see Details.
tileColor

Tile border colour.
palette

Optional named values passed to scale_fill_manual().
showNames

Whether to display row or column names on the annotation axis.

Value

A ggplot for one variable, a patchwork for multiple variables, or a spacer when no column annotations are present.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
cd <- S4Vectors::DataFrame(
    group = c("A", "B", "A"), row.names = LETTERS[1:3]
)
plotColData(SummarizedHeatmap(mat, colData = cd))

Plot the stored column dendrogram

Description

Plot the stored column dendrogram

Usage

plotColDendro(x, side = "top", linewidth = 0.5)

Arguments

x

A SummarizedHeatmap object.
side

Side on which the dendrogram is oriented. The default places leaves toward the heatmap when shown to its left.
linewidth

Dendrogram line width.

Value

A ggplot object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
plotColDendro(SummarizedHeatmap(mat))

Compose a complete heatmap with patchwork

Description

The component plots remain available through their individual plotting functions. This helper arranges them around the main heatmap panel, constructing the components in a deterministic order (the main heatmap, then column dendrogram, column annotation, then row dendrogram, row annotation) so that, when collectGuides = TRUE, their legends are always collected into the shared guide area in that same order, regardless of which side of the heatmap each panel is placed on. guide_area() (the M panel) only controls where the collected guides are drawn, not the order they are collected in; see .orderPanelsForGuides() for the ordering itself. Column annotation plots are stacked vertically. The row dendrogram and row annotation panels move to whichever side of the heatmap rowDendroSide/ rowAnnotationSide request ("left" or "right", both defaulting to "left"); the column dendrogram and column annotation panels likewise move with colDendroSide/colAnnotationSide ("top" or "bottom", both defaulting to "top"). When a dendrogram and its matching annotation share a side, the annotation sits adjacent to the heatmap and the dendrogram sits further out; by default this puts both on the same side for each axis. Pass named variable vectors to rowVars or colVars to control annotation strip labels; pass NULL to rowAnnotationSide/ colAnnotationSide to omit that annotation panel entirely. Any omitted panel – an annotation set to NULL, a dendrogram hidden with showRowDendro/showColDendro = FALSE, or a dendrogram that was never stored – is dropped from the grid rather than left as a blank but still-sized slot, so the remaining panels use the reclaimed space.

Usage

plotHeatmap(
  x,
  rowVars = NULL,
  colVars = NULL,
  showRowDendro = TRUE,
  showColDendro = TRUE,
  rowDendroSide = "left",
  colDendroSide = "top",
  rowAnnotationSide = "left",
  colAnnotationSide = "top",
  collectGuides = TRUE,
  guideWidth = 3,
  ...
)

Arguments

x

A SummarizedHeatmap object.
rowVars, colVars

Optional annotation variables to display. NULL includes all available variables.
showRowDendro, showColDendro

Whether to display stored dendrograms.
rowDendroSide

"left" or "right": which side of the heatmap the row dendrogram panel is placed on (and oriented toward).
colDendroSide

"top" or "bottom": which side of the heatmap the column dendrogram panel is placed on (and oriented toward).
rowAnnotationSide, colAnnotationSide

Which side of the heatmap the annotation panel is placed on, restricted to "left"/"right" (rows) or "top"/"bottom" (columns); this only controls panel placement; see Details for how it affects the variable-name label's position. "right" (rows) places the annotation's variable-name label where it can be clipped if the figure is too small; see Details. Set to NULL to omit the annotation panel entirely.
collectGuides

Collect guides into a shared guide area.
guideWidth

Relative width of the guide area column, on the same scale as the dendrogram/annotation (1) and heatmap body (8) column widths. Increase this when stacked legends (e.g. several annotation variables) overflow their column and collide with the heatmap's row labels or with each other.
...

Additional arguments passed to plotHeatmapMain(), such as low/mid/high/midpoint (fill scale) or fillTitle (legend title). flip is not accepted here – flipping only the main panel would misalign it against the annotation and dendrogram panels arranged around it; call plotHeatmapMain() directly for a flipped main panel on its own.

Details

Each annotation strip's variable-name axis text is wrapped with patchwork::free(type = "space") so it packs tightly against the heatmap instead of forcing extra column/row width (see plotColData()/ plotRowData() for the axis text itself). Because "space" reserves no room for that text, it can get clipped at the edge of the plotting device if there isn't enough surrounding space to draw it – most likely with the non-default rowAnnotationSide = "right", which anchors the row annotation's variable-name label at the bottom of its strip, where it competes for space with the heatmap's own column identifier labels (the column annotation's variable-name label always sits to the right of its strip, matching the heatmap's own row labels, regardless of colAnnotationSide). Increase the figure's height or width if labels are clipped in that configuration.

Value

A patchwork object.

Examples

mat <- matrix(
    rnorm(24), 6,
    dimnames = list(paste0("f", 1:6), paste0("s", 1:4))
)
x <- SummarizedHeatmap(mat)
plotHeatmap(x)

Plot the assay as a ggplot heatmap

Description

The returned object is an ordinary ggplot and can be modified with standard ggplot2 layers and scales. The display follows the stored row and column orders.

Usage

plotHeatmapMain(
  x,
  tileColor = "white",
  high = "red3",
  mid = "white",
  low = "blue4",
  midpoint = 0,
  fillTitle = "Value",
  flip = FALSE
)

Arguments

x

A SummarizedHeatmap object.
tileColor

Tile border colour.
high, mid, low

Colours for high, midpoint, and low assay values.
midpoint

Assay value mapped to mid.
fillTitle

Title for the fill legend.
flip

If TRUE, transpose the visual orientation.

Value

A ggplot object.

Examples

mat <- matrix(
    rnorm(24), 6,
    dimnames = list(paste0("f", 1:6), paste0("s", 1:4))
)
plotHeatmapMain(SummarizedHeatmap(mat))

Plot row annotations

Description

Each selected row annotation is represented by an independent ggplot, labelled with its variable name as axis text next to the annotation tiles (in addition to its legend title). A single variable returns a ggplot; multiple variables return an (unwrapped) patchwork stacking the independent plots, so the result stays aligned with sibling panels and its guides can still be collected by an enclosing plot_layout(guides = "collect") – see plotHeatmap().

Usage

plotRowData(
  x,
  vars = NULL,
  side = "top",
  tileColor = "white",
  palette = NULL,
  showNames = FALSE
)

Arguments

x

A SummarizedHeatmap object.
vars

Character vector of rowData names. A named vector uses its names as displayed labels.
side

Which side of the annotation tiles the variable-name label is drawn on: "top" or "bottom" for row annotations (the tiles are always laid out with row identifiers on the vertical axis, matching the heatmap's rows, so the label sits on that narrow axis's top or bottom edge). "bottom" places the label where it is more prone to clipping when combined with patchwork::free(type = "space"); see Details.
tileColor

Tile border colour.
palette

Optional named values passed to scale_fill_manual().
showNames

Whether to display row or column names on the annotation axis.

Details

Combining a multiple-variable result directly with another plot using patchwork operators (+, /, |) can silently flatten its panel list into the parent's, which may break a plot_layout(heights = ...)/ plot_layout(design = ...) built around an expected panel count. Use patchwork::wrap_plots(list(annotation, otherPlot), ...) instead of an operator to combine them safely (this is how plotHeatmap() does it internally).

When composing a custom layout, wrap the result with patchwork::free(type = "space") so its variable-name axis text packs tightly against neighbouring panels instead of forcing extra column/row width (plotHeatmap() does this for every annotation strip). Because "space" reserves no room for that text, it can get clipped at the edge of the plotting device when there isn't enough surrounding space – most likely with side = "right" or side = "bottom", where the (possibly rotated) label competes for space with other axis labels. Increase the figure's height or width if labels are clipped in that configuration.

Value

A ggplot for one variable, a patchwork for multiple variables, or a spacer when no row annotations are present.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
rd <- S4Vectors::DataFrame(
    kind = rep(c("gene", "control"), 2), row.names = letters[1:4]
)
plotRowData(SummarizedHeatmap(mat, rowData = rd))

Plot the stored row dendrogram

Description

Plot the stored row dendrogram

Usage

plotRowDendro(x, side = "left", linewidth = 0.5)

Arguments

x

A SummarizedHeatmap object.
side

Side on which the dendrogram is oriented. The default places leaves toward the heatmap when shown to its left.
linewidth

Dendrogram line width.

Value

A ggplot object.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
plotRowDendro(SummarizedHeatmap(mat))

Access stored row dendrogram

Description

Access stored row dendrogram

Usage

rowDendro(x)

## S4 method for signature 'SummarizedHeatmap'
rowDendro(x)

Arguments

x

A SummarizedHeatmap object.

Value

A dendrogram, or NULL if rows are not clustered.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
rowDendro(SummarizedHeatmap(mat))

Access row display order

Description

Access row display order

Usage

rowOrder(x)

## S4 method for signature 'SummarizedHeatmap'
rowOrder(x)

Arguments

x

A SummarizedHeatmap object.

Value

Integer row indices in display order.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
rowOrder(SummarizedHeatmap(mat))

Display a concise summary of a SummarizedHeatmap

Description

Display a concise summary of a SummarizedHeatmap

Usage

## S4 method for signature 'SummarizedHeatmap'
show(object)

Arguments

object

A SummarizedHeatmap object.

Value

The method displays a summary and returns invisibly.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
show(SummarizedHeatmap(mat))

Create a SummarizedHeatmap

Description

Create a heatmap representation from a numeric matrix or from a single assay of a SummarizedExperiment object. Rows and columns are clustered by default when their sizes permit; stored orders are integer indices into the assay dimensions. Missing dimension names are filled with stable sequential identifiers when x is a matrix.

Usage

SummarizedHeatmap(
  x,
  assay = NULL,
  rowOrder = NULL,
  colOrder = NULL,
  clusterRows = TRUE,
  clusterCols = TRUE,
  distMethod = "euclidean",
  hclustMethod = "average",
  ...
)

Arguments

x

A numeric matrix, or a SummarizedExperiment object.
assay

When x is a SummarizedExperiment, the name or integer index of the assay to use. Required when x has more than one assay; optional but still validated when x has exactly one. Unused when x is a matrix. The selected assay's original name is preserved in the resulting SummarizedHeatmap (falling back to "matrix" when the source assay is unnamed).
rowOrder

Optional manual row order, as integer indices or row names. Supplying it leaves the row dendrogram unset and takes precedence over clusterRows.
colOrder

Optional manual column order, as integer indices or column names. Supplying it leaves the column dendrogram unset and takes precedence over clusterCols.
clusterRows

Whether to compute a row dendrogram and clustering order. Ignored (with no dendrogram computed) when rowOrder is supplied. When FALSE and rowOrder is not supplied, rows keep their natural order and no dendrogram is stored.
clusterCols

Whether to compute a column dendrogram and clustering order. Ignored (with no dendrogram computed) when colOrder is supplied. When FALSE and colOrder is not supplied, columns keep their natural order and no dendrogram is stored.
distMethod

Distance method passed to stats::dist().
hclustMethod

Linkage method passed to stats::hclust(). Defaults to average linkage, matching the original constructor.
...

Additional arguments passed to SummarizedExperiment::SummarizedExperiment(), such as rowData and colData. Only used when x is a matrix; ignored when x is a SummarizedExperiment, whose own annotations are preserved instead.

Details

A SummarizedHeatmap always holds exactly one assay. When x is a SummarizedExperiment with a single assay, that assay is used automatically. When it has multiple assays, assay must be supplied to select one by name or position. Either way, the selected assay's original name is preserved in the resulting SummarizedHeatmap; rowData, colData, and metadata are carried over from x unchanged.

Value

A valid SummarizedHeatmap object.

Examples

mat <- matrix(rnorm(24),
    nrow = 6,
    dimnames = list(paste0("feature", 1:6), paste0("sample", 1:4))
)
x <- SummarizedHeatmap(mat)
validObject(x)

se <- SummarizedExperiment::SummarizedExperiment(
    assays = list(counts = mat)
)
y <- SummarizedHeatmap(se)
validObject(y)
SummarizedExperiment::assayNames(y) # "counts", preserved from se

SummarizedHeatmap class

Description

A single assay and its row and column annotations, display orders, and optional hierarchical clusterings. The class extends SummarizedExperiment but is restricted to exactly one assay; use SummarizedHeatmap() to build one from a matrix or from a SummarizedExperiment (selecting an assay when it holds more than one).

Slots

rowDendro

Row dendrogram, or NULL when rows are not clustered.

colDendro

Column dendrogram, or NULL when columns are not clustered.

rowOrder

Integer indices giving row display order.

colOrder

Integer indices giving column display order.

Examples

mat <- matrix(rnorm(12), 4, dimnames = list(letters[1:4], LETTERS[1:3]))
show(SummarizedHeatmap(mat))