Enrichment Plot

Generates various types of plots for enrichment (over-representation) analysis.

Usage

EnrichmentPlot(
  object = NULL,
  db = "GO_BP",
  group.by = NULL,
  test.use = "wilcox",
  res = NULL,
  plot_type = c("bar", "annotated_bar", "dot", "lollipop", "network", "enrichmap",
    "wordcloud", "comparison", "rank"),
  split_by = c("Database", "Groups"),
  color_by = "Database",
  group_use = NULL,
  id_use = NULL,
  pvalueCutoff = NULL,
  padjustCutoff = 0.05,
  score_col = NULL,
  scoreCutoff = NULL,
  score_label = "Score",
  topTerm = ifelse(plot_type == "enrichmap", 100, ifelse(plot_type == "rank", 80, 6)),
  compare_only_sig = FALSE,
  topWord = 100,
  word_type = c("term", "feature"),
  word_size = c(2, 8),
  words_excluded = NULL,
  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,
  enrichmap_nlabel = 4,
  enrlichmap_nlabel = NULL,
  enrichmap_show_keyword = FALSE,
  enrichmap_mark = c("ellipse", "hull"),
  enrichmap_expand = c(0.5, 0.5),
  character_width = if (plot_type == "rank") 26 else 50,
  lineheight = 0.7,
  palette = if (plot_type == "rank") "Chinese" else "Spectral",
  palcolor = NULL,
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  theme_use = "theme_scop",
  theme_args = list(),
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  seed = 11,
  verbose = TRUE,
  srt = NULL,
  rank_by = "FoldEnrichment",
  rank_nlabel = 5,
  rank_label_terms = NULL,
  rank_pt_size = c(2, 5),
  rank_pt_alpha = 0.23,
  rank_label_size = 3.2,
  grid_major = TRUE,
  rank_shared_y = FALSE,
  show_genes = TRUE,
  show_count = TRUE,
  gene_width = 70,
  row_step = 0.82,
  db_gap = 0.2
)

Arguments

