Contents

visualize$associations$heatmap

Association results as a heatmap or dotplot

Draws one cell per (row, column) combination of an association table, filled by color.by and starred by asterisk.by. Supplying size.by turns the cells into size-scaled dots. Requires ComplexHeatmap.

Usage

visualize.associations.heatmap(
  associations,
  rows.by = predictor,
  rows.group.by = NULL,
  columns.by = outcome,
  columns.group.by = NULL,
  color.by = estimate,
  size.by = NULL,
  asterisk.by = adj.pval,
  column_names_rot = 45,
  border = TRUE,
  palette = NULL,
  ...
)

Arguments

Argument	Description
`associations`	A PolyGeniusAssociation, or any data frame of association rows. Coerced with as.data.frame(); no schema is required.
`rows.by`	Unquoted expression for the row variable, default predictor. Must resolve to one value per row of associations.
`rows.group.by`	Unquoted expression assigning each association row to a group, or NULL (default) for no split. Splits the rows into labelled blocks (row_split); each rows.by level must map to exactly one group. Block order follows the expression's own factor levels when it is a factor, otherwise first appearance.
`columns.by`	Unquoted expression for the column variable, default outcome. Must resolve to one value per row of associations.
`columns.group.by`	Unquoted expression, or NULL (default). As rows.group.by, but splits the columns (column_split).
`color.by`	Unquoted expression for the fill/color variable, default estimate. Coerced with as.numeric() and mapped through a diverging ramp centered on zero.
`size.by`	Unquoted expression for the size variable, or NULL (default). When supplied, each cell is drawn as a circle whose radius encodes size.by rescaled to the observed range and whose fill encodes color.by.
`asterisk.by`	Unquoted expression for the significance variable overlaid as stars, default adj.pval.
`column_names_rot`	Numeric scalar (degrees), default 45. Column-label rotation.
`border`	Logical scalar, default TRUE. Draw a border around the heatmap body.
`palette`	Diverging color palette for the color.by gradient: a palette-system or hue name, a vector of two or more colors, a circlize::colorRamp2 function, or NULL (default) for the package diverging ramp. A supplied function is used as-is; colors are otherwise spread symmetrically about zero.
`...`	Further arguments passed to ComplexHeatmap::Heatmap() (e.g. cluster_rows, cluster_columns). A row_split/column_split passed here wins over rows.group.by/columns.group.by; in dotplot mode rect_gp is set to gpar(type = "none") unless supplied here.

Value

A ComplexHeatmap::Heatmap object, undrawn. It does not compose with +; print it or call ComplexHeatmap::draw() on it to render.

Details

Every value is read from the association table as it stands; the only derivation is the significance cut that turns asterisk.by into stars (**** at or below 1e-4, *** at or below 1e-3, ** at or below 1e-2, * at or below 0.05, blank above and for NA).

Row and column order follow the factor levels of rows.by/columns.by when those are factors, dropping absent levels, and first appearance otherwise. Each rows.by x columns.by combination must appear at most once; a repeated cell aborts rather than being silently overwritten. Absent combinations are drawn in the neutral background color. The legend is titled with the color.by expression.

Examples

assoc <- data.frame(
  predictor = rep(c("PRS.AD", "PRS.T2D"), each = 2),
  outcome   = rep(c("dementia", "diabetes"), 2),
  estimate  = c(0.42, 0.05, 0.03, 0.51),
  adj.pval  = c(1e-5, 0.4, 0.6, 1e-7))
if (requireNamespace("ComplexHeatmap", quietly = TRUE)) {
  visualize$associations$heatmap(assoc)
  # dotplot: radius encodes a second quantity
  visualize$associations$heatmap(assoc, size.by = -log10(adj.pval))
}