plotCnvHeatmap: Plot CNV Heatmap
In theMILOlab/SPATA2: A Toolbox for Spatial Expression Analysis

plotCnvHeatmap

R Documentation

Plot CNV Heatmap

Description

Plots the results of runCNV() in form of a heatmap. Use arguments across and across_subset to visualize CNV differences between subgroups of cluster variables or other grouping variables (e.g. based on histology created with createSpatialSegmentation().

Usage

plotCnvHeatmap(
  object,
  across = NULL,
  across_subset = NULL,
  relevel = NULL,
  arm_subset = c("p", "q"),
  chrom_subset = 1:22,
  chrom_separate = 1:22,
  chrom_arm_subset = NULL,
  n_bins_bcsp = 500,
  n_bins_genes = 500,
  summarize_with = "mean",
  display_arm_annotation = TRUE,
  colors_arm_annotation = c(p = "white", q = "black"),
  display_chrom_annotation = FALSE,
  display_chrom_names = TRUE,
  text_alpha = 1,
  text_color = "black",
  text_position = "top",
  text_size = 3.5,
  display_hlines = is.character(across),
  hline_alpha = 0.75,
  hline_color = "black",
  hline_size = 0.5,
  hline_type = "dashed",
  display_vlines = TRUE,
  vline_alpha = 0.75,
  vline_color = "black",
  vline_size = 0.5,
  vline_type = "dashed",
  display_border = TRUE,
  border_color = "black",
  border_size = 0.5,
  clrp = NULL,
  clrp_adjust = NULL,
  clrsp = "Blue-Red 3",
  limits = NULL,
  meta_vars = NULL,
  meta_vars_clrs = list(),
  normalize = NULL,
  arrange_by = across,
  arrange_desc = FALSE,
  annotation_size_top = 0.025,
  annotation_size_side = 0.025,
  pretty_name = TRUE,
  ggpLayers = list(),
  bcs_rm = NULL,
  verbose = NULL,
  ...
)

Arguments

`object`	An object of class `SPATA2` or, in case of S4 generics, objects of classes for which a method has been defined.
`across`	Character value or NULL. Specifies the grouping variable of interest. Use `getGroupingOptions()` to obtain all variable names that group the barcode spots of your object in a certain manner.
`across_subset`	Character vector or NULL. Specifies the particular groups of interest the grouping variable specified in argument `across` contains. If set to NULL all of them are chosen. You can prefix groups you are NOT interested in with a '-'. (Saves writing if there are more groups you are interested in than groups you are not interested in.) Use `getGroupNames()` to obtain all valid input options.
`relevel`	Logical value. If set to TRUE the input order of `across_subset` determines the order in which the groups of interest are displayed. Groups that are not included are dropped which affects the colors with which they are displayed.
`arm_subset`	Character vector. A combination of 'p' and/or 'q'. Denotes which chromosome arms are included. Defaults to both.
`chrom_subset`	Character or numeric vector. Denotes the chromosomes that are included. Defaults to all 1-22.
`chrom_separate`	Character or numeric vector. Denotes the chromosomes that are separated from their neighbors by vertical lines. Defaults to all 1-22. If FALSE or NULL, no vertical lines are drawn. Requires `display_vlines` to be set to TRUE.
`chrom_arm_subset`	Character vector. Denotes the exact chromosome-arm combinations that are included.
`n_bins_bcsp`, `n_bins_genes`	Numeric values. Denotes the number of bins into which CNV results of barcode-spot ~ gene pairs are summarized. Reduces the plotting load. Set to `Inf` if you want all barcode-spots ~ gene pairs to be plotted in one tile. `n_bins_bcsp` effectively specifies the number of rows of the heatmap, `n_bins_genes` specifies the number of columns.
`summarize_with`	Character value. Name of the function with which to summarize. Either 'mean' or 'median'.
`display_arm_annotation`	Logical value. If TRUE, guiding information of the chromosome arms are plotted on top of the heatmap.
`colors_arm_annotation`	Named character vector. Denotes the colors with which the chromosome arms are displayed. Names must be 'p' and/or 'q'.
`display_chrom_annotation`	Logical value. If TRUE, guiding information of the chromosomes are plotted on top of the heatmap.
`display_chrom_names`	Logical value. If TRUE, the chromosome names/numbers are plotted on top or on the bottom of the heatmap.
`text_alpha`, `text_color`, `text_size`	Parameters given to `ggplot2::geom_text()` that are used to manipulate the appearance of the chromosome names.
`text_position`	Character value. Either 'top' or 'bottom'.
`display_hlines`	Logical value. If TRUE and if `across` is not NULL, horizontal lines are drawn to aid the eye by separating the grouping rows of the heatmap. Appearance of the lines can be adjusted with the `hline`-arguments.
`hline_alpha`, `hline_color`, `hline_size`, `hline_type`	Parameters given to `ggplot2::geom_hline()` that control the appearance of vertical lines of the plot.
`display_vlines`	Logical value. If TRUE, vertical lines are drawn to aid the eye by separating the chromosome columns of the heatmap. Appearance of the lines can be adjusted with the `vlines`-arguments.
`vline_alpha`, `vline_color`, `vline_size`, `vline_type`	Parameters given to `ggplot2::geom_vline()` that control the appearance of vertical lines of the plot.
`display_border`	Logical value. If TRUE, a border is drawn around the heatmap and each annotation. Can be provided as a named vector to adress single parts of the heatmap. Valid names are 'arm', 'chrom', 'grouping' and 'main'.
`border_color`, `border_size`	Impact the appearance of the border if `display_border` is TRUE.
`clrp`	Character value. Specifies the color palette to be used to represent groups of discrete variables. Run `validColorPalettes()` to obtain valid input options.
`clrp_adjust`	Named character vector or NULL. If character, it adjusts the color palette that is used to represent the groups. Names of the input vector must refer to the group and the respective named element denotes the color with which to represent the group.
`clrsp`	Character vector. The colorspectrum with which the tiles of the heatmap are colored. Should be one of `validColorSpectra()[['Diverging']]`.
`limits`	Numeric vector of length two or `NULL`. If numeric, sets the limits of the colorscale (`oob` is set to `scales::squish`).
`meta_vars`	Character vector or `NULL`. If character, the variables to display o
`normalize`	Logical. If set to TRUE values will be scaled to 0-1. Hint: Variables that are uniformly expressed can not be scaled and are discarded.
`annotation_size_top`, `annotation_size_side`	Numeric values. Used to adjust the size of the row/column annotation of the heatmap.
`pretty_name`	Logical. If TRUE makes legend names pretty.
`ggpLayers`	A list of additional `gg` elements to customize the output plot. See details for more.
`bcs_rm`	Character vector or `NULL`. If character, specifies the observations to be removed prior to analysis or visualization by their barcode.
`verbose`	Logical. If `TRUE`, informative messages regarding the computational progress will be printed. (Warning messages will always be printed.)
`...`	Used to absorb deprecated arguments or functions.

Details

The output plot of this function consists of several elements - each element being a ggplot. These elements are combined/aligned using the aplot package. Therefore, the output plot is of class aplot and can not be adjusted by adding additional gg objects using the + operator of the ggplot2 framework.

Individual customization is still possible with the ggpLayers argument. Every single element of the output plot is named:

main: The heatmap itself and the horizontal and vertical lines.
arm: The arm annotation on top of the heatmap.
chrom: The chromosome annotation on top of the heatmap. (not displayed by default)
names: The chromosome name annotation on top of the heatmap.
grouping: The grouping annotation on the left side of the heatmap if across is not NULL.

ggpLayers takes a list as input. Unnamed elements of the list are added to all elements of the plot. E.g.: ggpLayers = list(theme(legend.position = "none")) removes all legends.

To address single elements of the output plot corresponding elements of the list must be named. E.g.: ggpLayers = list(grouping = theme(legend.position = "none")) removes only the legend of the grouping while leaving the legends that come with other plot elements as they are.