Manipulation#

MATLAB functions in RAVEN/src/manipulation of the RAVEN toolbox.

Functions#

Function	Summary
`addExchangeRxns`	Add exchange reactions for some metabolites.
`addGenesRaven`	Add genes to a model.
`addMets`	Add metabolites to a model.
`addRxns`	Add reactions to a model.
`addRxnsGenesMets`	Copy reactions from a source model into another model.
`addTransport`	Add transport reactions between compartments.
`changeGrRules`	Change multiple grRules at the same time.
`changeRxns`	Modify the equations of reactions in a model.
`closeModel`	Add boundary metabolites and their exchange reactions.
`contractModel`	Contract a model by grouping all identical reactions.
`convertToIrrev`	Convert a model to irreversible form.
`copyToComps`	Copy reactions to new compartment(s).
`deleteUnusedGenes`	Delete all genes not associated to any reaction.
`expandModel`	Expand reactions that use several gene associations.
`findDuplicateRxns`	Find reactions that share identical stoichiometry.
`findPotentialErrors`	Identify reactions with non-DNF GPR rules.
`generateNewIds`	Generate a list of new metabolite or reaction ids.
`mergeCompartments`	Merge all compartments in a model.
`mergeModels`	Merge models into one model structure.
`permuteModel`	Change the order of the reactions or metabolites in a model.
`removeBadRxns`	Remove reactions that enable production/consumption from nothing.
`removeGenes`	Delete a set of genes from a model.
`removeLowScoreGenes`	Remove low-scoring genes from model.
`removeMets`	Delete a set of metabolites from a model.
`removeReactions`	Delete a set of reactions from a model.
`replaceMets`	Replace a metabolite with another already in the model.
`reverseRxns`	Reverses the given reactions in place: negates their stoichiometry and
`setExchangeBounds`	Define exchange flux bounds for a set of metabolites.
`setParam`	Set parameters for reactions.
`simplifyModel`	Simplify a model by deleting reactions and metabolites.
`sortIdentifiers`	Sort model identifiers alphabetically.
`sortModel`	Standardize a model's internal ordering: by default orients
`standardizeGrRules`	Standardize gene-reaction rules in a model.

Reference#

addExchangeRxns#

function [model, addedRxns]=addExchangeRxns(model,reactionType,varargin)

Add exchange reactions for some metabolites.

This is a faster version than addRxns when adding exchange reactions. New reactions are named "metName exchange (OUT/IN/BOTH)" while reaction ids are formatted as "EXC_OUT/IN/BOTH_METID".

Parameters

model : struct

a model structure.

reactionType : char

the type of reactions to add:

'in' : input reactions
'out' : output reactions
'both' : reversible input/output reactions. Positive direction corresponds to output

Name-Value Arguments

mets : cell or logical or double: either a cell array of metabolite IDs, a logical vector with the same number of elements as metabolites in the model, or a vector of indexes to add for (default model.mets).

Returns

model : struct: updated model structure.
addedRxns : cell: ids of the added reactions.

Examples

[model, addedRxns] = addExchangeRxns(model, reactionType, mets);

addGenesRaven#

function newModel=addGenesRaven(model,genesToAdd)

Add genes to a model.

This function does not make extensive checks about MIRIAM formats, forbidden characters or such.

Parameters

model : struct

a model structure.

genesToAdd : struct

the genes to add, which can have the following fields:

genes : cell array with unique strings that identifies each gene. Only characters which are allowed in SBML ids are allowed (mainly a-z, 0-9 and "_"). However, there is no check for this performed, as it only matters if the model should be exported to SBML
geneShortNames : cell array of gene abbreviations (optional, default "")
geneMiriams : cell array with MIRIAM structures (optional, default [])
proteins : cell array of protein names associated to each gene (optional, default "")

Returns

newModel : struct: an updated model structure.

Examples

newModel = addGenesRaven(model, genesToAdd);

addMets#

function newModel=addMets(model,metsToAdd,varargin)

Add metabolites to a model.

This function does not make extensive checks about MIRIAM formats, forbidden characters or such.

Parameters

model : struct

a model structure.

metsToAdd : struct

the metabolite structure, which can have the following fields:

mets : cell array with unique strings that identifies each metabolite (optional, default IDs of new metabolites are numbered with the prefix defined below)
metNames : cell array with the names of each metabolite
compartments : cell array with the compartment of each metabolite. Should match model.comps. If this is a string rather than a cell array it is assumed that all mets are in that compartment
b : Nx1 or Nx2 matrix with equality constraints for each metabolite (optional, default 0)
unconstrained : vector describing if each metabolite is an exchange metabolite (1) or not (0) (optional, default 0)
inchis : cell array with InChI strings (optional, default "")
metSmiles : cell array with SMILES strings (optional, default "")
metFormulas : cell array with the formulas (optional, default "")
metMiriams : cell array with MIRIAM structures (optional, default [])
metCharges : metabolite charge (optional, default NaN)
metDeltaG : Gibbs free energy of formation at biochemical standard condition in kJ/mole (optional, default NaN)
metNotes : cell array with metabolite notes as strings (optional, default "")

Name-Value Arguments

