do_EnrichmentHeatmap {SCpubr}

Create enrichment scores heatmaps.

Description

This function computes the enrichment scores for the cells using AddModuleScore and then aggregates the scores by the metadata variables provided by the user and displays it as a heatmap, computed by Heatmap.

Usage

do_EnrichmentHeatmap(
  sample,
  input_gene_list,
  features.order = NULL,
  groups.order = NULL,
  cluster = TRUE,
  scale_scores = TRUE,
  assay = NULL,
  slot = NULL,
  reduction = NULL,
  group.by = NULL,
  verbose = FALSE,
  na.value = "grey75",
  legend.position = "bottom",
  use_viridis = FALSE,
  viridis.palette = "G",
  viridis.direction = 1,
  legend.framewidth = 0.5,
  legend.tickwidth = 0.5,
  legend.length = 20,
  legend.width = 1,
  legend.framecolor = "grey50",
  legend.tickcolor = "white",
  legend.type = "colorbar",
  font.size = 14,
  font.type = "sans",
  axis.text.x.angle = 45,
  enforce_symmetry = FALSE,
  nbin = 24,
  ctrl = 100,
  flavor = "Seurat",
  legend.title = NULL,
  ncores = 1,
  storeRanks = TRUE,
  min.cutoff = NA,
  max.cutoff = NA,
  pt.size = 1,
  plot_cell_borders = TRUE,
  border.size = 2,
  return_object = FALSE,
  number.breaks = 5,
  sequential.palette = "YlGnBu",
  diverging.palette = "RdBu",
  diverging.direction = -1,
  sequential.direction = 1,
  flip = FALSE,
  grid.color = "white",
  border.color = "black",
  plot.title.face = "bold",
  plot.subtitle.face = "plain",
  plot.caption.face = "italic",
  axis.title.face = "bold",
  axis.text.face = "plain",
  legend.title.face = "bold",
  legend.text.face = "plain"
)

Arguments

sample

Seurat | A Seurat object, generated by CreateSeuratObject.

input_gene_list

named_list | Named list of lists of genes to be used as input.

features.order

character | Should the gene sets be ordered in a specific way? Provide it as a vector of characters with the same names as the names of the gene sets.

groups.order

named_list | Should the groups in theheatmaps be ordered in a specific way? Provide it as a named list (as many lists as values in group.by) with the order for each of the elements in the groups.

cluster

logical | Whether to perform clustering of rows and columns.

scale_scores

logical | Whether to transform the scores to a range of 0-1 for plotting.

assay

character | Assay to use. Defaults to the current assay.

slot

character | Data slot to use. Only one of: counts, data, scale.data. Defaults to "data".

reduction

character | Reduction to use. Can be the canonical ones such as "umap", "pca", or any custom ones, such as "diffusion". If you are unsure about which reductions you have, use Seurat::Reductions(sample). Defaults to "umap" if present or to the last computed reduction if the argument is not provided.

group.by

character | Metadata variable to group the output by. Has to be a character of factor column.

verbose

logical | Whether to show extra comments, warnings,etc.

na.value

character | Color value for NA.

legend.position

character | Position of the legend in the plot. One of:

• top: Top of the figure.

• bottom: Bottom of the figure.

• left: Left of the figure.

• right: Right of the figure.

• none: No legend is displayed.

use_viridis

logical | Whether to use viridis color scales.

viridis.palette

character | A capital letter from A to H or the scale name as in scale_fill_viridis.

viridis.direction

numeric | Either 1 or -1. Controls how the gradient of viridis scale is formed.

legend.framewidth, legend.tickwidth

numeric | Width of the lines of the box in the legend.

legend.length, legend.width

numeric | Length and width of the legend. Will adjust automatically depending on legend side.

legend.framecolor

character | Color of the lines of the box in the legend.

legend.tickcolor

character | Color of the ticks of the box in the legend.

legend.type

character | Type of legend to display. One of:

• normal: Default legend displayed by ggplot2.

• colorbar: Redefined colorbar legend, using guide_colorbar.

font.size

numeric | Overall font size of the plot. All plot elements will have a size relationship with this font size.

font.type

character | Base font family for the plot. One of:

• mono: Mono spaced font.

• serif: Serif font family.

• sans: Default font family.

axis.text.x.angle

numeric | Degree to rotate the X labels. One of: 0, 45, 90.

enforce_symmetry

logical | Whether the geyser and feature plot has a symmetrical color scale.

nbin

numeric | Number of bins to use in AddModuleScore.

ctrl

numeric | Number of genes in the control set to use in AddModuleScore.

flavor

character | One of: Seurat, UCell. Compute the enrichment scores using AddModuleScore or AddModuleScore_UCell.

legend.title

character | Title for the legend.

ncores

numeric | Number of cores used to run UCell scoring.

storeRanks

logical | Whether to store the ranks for faster UCell scoring computations. Might require large amounts of RAM.

min.cutoff, max.cutoff

numeric | Set the min/max ends of the color scale. Any cell/group with a value lower than min.cutoff will turn into min.cutoff and any cell with a value higher than max.cutoff will turn into max.cutoff. In FeaturePlots, provide as many values as features. Use NAs to skip a feature.

pt.size

numeric | Size of the dots.

plot_cell_borders

logical | Whether to plot border around cells.

border.size

numeric | Width of the border of the cells.

return_object

logical | Return the Seurat object with the enrichment scores stored.

number.breaks

numeric | Controls the number of breaks in continuous color scales of ggplot2-based plots.

sequential.palette

character | Type of sequential color palette to use. Out of the sequential palettes defined in brewer.pal.

diverging.palette

character | Type of symmetrical color palette to use. Out of the diverging palettes defined in brewer.pal.

diverging.direction

numeric | Either 1 or -1. Direction of the divering palette. This basically flips the two ends.

sequential.direction

numeric | Direction of the sequential color scale. Either 1 or -1.

flip

logical | Whether to invert the axis of the displayed plot.

grid.color

character | Color of the grid in the plot. In heatmaps, color of the border of the cells.

border.color

character | Color for the border of the heatmap body.

plot.title.face, plot.subtitle.face, plot.caption.face, axis.title.face, axis.text.face, legend.title.face, legend.text.face

character | Controls the style of the font for the corresponding theme element. One of:

• plain: For normal text.

• italic: For text in itallic.

• bold: For text in bold.

• bold.italic: For text both in itallic and bold.

Value

A ggplot2 object.

Examples

  # Check Suggests.
  value <- SCpubr:::check_suggests(function_name = "do_EnrichmentHeatmap", passive = TRUE)

  if (isTRUE(value)){
    # Consult the full documentation in https://enblacar.github.io/SCpubr-book/

    # Define your Seurat object.
    sample <- readRDS(system.file("extdata/seurat_dataset_example.rds", package = "SCpubr"))

    # Genes have to be unique.
    genes <- list("A" = rownames(sample)[1:5],
                  "B" = rownames(sample)[6:10],
                  "C" = rownames(sample)[11:15])

    # Default parameters.
    p <- SCpubr::do_EnrichmentHeatmap(sample = sample,
                                      input_gene_list = genes,
                                      nbin = 1,
                                      ctrl = 10)
    p

  } else if (base::isFALSE(value)){
    message("This function can not be used without its suggested packages.")
    message("Check out which ones are needed using `SCpubr::state_dependencies()`.")
  }