Contents

visualize$data$scores$heatmap

visualize PRS score matrices as heatmaps

Draws one matrix from data$scores as a samples-by-models heatmap using ComplexHeatmap, or models-by-samples when flip.orientation = TRUE. Annotations, labels, splits and facets on either axis are resolved with data$fetch().

Usage

visualize.scores.heatmap(
  data,
  scores.layer = X,
  annotate.samples.by = NULL,
  annotate.models.by = NULL,
  annotate.samples.color = NULL,
  annotate.models.color = NULL,
  samples.labels = NULL,
  models.labels = NULL,
  split.samples.by = NULL,
  split.models.by = NULL,
  facet.samples.by = NULL,
  facet.models.by = NULL,
  palette = NULL,
  n.breaks = 11L,
  symmetrize.range = FALSE,
  center.zero = FALSE,
  max.samples = 5000L,
  max.models = 500L,
  flip.orientation = FALSE,
  ...
)

Arguments

Argument	Description
`data`	A PolyGeniusStudy carrying at least one scores layer. A summary-mode study (no genotype backend attached, or an empty samples table) is refused, because this plot reads the score matrix directly.
`scores.layer`	Unquoted score-layer name, default X. Layer of data$scores to draw; data$scores.keys lists the available layers.
`annotate.samples.by`	Sample-side unquoted expression(s), usually c(...) or list(...), or NULL (default) for none. Drawn as row annotations, or column annotations when flip.orientation = TRUE.
`annotate.models.by`	Model-side unquoted expression(s), usually c(...) or list(...), or NULL (default) for none. Drawn as column annotations, or row annotations when flip.orientation = TRUE.
`annotate.samples.color`	Named list of colors for the sample-side annotations, keyed by annotation column, or NULL (default). Categorical annotations take a named color vector, continuous ones a color-mapping function such as circlize::colorRamp2(); keys matching no annotation are dropped and an unnamed element aborts.
`annotate.models.color`	Named list of colors for the model-side annotations, or NULL (default). Same form as annotate.samples.color.
`samples.labels`	Single sample-side unquoted expression, or NULL (default) to use the matrix dimnames. Used as row labels, or column labels when flip.orientation = TRUE, and drawn as given, repeats included. A c()/list() expression aborts.
`models.labels`	Single model-side unquoted expression, or NULL (default) to use the model names. Used as column labels, or row labels when flip.orientation = TRUE. A name or label shared by more than one drawn model carries a [#<position>] suffix, its position in data. A c()/list() expression aborts.
`split.samples.by`	Single sample-side unquoted expression, or NULL (default) to leave the axis unsplit. Drives row_split, or column_split when flip.orientation = TRUE; NA values form their own "NA" group.
`split.models.by`	Single model-side unquoted expression, or NULL (default) to leave the axis unsplit. Drives column_split, or row_split when flip.orientation = TRUE.
`facet.samples.by`	Single sample-side unquoted expression, or NULL (default) for one heatmap. Splits the matrix into separate heatmaps, stacked vertically, or concatenated horizontally when flip.orientation = TRUE.
`facet.models.by`	Single model-side unquoted expression, or NULL (default) for one heatmap. Splits the matrix into separate heatmaps, concatenated horizontally, or stacked vertically when flip.orientation = TRUE.
`palette`	Color palette for the score body: a palette-system or hue name, a vector of two or more colors, a colorRampPalette/circlize::colorRamp2 function, or NULL (default). NULL takes the package ramp whose role matches the matrix actually drawn, decided after thinning -- diverging when any drawn value is negative, sequential otherwise, since a raw score layer has no meaningful midpoint and a standardized one does.
`n.breaks`	Integer scalar, default 11L. Number of color breaks sampled from palette; must be at least 2, and odd and at least 3 when center.zero = TRUE.
`symmetrize.range`	Logical scalar, default FALSE. Forces the color range symmetric about zero. Forced TRUE whenever the drawn matrix contains a negative value, so a diverging ramp pivots on zero rather than on the arithmetic midrange.
`center.zero`	Logical scalar, default FALSE. Requires zero to be an explicit center break. Aborts unless the range spans zero or symmetrize.range is TRUE.
`max.samples`	Numeric scalar, default 5000L. Cap on the samples drawn (rows in the native orientation), applied by systematic evenly-spaced thinning across the full sample set and reported when it fires; a larger value or Inf disables it. The matrix alone is 2.0 GB at the 50,000-sample by 5,000-model corner case.
`max.models`	Numeric scalar, default 500L. Cap on the models drawn (columns in the native orientation), by the same systematic thinning; a larger value or Inf disables it.
`flip.orientation`	Logical scalar, default FALSE. FALSE keeps the native PolyGeniusStudy orientation, samples as rows and models as columns; TRUE transposes it. NA or a longer vector aborts.
`...`	Further arguments passed to ComplexHeatmap::Heatmap(); use_raster = TRUE is the house default (from ht.opt.polygenius()) unless overridden here. Passing row_labels, column_labels, left_annotation, top_annotation, row_split or column_split alongside the argument that also sets it aborts naming both.

Value

Depends on which facet arguments are supplied: neither — a ComplexHeatmap::Heatmap.

one, resolving to one level — a ComplexHeatmap::Heatmap.

one, resolving to several levels — a ComplexHeatmap::HeatmapList, already concatenated in the facet direction.

both — a list named by row-facet level, each element the concatenated strip for that level. ComplexHeatmap has no grid concatenation, so the two-axis case cannot reduce to one object -- draw the elements separately. None of these compose with + as a ggplot does; print or ComplexHeatmap::draw() them.

Details

The score matrix is drawn as stored; nothing is recomputed. max.samples and max.models thin before any facet, split, label or annotation is resolved, so every drawn cell comes from the same already-bounded subset. A sample-side or model-side expression data$fetch() cannot resolve aborts, as does a layer with no finite value at all. Facets follow the visual orientation, not the axis name: a row facet stacks vertically (ComplexHeatmap's %v%) and a column facet concatenates horizontally (+).

Examples

visualize$data$scores$heatmap(study, annotate.samples.by = c(sex, age))

# Facet the model axis; each level becomes one horizontally concatenated panel.
visualize$data$scores$heatmap(study, facet.models.by = trait, max.samples = 500)