Mechanistic prediction of fecal microbiota transplant engraftment and Clostridioides difficile colonization resistance with μODE

Shotgun metagenomics routinely resolves microbial community composition down to the strain level via metagenome-assembled genomes (MAGs), but translating these static catalogs into mechanistic, time-resolved understandings of ecosystem dynamics remains a critical computational bottleneck. Here, we present muODE, a fully automated framework that converts MAGs into dynamical simulations of community metabolism equipped with a composable, literature-grounded ecology layer, fundamentally designed to serve as a mechanistic hypothesis-testing engine. It employs dynamic flux balance analysis (dFBA) coupled to a shared extracellular pool and integrates a composable ecology layer capturing pH inhibition, time-varying antibiotic pharmacokinetics, bile-acid transformations, and spore dormancy. To evaluate the core engine, we cross-validated the dFBA machinery to machine precision against an independent reference implementation. We provide native export to the established COMETS engine for third-party verification. Benchmarking against two independent experimentally validated datasets confirmed that while monoculture growth is robustly captured, overflow secretion and directed community composition remain strictly bounded by the flux-routing limitations of max-biomass FBA. However, when applied to rate-modifying ecological feedback, muODE mechanistically and quantitatively reproduces bile-acid-mediated colonization resistance against Clostridioides difficile. With a single rate parameter calibrated so that baseline deoxycholate matched its measured physiological concentration, the framework reproduced the uncalibrated antibiotic-induced collapse of deoxycholate, with the calibrated inhibitor concentration coinciding with the independently set inhibitory threshold of the pathogen and driving a ~44x shift in the simulated pathogen-susceptibility ratio; bile-acid transformation is represented in the composable ecology layer rather than in the genome-scale stoichiometry. Finally, applying muODE end-to-end to a real longitudinal fecal microbiota transplant (FMT) yielding 139 de novo genome-scale metabolic models, the framework successfully recovered the clinical direction of treatment. By transparently diagnosing the structural competitive-exclusion bias that limits precise compositional prediction, muODE motivates the necessity of community-objective extensions while transitioning microbiome modeling from descriptive taxonomy toward testable, quantitatively-validated dynamic hypothesis testing, laying the essential mechanistic groundwork for the predictive engineering of safe, targeted ecological therapeutics. muODE is freely available at https://github.com/cumbof/muODE.