copyInfo : logical: when adding metabolites to a compartment where it previously did not exist, the function will copy any available annotation from the metabolite in another compartment (default true).
prefix : char: when metsToAdd.mets is not specified, new metabolite IDs are generated with the prefix specified here. If IDs with the prefix are already used in the model then the numbering will start from the highest existing integer+1 (default "m_").

Returns

newModel : struct: an updated model structure.

Examples

newModel = addMets(model, metsToAdd, copyInfo, prefix);

Notes

If multiple metabolites are added at once, the metMiriams cell array should be defined as (example with ChEBI and KEGG):

metsToAdd.metMiriams{1} = struct("name",{{"chebi";"kegg.compound"}},...
    "value",{{"CHEBI:18072";"C11821"}});
metsToAdd.metMiriams{2} = struct("name",{{"chebi";"kegg.compound"}},...
    "value",{{"CHEBI:31132";"C12248"}});

addRxns#

function newModel=addRxns(model,rxnsToAdd,varargin)

Add reactions to a model.

This function does not make extensive checks about formatting of gene-reaction rules.

When adding metabolites to a compartment where they previously do not exist, the function will copy any available information from the metabolite in another compartment.

Parameters

model : struct

a model structure.

rxnsToAdd : struct

the reaction structure, which can have the following fields:

rxns : cell array with unique strings that identifies each reaction
equations : cell array with equation strings. Decimal coefficients are expressed as "1.2". Reversibility is indicated by "<=>" or "=>"
mets : (alternative to equations) cell array with the metabolites involved in each reaction as nested arrays. E.g.: {{"met1","met2"},{"met1","met3","met4"}}. In the case of one single reaction added, it can be a string array: {"met1","met2"}
stoichCoeffs : (alternative to equations) cell array with the corresponding stoichiometries as nested vectors. E.g.: {[-1,+2],[-1,-1,+1]}. In the case of one single reaction added, it can be a vector: [-1,+2]
rxnNames : cell array with the names of each reaction (optional, default "")
lb : vector with the lower bounds (optional, default model.annotations.defaultLB or -inf for reversible reactions and 0 for irreversible when "equations" is used. When "mets" and "stoichCoeffs" are used it defaults for all to model.annotations.defaultLB or -inf)
ub : vector with the upper bounds (optional, default model.annotations.defaultUB or inf)
c : vector with the objective function coefficients (optional, default 0)
eccodes : cell array with the EC-numbers for each reaction. Delimit several EC-numbers with ";" (optional, default "")
subSystems : cell array with the subsystems for each reaction (optional, default "")
grRules : cell array with the gene-reaction relationship for each reaction. E.g. "(A and B) or (C)" means that the reaction could be catalyzed by a complex between A & B or by C on its own. All the genes have to be present in model.genes. Add genes with addGenesRaven before calling this function if needed (optional, default "")
rxnMiriams : cell array with Miriam structures (optional, default [])
rxnComps : cell array with compartments (as in model.comps) (optional, default {})
rxnNotes : cell array with reaction notes (optional, default "")
rxnDeltaG : Gibbs free energy at biochemical standard condition in kJ/mole (optional, default NaN)
rxnReferences : cell array with reaction references (optional, default "")
rxnConfidenceScores : vector with reaction confidence scores (optional, default NaN)

Name-Value Arguments

eqnType : double or char

describes how the equation string should be interpreted (default 1). Accepts integer values 1/2/3 or the string aliases "id", "name", "name[comp]":

1 / "id" : the metabolites are matched to model.mets. New metabolites (if allowed) are added to "compartment"
2 / "name" : the metabolites are matched to model.metNames and all metabolites are assigned to "compartment". Any new metabolites that are added will be assigned IDs "m1", "m2"... If IDs on the same form are already used in the model then the numbering will start from the highest used integer+1
3 / "name[comp]" : the metabolites are written as "metNames[comps]". Only compartments in model.comps are allowed. Any new metabolites that are added will be assigned IDs "m1", "m2"... If IDs on the same form are already used in the model then the numbering will start from the highest used integer+1

compartment : char

the compartment the metabolites should be placed in when using eqnType=2. Must match model.comps (optional when eqnType=1 or eqnType=3).

allowNewMets : logical or char

true if the function is allowed to add new metabolites. Can also be a string, which will be used as prefix for the new metabolite IDs. It is highly recommended to first add any new metabolites with addMets rather than automatically through this function. addMets supports more annotation of metabolites, allows for the use of exchange metabolites, and using it reduces the risk of parsing errors (default false).

allowNewGenes : logical

true if the function is allowed to add new genes (default false).

Returns

newModel : struct: an updated model structure.

Examples

newModel = addRxns(model, rxnsToAdd, eqnType, compartment, ...
                   allowNewMets, allowNewGenes);

addRxnsGenesMets#

function model=addRxnsGenesMets(model,sourceModel,rxns,varargin)

Copy reactions from a source model into another model.

Copies reactions from a source model to a new model, including (new) metabolites and genes.

This function only works if the draft model and source model follow the same metabolite and compartment naming convention. Metabolites are only matched by metaboliteName[compartment]. Useful if one wants to copy additional reactions from source to draft after getModelFromHomology was used involving the same models.

Parameters

model : struct: draft model where reactions should be copied to.
sourceModel : struct: model where reactions and metabolites are sourced from.
rxns : cell or char: reaction IDs (from source model). Can also be a string if only one reaction is added.

