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.md

GitHub

GATOM: 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

  1. 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].
  2. Give baseMean as any expression measure. gatom only ranks genes by it and keeps the top 12,000; AveExpr and 2^AveExpr give the same graph. Report attr(g, "genes_kept").
  3. Read genes from edges. gatom_genes() returns edge gene symbols for every id type.
  4. Run the k sensitivity branches. k_gene sets 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.
  5. Keep seed = 42. It is the vignette's seed and reproduces the historical modules.
  6. Use the exact solver for reported modules. gatom_solver("virgo") is the authors' recommendation; it needs CPLEX at CPLEX_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. Report attr(m, "solver") and attr(m, "solved_to_optimality").
  7. 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), never gatom_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 with genes_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/cplex and the read-only CPLEX mount (init-project.sh --cplex).
  • References in 00_data/references/gatom from gatom_download_refs() with SHA256SUMS; gatom_refs() prints "(verified)". Never read the gene2reaction TSV yourself or pass gene2reaction_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 recipe
  • bulk-rnaseq-gsea — pathway enrichment statistics
  • genenmf-metaprogram-discovery

Upstream: the gatom vignette (vignette("gatom-tutorial", package = "gatom")) and http://artyomovlab.wustl.edu/publications/supp_materials/GATOM/