Skip to contents

RunDynamicEnrichment

Source: R/RunDynamicEnrichment.R
RunDynamicEnrichment.Rd

Calculates gene-set scores from the specified database (db) for each lineage using the specified scoring method (score_method). It then treats these scores as expression values and uses them as input to the RunDynamicFeatures function to identify dynamically enriched terms along the lineage.

Usage

RunDynamicEnrichment(
  srt,
  lineages,
  score_method = "AUCell",
  layer = "data",
  assay = NULL,
  min_expcells = 20,
  r.sq = 0.2,
  dev.expl = 0.2,
  padjust = 0.05,
  IDtype = "symbol",
  species = "Homo_sapiens",
  db = "GO_BP",
  db_update = FALSE,
  db_version = "latest",
  convert_species = TRUE,
  Ensembl_version = NULL,
  mirror = NULL,
  features = NULL,
  TERM2GENE = NULL,
  TERM2NAME = NULL,
  minGSSize = 10,
  maxGSSize = 500,
  backend = c("cpp", "r"),
  cores = 1,
  verbose = TRUE,
  seed = 11,
  ...
)

Arguments

srt

A Seurat object or SummarizedExperiment object containing the results of differential expression analysis (RunDEtest()). If specified, the genes and groups will be extracted from the object automatically. If not specified, the geneID and geneID_groups arguments must be provided.

lineages

Lineage names for which dynamic features should be calculated.

score_method

The method to use for scoring. Can be "Seurat", "AUCell", "UCell", "GSVA", "ssGSEA", "zscore", "PLAGE", or "VISION". Multiple methods can be supplied at once; each method will be written to a method-suffixed assay before dynamic-feature fitting.

layer

Assay layer to use.

assay

Assay to use. NULL uses the default assay.

min_expcells

The minimum number of expected cells.

r.sq

The R-squared threshold.

dev.expl

The deviance explained threshold.

padjust

The p-value adjustment threshold.

IDtype

Type of gene IDs in the srt object or geneID argument. This argument is used to convert the gene IDs to a different type if IDtype is different from result_IDtype.

species

"Homo_sapiens" or "Mus_musculus".

db

Annotation sources. One or more of "GO", "GO_BP", "GO_CC", "GO_MF", "KEGG", "WikiPathway", "Reactome", "CORUM", "MP", "DO", "HPO", "PFAM", "CSPA", "Surfaceome", "SPRomeDB", "VerSeDa", "TFLink", "hTFtarget", "TRRUST", "JASPAR", "ENCODE", "MSigDB", "CellTalk", "CellChat", "Chromosome", "GeneType", "Enzyme", "TF", "CytoTRACE2". MSigDB subcollections use "MSigDB_<collection>" (e.g. "MSigDB_H"). "CytoTRACE2" is species-independent and is required by RunCytoTRACE.

db_update

Force a refresh. FALSE loads the cache when available.

db_version

Database version to retrieve.

convert_species

Use a species-converted database when the annotation is missing for species.

Ensembl_version

Ensembl version. NULL uses the latest.

mirror

Specify an Ensembl mirror to connect to. The valid options here are "www", "uswest", "useast", "asia".

features

A named list of feature lists for custom enrichment gene sets. If provided, it takes precedence over TERM2GENE and db.

TERM2GENE

A data frame specifying the gene-term mapping for a custom database. The first column should contain the term IDs, and the second column should contain the gene IDs.

TERM2NAME

A data frame specifying the term-name mapping for a custom database. The first column should contain the term IDs, and the second column should contain the corresponding term names.

minGSSize

The minimum size of a gene set to be considered in the enrichment analysis.

maxGSSize

The maximum size of a gene set to be considered in the enrichment analysis.

backend

Enrichment backend. "cpp" is the default and uses a fast native hypergeometric ORA implementation and returns the enrichment table without enrichResult objects. "r" uses clusterProfiler::enricher() and returns enrichResult objects in results. GO_simplify = TRUE currently uses the R backend.

cores

The number of worker processes to use for parallelization. Default is 1.

verbose

Whether to print the message. Default is TRUE.

seed