Name-Value Arguments

addGene : logical or char or cell

three options (default false):

false : no genes are annotated to the new reactions
true : grRules are copied from the sourceModel and new genes are added when required
string or cell array : new grRules are specified as string or cell array, and any new genes are added when required

rxnNote : cell or char

strings explaining why reactions were copied to the model, to be included as newModel.rxnNotes. Can also be a string if the same rxnNotes should be added for each new reaction, or only one reaction is to be added (default "Added via addRxnsAndMets()").

confidence : double

integer specifying confidence score for all reactions, following doi:10.1038/nprot.2009.203 (default 0):

4 : biochemical data: direct evidence from enzyme assays
3 : genetic data: knockout/-in or overexpression analysis
2 : physiological data: indirect evidence, e.g. secretion products or defined medium requirement; sequence data: genome annotation
1 : modeling data: required for functional model, hypothetical reaction
0 : no evidence

Returns

model : struct: an updated model structure.

Examples

newModel = addRxnsGenesMets(model, sourceModel, rxns, addGene, ...
                            rxnNote, confidence);

addTransport#

function [model, addedRxns]=addTransport(model,fromComp,toComps,varargin)

Add transport reactions between compartments.

This is a faster version than addRxns when adding transport reactions. New reaction names are formatted as "metaboliteName, fromComp-toComp", while new reaction IDs are sequentially counted with a tr_ prefix: e.g. tr_0001, tr_0002, etc.

Parameters

model : struct: a model structure.
fromComp : char: the id of the compartment to transport from (should match model.comps).
toComps : cell: compartment names to transport to (should match model.comps).

Name-Value Arguments

metNames : cell: the metabolite names to add transport for (default all metabolites in fromComp).
isRev : logical: true if the transport reactions should be reversible (default true).
onlyToExisting : logical: true if transport of a metabolite should only be added if it already exists in toComp. If false, then new metabolites are added with addMets first (default true).
prefix : char: prefix to reaction IDs (default "tr_").

Returns

model : struct: updated model structure.
addedRxns : cell: ids of the added reactions.

Examples

[model, addedRxns] = addTransport(model, fromComp, toComps, ...
                     metNames, isRev, onlyToExisting, prefix);

changeGrRules#

function model = changeGrRules(model,rxns,grRules,varargin)

Change multiple grRules at the same time.

Parameters

model : struct: a model structure to change the gene association.
rxns : char or cell: reaction IDs.
grRules : char or cell: additional or replacement gene association. Should be written with ' and ' to indicate subunits, ' or ' to indicate isoenzymes, and brackets '()' to separate different instances.

Name-Value Arguments

replace : logical: true if old gene association should be replaced with new association. False if new gene association should be concatenated to the old association (default true).

Returns

model : struct: an updated model structure.

Examples

model = changeGrRules(model, rxns, grRules, replace);

changeRxns#

function model=changeRxns(model,rxns,equations,varargin)

Modify the equations of reactions in a model.

Parameters

model : struct

a model structure.

rxns : cell

cell array with reaction ids.

equations : cell or struct

cell array with equations. Alternatively, it can be a structure with the fields "mets" and "stoichCoeffs", in the same fashion as addRxns. E.g.:

equations.mets = {{"met1","met2"},{"met1","met3"}}
equations.stoichCoeffs = {[-1,+2],[-1,+1]}

Name-Value Arguments

eqnType : double

describes how the equation string should be interpreted (default 1):

1 : the metabolites are matched to model.mets. New metabolites (if allowed) are added to "compartment".
2 : the metabolites are matched to model.metNames and all metabolites are assigned to "compartment". Any new metabolites that are added will be assigned IDs "m1", "m2"... If IDs on the same form are already used in the model then the numbering will start from the highest used integer+1.
3 : the metabolites are written as "metNames[compNames]". Only compartments in model.compNames are allowed. Any new metabolites that are added will be assigned IDs "m1", "m2"... If IDs on the same form are already used in the model then the numbering will start from the highest used integer+1.

compartment : char

a string with the compartment the metabolites should be placed in when using eqnType=2. Must match model.compNames (optional when eqnType=1 or eqnType=3).

allowNewMets : logical

true if the function is allowed to add new metabolites. It is highly recommended to first add any new metabolites with addMets rather than automatically through this function. addMets supports more annotation of metabolites, allows for the use of exchange metabolites, and using it reduces the risk of parsing errors (default false).

Returns

model : struct: an updated model structure.

Examples

model = changeRxns(model, rxns, equations, eqnType, compartment, allowNewMets);

Notes

This function should be used with some care, since it does not care about bounds on the reactions. Changing an irreversible reaction to a reversible one (or the other way around) will only change the model.rev field and not the model.lb/model.ub fields. The reaction will therefore still be having the same reversibility because of the bounds. Use setParams to change the bounds.

When adding metabolites to a compartment where it previously does not exist, the function will copy any available information from the metabolite in another compartment.

closeModel#

function closedModel=closeModel(model)

Add boundary metabolites and their exchange reactions.

Adds boundary metabolites and their participation in exchange reactions.

Parameters

model : struct: a model structure.

Returns

closedModel : struct: an updated model structure with boundary metabolites added.