object: A Seurat object containing the results of RunDEtest and RunEnrichment. If specified, enrichment results will be extracted from the Seurat object automatically. If not specified, the res arguments must be provided.
db: The database to use for enrichment plot.
group.by: Grouping variable in the Seurat object. This argument is only used if object is specified. NULL (the default) selects the results that RunEnrichment stored for custom gene sets or custom cell groups, which are keyed as "custom".
test.use: Test to be used in differential expression analysis. This argument is only used if object is specified.
res: Enrichment results generated by RunEnrichment function. If provided, 'object', 'test.use' and 'group.by' are ignored.
plot_type: The type of plot to generate. "rank" displays existing enrichment results as ranked solid points, with one panel per group. Options are "bar", "annotated_bar", "dot", "lollipop", "network", "enrichmap", "wordcloud", "comparison", and "rank". "annotated_bar" draws horizontal bars with database bands, term labels, hit-gene labels and optional Count dots.
split_by: The splitting variable(s) for the plot. Can be "Database", "Groups", or both. Default is c("Database", "Groups") for plots. For "annotated_bar", the default is "Groups" (database bands within each group). Including "Database" creates separate database panels; groups are always kept in separate panels in this mode.
color_by: The variable used for coloring. Annotated bars use "Database": each database receives one palette color. As in the bar view of GSEAPlot, significance controls opacity (0.4 to 1). Bars, Count dots and hit-gene labels share the same color and opacity per term.
group_use: The group(s) to be used for enrichment plot.
id_use: List of IDs to be used to display specific terms in the enrichment plot. Default value is NULL.
pvalueCutoff: The p-value cutoff. Only work when padjustCutoff is NULL.
padjustCutoff: The p-adjusted cutoff.
score_col: Optional numeric score column. When supplied, terms are ranked and weighted by the absolute score and no p-value semantics are used. This is intended for activity or importance results such as pathway scores.
scoreCutoff: Optional minimum absolute score used with score_col.
score_label: Legend label used with score_col.
topTerm: The number of top terms to display. Default is 6, 100 for "enrichmap", or 80 for "rank". Rank plots select the highest rank_by values after significance filtering.
compare_only_sig: Whether to compare only significant terms.
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.
words_excluded: Words to be excluded from the wordcloud. Default is NULL, which means that the built-in words (words_excluded) will be used.
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.
enrichmap_nlabel: The number of labels to display for each cluster in enrichmap plot.
enrlichmap_nlabel: Deprecated. Please use enrichmap_nlabel instead.
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.
character_width: The maximum width of character of descriptions.
lineheight: The line height for y-axis labels.
palette: Color palette name. Defaults to "Chinese" for rank plots and "Spectral" otherwise. Available palettes can be found in thisplot::show_palettes.
palcolor: Custom colors used to create a color palette.
aspect.ratio: Panel aspect ratio.
legend.position: Legend placement ("none", "left", "right", "bottom", "top"), direction, and title. legend.title = NULL uses the group name.
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.
seed: Random seed used for plot construction. The caller's RNG state is restored on return, including errors.
verbose: Whether to print messages.
srt: Deprecated alias for object; supply exactly one of the two. It will be removed in scop 1.0.0.
rank_by: Numeric enrichment column used for descending rank and the y-axis in rank plots. Default is "FoldEnrichment".
rank_nlabel: Number of leading terms to label per rank panel (default 5).
rank_label_terms: Optional term IDs or descriptions to label, or a named list by group. Only displayed terms are labeled; this does not select terms.
rank_pt_size: Positive increasing length-two point-size range for rank plots (default c(2, 5)), mapped to -log10(p.adjust).
rank_pt_alpha: Background-point opacity in rank plots, from 0 to 1.
rank_label_size: Text size for rank labels with black text and a white halo.
grid_major: Whether to show major panel grid lines for rank plots (default TRUE).
rank_shared_y: Whether rank panels share a y-axis range. Default is FALSE; compare numeric ticks when panels have independent ranges.
show_genes: Logical; display hit genes below each annotated bar label. Genes are taken from geneID as stored by RunEnrichment; no ID conversion is performed. Missing gene strings are displayed as blank labels.
show_count: Logical; display Count-sized dots beside annotated bars. Missing counts are omitted. Use legend.position = "none" to hide the legend.
gene_width: Positive integer (at least 4); maximum characters in an annotated bar's comma-separated hit-gene label, including the ellipsis. These three arguments apply only to "annotated_bar".
row_step: Positive numeric row spacing for annotated bars, at least 0.8; defaults to 0.82 for a compact layout.
db_gap: Non-negative numeric extra spacing between database bands in annotated bars; defaults to 0.2.

Value

A ggplot for one panel, a patchwork for combined panels, or a named list of plots when combine = FALSE. Annotated bars select up to topTerm terms per database and group, ordered by the selected p-value metric. Database bands follow db order and panels share the same x-axis range. Zero p-values are capped at .Machine$double.xmin before transformation; missing p-values are omitted with a warning in this mode.

A plot, or a list of plots when combine = FALSE. For "rank", the combined result is a patchwork with an enrichment_data attribute containing displayed terms, ranks, scores and label-selection flags; the uncombined result is a named list of ggplots with these columns in plot data.

Details

Rank plots require one database and adjusted P values in [0, 1]. They compare stored ORA results, not between-group differential significance. split_by and color_by do not change rank panels: each group has one panel and one color. Missing or nonfinite rank scores/adjusted P values are omitted with a warning. Zero adjusted P values are capped at .Machine$double.xmin only for the point-size transform. Groups without retained terms have empty panels; if no term passes the existing enrichment filter, an error is raised.

Annotated bars place term labels inside bars and hit genes underneath, with rounded database bands. Term text switches between black and white for the displayed fill. A thin contrasting outline keeps overflow text readable. Colors map one-to-one to db in the requested order; named palcolor values must cover all selected databases. Descriptions are truncated to at most character_width characters, with shorter limits for shorter bars. Actual text fit also depends on export dimensions and font size.

Examples

# Plot an existing ORA result without running enrichment again:
rank_result <- list(enrichment = data.frame(
  ID = paste0("term", 1:6), Description = paste("Pathway", 1:6),
  Groups = rep(c("A", "B"), each = 3), Database = "custom",
  p.adjust = c(0.001, 0.01, 0.02, 0.002, 0.01, 0.03),
  FoldEnrichment = c(8, 5, 3, 7, 4, 2)
))
EnrichmentPlot(
  res = rank_result, db = "custom", plot_type = "rank",
  rank_pt_size = c(2, 5), rank_nlabel = 2, ncol = 2
)


