Debugging

conditionSpecificGapFilling(model, database)

Part of the DEMETER pipeline. Resolves reactions that were replaced by irreversible versions during the conversion from KBase to VMH nomenclature. As a result, models may no longer grow. This function adds reactions that restore grow and allow the production of biomass precursors in a realisitc manner. All solutions were identified through manual inspection. Any new solutions identified for reaction combinations not yet encountered by DEMETER may be added.

USAGE

[model] = conditionSpecificGapFilling(model,database)

INPUT model COBRA model structure database rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

OUTPUT model COBRA model structure

debugCouplingConstraints(model, biomassReaction, database)

Part of the DEMETER pipeline. In rare cases, the implementation of coupling constraints, which is required for the Microbiome Modeling Toolbox, renders the model unable to grow. This can be fixed by adding certain reactions that were identiifed through manual testing.

USAGE

[model,addedCouplingRxns] = debugCouplingConstraints (model,biomassReaction,database)

INPUTS model: COBRA model structure biomassReaction: Reaction ID of the biomass objective function database: rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

OUTPUT model: COBRA model structure addedCouplingRxns: Reactions added to enable growth with coupling

constraints

debugModel(model, testResults, inputDataFolder, infoFilePath, microbeID, biomassReaction)

This function runs a suite of debugging functions on a refined reconstruction produced by the DEMETER pipeline. Tests are performed whether or not the models can produce biomass aerobically and anaerobically, and whether or not unrealistically high ATP is produced on a complex medium.

USAGE

[revisedModel,gapfilledReactions,replacedReactions]=debugModel (model,testResults,inputDataFolder,infoFilePath,microbeID,biomassReaction)

INPUTS model: COBRA model structure testResults: Structure with results of test run inputDataFolder: Folder with input tables with experimental data

and databases that inform the refinement process

infoFilePath File with information on reconstructions to refine microbeID: ID of the reconstructed microbe that serves as

the reconstruction name and to identify it in input tables

biomassReaction: Reaction ID of the biomass objective function

OUTPUT revisedModel: Gapfilled COBRA model structure gapfilledReactions: Reactions gapfilled to enable flux replacedReactions: Reactions replaced because they were causing

futile cycles

findFutileCycle(model, cut, closedModel)

This function attempts to find reactions involved in the atp-driving futile cycle

INPUT model model structure cut cutoff value for reactions to be displayed closedModel if 1 the model will be closed otw the applied medium

constraints count (DEFAULT:1);

OUTPUT T Table of reactions potentially involved

Ines Thiele 03/2022

identifyFutileCycles(model)

This function serves to debug a refined reconstruction generated by the DEMETER pipeline that produced infeasible amounts of ATP. The output futileCycleReactions shows reactions that are involved in futile cycles. To eliminate the futile cycle, one of these reactions needs to be replaced by an irreversible version of the same reaction. To accomplish this, the replacement step needs to be added to the function removeFutileCycles. It is requested that identified solutions are submitted as a pull request.

USAGE

[gapfilledReactions,replacedReactions,revisedModel]=debugModel (model,testResultsFolder, inputDataFolder,reconVersion,microbeID,biomassReaction)

INPUT model: COBRA model structure

OUTPUT futileCycleReactions: Reactions that are involved in futile cycles and

need to be constrained

FutileCyclesTest Computed fluxes for ATP production

removeFutileCycles(model, biomassReaction, database, unionRxns, constrainedModel)

Part of the DEMETER pipeline. Resolves reactions that are running in infeasible directions and causing futile cycles that result in unrealistically high ATP production. All solutions were identified through manual inspection. Any new solutions identified for reaction combinations not yet encountered by DEMETER may be added.

USAGE

[model, deletedRxns, addedRxns, gfRxns] = removeFutileCycles (model, biomassReaction, database,unionRxns,constrainedModel)

INPUTS model: COBRA model structure biomassReaction: Reaction ID of the biomass objective function database: rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

unionRxns: Union of reactions from multiple reconstructions

(only for debugging multi-species models)

constrainedModels: COBRA model constrained with defined medium (for

certain steps of DEMETER)

OUTPUT model: COBRA model structure deletedRxns: Deleted reactions that were causing futile cycles addedRxns: Added irreversible versions of the deleted reactions gfRxns: Additional gap-filled reactions needed to enable