Examples

closedModel = closeModel(model);

contractModel#

function [reducedModel, removedRxns, indexedDuplicateRxns]=contractModel(model,varargin)

Contract a model by grouping all identical reactions.

This is what simplifyModel's deleteDuplicates option runs; it is not a separate implementation. If the duplicated reactions have "EXP*" suffixes (where * is a digit), then the model is assumed to have been passed through expandModel, and these suffixes are removed here.

Reactions are merged, so their gene associations are combined rather than discarded. Use findDuplicateRxns instead to see which reactions are duplicates without changing the model.

Parameters

model : struct: a model structure.

Name-Value Arguments

distReverse : logical: distinguish reactions with same metabolites but different reversibility as different reactions (default true).
mets : char or cell: string or cell array of strings with metabolite identifiers, whose involved reactions should be checked for duplication (by default all reactions are considered). This option is used by replaceMets.

Returns

reducedModel : struct: a model structure without duplicate reactions.
removedRxns : cell: cell array for the removed duplicate reactions.
indexedDuplicateRxns : cell: indexed cell array for the removed duplicate reactions (multiple values separated by semicolon).

Examples

[reducedModel, removedRxns, indexedDuplicateRxns] = contractModel(model, distReverse, mets);

Notes

This code might not work for advanced grRules strings that involve nested expressions of "and" and "or".

convertToIrrev#

function [irrevModel,matchRev,rev2irrev,irrev2rev]=convertToIrrev(model,varargin)

Convert a model to irreversible form.

Reversible reactions are split into one forward and one reverse reaction. The reverse reactions are saved as 'rxnID_REV'. A warning is shown if some reaction identifiers already end with '_REV'.

Parameters

model : struct: a model structure.

Name-Value Arguments

rxns : cell: cell array with the reactions to split, if reversible (default model.rxns).

Returns

irrevModel : struct: a model structure where reversible reactions have been split into one forward and one reverse reaction.
matchRev : double: matching forward reaction to its backward reaction.
rev2irrev : cell: forward and backward reactions for reversible reactions.
irrev2rev : double: matching all reactions back to original model.

Examples

[irrevModel,matchRev,rev2irrev,irrev2rev]=convertToIrrev(model,rxns);

copyToComps#

function model=copyToComps(model,toComps,varargin)

Copy reactions to new compartment(s).

Parameters

model : struct: a model structure.
toComps : cell: cell array of compartment ids. If there is no match to model.comps then it is added as a new compartment (see compNames and compOutside).

Name-Value Arguments

rxns : cell or logical or double: either a cell array of reaction IDs, a logical vector with the same number of elements as reactions in the model, or a vector of indexes to copy (default model.rxns).
deleteOriginal : logical: true if the original reactions should be removed, making it move the reactions instead (default false).
compNames : cell: cell array of compartment names. Used if new compartments should be added (default toComps).
compOutside : cell: cell array of the id (as in comps) for the compartment surrounding each of the compartments. Used if new compartments should be added (default all {''}).

Returns

model : struct: an updated model structure.

Examples

model=copyToComps(model,toComps,rxns,deleteOriginal,compNames,compOutside);

Notes

New reactions and metabolites will be named as "id_toComps(i)".

deleteUnusedGenes#

function reducedModel=deleteUnusedGenes(model,varargin)

Delete all genes not associated to any reaction.

Parameters

model : struct: a model structure.

Name-Value Arguments

verbose : double: 0 for silent; 1 for printing the number of deleted genes; 2 for printing the list of deleted genes (default 1).

Returns

reducedModel : struct: an updated model structure.

Examples

reducedModel=deleteUnusedGenes(model);

expandModel#

function [newModel, rxnToCheck]=expandModel(model)

Expand reactions that use several gene associations.

Each reaction that uses several gene associations is split into several reactions, each under the control of only one gene.

Parameters

model : struct: a model structure.

Returns

newModel : struct: model structure with separate reactions for iso-enzymes, where the reaction ids are renamed as id_EXP_1, id_EXP_2, etc.
rxnToCheck : cell: cell array with original reaction identifiers for those whose grRule was not in disjunctive normal form, and so had to be expanded by distributivity, plus any whose grRule could not be parsed.

Examples

[newModel, rxnToCheck]=expandModel(model);

Notes

The isozymes are the AND-clauses of the grRule in disjunctive normal form, so nested expressions are expanded correctly: "g1 and (g2 or g3)" yields "g1 and g2" and "g1 and g3". Reactions listed in rxnToCheck are expanded correctly too; they are reported only because a rule needing distributivity is often a sign that the GPR was not what its author intended. Use standardizeGrRules/findPotentialErrors to inspect them.

findDuplicateRxns#

function pairs = findDuplicateRxns(model, varargin)

Find reactions that share identical stoichiometry.

The upstream version of yeast-GEM's findDuplicatedRxns.

Only stoichiometry is compared — bounds, GPRs, and annotations are ignored. The default treats A→B and B→A as duplicates (typical curation use case: "find reactions that could be merged").

Parameters

model : struct: RAVEN model struct.

Name-Value Arguments

ignoreDirection : logical: treat A→B and B→A as duplicates (default true).

Returns

