bulkirna
bulkiRNA — the installed R package for bulk and pseudo-bulk RNA-seq. Use for any bulk count matrix, gene annotation, DGEList, filterByExpr, TMM, limma or edgeR DE, PCA, volcano, GSEA, ORA, MSigDB, CoR
SKILL.mdskills/bulkirna/SKILL.md
GitHubbulkiRNA
bulkiRNA is the house library for bulk RNA-seq. It ships in every scdock-r-dev image from
v0.5.15 and replaces the retired RNAseq-toolkit scripts. Load it and call it:
library(bulkiRNA)
packageVersion("bulkiRNA") # 1.3.0 in v0.5.21
bulkirna_api() # every export: layer, lifecycle, stochastic flag
?build_dge # each export documents its contract
Rules this skill imposes
- Call the export. Reading counts, annotating genes, building a DGEList, ranking genes,
loading gene sets, testing them and drawing DE or gene-set figures are package functions.
Check
bulkirna_api()and the help page before writing any helper. - Wrap a gap, then name it. When an export falls short, keep it in the call path, add the smallest project helper around it, and state the missing behaviour in your summary.
- Treat
RNAseq-toolkitas retired. An instruction tosource()a script from01_modules/RNAseq-toolkit/is stale; the export of the same name replaces it. - Annotate before filtering. Ensembl IDs dropped by a filter cannot be recovered.
- Fit with limma-trend or edgeR QL. Rank on the moderated t.
- Carry
contrastas a string. It is the join key across DE, gene-set and master tables. - Compute writes tables; viz writes figures.
gs_save()writes.pdf,.pngand the same-stem.tsvfrom one plot object. - Pass seeds and size bounds from config.
bulkirna_stochastic()lists every stochastic export with its seed argument and default.gs_test()has no size default: setmin_size = 10, max_size = 500explicitly.
Task → export
| Task | Export |
|---|---|
| Read featureCounts, Salmon or generic counts | read_counts_matrix() |
Read a sample sheet (.csv, .tsv, .xlsx) |
read_metadata() |
| Ensembl → symbol, Entrez, biotype | annotate_genes() |
| Symbol ↔ Entrez | gene_to_entrez(), entrez_to_gene() |
| Drop ribosomal, mito, haemoglobin, cell-cycle, sex genes | filter_confounder_genes() |
| DGEList with order checks and TMM | build_dge() |
Provenance (genome, resolved Ensembl release, RNG, sessionInfo()) |
write_session_provenance() |
| PCA, 3-D PCA | de_pca(), de_pca_3d() |
| Volcano, volcano row, MD, B-vs-FC | de_volcano(), de_volcano_grid(), de_md_plot(), de_bfc_plot() |
| Rank vector from a DE table | gs_ranks() |
| Gene-set databases | gsdb_msigdb(), gsdb_load(), gsdb_from_file(), gsdb_coresh(), gsdb_list() |
| GSEA, ORA, score-matrix limma | gs_test() — method follows the class of x |
| Per-sample scores (GSVA, ssGSEA, z-score, PLAGE) | gs_score() |
| Coregulation (GESECA) | gs_coregulation() |
| Top sets, leading edge, filter, split | gs_top(), gs_leading_edge(), gs_filter(), gs_split() |
| Write and read results | gs_write(), gs_read() |
| Master table | gs_to_master(), gs_validate_master(), gs_master_columns() |
| Gene-set figures | gs_plot_dot(), gs_plot_bar(), gs_plot_heatmap(), gs_plot_running(), gs_plot_size() |
| Save a figure and its table | gs_save() |
| CoReSh signature search | coresh_search(), coresh_sets(), coresh_labels() — skill coresh-signature-search |
| GATOM metabolic modules | gatom_refs(), gatom_de(), gatom_graph(), gatom_score(), gatom_solve(), gatom_module(), gatom_pathways() — skill gatom-metabolomic-predictions |
TF activity, PROGENy and WGCNA have no export yet; write those stages by hand and validate their
master rows with gs_validate_master().
Recipe: counts to a filtered, normalised DGEList
Paths and parameters come from analysis_config.yaml.
counts <- read_counts_matrix(cfg$inputs$counts) # versioned Ensembl rownames
samples <- as.data.frame(read_metadata(cfg$inputs$samples))
rownames(samples) <- samples$Sample_ID
counts <- counts[, rownames(samples)]
samples$group <- factor(samples[[cfg$design$group_column]])
genes <- as.data.frame(annotate_genes(rownames(counts), species = "Mus musculus",
input_gene_name = attr(counts, "input_gene_name")))
rownames(genes) <- rownames(counts)
dge <- build_dge(counts, samples, genes) # raw counts + TMM
design <- model.matrix(~ 0 + group, data = dge$samples)
colnames(design) <- levels(dge$samples$group)
keep <- edgeR::filterByExpr(dge, design = design)
dge <- edgeR::calcNormFactors(dge[keep, , keep.lib.sizes = FALSE], method = "TMM")
write_session_provenance(file.path(out_dir, "provenance.txt"),
genome_build = cfg$project$genome_build)
annotate_genes() stores the quantifier's name in input_gene_name. From 1.2.0 it fills
Symbol from input_gene_name where org.db and biomaRt have no symbol; 1.1.0 left the Ensembl ID
there.
Recipe: contrast to gene sets
logcpm <- edgeR::cpm(dge, log = TRUE, prior.count = 2)
cm <- limma::makeContrasts(contrasts = cfg$contrasts$expr, levels = design)
fit <- limma::eBayes(limma::contrasts.fit(limma::lmFit(logcpm, design), cm), trend = TRUE)
de <- limma::topTable(fit, coef = 1, n = Inf, sort.by = "none", genelist = dge$genes)
ranks <- gs_ranks(de, metric = "t", genes = "Symbol", collapse = "max_abs")
db <- gsdb_msigdb(species = "Mus musculus", collection = "H")
res <- gs_test(ranks, db, contrast = cfg$contrasts$name, min_size = 10, max_size = 500)
gs_write(res, "03_results/<stage>/tables", name = "gsea")
p <- gs_plot_dot(res, top_n = 10) # viz stage reads the tables back with gs_read()
gs_save(p, "03_results/<stage>/figures/_overview/hallmark_dot", width = 8, height = 6)
gs_result is a tibble: dplyr verbs and rbind() work on it.
Traps
gsdb_msigdb()defaults to human sets mapped to mouse; passdb_species = "MM"for mouse-native collections.gs_to_master(db = )takes thegs_dbobject.- A renamed provider keeps its join key: set
attr(db, "database")orgsdb_from_file(database = ). annotate_genes()takes"Mus musculus";gene_to_entrez()takes"mouse". Both accept either alias.- Seed defaults differ by design: fgsea
123L, CoReSh1L, GATOM42. Keep them.
See also
annotate-bulk-rnaseq-data— the TE path and gene + TE matricesbulk-rnaseq-gsea— database choice, interpretation, figure setbulk-rnaseq-pathway-explorer— reading a gene-set resultcoresh-signature-search,gatom-metabolomic-predictions— those two analyses end to endanalysis-code-conventions— stage layout and helpers