Plot CNV Heatmap

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().

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.

Value

A plot of class aplot.

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.

Tutorials

Extensive tutorials for how to use this function can be found on our website https://themilolab.github.io/SPATA2/ .