pairs : double: Nx2 numeric array of reaction-index pairs (i, j) where reactions i and j share the same (possibly negated) stoichiometry, with i < j. Empty if the model has no duplicates.

Examples

pairs = findDuplicateRxns(model);
pairs = findDuplicateRxns(model, false);

findPotentialErrors#

function issues=findPotentialErrors(model)

Identify reactions with non-DNF GPR rules.

Detects grRules that are not in disjunctive normal form (DNF) — i.e. rules where an OR operator is nested inside an AND context. Standard RAVEN format requires DNF: groups of genes that must all be present together (enzyme complexes) are written as conjunctions, and the reaction is catalysed by at least one complex (disjunction of conjunctions).

Parameters

model : struct: a model structure with grRules and rxns fields.

Returns

issues : struct

struct array — one element per problematic reaction — with fields:

index : double — 1-based index into model.rxns.
rxn : char — reaction ID.
grRule : char — the problematic grRule string.
reason : char — short explanation.

Notes

Detection walks the parse tree from parseGrRule rather than searching the raw string, so gene IDs that contain substrings such as "and" or "or" do not cause false positives or negatives.

A rule is non-DNF when an AND operator has an OR anywhere beneath it. Bracketing alone never makes a rule non-DNF: "((G1 and G2) or G3)" and "(G1 or G2) or (G3 and G4)" are both fine. Use standardizeGrRules to attempt automatic repair.

Rules that cannot be parsed at all are reported as issues too, with the parser's message as the reason.

Examples

issues = findPotentialErrors(model);
if ~isempty(issues)
    fprintf("%d reactions with non-DNF grRules\n", numel(issues));
end
indexes2check = vertcat(issues.index);

generateNewIds#

function newIds=generateNewIds(model,type,prefix,varargin)

Generate a list of new metabolite or reaction ids.

The ids are sequentially numbered with a defined prefix. The model is queried for the highest existing number of that type of id.

Parameters

model : struct: model structure.
type : char: type of id, 'rxns' or 'mets'.
prefix : char: prefix to be used in all ids, e.g. 's_' or 'r_'.

Name-Value Arguments

quantity : double: number of new ids that should be generated (default 1).
numLength : double: length of the numerical part of the id. E.g. 4 gives ids like r_0001 and 6 gives ids like r_000001. If the prefix is already used in the model, then the model-defined length will be used instead (default 4).

Returns

newIds : cell: cell array with the generated ids.

Examples

newIds = generateNewIds(model, type, prefix, quantity, numLength);

mergeCompartments#

function [model, deletedRxns, duplicateRxns]=mergeCompartments(model,varargin)

Merge all compartments in a model.

Parameters

model : struct: a model structure.

Name-Value Arguments

keepUnconstrained : logical: keep metabolites that are unconstrained in a "unconstrained" compartment. If these are merged the exchange reactions will most often be deleted (default false).
deleteRxnsWithOneMet : logical: delete reactions with only one metabolite. These reactions come from reactions such as A[c] + B[c] => A[m]. In some models hydrogen is balanced around each membrane with reactions like this (default false).
distReverse : logical: distinguish reactions with same metabolites but different reversibility as different reactions (default true).

Returns

model : struct: a model with all reactions located to one compartment.
deletedRxns : cell: reactions that were deleted because of only having one metabolite after merging.
duplicateRxns : cell: identical reactions that occurred in different compartments and were deleted because they turned to be duplicated after merging.

Examples

[model, deletedRxns, duplicateRxns] = mergeCompartments(model);

Notes

Merges all compartments into one "s" compartment (for "System"). This can be useful for example to ensure that there are metabolic capabilities to synthesize all metabolites.

If the metabolite IDs reflect the compartment that they are in the IDs may no longer be representative.

mergeModels#

function model=mergeModels(models,varargin)

Merge models into one model structure.

Merges models into one model structure. Reactions are added without any checks, so duplicate reactions might appear. Metabolites are matched by their name and compartment (metaboliteName[comp]), while genes are matched by their name.

Parameters

models : cell: a cell array with model structures.

Name-Value Arguments

metParam : char: string, metabolite name ("metNames") or ID ("mets") are used for matching (default "metNames").
supressWarnings : logical: whether warnings should be supressed (default false).
copyToComps : logical: internal flag used by copyToComps.m when it calls mergeModels to duplicate a model into a new compartment; leave at default when calling mergeModels directly (default false).

Returns

model : struct: a model structure with the merged model. Follows the structure of normal models but also has "rxnFrom/metFrom/geneFrom" fields to indicate from which model each reaction/metabolite/gene was taken. If the model already has "rxnFrom/metFrom/geneFrom" fields, then these fields are not modified.

Examples

model = mergeModels(models);

permuteModel#

function newModel=permuteModel(model, indexes, type)

Change the order of the reactions or metabolites in a model.

Parameters

model : struct: a model structure.
indexes : double: a vector with the same length as the number of items in the model, which gives the new order of items.
type : char: 'rxns' for reactions, 'mets' for metabolites, 'genes' for genes, 'comps' for compartments.

Returns

newModel : struct: an updated model structure.

Examples

newModel = permuteModel(model, indexes, type);

removeBadRxns#

function [newModel, removedRxns]=removeBadRxns(model,varargin)

Remove reactions that enable production/consumption from nothing.

