Skip to contents

Plots for GSVA (Gene Set Variation Analysis)

Source: R/GSVAPlot.R
GSVAPlot.Rd

Plots for GSVA (Gene Set Variation Analysis)

Usage

GSVAPlot(
  srt = NULL,
  res = NULL,
  group.by = NULL,
  sample.by = NULL,
  assay_name = "GSVA",
  db = NULL,
  mode = c("score", "diff"),
  plot_type = c("heatmap", "bar", "network", "enrichmap", "wordcloud", "comparison",
    "volcano"),
  split_by = c("Database", "Groups"),
  color_by = "Database",
  group_use = NULL,
  features = NULL,
  topTerm = NULL,
  score_cutoff = NULL,
  sort.by = c("abs", "score"),
  aggregate.fun = c("mean", "median"),
  test.use = c("wilcox", "t.test"),
  p.adjust.method = "BH",
  pvalueCutoff = NULL,
  padjustCutoff = NULL,
  topWord = 100,
  word_type = c("term", "feature"),
  word_size = c(2, 8),
  network_layout = "fr",
  network_labelsize = 5,
  network_blendmode = "blend",
  network_layoutadjust = TRUE,
  network_adjscale = 60,
  network_adjiter = 100,
  enrichmap_layout = "fr",
  enrichmap_cluster = "fast_greedy",
  enrichmap_label = c("term", "feature"),
  enrichmap_labelsize = 5,
  enrlichmap_nlabel = 4,
  enrichmap_show_keyword = FALSE,
  enrichmap_mark = c("ellipse", "hull"),
  enrichmap_expand = c(0.5, 0.5),
  words_excluded = NULL,
  lineheight = 0.7,
  feature_split = NULL,
  n_split = NULL,
  split_order = NULL,
  split_method = c("kmeans", "hclust", "mfuzz"),
  decreasing = FALSE,
  fuzzification = NULL,
  cluster_rows = FALSE,
  cluster_columns = FALSE,
  cluster_row_slices = FALSE,
  show_row_names = FALSE,
  show_column_names = FALSE,
  row_names_side = "right",
  column_names_side = "bottom",
  row_names_rot = 0,
  column_names_rot = 90,
  character_width = 50,
  palette = "simspec",
  palcolor = NULL,
  group_palette = "Chinese",
  group_palcolor = NULL,
  heatmap_palette = "RdBu",
  heatmap_palcolor = NULL,
  limits = NULL,
  height = NULL,
  width = NULL,
  units = "inch",
  use_raster = NULL,
  raster_device = "png",
  raster_by_magick = FALSE,
  ht_params = list(),
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  theme_use = "theme_scop",
  theme_args = list(),
  combine = TRUE,
  return_data = FALSE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  border = TRUE,
  nlabel = 0,
  seed = 11,
  verbose = TRUE
)

Arguments

srt

A Seurat object containing the results of RunGSVA. If specified, GSVA results will be extracted from the Seurat object automatically. If not specified, the res argument must be provided.

res

GSVA results generated by RunGSVA function. If provided, 'srt' and 'group.by' are ignored.

group.by

Grouping variable used in RunGSVA.

sample.by

Metadata column identifying biological samples for sample-level aggregation. Required when mode = "diff".

assay_name

Assay or tools slot containing GSVA results.

db

The database name used in RunGSVA. Only used for compatibility with EnrichmentPlot. Default is NULL (will be inferred from GSVA results or set to "GSVA").

mode

Plot mode. "score" keeps the original GSVA score plotting behavior; "diff" performs a two-group differential pathway activity test on sample-aggregated GSVA scores.

plot_type

The type of plot to generate. Options are: "heatmap", "bar", "network", "enrichmap", "wordcloud", "comparison", and "volcano". When omitted, the default is "heatmap" for mode = "score" and "volcano" for mode = "diff".

split_by

The splitting variable(s) for the plot. Can be "Database", "Groups", or both.

color_by

The variable used for coloring.

group_use

The group(s) to be used for GSVA plot. Default is NULL (all groups).

features

Features to plot.

topTerm

The number of top terms to display. Default is 6, or 100 if plot_type is "enrichmap".

score_cutoff

The score cutoff for the GSVA plot. Default is NULL (no cutoff).

sort.by

Ranking metric used when return_data = TRUE in mode = "score". "abs" uses absolute GSVA score and "score" uses signed GSVA score.

aggregate.fun

Function used to aggregate cells within each sample.by and group.by combination in mode = "diff". Supports "mean" and "median".

test.use

Statistical test for mode = "diff". Supports "wilcox" and "t.test".

p.adjust.method

Multiple-testing correction method passed to stats::p.adjust() in mode = "diff".

pvalueCutoff

The p-value cutoff. Only work when padjustCutoff is NULL.

padjustCutoff

The p-adjusted cutoff.

topWord

The number of top words to display for wordcloud.

word_type

The type of words to display in wordcloud. Options are "term" and "feature".

word_size

The size range for words in wordcloud.

network_layout

The layout algorithm to use for network plot. Options are "fr", "kk", "random", "circle", "tree", "grid", or other algorithm from igraph package.

network_labelsize

The label size for network plot.

network_blendmode

The blend mode for network plot.

network_layoutadjust

Whether to adjust the layout of the network plot to avoid overlapping words.

network_adjscale

The scale for adjusting network plot layout.

network_adjiter

