bulk-rnaseq-gsea
GSEA for bulk RNA-seq with bulkiRNA: which MSigDB and custom databases to run, rank metric, size bounds 10/500, per-database figures and the master table. Use for preranked GSEA, fgsea, Hallmark, KEGG
SKILL.mdskills/bulk-rnaseq-gsea/SKILL.md
GitHubBulk RNA-seq GSEA
This skill sets the house GSEA stage: databases, parameters, figures and the master table. The
package does the mechanics. Read bulkirna first for the DE recipe that produces the input, then
?gs_test, ?gsdb_msigdb, ?gs_plot_dot and ?gs_to_master for each contract.
Rules this skill imposes
- Rank on the moderated t.
gs_ranks(de, metric = "t", genes = "Symbol", collapse = "max_abs"). - Bound set size at 10 and 500 on
gs_test(). Pass both explicitly. Leave the provider bounds atNULL:gsdb_*(min_size = )filters raw sets, before intersection with the ranked genes, and changes which pathways are tested. - Keep every tested set.
gs_test()returns all of them. Select for display withgs_top()and the renderers'top_n; mark significance withhighlight. - Name each provider with the project's database key. The names of the list passed as
dbbecome thedatabasecolumn. Figures, tables and master rows join on it. - Seed from config. fgsea's default is
123L;bulkirna_stochastic()lists it. - One stage computes, one renders. The compute stage ends at
gs_write(). The viz stage starts atgs_read().
Databases
House set for a mouse project. Human MSigDB is mapped to mouse orthologs (db_species = "HS",
the default).
| Key | Call | Why |
|---|---|---|
Hallmark |
gsdb_msigdb(sp, collection = "H") |
50 curated programs; first read of any contrast |
KEGG |
gsdb_msigdb(sp, "C2", "CP:KEGG_LEGACY") |
metabolic and signalling maps |
Reactome |
gsdb_msigdb(sp, "C2", "CP:REACTOME") |
fine-grained mechanism |
WikiPathways |
gsdb_msigdb(sp, "C2", "CP:WIKIPATHWAYS") |
community pathways |
TF_Targets |
gsdb_msigdb(sp, "C3", "TFT:GTRD") |
TF target sets |
GO_BP, GO_MF, GO_CC |
gsdb_msigdb(sp, "C5", "GO:BP") and so on |
broad coverage; slowest |
MitoPathways |
gsdb_load("mitopathways", species = sp) |
mitochondrial hierarchy (MitoCarta 3.0) |
MitoXplorer |
gsdb_load("mitoxplorer", species = sp) |
mitochondrial processes |
TransportDB |
gsdb_load("transportdb", species = sp) |
transporter families |
Pass a subcollection for C2, C3 and C5; NULL loads the whole collection. Subcollection names
follow the installed msigdbr: list them with msigdbr::msigdbr_collections(). gsdb_list() lists
the bundled databases; mito_unified merges the two mito sources. Project GMT, GMX, TSV and
GATOM-module sets: references/custom-databases.md.
Parameters
| Setting | House value | Where |
|---|---|---|
| Rank metric | moderated t from limma-trend | gs_ranks(metric = "t") |
| Set size | 10 to 500 genes tested | gs_test(min_size = 10, max_size = 500) |
| p-value floor | none, eps = 0 (the default) |
gs_test(eps = ) |
| Permutations | n_perm_simple = 100000 (the default) |
gs_test(n_perm_simple = ) |
| Seed | 123L from config |
gs_test(seed = ) |
| Significance | FDR < 0.05 | renderer highlight = 0.05 |
| Display | top 20 per database; top 10 per database pooled | renderer top_n |
Compute
library(bulkiRNA)
sp <- cfg$project$species # "Mus musculus"
dbs <- list(
Hallmark = gsdb_msigdb(sp, collection = "H"),
Reactome = gsdb_msigdb(sp, "C2", "CP:REACTOME"),
GO_BP = gsdb_msigdb(sp, "C5", "GO:BP"),
MitoPathways = gsdb_load("mitopathways", species = sp)
)
ranks <- lapply(de_tables, gs_ranks, metric = "t", genes = "Symbol", collapse = "max_abs")
res <- do.call(rbind, lapply(names(ranks), function(ct)
gs_test(ranks[[ct]], dbs, contrast = ct, min_size = 10, max_size = 500,
seed = cfg$gsea$seed)))
gs_write(res, file.path(stage_dir, "tables"), name = "gsea", prune = TRUE)
saveRDS(list(dbs = dbs, ranks = ranks), file.path(stage_dir, "gsea_inputs.rds"))
de_tables is a named list of full limma::topTable(n = Inf, sort.by = "none") tables keyed by
the contrast string. prune = TRUE makes a re-run replace the stage's tables. The viz and master
stages read set membership and ranks from gsea_inputs.rds.
Figure set
Per contrast and database, from x <- gs_filter(res, contrast = ct, database = key). Size each
canvas with gs_plot_size(type, key) and write with gs_save(), which emits .pdf, .png and
the same-stem .tsv.
| Stem | Call |
|---|---|
<key>_dot |
gs_plot_dot(x, top_n = 20, highlight = 0.05) |
<key>_up_dot, <key>_down_dot |
gs_plot_dot(x, top_n = 20, direction = "up"), "down" |
<key>_nes_bar |
gs_plot_bar(x, top_n = 20, highlight = 0.05) |
<key>_running |
gs_plot_running(x, ranks = ranks[[ct]], db = dbs[[key]], top_n = 5, metric_label = "t statistic") |
running/<pathway_id> |
gs_plot_running(x, ranks = ranks[[ct]], db = dbs[[key]], pathways = id) for each id in gs_top(x, n = 10)$pathway_id |
Across databases, per contrast, under _overview/:
| Stem | Call |
|---|---|
pooled_<contrast> |
gs_plot_dot(gs_filter(res, contrast = ct), top_n = 10, facet = "database") |
focused_top5_<contrast> |
the same over the key databases, top_n = 5 |
<key>_contrasts_heatmap |
gs_plot_heatmap(gs_filter(res, database = key), top_n = 20, by = "contrast") |
Pass one shared limits to every figure meant for side-by-side comparison; the default derives
limits from each figure's own data.
Master table
gs_to_master() serialises a result to the versioned master schema; gs_validate_master() checks
it. Assembly across stages and non-GSEA rows: references/master-table.md.
Reading the result
statis NES. Its sign follows the contrast string: positive means enriched in the first term.padjis adjusted within one database and one contrast.log2err = Infmarks a p-value past the estimator's resolution. Report it as below that floor.gs_leading_edge()shows which sets share driving genes and which are independent.
Checks before reporting
setequal(unique(res$database), names(dbs)) # every database returned tested sets
table(res$database, res$contrast) # every cell non-empty
summary(res) # tested sets and hits per database
sum(names(ranks[[1]]) %in% unlist(dbs$Hallmark)) # thousands of shared symbols
A database with no tested sets means Ensembl IDs or human symbols in the ranks. Fix the ranks.
Traps
gsdb_msigdb()keys itselfmsigdb_C2_CP_REACTOME; the list name overrides it, andgs_plot_size()recognises project keys such asHallmark,KEGG,GO_BP.db_species = "MM"selects mouse-native sets: a different collection with different set ids.gs_plot_running()needsdb: ags_resultcarries no set membership.- Shape-21 points in a hand-built figure use
color = "transparent"under ggplot2 4.0+.
See also
bulkirna: DE recipe, task-to-export table, general trapsbulk-rnaseq-pathway-explorer: interactive HTML from the master tablebulk-rnaseq-activity-inference: TF and PROGENy activitiesgatom-metabolomic-predictions: metabolic modules; their genes enter as a custom databasecoresh-signature-search: signature search across GEO datasetste-geneset-gsea: TE family and class sets