Iteratively removes reactions which enable production/consumption of some metabolite without any uptake/excretion.

Parameters

model : struct: a model structure. For the intended function, the model should not allow for any uptake/excretion. The easiest way to achieve this is to import the model using importModel("filename", false).

Name-Value Arguments

rxnRules : double

which reactions may be removed (default 1):

1 : only remove reactions which are unbalanced
2 : also remove reactions which could not be checked for mass balancing
3 : all reactions can be removed

ignoreMets : cell or logical or double

either a cell array of metabolite IDs, a logical vector with the same number of elements as metabolites in the model, or a vector of indexes for metabolites to exclude from this analysis (default []).

isNames : logical

true if the supplied mets represent metabolite names (as opposed to IDs). This is a way to delete metabolites in several compartments at once without knowing the exact IDs. This only works if ignoreMets is a cell array (default false).

balanceElements : cell

a cell array with the elements for which to balance the reactions. May contain any combination of the elements defined in parseFormulas (default {"C";"P";"S";"N";"O"}).

refModel : struct

a reference model which can be used to ensure that the resulting model is still functional. The intended use is that the reference model is a copy of model, but with uptake/excretion allowed and some objectives (such as production of biomass) constrained to a non-zero flux. Before a reaction is removed from "model" the function first checks that the same deletion in "refModel" does not render the problem unfeasible.

ignoreIntBounds : logical

true if internal bounds (including reversibility) should be ignored. Exchange reactions are not affected. This can be used to find unbalanced solutions which are not possible using the default constraints (default false).

printReport : logical

true if a report should be printed (default false).

seed : double

seed for the random number generator, so that which reaction is removed among several equally-valid candidates is reproducible across runs (default: current rng state is left untouched).

Returns

newModel : struct: a model structure after the problematic reactions have been deleted.
removedRxns : cell: a cell array with the reactions that were removed.

Notes

The purpose of this function is to remove reactions which enable production/consumption of metabolites even when exchange reactions are not used. Many models, especially if they are automatically inferred from databases, will have unbalanced reactions which allow for net-production/consumption of metabolites without any consumption or excretion. A common reason for this is when general compounds have different meaning in different reactions (as DNA has in these two reactions):

dATP + dGTP + dCTP + dTTP <=> DNA + 4 PPi
0.25 dATP + 0.25 dGTP + 0.25 dCTP + 0.25 dTTP <=> DNA + PPi

Reactions that are problematic like this are always elementally unbalanced, but it is not always the case that you would like to exclude all unbalanced reactions from your model. This function tries to remove as few problematic reactions as possible so that the model cannot produce/consume anything from nothing. This is done by repeatedly calling findLeakMetabolite, checking if any of the involved reactions are elementally unbalanced, removing one of them, and then iterating until no metabolites can be produced/consumed. The 'produce' direction is run before the 'consume' one.

Examples

[newModel, removedRxns] = removeBadRxns(model, rxnRules, ignoreMets, ...
    isNames, balanceElements, refModel, ignoreIntBounds, printReport);

removeGenes#

function reducedModel = removeGenes(model,genesToRemove,varargin)

Delete a set of genes from a model.

Parameters

model : struct: a model structure.
genesToRemove : cell or logical or double: either a cell array of gene IDs, a logical vector with the same number of elements as genes in the model, or a vector of indexes to remove.

Name-Value Arguments

removeUnusedMets : logical: remove metabolites that are no longer in use (default false).
removeBlockedRxns : logical: remove reactions that get blocked after deleting the genes (default false).
standardizeRules : logical: format gene rules to be compliant with the standard format (default true).

Returns

reducedModel : struct: an updated model structure.

Examples

reducedModel = removeGenes(model, genesToRemove, removeUnusedMets, ...
                   removeBlockedRxns, standardizeRules);

removeLowScoreGenes#

function [newModel,remGenes] = removeLowScoreGenes(model,geneScores,varargin)

Remove low-scoring genes from model.

This function removes genes from a model based on their scores, a step used by the tINIT package. The function recognizes and differentiates between isozymes and subunits of an enzyme complex. Genes are removed from each grRule, subject to the following conditions:

1) At least one gene must remain associated with the reaction.
2) Genes involved in a complex (joined by ANDs) are not removed.

Parameters

model : struct

model structure from which genes are to be removed.

geneScores : double

a vector of scores associated with the model genes. Genes with a positive score will remain in the model, whereas genes with a negative score will try to be removed.

If all genes associated with a reaction have a negative score, then the least-negative gene will remain; if there is a tie, the gene listed first in the rule will be kept.

If a negative-scoring gene is a subunit in a complex, it will not be removed; however, the entire complex may be removed. See the following example cases:

Original: G1 or (G2 and G3 and G4); Negative: G1, G2; New: G2 and G3 and G4.
Original: G1 or (G2 and G3) or (G4 and G5); Negative: G1, G2; New: G4 and G5 [using default complexScoring].
Original: (G1 and (G2 or G3) and G4); Negative: G2; New: (G1 and G3 and G4).

Name-Value Arguments

isozymeScoring : char: method used to combine the scores of multiple isozymes; "min", "max", "median", or "average" (default "max").
complexScoring : char: method used to combine the scores of enzyme complex subunits: "min", "max", "median", or "average" (default "min").

