Contents

visualize$data$scores$distribution.heatmap

visualize PRS score distributions as heatmaps

Reduces one score layer to a model-by-distribution heatmap: one row per model, one column per density grid point or histogram bin, on a score grid shared by every row so rows are comparable. Requires ComplexHeatmap.

Usage

visualize.scores.distribution.heatmap(
  data,
  scores.layer = X,
  models = NULL,
  samples = NULL,
  type = c("density", "histogram"),
  n.bins = 100L,
  annotate.models.by = NULL,
  annotate.models.color = NULL,
  models.labels = NULL,
  split.models.by = NULL,
  facet.samples.by = NULL,
  palette = NULL,
  n.breaks = 11L,
  symmetrize.range = FALSE,
  center.zero = FALSE,
  max.models = 500L,
  ...
)

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. Must be numeric and matrix-like.
`models`	Unquoted model-side subsetting selector, or NULL (default) to keep every model: numeric positions, model names, a logical vector, or a single logical expression resolved with data$fetch(.context = "models"). A fetching expression, one returning data rather than a selection, aborts.
`samples`	Unquoted sample-side subsetting selector, or NULL (default) to keep every sample. Same forms as models.
`type`	One of "density" (default), "histogram". Distribution summary each row carries.
`n.bins`	Integer scalar, default 100L. Number of density grid points or histogram bins; must be a whole number of at least 2.
`annotate.models.by`	Model-side unquoted expression(s), usually c(...) or list(...), or NULL (default) for none. Drawn as row annotations.
`annotate.models.color`	Named list of colors for the row 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.
`models.labels`	Single model-side unquoted expression, or NULL (default) to use the model names. Used as row labels. 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.models.by`	Single model-side unquoted expression, or NULL (default) to leave the rows unsplit. Drives row_split.
`facet.samples.by`	Single sample-side unquoted expression, or NULL (default) for one panel over all selected samples. Samples are split by its levels, each group's distributions are computed separately on the shared grid, and the panels are concatenated horizontally.
`palette`	Color palette for the distribution body: a palette-system or hue name, a vector of two or more colors, a colorRampPalette/circlize::colorRamp2 function, or NULL (default) for the package sequential green ramp.
`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, which mostly spends half the ramp on values that cannot occur -- densities and counts are non-negative.
`center.zero`	Logical scalar, default FALSE. Requires zero to be an explicit center break. Aborts on non-negative distribution values unless symmetrize.range is TRUE.
`max.models`	Numeric scalar, default 500L. Cap on the rows drawn, applied after the models filter by systematic evenly-spaced thinning and reported when it fires; a larger value or Inf disables it.
`...`	Further arguments passed to ComplexHeatmap::Heatmap(); use_raster = TRUE is the house default (from ht.opt.polygenius()) unless overridden here. cluster_columns is always FALSE and passing it aborts, because the columns are an ordered score grid.

Value

A ComplexHeatmap::Heatmap, or a horizontally concatenated ComplexHeatmap::HeatmapList when facet.samples.by resolves to more than one level. Neither composes with + as a ggplot does; print or ComplexHeatmap::draw() it.

Details

Rows are a display summary of data$scores[[scores.layer]] -- stats::density() evaluated on the shared grid, or graphics::hist() counts over the shared breaks -- and no statistic from the study is recomputed. The grid is fixed once from every selected sample, before any sample facet, so facets share one x-axis and one color scale; a degenerate layer whose values are all equal is widened by 1% of its magnitude, or by 1 at zero, so the grid has a width. A model with no finite score gives an all-zero row, and one with a single distinct value gives a spike of height n at the nearest grid point rather than a kernel density.

A non-numeric or non-matrix-like layer aborts, as does a models or samples selector that matches nothing, and a layer with no finite value at all.

Examples

visualize$data$scores$distribution.heatmap(study)

visualize$data$scores$distribution.heatmap(
  study,
  type             = "histogram",
  n.bins           = 50,
  facet.samples.by = diagnosis
)