Manipulation¶

MATLAB functions in RAVEN/manipulation of the RAVEN toolbox. Help text is collected from the source of the tracked branch.

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.
`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.
`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`	Sort a model based on metabolite names and compartments.
`standardizeGrRules`	Standardize gene-reaction rules in a model.

Reference¶

addExchangeRxns¶

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`reactionType`	`char`	the type of reactions to add: 'in' : input reactions 'out' : output reactions 'both' : reversible input/output reactions. Positive direction corresponds to output	required

Name-value arguments:

Name	Type	Description	Default
`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).

Output arguments:

Name	Type	Description
`model`	`struct`	updated model structure.
`addedRxns`	`cell`	ids of the added reactions.

Examples:

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

addGenesRaven¶

Add genes to a model.

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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 "")	required

Output arguments:

Name	Type	Description
`newModel`	`struct`	an updated model structure.

Examples:

newModel = addGenesRaven(model, genesToAdd);

addMets¶

Add metabolites to a model.

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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 "")	required

Name-value arguments:

Name	Type	Description	Default
`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_").

Output arguments:

Name	Type	Description
`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¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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)	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`newModel`	`struct`	an updated model structure.

Examples:

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

addRxnsGenesMets¶

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.

Input arguments:

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

Name-value arguments:

Name	Type	Description
`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

Output arguments:

Name	Type	Description
`model`	`struct`	an updated model structure.

Examples:

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

addTransport¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`fromComp`	`char`	the id of the compartment to transport from (should match model.comps).	required
`toComps`	`cell`	compartment names to transport to (should match model.comps).	required

Name-value arguments:

Name	Type	Description
`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_").

Output arguments:

Name	Type	Description
`model`	`struct`	updated model structure.
`addedRxns`	`cell`	ids of the added reactions.

Examples:

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

changeGrRules¶

Change multiple grRules at the same time.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure to change the gene association.	required
`rxns`	`char or cell`	reaction IDs.	required
`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.	required

Name-value arguments:

Name	Type	Description	Default
`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).

Output arguments:

Name	Type	Description
`model`	`struct`	an updated model structure.

Examples:

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

changeRxns¶

Modify the equations of reactions in a model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`rxns`	`cell`	cell array with reaction ids.	required
`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]}	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`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¶

Add boundary metabolites and their exchange reactions.

Adds boundary metabolites and their participation in exchange reactions.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Output arguments:

Name	Type	Description
`closedModel`	`struct`	an updated model structure with boundary metabolites added.

Examples:

closedModel = closeModel(model);

contractModel¶

Contract a model by grouping all identical reactions.

Similar to the deleteDuplicates part in simplifyModel but more care is taken here when it comes to gene associations. 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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`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.

Output arguments:

Name	Type	Description
`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¶

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`rxns`	`cell`	cell array with the reactions to split, if reversible (default model.rxns).

Output arguments:

Name	Type	Description
`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¶

Copy reactions to new compartment(s).

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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).	required

Name-value arguments:

Name	Type	Description
`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 {''}).

Output arguments:

Name	Type	Description
`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¶

Delete all genes not associated to any reaction.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`verbose`	`double`	0 for silent; 1 for printing the number of deleted genes; 2 for printing the list of deleted genes (default 1).

Output arguments:

Name	Type	Description
`reducedModel`	`struct`	an updated model structure.

Examples:

reducedModel=deleteUnusedGenes(model);

expandModel¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Output arguments:

Name	Type	Description
`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 that contained nested and/or-relationships in grRules.

Examples:

[newModel, rxnToCheck]=expandModel(model);

Notes

grRules strings that involve nested expressions of 'and' and 'or' might not be parsed correctly if they are not standardized (if the standardizeGrRules function was not first run on the model). For those reactions, it is therefore advisable to inspect the reactions in rxnToCheck to confirm correct model expansion.

findDuplicateRxns¶

Find reactions that share identical stoichiometry.