Returns

newModel : struct: model with updated gene, grRules, and rxnGeneMat fields after attempting to remove negative-score genes.
remGenes : cell: a list of negative-score genes that were fully removed from the model. Negative-score genes that were removed from some grRules but not all will not be included in this list.

removeMets#

function reducedModel=removeMets(model,metsToRemove,varargin)

Delete a set of metabolites from a model.

Parameters

model : struct: a model structure.
metsToRemove : cell or logical or double: either a cell array of metabolite IDs, a logical vector with the same number of elements as metabolites in the model, or a vector of indexes to remove.

Name-Value Arguments

isNames : logical: true if the supplied mets represent metabolite names (as opposed to IDs). This is a way to delete metabolites in several compartments at once without knowing the exact IDs. This only works if metsToRemove is a cell array (default false).
removeUnusedRxns : logical: remove reactions that are no longer in use (default false).
removeUnusedGenes : logical: remove genes that are no longer in use (default false).
removeUnusedComps : logical: remove compartments that are no longer in use (default false).

Returns

reducedModel : struct: an updated model structure.

Examples

reducedModel = removeMets(model, metsToRemove, isNames, ...
    removeUnusedRxns, removeUnusedGenes, removeUnusedComps);

removeReactions#

function reducedModel=removeReactions(model,rxnsToRemove,varargin)

Delete a set of reactions from a model.

Parameters

model : struct: a model structure.
rxnsToRemove : cell or logical or double: either a cell array of reaction IDs, a logical vector with the same number of elements as reactions in the model, or a vector of indexes to remove.

Name-Value Arguments

removeUnusedMets : logical: remove metabolites that are no longer in use (default false).
removeUnusedGenes : logical: remove genes that are no longer in use (default false).
removeUnusedComps : logical: remove compartments that are no longer in use (default false).

Returns

reducedModel : struct: an updated model structure.

Examples

reducedModel = removeReactions(model, rxnsToRemove, removeUnusedMets, ...
    removeUnusedGenes, removeUnusedComps);

replaceMets#

function [model, removedRxns, idxDuplRxns]=replaceMets(model,metabolite,replacement,varargin)

Replace a metabolite with another already in the model.

Replaces metabolite names and annotation with a replacement metabolite that is already in the model. If this results in duplicate metabolites, the replacement metabolite will be kept, while the S matrix is updated to use the replacement metabolite instead. At the end, contractModel is run to remove any duplicate reactions that might have occurred.

Parameters

model : struct: a model structure.
metabolite : char: string with name of metabolite to be replaced.
replacement : char: string with name of replacement metabolite.

Name-Value Arguments

verbose : logical: whether to print the ids of reactions that involve the replaced metabolite (default false).
identifiers : logical: true if 'metabolite' and 'replacement' refer to metabolite identifiers instead of metabolite names (default false).

Returns

model : struct: model structure with selected metabolites replaced.
removedRxns : cell: identifiers of duplicate reactions that were removed.
idxDuplRxns : double: index of removedRxns in original model.

Examples

[model, removedRxns, idxDuplRxns] = replaceMets(model, metabolite, ...
    replacement, verbose);

Notes

This function is useful when the model contains both 'oxygen' and 'o2' as metabolite names. If 'oxygen' and 'o2' are identifiers instead, then the 'identifiers' flag should be set to true.

reverseRxns#

function model=reverseRxns(model, rxns)

Reverses the given reactions in place: negates their stoichiometry and

objective coefficient, and swaps/negates their lower and upper bounds,
so flux in the new positive direction is what was previously negative flux.
model     the model to change (input/output)
rxns      the rxns to reverse

setExchangeBounds#

function [exchModel,unusedMets] = setExchangeBounds(model,varargin)

Define exchange flux bounds for a set of metabolites.

Parameters

model : struct: a model structure.

Name-Value Arguments

mets : cell or double: a cell array of metabolite names (case insensitive) or metabolite IDs, or a vector of metabolite indices (default all exchanged metabolites).
lb : double: lower bound of exchange flux. Can be either a vector of bounds corresponding to each of the provided metabolites, or a single value that will be applied to all (default model.annotation.defaultLB if it exists, otherwise -1000).
ub : double: upper bound of exchange flux. Can be either a vector of bounds corresponding to each of the provided metabolites, or a single value that will be applied to all (default model.annotation.defaultUB if it exists, otherwise 1000).
closeOthers : logical: close exchange reactions for all other exchanged metabolites not present in the provided list. This will prevent IMPORT of the metabolites, but their EXPORT will not be modified (default true).
mediaOnly : logical: only consider exchange reactions involving exchange to or from the extracellular (media) compartment. Reactions such as "sink" reactions that exchange metabolites directly with an intracellular compartment will therefore be ignored even though "getExchangeRxns" identifies such reactions as exchange reactions. The function will attempt to identify the extracellular compartment by the "compNames" field, and also requires the "metComps" field to be present, otherwise the mediaOnly flag will be ignored (default false).

Returns

exchModel : struct: a model structure with updated exchange flux bounds for the provided set of metabolites.
unusedMets : cell: metabolites provided by the user that were not used because they are not involved in any exchange reactions in the model.

Examples

exchModel = setExchangeBounds(model, mets, lb, ub, closeOthers, ...
    mediaOnly);