growth. Low confidence score.

runDebuggingTools(refinedFolder, testResultsFolder, inputDataFolder, infoFilePath, reconVersion, varargin)

This function runs a suite of debugging functions on a set of refined reconstructions produced by the DEMETER pipeline. Tests are performed whether or not the models can produce biomass aerobically and anaerobically, and whether or not unrealistically high ATP is produced on the complex medium.

USAGE

[debuggingReport, fixedModels, failedModels]=runDebuggingTools(refinedFolder,testResultsFolder,inputDataFolder,infoFilePath,reconVersion,varargin)

INPUTS refinedFolder Folder with refined COBRA models generated by

the refinement pipeline

testResultsFolder Folder where the test results are saved inputDataFolder Folder with experimental data and database files infoFilePath File with information on reconstructions to refine reconVersion Name of the refined reconstruction resource

OPTIONAL INPUTS numWorkers Number of workers in parallel pool (default: 2) translatedDraftsFolder Folder with translated draft COBRA models

generated by KBase pipeline to analyze (will only be re-analyzed if folder is provided)

OUTPUT debuggingReport Report of changes that where made to debug the

models, if any

fixedModels IDs of models that passed tests after additional

gap-filling

failedModels IDs of models that still do not pass one or more

tests

runGapfillingFunctions(model, objectiveFunction, biomassReaction, osenseStr, database, curateDefMedia)

This function runs a set of gapfillling functions on a reconstruction to refined as part of the DEMETER pipeline. Reactions are filled in to enable flux through an objective function, e.g., the biomass objective function.

USAGE

[model,condGF,targetGF,relaxGF] = runGapfillingFunctions (model,objectiveFunction,biomassReaction,osenseStr,database)

INPUTS model: COBRA model structure objectiveFunction Reaction ID of the objective function for which flux

will be enabled through gapfilling

biomassReaction: Reaction ID of the biomass objective function that

will be restored afterwards (if objectiveFunction is not biomassReaction)

osenseStr: Maximize (‘max’)/minimize (‘min’) linear part of the

objective

database: rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

OPTIONAL INPUT curateDefMedia: boolean indicating that growth on defined medium is

being curated (default=false)

OUTPUT model: COBRA model structure condGF Reactions added based on conditions (recognizing

certain patterns of reactions)

targetGF Reactions added based on targeted gapfilling

(specific metabolites that could not be produced)

relaxGF Reactions added based on relaxFBA (lowest level of

confidence)

targetedGapFilling(model, osenseStr, database)

This function gapfills a reconstruction during the DEMETER refinement suite to conform with experimental data and/or to enable growth. Metabolites are identified that would enable flux and reactions are gapfilled based on that.

USAGE

model = targetedGapFilling (model,osenseStr,database)

INPUTS model: COBRA model structure osenseStr: Maximize (‘max’)/minimize (‘min’)linear part of the

objective.

database: rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

OUTPUT model: Gapfilled COBRA model structure

untargetedGapFilling(model, osenseStr, database, excludeDMs, excludeSinks, excludeExchanges)

This script is part of the DEMETER pipeline and attemps to find a reaction from the complete reaction database through the use of relaxedFBA that could enable flux through the objective function. This function will be performed only if targeted gap-filling failed.

USAGE

[model,addedRxns] = untargetedGapFilling (model,osenseStr,database)

INPUTS model: COBRA model structure osenseStr: Maximize (‘max’)/minimize (‘min’)linear part of the

objective.

database: rBioNet reaction database containing min. 3 columns:

Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula.

excludeDMs boolean indicating if demand reactions should be

excluded from gap-filling reactions (default: true)

excludeSinks boolean indicating if sink reactions should be

excluded from gap-filling reactions (default: true)

excludeExchanges boolean indicating if exchanges reactions should be

excluded from gap-filling reactions (default: false)

OUTPUT model: Gapfilled COBRA model structure addedRxns: Added gapfilled reactions

verifyGapfilledReactions(model, osenseStr)

Part of the DEMETER pipeline. Checks whether reactions that were added by the gapfilling steps performed in DEMETER are required for biomass production. Reactions that are no longer needed are removed.

USAGE

model = verifyGapfilledReactions(model,osenseStr)

INPUT model COBRA model structure osenseStr: Maximize (‘max’)/minimize (‘min’) linear part of the

objective