Counterpart of raven_python.manipulation.find_duplicate_reactions, and 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").

Input arguments:

Name	Type	Description	Default
`model`	`struct`	RAVEN model struct.	required

Name-value arguments:

Name	Type	Description	Default
`ignoreDirection`	`logical`	treat A→B and B→A as duplicates (default true).

Output arguments:

Name	Type	Description
`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¶

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure with grRules and rxns fields.	required

Output arguments:

Name	Type	Description
`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 uses a parse-tree walk rather than substring search, so gene IDs that contain substrings such as "and" or "or" do not cause false positives or negatives.

A rule is non-DNF when the top-level operator is AND and one of its operands contains OR, or equivalently when any OR subexpression appears inside a bracket group that is joined to another group by AND. Use standardizeGrRules to attempt automatic repair.

Examples:

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

generateNewIds¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	model structure.	required
`type`	`char`	type of id, 'rxns' or 'mets'.	required
`prefix`	`char`	prefix to be used in all ids, e.g. 's_' or 'r_'.	required

Name-value arguments:

Name	Type	Description	Default
`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).

Output arguments:

Name	Type	Description
`newIds`	`cell`	cell array with the generated ids.

Examples:

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

mergeCompartments¶

Merge all compartments in a model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`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¶

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.

Input arguments:

Name	Type	Description	Default
`models`	`cell`	a cell array with model structures.	required

Name-value arguments:

Name	Type	Description
`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`	whether mergeModels is run via copyToComps (default false).

Output arguments:

Name	Type	Description
`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¶

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

Input arguments:

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

Output arguments:

Name	Type	Description
`newModel`	`struct`	an updated model structure.

Examples:

newModel = permuteModel(model, indexes, type);

removeBadRxns¶

Remove reactions that enable production/consumption from nothing.

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

Input arguments:

Name	Type	Description	Default
`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).	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`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 makeSomething/consumeSomething, checking if any of the involved reactions are elementally unbalanced, removing one of them, and then iterating until no metabolites can be produced/consumed. makeSomething is called before consumeSomething.

Examples:

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

removeGenes¶

Delete a set of genes from a model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`reducedModel`	`struct`	an updated model structure.

Examples:

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

removeMets¶

Delete a set of metabolites from a model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`reducedModel`	`struct`	an updated model structure.

Examples:

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

removeReactions¶

Delete a set of reactions from a model.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`reducedModel`	`struct`	an updated model structure.

Examples:

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

replaceMets¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`metabolite`	`char`	string with name of metabolite to be replaced.	required
`replacement`	`char`	string with name of replacement metabolite.	required

Name-value arguments:

Name	Type	Description	Default
`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).

Output arguments:

Name	Type	Description
`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.

setExchangeBounds¶

Define exchange flux bounds for a set of metabolites.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`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¶

Set parameters for reactions.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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).	required
`rxnList`	`cell or double`	a cell array of reaction IDs or a vector with their corresponding indexes.	required
`params`	`double`	a vector of the corresponding values.	required
`var`	`double`	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%).	required

Output arguments:

Name	Type	Description
`model`	`struct`	an updated model structure.

Examples:

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

simplifyModel¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`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¶

Sort model identifiers alphabetically.

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Output arguments:

Name	Type	Description
`newModel`	`struct`	an updated model structure with alphabetically sorted identifiers.

Examples:

newModel = sortIdentifiers(model);

sortModel¶

Sort a model based on metabolite names and compartments.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description
`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).

Output arguments:

Name	Type	Description
`model`	`struct`	an updated model structure.

Examples:

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

standardizeGrRules¶

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.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required

Name-value arguments:

Name	Type	Description	Default
`embedded`	`logical`	true if this function is called inside of another RAVEN function (default false).

Output arguments:

Name	Type	Description
`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 this function is going to be used in a model reconstruction or modification pipeline it is recommended to run this function just at the beginning of the process.