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)

INPUTS:

• model – COBRA model structure with fields:

  • .rxns - n x 1 reaction identifiers

• database – rBioNet reaction database containing min. 3 columns: Column 1: reaction abbreviation, Column 2: reaction name, Column 3: reaction formula, with fields:

  • .reactions - cell array of reaction abbreviations (column 1) and reaction formulas (column 3)

OUTPUTS:

model – COBRA model structure with condition-specific gap-filling reactions added

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 with fields:

  • .rxns - n x 1 reaction identifiers

  • .comments - n x 1 cell array of free-text comments for each reaction

  • .rxnConfidenceScores - n x 1 reaction confidence scores

• 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, with fields:

  • .reactions - cell array of reaction abbreviations (column 1) and reaction formulas (column 3)

OUTPUTS:

• model – COBRA model structure with coupling-constraint gap-filling reactions added

• 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 with fields:

  • .rxns - n x 1 reaction identifiers

  • .grRules - n x 1 gene-protein-reaction rules

  • .comments - n x 1 cell array of free-text comments for each reaction

• testResults – Structure with results of test run; one field per test, accessed dynamically by field name

• 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

OUTPUTS:

• 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

USAGE:

T = findFutileCycle (model, cut, closedModel)

INPUTS:

model – COBRA model structure

OPTIONAL INPUTS:

• cut – cutoff value for reactions to be displayed

• closedModel – if 1 the model will be closed otw the applied medium constraints count (default: 1)

OUTPUTS:

T – Table of reactions potentially involved

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:

[futileCycleReactions, FutileCyclesTest] = identifyFutileCycles (model)

INPUTS:

model – COBRA model structure with fields:

• .rxns - n x 1 reaction identifiers

• .lb - n x 1 lower bounds

• .ub - n x 1 upper bounds

OUTPUTS:

• 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 with fields:

  • .rxns - n x 1 reaction identifiers

  • .mets - m x 1 metabolite identifiers

  • .lb - n x 1 lower bounds

  • .grRules - n x 1 gene-protein-reaction rules

  • .comments - n x 1 cell array of free-text comments for each reaction

  • .rxnConfidenceScores - n x 1 reaction confidence scores

• 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, with fields:

  • .reactions - cell array of reaction abbreviations (column 1) and reaction formulas (column 3)

OPTIONAL INPUTS:

• unionRxns – Union of reactions from multiple reconstructions (only for debugging multi-species models)

• constrainedModel – COBRA model constrained with defined medium (for certain steps of DEMETER)

OUTPUTS:

• model – COBRA model structure with futile cycles removed

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

varargin – Optional name-value arguments:

• 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) (default: ‘’)

OUTPUTS:

• 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, curateDefMedia)

INPUTS:

• model – COBRA model structure with fields:

  • .rxns - n x 1 reaction identifiers

  • .lb - n x 1 lower bounds

• 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 INPUTS:

curateDefMedia – boolean indicating that growth on defined medium is being curated (default: false)

OUTPUTS:

• 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 with fields:

  • .rxns - n x 1 reaction identifiers

  • .grRules - n x 1 gene-protein-reaction rules

• 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, with fields:

  • .reactions - cell array of reaction abbreviations (column 1), names (column 2), formulas (column 3), and subsystems (column 11)

OUTPUTS:

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, excludeDMs, excludeSinks, excludeExchanges)

INPUTS:

• model – COBRA model structure with fields:

  • .rxns - n x 1 reaction identifiers

  • .c - n x 1 objective coefficients

  • .lb - n x 1 lower bounds

  • .ub - n x 1 upper bounds

• 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, with fields:

  • .reactions - cell array of reaction abbreviations (column 1) and reaction formulas (column 3)

OPTIONAL INPUTS:

• 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)

OUTPUTS:

• 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, condGF, targetGF, relaxGF] = verifyGapfilledReactions (model, osenseStr)

INPUTS:

• model – COBRA model structure with fields:

  • .rxns - n x 1 reaction identifiers

  • .grRules - n x 1 gene-protein-reaction rules

• osenseStr – Maximize (‘max’)/minimize (‘min’) linear part of the objective

OUTPUTS:

• model – COBRA model structure

• condGF – Reactions added based on conditions (recognizing certain patterns of reactions)

• targetGF – Reactions added based on tagrted gapfilling (specific metabolites that could not be produced)

• relaxGF – Reactions added based on relaxFBA (lowest level of confidence)