Notes

Exchange reactions involving more than one metabolite will be ignored.

setParam#

function model=setParam(model, paramType, rxnList, params, var)

Set parameters for reactions.

Parameters

model : struct

a model structure.

paramType : char

the type of parameter to set:

"lb" : lower bound.
"ub" : upper bound.
"eq" : both upper and lower bound (equality constraint).
"obj" : objective coefficient.
"rev" : reversibility (only changes the model.rev fields, does not affect model.lb and model.ub).
"var" : variance around measured bound.
"unc" : unconstrained, set lower and upper bound to the default values (-1000 and 1000, or any other values that are defined in model.annotation.defaultLB and .defaultUB).

rxnList : cell or double

a cell array of reaction IDs or a vector with their corresponding indexes.

params : double

a vector of the corresponding values.

var : double, optional

percentage of variance around measured value, if "var" is set as paramType. Defining "var" as 5 results in lb and ub at 97.5% and 102.5% of the provided params value (if params value is negative, then lb and ub are 102.5% and 97.5%).

Returns

model : struct: an updated model structure.

Examples

model = setParam(model, paramType, rxnList, params, var);

simplifyModel#

function [reducedModel, deletedReactions, deletedMetabolites]=simplifyModel(model,varargin)

Simplify a model by deleting reactions and metabolites.

This function is for reducing the model size by removing reactions and associated metabolites that cannot carry flux. It can also be used for identifying different types of gaps.

Parameters

model : struct: a model structure.

Name-Value Arguments

deleteUnconstrained : logical: delete metabolites marked as unconstrained (default true).
deleteDuplicates : logical: delete all but one of duplicate reactions (default false).
deleteZeroInterval : logical: delete reactions that are constrained to zero flux (default false).
deleteInaccessible : logical: delete dead end reactions (default false).
deleteMinMax : logical: delete reactions that cannot carry a flux by trying to minimize/maximize the flux through that reaction. May be time consuming (default false).
groupLinear : logical: group linearly dependent pathways (default false).
constrainReversible : logical: check if there are reversible reactions which can only carry flux in one direction, and if so constrain them to be irreversible. This tends to allow for more reactions grouped when using groupLinear (default false).
reservedRxns : cell: cell array with reaction IDs that are not allowed to be removed (default none).
suppressWarnings : logical: true if warnings should be suppressed (default false).

Returns

reducedModel : struct: an updated model structure.
deletedReactions : cell: a cell array with the IDs of all deleted reactions.
deletedMetabolites : cell: a cell array with the IDs of all deleted metabolites.

Examples

[reducedModel, deletedReactions, deletedMetabolites] = ...
    simplifyModel(model, deleteUnconstrained, deleteDuplicates, ...
    deleteZeroInterval, deleteInaccessible, deleteMinMax, ...
    groupLinear, constrainReversible, reservedRxns, suppressWarnings);

sortIdentifiers#

function newModel = sortIdentifiers(model)

Sort model identifiers alphabetically.

Sort reactions, metabolites, genes and compartments alphabetically by their identifier.

Parameters

model : struct: a model structure.

Returns

newModel : struct: an updated model structure with alphabetically sorted identifiers.

Examples

newModel = sortIdentifiers(model);

sortModel#

function model=sortModel(model,varargin)

Standardize a model's internal ordering: by default orients

reversible reactions consistently; can also reorder metabolites within reaction equations and/or reactions within each subsystem, depending on which options are enabled.

Parameters

model : struct: a model structure.

Name-Value Arguments

sortReversible : logical: sorts the reversible reactions so that the metabolite that is first in lexicographical order is a reactant (default true).
sortMetName : logical: sort the metabolite names in the equation, also uses compartment abbreviation (default false).
sortReactionOrder : logical: sorts the reaction order within each subsystem so that reactions consuming some metabolite come after reactions producing it. This overrides the sortReversible option and reactions are sorted so that the production direction matches the consumption direction (default false).
seed : double: seed for the random number generator used by the sortReactionOrder local search, so its result is reproducible across runs (default: current rng state is left untouched).

Returns

model : struct: an updated model structure.

Examples

model = sortModel(model, sortReversible, sortMetName, sortReactionOrder);

standardizeGrRules#

function [grRules,rxnGeneMat,indexes2check] = standardizeGrRules(model,varargin)

Standardize gene-reaction rules in a model.

The grRules are standardized according to the following:

No overall containing brackets
Just enzyme complexes are enclosed into brackets
" and " and " or " strings are strictly set to lowercase

A rxnGeneMat matrix consistent with the standardized grRules is created.

Parameters

model : struct: a model structure.

Name-Value Arguments

embedded : logical: if true, suppresses the console warning about potentially problematic grRules relationships, for use when this function is called inside of another RAVEN function that handles reporting itself (default false).

Returns

grRules : cell: [nRxns x 1] cell array with the standardized grRules.
rxnGeneMat : double: [nRxns x nGenes] sparse matrix consistent with the standardized grRules.
indexes2check : double: indices of the grRules with potentially problematic relationships that should be checked manually.

Examples

[grRules, rxnGeneMat, indexes2check] = standardizeGrRules(model, embedded);

Notes

If used in a model reconstruction or modification pipeline, run this function first.