# Constructed results illustrating the annotated layout (not biological data).
annotated_res <- list(enrichment = data.frame(
  ID = c("term1", "term2"), Description = c("Response process", "Cell component"),
  Database = c("GO_BP", "GO_CC"), Groups = "Example",
  p.adjust = c(0.001, 0.01), geneID = c("GeneA/GeneB", "GeneC/GeneD"), Count = 2
))
EnrichmentPlot(res = annotated_res, db = "GO", plot_type = "annotated_bar")


data(pancreas_sub)
pancreas_sub <- RunStandardWorkflow(pancreas_sub)
#> ℹ [2026-11-12 05:13:11] Start standard processing workflow...
#> ℹ [2026-11-12 05:13:11] Checking a list of <Seurat>...
#> ! [2026-11-12 05:13:11] Data 1/1 of the `srt_list` is "unknown"
#> ℹ [2026-11-12 05:13:11] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on 1/1 of `srt_list`...
#> ℹ [2026-11-12 05:13:11] Perform `FindVariableFeatures()` on 1/1 of `srt_list`...
#> ℹ [2026-11-12 05:13:11] Use the separate HVF from `srt_list`
#> ℹ [2026-11-12 05:13:11] Number of available HVF: 2000
#> ℹ [2026-11-12 05:13:11] Finished check
#> ℹ [2026-11-12 05:13:11] Perform `ScaleData()`
#> ℹ [2026-11-12 05:13:11] Perform pca linear dimension reduction
#> ℹ [2026-11-12 05:13:11] Use stored estimated dimensions 1:23 for Standardpca
#> ℹ [2026-11-12 05:13:12] Perform `Seurat::FindClusters()` with `cluster_algorithm = 'louvain'` and `cluster_resolution = 0.6`
#> ℹ [2026-11-12 05:13:12] Reorder clusters...
#> ℹ [2026-11-12 05:13:12] Skip `log1p()` because `layer = data` is not "counts"
#> ℹ [2026-11-12 05:13:12] Perform umap nonlinear dimension reduction
#> ✔ [2026-11-12 05:13:20] Standard processing workflow completed
pancreas_sub <- RunDEtest(
  pancreas_sub,
  group.by = "CellType"
)
#> ℹ [2026-11-12 05:13:20] Data type is log-normalized
#> ℹ [2026-11-12 05:13:20] Start differential expression test
#> ℹ [2026-11-12 05:13:20] Find all markers(wilcox) among [1] 5 groups...
#> ✔ [2026-11-12 05:13:20] Differential expression test completed

pancreas_sub <- RunEnrichment(
  pancreas_sub,
  db = c("GO_BP", "GO_CC"),
  group.by = "CellType",
  species = "Mus_musculus"
)
#> ℹ [2026-11-12 05:13:20] Start Enrichment analysis
#> ℹ [2026-11-12 05:13:20] Species: "Mus_musculus"
#> ℹ [2026-11-12 05:13:20] Loading cached: GO_BP version: 3.23.0 nterm:14957 created: 2026-11-12 05:06:29
#> ℹ [2026-11-12 05:13:52] Preparing database: GO_BP
#> ℹ [2026-11-12 05:14:03] Preparing database: GO_CC
#> ℹ [2026-11-12 05:14:08] Convert ID types for the GO_BP database
#> ℹ [2026-11-12 05:14:08] Converted ID types using local annotation package org.Mm.eg.db
#> ℹ [2026-11-12 05:14:10] Convert ID types for the GO_CC database
#> ℹ [2026-11-12 05:14:10] Converted ID types using local annotation package org.Mm.eg.db
#> ℹ [2026-11-12 05:14:10] Permform enrichment...
#> ✔ [2026-11-12 05:14:12] Enrichment analysis done

EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "bar"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  plot_type = "bar",
  color_by = "Groups",
  ncol = 2
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  plot_type = "bar",
  id_use = list(
    "Ductal" = c(
      "GO:0002181", "GO:0045787",
      "GO:0006260", "GO:0050679"
    ),
    "Ngn3-low-EP" = c(
      "GO:0050678", "GO:0051101",
      "GO:0072091", "GO:0006631"
    ),
    "Ngn3-high-EP" = c(
      "GO:0035270", "GO:0030325",
      "GO:0008637", "GO:0030856"
    ),
    "Pre-endocrine" = c(
      "GO:0090276", "GO:0031018",
      "GO:0030073", "GO:1903532"
    )
  )
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  topTerm = 3,
  plot_type = "comparison"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  topTerm = 3,
  plot_type = "comparison",
  compare_only_sig = TRUE
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = c("Ductal", "Endocrine"),
  plot_type = "comparison"
)


EnrichmentPlot(
  pancreas_sub,
  db = c("GO_BP", "GO_CC"),
  group.by = "CellType",
  group_use = c("Ductal", "Endocrine"),
  plot_type = "bar",
  split_by = "Groups"
)


EnrichmentPlot(
  pancreas_sub,
  db = c("GO_BP", "GO_CC"),
  group.by = "CellType",
  group_use = c("Ductal", "Endocrine"),
  plot_type = "bar",
  split_by = "Database",
  color_by = "Groups"
)


EnrichmentPlot(
  pancreas_sub,
  db = c("GO_BP", "GO_CC"),
  group.by = "CellType",
  group_use = c("Ductal", "Endocrine"),
  plot_type = "bar",
  split_by = c("Database", "Groups")
)


EnrichmentPlot(
  pancreas_sub,
  db = c("GO_BP", "GO_CC"),
  group.by = "CellType",
  plot_type = "bar",
  split_by = "Database",
  color_by = "Groups",
  palette = "Set1"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "dot",
  palette = "GdRd"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "lollipop",
  palette = "GdRd"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "wordcloud"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "wordcloud",
  word_type = "feature"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "network"
)
#> Found more than one class "dist" in cache; using the first, from namespace 'spam'
#> Also defined by ‘BiocGenerics’
#> Found more than one class "dist" in cache; using the first, from namespace 'spam'
#> Also defined by ‘BiocGenerics’
#> ✔ [2026-11-12 05:14:28] shadowtext installed successfully


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "network",
  id_use = c(
    "GO:0050678",
    "GO:0035270",
    "GO:0090276",
    "GO:0030073"
  )
)
#> ✔ [2026-11-12 05:14:29] shadowtext installed successfully


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "network",
  network_layoutadjust = FALSE
)
#> ✔ [2026-11-12 05:14:29] shadowtext installed successfully


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "network",
  topTerm = 4,
  network_blendmode = "average",
  theme_use = "theme_blank",
  theme_args = list(add_coord = FALSE)
) |> thisplot::panel_fix(height = 5)
#> ✔ [2026-11-12 05:14:31] shadowtext installed successfully


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "enrichmap"
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "enrichmap",
  enrichmap_expand = c(2, 1)
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "enrichmap",
  enrichmap_show_keyword = TRUE,
  character_width = 10
)


EnrichmentPlot(
  pancreas_sub,
  db = "GO_BP",
  group.by = "CellType",
  group_use = "Ductal",
  plot_type = "enrichmap",
  topTerm = 200,
  enrichmap_mark = "hull",
  enrichmap_label = "feature",
  enrichmap_nlabel = 3,
  character_width = 10,
  theme_use = "theme_blank",
  theme_args = list(add_coord = FALSE)
) |> thisplot::panel_fix(height = 4)


pancreas_sub <- RunEnrichment(
  pancreas_sub,
  db = c("MP", "DO"),
  group.by = "CellType",
  convert_species = TRUE,
  species = "Mus_musculus"
)
#> ℹ [2026-11-12 05:14:35] Start Enrichment analysis
#> ℹ [2026-11-12 05:14:35] Species: "Mus_musculus"
#> ℹ [2026-11-12 05:14:35] Preparing MP database
#> ℹ [2026-11-12 05:14:42] Species: "Mus_musculus"
#> ℹ [2026-11-12 05:14:42] Preparing DO database
#> ℹ [2026-11-12 05:14:47] Permform enrichment...
#> ✔ [2026-11-12 05:14:47] Enrichment analysis done

EnrichmentPlot(
  pancreas_sub,
  db = c("MP", "DO"),
  group.by = "CellType",
  group_use = "Ductal",
  ncol = 1
)

Usage

Arguments

Value

Details

See also

Examples