The number of iterations for adjusting network plot layout.

enrichmap_layout

The layout algorithm to use for enrichmap plot. Options are "fr", "kk", "random", "circle", "tree", "grid", or other algorithm from igraph package.

enrichmap_cluster

The clustering algorithm to use for enrichmap plot. Options are "walktrap", "fast_greedy", or other algorithm from igraph package.

enrichmap_label

The label type for enrichmap plot. Options are "term" and "feature".

enrichmap_labelsize

The label size for enrichmap plot.

enrlichmap_nlabel

The number of labels to display for each cluster in enrichmap plot.

enrichmap_show_keyword

Whether to show the keyword of terms or features in enrichmap plot.

enrichmap_mark

The mark shape for enrichmap plot. Options are "ellipse" and "hull".

enrichmap_expand

The expansion factor for enrichmap plot.

words_excluded

Words to be excluded from the wordcloud. Default is NULL, which means that the built-in words (words_excluded) will be used.

lineheight

The line height for y-axis labels.

feature_split

Feature splitting. split_method is "kmeans", "hclust", or "mfuzz".

n_split

Number of splits for feature dependencies.

split_order

Order of feature split groups (e.g. c("A", "B")).

split_method

Method for splitting features into groups.

decreasing

Order groups decreasingly.

fuzzification

Mfuzz fuzzification coefficient.

cluster_rows

Whether to cluster heatmap rows/columns. Defaults are both FALSE.

cluster_columns

Whether to cluster heatmap rows/columns. Defaults are both FALSE.

cluster_row_slices

Whether to cluster row slices.

show_row_names

Whether to draw row/column names for the heatmap body.

show_column_names

Whether to draw row/column names for the heatmap body.

row_names_side, column_names_side, row_names_rot, column_names_rot

Name placement.

character_width

The maximum width of character of descriptions.

palette, palcolor

Palette name (thisplot::show_palettes) or custom colors.

heatmap_palette, heatmap_palcolor, group_palette, group_palcolor

Heatmap and group colors.

limits

Color-scale limits (length 2).

width, height, units

Heatmap size. NULL sizes from matrix dimensions.

use_raster, raster_device, raster_by_magick

Raster device (NULL chooses automatically).

ht_params

Extra arguments passed to ComplexHeatmap::Heatmap, overriding defaults.

aspect.ratio

Panel aspect ratio.

legend.position

Legend side ("right", "left", "top", "bottom"). Gap to the heatmap grows automatically when long row names are on the right.

legend.direction

Legend direction: "horizontal" or "vertical".

theme_use, theme_args

Theme name or function, plus extra theme arguments.

combine, nrow, ncol, byrow

Combine plots with patchwork. combine = FALSE returns a list of ggplots.

return_data

Whether to return the ranking/statistics table instead of a plot.

border

Draw borders. Kept for compatibility; more specific *_border arguments inherit this when NULL.

nlabel

The maximum number of labels to show on each side of the heatmap. If set to 0, no labels will be shown. This can be useful for reducing clutter in large heatmaps.

seed

Random seed.

verbose

Whether to print messages.

Details

GSVA itself returns pathway activity/enrichment scores, not statistical p-values. In mode = "score", plots use signed GSVA_Score values directly and score_cutoff is the only score threshold. Use mode = "diff" for real sample-level statistical tests and adjusted p-values on GSVA scores.

See also

RunGSVA, EnrichmentPlot

Examples

data(pancreas_sub)
pancreas_sub <- pancreas_sub[, 1:80]
pancreas_sub <- Seurat::NormalizeData(pancreas_sub, verbose = FALSE)
features_all <- rownames(pancreas_sub)
pancreas_sub <- RunGSVA(
  pancreas_sub,
  features = list(
    A = features_all[1:5],
    B = features_all[6:10]
  ),
  method = "zscore",
  minGSSize = 2,
  min.sz = 2
)
#> ℹ [2026-08-30 04:31:17] Start GSVA analysis
#> ℹ [2026-08-30 04:31:17] Single-cell GSVA mode: using expression matrix directly ...
#> ℹ [2026-08-30 04:31:17] Expression matrix: 12238 genes x 80 cells
#> ℹ [2026-08-30 04:31:17] Processing database: "custom" ...
#> ℹ [2026-08-30 04:31:17] Initial overlap: 6 genes out of 12238 expression genes and 10 genes in gene sets
#> ℹ [2026-08-30 04:31:17] Running GSVA for 2 gene sets ...
#> Warning: Feature names cannot have underscores ('_'), replacing with dashes ('-')
#> Warning: Layer counts isn't present in the assay object; returning NULL
#> ℹ [2026-08-30 04:31:17] GSVA results stored in assay "GSVA", meta.data, and tools slot "GSVA_cell_zscore"
#> ✔ [2026-08-30 04:31:17] GSVA analysis done

ht <- GSVAPlot(
  pancreas_sub,
  plot_type = "heatmap",
  group.by = "CellType",
  topTerm = 2,
  width = 1,
  height = 2
)
#> Warning: Data is of class matrix. Coercing to dgCMatrix.
ht$plot


GSVAPlot(
  srt = pancreas_sub,
  group.by = "CellType",
  plot_type = "comparison",
  topTerm = 1
)


GSVAPlot(
  srt = pancreas_sub,
  group.by = "CellType",
  plot_type = "bar",
  topTerm = 2
)