gatom-metabolomic-predictions
GATOM metabolic modules via bulkiRNA: finds the maximally regulated metabolic subnetwork from DE results using atom-transition graphs and BUM-scored SGMWCS. Use to read transcriptomic or metabolomic D
SKILL.mdskills/gatom-metabolomic-predictions/SKILL.md
GitHubGATOM: active metabolic modules
GATOM scores a metabolic graph with a beta-uniform mixture (BUM) and solves for the
maximum-weight connected subgraph. The module is a scored optimum; it carries no permutation
p-value. GATOM is three calls, and bulkiRNA wraps each as one layer that records what it did on
its result. Read skills/bulkirna for the DE fit.
gatom_refs() + gatom_de() -> gatom_graph() -> gatom_score() -> gatom_solve()
gatom_solver()
gatom_module() = the three layers in order gatom_genes(), gatom_pathways() read a module
gatom_plot_module() draws one; gatom_save_html() writes one
Rules this skill imposes
- Feed raw p-values from the unfiltered DE table. BUM is fitted to the whole p-value
distribution.
gatom_de()rejects an adjusted-looking column and values outside[0, 1]. - Give
baseMeanas any expression measure. gatom only ranks genes by it and keeps the top 12,000;AveExprand2^AveExprgive the same graph. Reportattr(g, "genes_kept"). - Read genes from edges.
gatom_genes()returns edge gene symbols for every id type. - Run the k sensitivity branches.
k_genesets the gene threshold at the k-th smallest p-value, capped at FDR 0.1: a larger k grows the module. Run 25, 50 and 75 on one graph, and report the module size per k and the shared core. - Keep
seed = 42. It is the vignette's seed and reproduces the historical modules. - Use the exact solver for reported modules.
gatom_solver("virgo")is the authors' recommendation; it needs CPLEX atCPLEX_HOME."rnc"is the vignette's heuristic for exploration: on 18 KathleenM graphs it reached the optimum in 6, and elsewhere 51-92% of the optimal weight with different genes. Reportattr(m, "solver")andattr(m, "solved_to_optimality"). - Report the run from the module. Every module carries its network, topology, gene counts, BUM fit, k, seed, solver and solution weight as attributes. Save them with the module.
Task → export
| Task | Export |
|---|---|
Fetch network files and SHA256SUMS |
gatom_download_refs(dir, species, networks, overwrite) |
| Load and verify one network's references | gatom_refs(species, dir, network = "kegg" | "rhea" | "combined" | "lipids") |
| Build the gene DE input | gatom_de(x, id, pval, log2FC, baseMean) |
| Build the graph | gatom_graph(de, refs, topology, met_de, keep_reactions_without_enzymes) |
| Score it | gatom_score(g, k_gene, k_met, seed) |
| Choose the solver | gatom_solver("rnc"), gatom_solver("virgo", cplex_dir, threads, penalty, timelimit) |
| Solve for the module | gatom_solve(gs, solver, seed) |
| All three in one call | gatom_module(de, refs, k_gene, k_met, met_de, seed, solver, topology = ...) |
| Module genes | gatom_genes(m) |
| Pathway annotation | gatom_pathways(m, refs, universe, min_size, collapse) |
| Interactive HTML | gatom_save_html(m, path, name) |
| Network figure (PDF + PNG + edge table) | p <- gatom_plot_module(m, seed = 42); gs_save(p, stem, width = 11, height = 9) or the project's save_overview(p, ..., void = TRUE) |
| GraphML for Cytoscape or Gephi | igraph::write_graph(m, path, format = "graphml") |
| Graphviz dot | gatom::saveModuleToDot(m, path, name); render with neato -Tsvg |
| Readable lipid labels | gatom::abbreviateLabels(m, orig.names = TRUE, abbrev.names = TRUE) |
The last three are gatom's and igraph's own calls: they are deterministic and keep the
module's attributes, so bulkiRNA does not wrap them. GraphML keeps all 17 edge attributes
(gene, log2FC, pval, reaction, ...) and the metabolite attributes; style by them in the GUI.
gatom's saveModuleToPdf() is not used: its ggnet2 layout can put every node on one line and
then fails to draw (4 of 18 modules in one project). gatom_plot_module() draws with ggraph,
seeds the layout and the label repel, and leaves the caller's random stream untouched.
abbreviateLabels() needs a lipid-network module with Species metabolite ids; with both flags it keeps the species name and falls back to
the LipidMaps, then SwissLipids abbreviation.
Recipe
refs_dir <- "00_data/references/gatom"
gatom_download_refs(dir = refs_dir, species = "Mus musculus",
networks = c("kegg", "combined")) # one-time, networked
refs <- gatom_refs("Mus musculus", dir = refs_dir, network = "combined")
print(refs) # files and "(verified)"
de <- gatom_de(tt, id = Symbol, pval = P.Value, log2FC = logFC, baseMean = AveExpr)
g <- gatom_graph(de, refs) # reports genes kept
solver <- gatom_solver("virgo") # or gatom_solver("rnc")
mods <- lapply(c(25, 50, 75), function(k) {
gatom_solve(gatom_score(g, k_gene = k, seed = 42), solver, seed = 42)
})
names(mods) <- paste0("k", c(25, 50, 75))
sapply(mods, attr, "n_edges") # module size per k
core <- Reduce(intersect, lapply(mods, gatom_genes)) # interpret these first
pw <- gatom_pathways(mods$k50, refs) # fora + collapse, as the vignette
gatom_save_html(mods$k50, "03_results/<stage>/plots/GATOM/combined_k50.html",
name = "<contrast>: combined, k = 50")
p <- gatom_plot_module(mods$k50, seed = 42) + ggplot2::labs(title = "<contrast>: combined, k = 50")
gs_save(p, "03_results/<stage>/plots/GATOM/combined_k50", width = 11, height = 9) # pdf, png, tsv
igraph::write_graph(mods$k50, "03_results/<stage>/plots/GATOM/combined_k50.graphml",
format = "graphml")
Build the graph once and score it per k. Treat a gene present at one k only as a size effect.
What a module records
| Attribute | Meaning |
|---|---|
network, topology, species |
the reference set and graph shape |
genes_in_de, genes_kept, graph_genes |
the 12,000-gene cut-off and the annotation universe |
k_gene, gene_threshold, gene_bum_alpha, gene_fdr |
the scoring and its BUM fit (met_* likewise) |
solver, solver_params, seed |
how it was solved |
solution_weight, solved_to_optimality |
the objective and whether it is proven optimal |
gene_threshold and gene_bum_alpha are exact. gene_fdr has six decimals; 0 means below
5e-7.
Networks
network |
Content | Topology |
|---|---|---|
"kegg" |
KEGG reactions | "atoms" |
"rhea" |
Rhea reactions | "atoms" |
"combined" |
KEGG + Rhea + BiGG transport | "atoms" |
"lipids" |
Rhea lipid subnetwork | "metabolites", as the vignette recommends |
gatom_refs() loads the network's gene2reaction table with it.
The exact solver
CPLEX is IBM-licensed and mounted into the container read-only at /opt/cplex, with
CPLEX_HOME=/opt/cplex. A dev container gets both from init-project.sh --cplex <dir>; a
throwaway container from -v <dir>:/opt/cplex:ro -e CPLEX_HOME=/opt/cplex. gatom_solver("virgo")
stops with a message naming CPLEX_HOME when the mount is missing. To compare solvers, solve the
same scored graph with each and compare solution_weight, module size and genes.
Metabolite DE (met_de)
Pass a metabolite table as met_de with an ID column, raw pval and log2FC, and set k_met.
For metabolite data alone, pass de = NULL and k_gene = NULL. met_de$ID matches the met.db
base ID or any refs$met_db$mapFrom type: KEGG, HMDB or ChEBI for KEGG; KEGG or ChEBI for
combined. HMDB exists as 5-digit (HMDB00634) and 7-digit (HMDB0000008) accessions; compare a
few refs$met_db$mapFrom IDs against met_de$ID before solving.
Reading a module
- Colour and read edges by
log2FC. Vertices carry metabolite scores.gatom_plot_module()does both, on symmetric limits, and fills nodes only when the module has metabolite data. - In the atoms topology one metabolite can appear as several nodes (one per atom mapping).
- State network, species,
k_gene, seed and solver with every module figure and table.
Pitfalls
| Symptom | Cause and fix |
|---|---|
do not fit a beta-uniform mixture |
The p-values are pre-filtered, adjusted or uninformative. Use the full table's raw p-values. |
The metabolic graph has no edges |
id holds an id type the annotation lacks. Use symbols, Entrez, Ensembl or RefSeq. |
cplex_dir is empty |
CPLEX_HOME points at no CPLEX. Add the /opt/cplex mount and CPLEX_HOME. |
do not match its SHA256SUMS |
A reference file changed. Refetch with overwrite = TRUE. |
met_de matches few metabolites |
ID-format mismatch. Inspect refs$met_db IDs. |
gatom_save_html() fails on pandoc |
Install pandoc or set RSTUDIO_PANDOC; the error names the fix. |
could not find function "gatom_save_pdf" |
Removed in bulkiRNA 1.3.0 with gatom's saveModuleToPdf(). Use gatom_plot_module() and gs_save(). |
| HTML opens blank | The <name>_files/ folder beside it was not copied. Keep both together. |
What a GATOM stage must deliver
A project stage is a compute script and a viz twin. Compute never plots; viz never computes and
reads only the saved modules. Use the project's own numbering (e.g. 07a_gatom.R,
07b_gatom_viz.R, 07c_gatom_annotate.R), not a fixed one.
Compute (one graph per contrast x network, then one score and solve per k_gene):
- calls the layers (
gatom_graph->gatom_score->gatom_solve), nevergatom_module(), so the graph is built once and reused across k; solver <- gatom_solver("virgo")for reported modules, with the comment block below above it;stopifnot(all(solved_to_optimality))after the run: an exact solver that did not prove its optimum must fail the stage, not pass silently;- saves the modules and a summary table with contrast, network,
k_gene, genes, reactions,solver,solution_weight,solved_to_optimality, BUM fit, plus a graphs table withgenes_in_de,genes_kept, graph size; and the stable core (genes at every k).
Annotation: gatom_pathways(m, refs) per module; keep every tested row and the main flag,
show padj < 0.05, and treat 2-5 gene overlaps as labels, not evidence.
Viz: module size vs k; module genes with log2FC and k-membership; pathway dotplot; per
k50 module a gatom_plot_module() figure, the HTML view, and GraphML for every module. Each
figure carries its source table and caption through the project's save_overview() or gs_save().
Captions state: network, topology, k, seed, solver and optimality, "no metabolite data" when
met_de was absent, the 12,000-gene cut-off, and the tied-optima note below.
CPLEX comment block (required above the solver line)
## CPLEX: gatom_solver("virgo") builds mwcsr::virgo_solver() with the vignette's threads = 4,
## penalty = 0.001 and reads IBM CPLEX (academic licence, never built into the image) from
## $CPLEX_HOME. The container mounts <host CPLEX dir> read-only at /opt/cplex and sets
## CPLEX_HOME=/opt/cplex (.devcontainer/docker-compose.yml). Without the mount this line stops
## naming CPLEX_HOME instead of falling back to mwcsr's approximate mode.
## Virgo proves optimality (stopifnot below), but where subgraphs tie for the optimum it can
## return a different one per run whatever the seed: weight and genes hold, the route through
## unscored metabolites can change.
Tied optima: what is and is not reproducible
Virgo can return a different equally optimal module on each call, even single-threaded; the R
seed does not control it. Weight, gene set and reactions held across five solves of one module;
the metabolite count varied by one. Compare modules by solution_weight and genes, never by
byte-identical node or edge tables, and say so in the caption. Gene-level results (cores,
pathways, gene figures) reproduce.
Container and project prerequisites
- Image
scdock-r-dev>= v0.5.21 (bulkiRNA 1.3.0);packageVersion("bulkiRNA")to confirm. - Compose:
CPLEX_HOME=/opt/cplexand the read-only CPLEX mount (init-project.sh --cplex). - References in
00_data/references/gatomfromgatom_download_refs()withSHA256SUMS;gatom_refs()prints "(verified)". Never read the gene2reaction TSV yourself or passgene2reaction_extra;gatom_refs()loads it for the network. - Run R inside the container; projects are mounted read-only when you only validate.
See also
bulkirna— DE fit and the general recipebulk-rnaseq-gsea— pathway enrichment statisticsgenenmf-metaprogram-discovery
Upstream: the gatom vignette (vignette("gatom-tutorial", package = "gatom")) and
http://artyomovlab.wustl.edu/publications/supp_materials/GATOM/