Optional integer seed. When supplied, every input receives a deterministic independent L'Ecuyer-CMRG random-number stream, making results reproducible across worker counts and scheduling order. The caller's random number state is restored when the call finishes.

...

Passed to helper functions.

See also

RunDynamicFeatures, DynamicHeatmap

Examples

data(pancreas_sub)
pancreas_sub <- RunStandardWorkflow(pancreas_sub)
#> ℹ [2026-08-30 04:58:40] Start standard processing workflow...
#> ℹ [2026-08-30 04:58:40] Checking a list of <Seurat>...
#> ! [2026-08-30 04:58:40] Data 1/1 of the `srt_list` is "unknown"
#> Warning: Data 1/1 of the `srt_list` is "unknown"
#> ℹ [2026-08-30 04:58:40] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on 1/1 of `srt_list`...
#> ℹ [2026-08-30 04:58:40] Perform `FindVariableFeatures()` on 1/1 of `srt_list`...
#> ℹ [2026-08-30 04:58:40] Use the separate HVF from `srt_list`
#> ℹ [2026-08-30 04:58:40] Number of available HVF: 2000
#> ℹ [2026-08-30 04:58:40] Finished check
#> ℹ [2026-08-30 04:58:40] Perform `ScaleData()`
#> ℹ [2026-08-30 04:58:40] Perform pca linear dimension reduction
#> ℹ [2026-08-30 04:58:41] Use stored estimated dimensions 1:23 for Standardpca
#> ℹ [2026-08-30 04:58:41] Perform `Seurat::FindClusters()` with `cluster_algorithm = 'louvain'` and `cluster_resolution = 0.6`
#> ℹ [2026-08-30 04:58:41] Reorder clusters...
#> ℹ [2026-08-30 04:58:41] Skip `log1p()` because `layer = data` is not "counts"
#> ℹ [2026-08-30 04:58:41] Perform umap nonlinear dimension reduction
#> ✔ [2026-08-30 04:58:49] Standard processing workflow completed
pancreas_sub <- RunSlingshot(
  pancreas_sub,
  group.by = "CellType",
  reduction = "UMAP"
)
#> Warning: Removed 7 rows containing missing values or values outside the scale range
#> (`geom_path()`).
#> Warning: Removed 7 rows containing missing values or values outside the scale range
#> (`geom_path()`).

pancreas_sub <- RunDynamicFeatures(
  pancreas_sub,
  lineages = "Lineage1",
  fit_method = "pretsa",
  n_candidates = 200
)
#> ℹ [2026-08-30 04:58:50] Start find dynamic features
#> ℹ [2026-08-30 04:58:50] Data type is raw counts
#> ℹ [2026-08-30 04:58:50] Number of candidate features (union): 200
#> ℹ [2026-08-30 04:58:51] Data type is raw counts
#> ℹ [2026-08-30 04:58:51] Calculating dynamic features for "Lineage1"...
#> ✔ [2026-08-30 04:58:51] Find dynamic features done
ht1 <- DynamicHeatmap(
  pancreas_sub,
  lineages = "Lineage1",
  cell_annotation = "CellType",
  n_split = 3
)
#> ℹ [2026-08-30 04:58:51] [1] 134 features from Lineage1 passed the threshold (exp_ncells>[1] 20 & r.sq>[1] 0.2 & dev.expl>[1] 0.2 & padjust<[1] 0.05): 
#> ℹ                       Ins1,Ins2,Nnat,Iapp,Lrpprc,Npy,Chgb,Slc38a5,2810417H13Rik,Rbp4...
#> ℹ [2026-08-30 04:58:51] 
#> ℹ                       The size of the heatmap is fixed because certain elements are not scalable.
#> ℹ                       The width and height of the heatmap are determined by the size of the current viewport.
#> ℹ                       If you want to have more control over the size, you can manually set the parameters 'width' and 'height'.

pancreas_sub <- RunDynamicEnrichment(
  pancreas_sub,
  lineages = "Lineage1",
  score_method = "AUCell",
  db = "GO_BP",
  species = "Mus_musculus"
)
#> ℹ [2026-08-30 04:58:52] Species: "Mus_musculus"
#> ℹ [2026-08-30 04:58:52] Loading cached: GO_BP version: 3.23.0 nterm:14957 created: 2026-08-30 04:25:22
#> ℹ [2026-08-30 04:58:56] Start cell scoring
#> ℹ [2026-08-30 04:58:56] Data type is log-normalized
#> ℹ [2026-08-30 04:58:57] Number of feature lists to be scored: 2729
#> Warning: Feature names cannot have underscores ('_'), replacing with dashes ('-')
#> Warning: Feature names cannot have underscores ('_'), replacing with dashes ('-')
#> ✔ [2026-08-30 04:59:07] Cell scoring completed
#> ℹ [2026-08-30 04:59:07] Start find dynamic features
#> ℹ [2026-08-30 04:59:07] Data type is log-normalized
#> ℹ [2026-08-30 04:59:07] Number of candidate features (union): 2729
#> ℹ [2026-08-30 04:59:08] Data type is log-normalized
#> ℹ [2026-08-30 04:59:08] Calculating dynamic features for "Lineage1"...
#> ℹ [2026-08-30 04:59:08] Using 1 core
#> ⠙ [2026-08-30 04:59:08] Running for GO-BP-2..deoxyribonucleotide.biosynthetic.p…
#> ⠹ [2026-08-30 04:59:08] Running for GO-BP-brain.morphogenesis [201/2729]       …
#> ⠸ [2026-08-30 04:59:08] Running for GO-BP-endothelial.cell.migration [532/2729]…
#> ⠼ [2026-08-30 04:59:08] Running for GO-BP-macrophage.differentiation [866/2729]…
#> ⠴ [2026-08-30 04:59:08] Running for GO-BP-negative.regulation.of.microtubule.po…
#> ⠦ [2026-08-30 04:59:08] Running for GO-BP-positive.regulation.of.cartilage.deve…
#> ⠧ [2026-08-30 04:59:08] Running for GO-BP-pyramidal.neuron.differentiation [185…
#> ⠇ [2026-08-30 04:59:08] Running for GO-BP-regulation.of.mitotic.metaphase.anaph…
#> ⠏ [2026-08-30 04:59:08] Running for GO-BP-retina.development.in.camera.type.eye…
#> ✔ [2026-08-30 04:59:08] Completed 2729 tasks in 24.9s
#> 
#> ℹ [2026-08-30 04:59:08] Building results
#> ✔ [2026-08-30 04:59:33] Find dynamic features done
#> ✔ [2026-08-30 04:59:33] Dynamic enrichment analysis completed
ht2 <- DynamicHeatmap(
  pancreas_sub,
  assay = "GO_BP",
  lineages = "Lineage1_GO_BP",
  cell_annotation = "CellType",
  n_split = 3,
  split_method = "kmeans-peaktime"
)
#> ℹ [2026-08-30 04:59:33] [1] 1897 features from Lineage1_GO_BP passed the threshold (exp_ncells>[1] 20 & r.sq>[1] 0.2 & dev.expl>[1] 0.2 & padjust<[1] 0.05): 
#> ℹ                       GO-BP-2..deoxyribonucleotide.biosynthetic.process,GO-BP-2..deoxyribonucleotide.metabolic.process,GO-BP-ADP.catabolic.process,GO-BP-ADP.metabolic.process,GO-BP-ATP.metabolic.process,GO-BP-ATP.synthesis.coupled.electron.transport,GO-BP-B.cell.activation,GO-BP-B.cell.proliferation,GO-BP-CENP.A.containing.chromatin.assembly,GO-BP-D.glucose.import.across.plasma.membrane...
#> ! [2026-08-30 04:59:33] The values in the 'counts' layer are non-integer. Set the library size to 1.
#> Warning: The values in the 'counts' layer are non-integer. Set the library size to 1.
#> ℹ [2026-08-30 04:59:34] 
#> ℹ                       The size of the heatmap is fixed because certain elements are not scalable.
#> ℹ                       The width and height of the heatmap are determined by the size of the current viewport.
#> ℹ                       If you want to have more control over the size, you can manually set the parameters 'width' and 'height'.