Queries#

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

Functions#

Function	Summary
`buildEquation`	Construct single equation string for a given reaction.
`checkModelStruct`	Check a model structure for errors and inconsistencies.
`constructEquations`	Construct equation strings for reactions.
`constructS`	Construct a stoichiometric matrix from a cell array of equations.
`getAllRxnsFromGenes`	Find all reactions annotated by the genes of a set.
`getElementalBalance`	Check whether the reactions of a model are balanced.
`getExchangeRxns`	Retrieve the exchange reactions from a model.
`getGenesFromGrRules`	Extract gene list and rxnGeneMat from grRules array.
`getIndexes`	Retrieve the indexes for a list of reactions or metabolites.
`getRxnsInComp`	Get the reactions in a specified compartment.
`getTransportRxns`	Retrieve the transport reactions from a model.
`modelSummary`	Print an overview of a RAVEN model and its flux state.
`parseFormulas`	Get the elemental composition from formulas.
`parseRxnEqu`	Get all metabolite names from a cell array of equations.
`printFluxes`	Print reactions and fluxes to the screen or to a file.
`printModelStats`	Print statistics about a model to the screen.

Reference#

buildEquation#

function equationString=buildEquation(mets,stoichCoeffs,isrev)

Construct single equation string for a given reaction.

Parameters

mets : cell: metabolites involved in the reaction.
stoichCoeffs : double: vector with the corresponding stoichiometric coefficients, of the same length as mets. Negative coefficients are reactants and positive coefficients are products.
isrev : logical: true if the reaction is reversible (written with "<=>"), false if it is irreversible (written with "=>").

Returns

equationString : char: the equation as a string.

Examples

equationString = buildEquation(mets, stoichCoeffs, isrev);

checkModelStruct#

function issues=checkModelStruct(model,varargin)

Check a model structure for errors and inconsistencies.

Parameters

model : struct: a model structure.

Name-Value Arguments

throwErrors : logical: true if structural problems (wrong types, missing required fields, duplicate IDs and other problems of structure) should throw an error. Advisory notices such as unused elements and bound inconsistencies are always reported as warnings regardless of this flag (default true).
trimWarnings : logical: true if a given warning or error lists at most 10 items, the last of which reports the number of remaining items (default true).

Returns

issues : struct

When called with an output argument, the function returns a struct array with one element per finding and neither throws nor prints. The default behaviour without an output argument is to print warnings and throw errors. Fields:

category (char): type of issue, one of "missing_field", "wrong_type", "empty_id", "duplicate", "invalid_id", "invalid_bounds", "unused", "objective", "gpr", "invalid_formula", "cross_reference" or "other".
target (char): the item involved (field name, reaction ID, metabolite ID or another item), or "" when not applicable.
message (char): the full diagnostic text.

Notes

The check is intended for use after importing or constructing a model and before exporting a model to SBML format.

Examples

checkModelStruct(model);
checkModelStruct(model, "throwErrors", false);
issues = checkModelStruct(model);

constructEquations#

function equationStrings=constructEquations(model,varargin)

Construct equation strings for reactions.

Parameters

model : struct: a model structure.

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 reaction indexes (default model.rxns).
useComps : logical: include the compartment of each metabolite (default true).
sortRevRxns : logical: sort reversible reactions so that the metabolite that is first in the lexicographic order is a reactant (default false).
sortMetNames : logical: sort the metabolite names in the equation. The compartment is included in the sorting even if useComps is false (default false).
useMetID : logical: use metabolite ID in generated equations. Cannot be true together with useFormula (default false).
useFormula : logical: use metabolite formula in generated equations. Cannot be true together with useMetID (default false).
useRevField : logical: use the model.rev field to indicate reaction reversibility. When false, a reaction is reversible if model.lb < 0 and model.ub > 0 (default true).

Returns

equationStrings : cell: a cell array with the equation of each reaction.

Examples

equationStrings = constructEquations(model, rxns, useComps, ...
    sortRevRxns, sortMetNames, useMetID, useFormula, useRevField);

Notes

If useRevField is false, the reactions have to be written in their forward direction (for example ub = 1000 and lb = -1000 or 0) for the reversibility to be determined correctly.

constructS#

function [S, mets, badRxns, reversible]=constructS(equations,varargin)

Construct a stoichiometric matrix from a cell array of equations.

Parameters

equations : cell: cell array of equations in the form "A + 2 B <=> 3 C", where <=> indicates reversible and => irreversible reactions.

Name-Value Arguments

mets : cell: cell array of metabolites. All metabolites in the equations must be present in the list, otherwise an error is thrown (default generated from the equations).
rxns : cell: cell array of reaction ids. Used to print reaction ids in error messages in place of equations (default []).

Returns

S : double: the resulting stoichiometric matrix.
mets : cell: cell array with the metabolites in the order of the rows of the S matrix.
badRxns : logical: logical vector with true for the reactions in which one or more metabolites occur more than once, for example as both substrate and product. An example is the phosphotransferase reaction ATP + ADP <=> ADP + ATP, which gives an empty column in the stoichiometric matrix.
reversible : logical: logical vector with true if the equation is reversible.

Examples

[S, mets, badRxns, reversible] = constructS(equations, mets);

getAllRxnsFromGenes#

function allRxns=getAllRxnsFromGenes(model,rxns)

Find all reactions annotated by the genes of a set.

Given a list of reactions, this function finds the associated genes in the model and returns all reactions that are annotated by these genes, including the given reactions.

Parameters

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

Returns

allRxns : cell or logical or double: the reactions in the same format as rxns: a cell array of IDs (unique and sorted), a logical vector with the same number of elements as reactions in the model, or a vector of indexes (unique and sorted).

Examples

allRxns = getAllRxnsFromGenes(model, rxns);

getElementalBalance#

function balanceStructure=getElementalBalance(model,varargin)

Check whether the reactions of a model are balanced.

Checks whether the reactions are elementally balanced, using the metFormulas field or, when that is absent, the inchis field. An error is thrown if the model has neither field. The charge balance is reported separately.

Parameters

model : struct: a model structure.

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. Only these reactions are checked (default model.rxns).
printUnbalanced : logical: print warnings about the reactions that are unbalanced (default false).
printUnparsable : logical: print warnings about the reactions that cannot be balanced because of missing information or parsing errors (default false).

Returns

balanceStructure : struct

elemental balance structure with fields:

balanceStatus : 1 if the reaction is balanced, 0 if it is unbalanced, -1 if it could not be balanced due to missing information (including a reaction without metabolites), -2 if it could not be balanced because a formula could not be parsed. Elemental only; charge is reported in chargeStatus
chargeStatus : 1 if the reaction is charge balanced, 0 if it is not, -1 if any participating metabolite has no charge, the reaction has no metabolites, or the model has no metCharges field; the charge balance is then unknown
chargeResidual : the sum of charges over the reaction, NaN where chargeStatus is -1
elements : struct with fields abbrevs (cell array with abbreviations for all used elements) and names (cell array with the names for all used elements)
leftComp : MxN matrix with the sum of coefficients for each of the elements (N) for the left side of the reactions (M)
rightComp : the corresponding matrix for the right side

Examples

balanceStructure = getElementalBalance(model, rxns, printUnbalanced, printUnparsable);

getExchangeRxns#

function [exchangeRxns, exchangeRxnsIndexes, exchangedMets]=getExchangeRxns(model,varargin)

Retrieve the exchange reactions from a model.

Exchange reactions are identified by having either no substrates or no products. In a model with metabolites marked in the unconstrained field, the exchange reactions are the reactions that involve such a metabolite (as substrate for 'in', as product for 'out').

Parameters

model : struct: a model structure.

Name-Value Arguments

reactionType : char

which exchange reactions should be returned (default 'all'):

'all' : all reactions, irrespective of reaction bounds
'uptake' : reactions with bounds that imply that only uptake is allowed. Reaction direction, upper and lower bounds are all considered
'excrete' : reactions with bounds that imply that only excretion is allowed. Reaction direction, upper and lower bounds are all considered
'reverse' : reactions with non-zero upper and lower bounds that imply that both uptake and excretion are allowed
'blocked' : reactions that have zero upper and lower bounds, not allowing any flux
'in' : reactions where the boundary metabolite is the substrate of the reaction; a positive flux value would imply uptake, but reaction bounds are not considered
'out' : reactions where the boundary metabolite is the product of the reaction; a negative flux value would imply uptake, but reaction bounds are not considered

Returns

exchangeRxns : cell: cell array with the IDs of the exchange reactions.
exchangeRxnsIndexes : double: vector with the indexes of the exchange reactions.
exchangedMets : double: vector with the index of the first metabolite with a non-zero coefficient in each exchange reaction (0 if there is none). Only computed when requested.

Notes

The union of 'in' and 'out' equals 'all'. Also, the union of 'uptake', 'excrete', 'reverse' and 'blocked' equals 'all'.

Examples

[exchangeRxns, exchangeRxnsIndexes] = getExchangeRxns(model, reactionType);

getGenesFromGrRules#

function [genes,rxnGeneMat] = getGenesFromGrRules(grRules, varargin)

Extract gene list and rxnGeneMat from grRules array.

Parameters

grRules : cell: a cell array of model grRules, from which a list of genes is to be extracted. Boolean operators can be text ("and", "or") or symbolic ("&", "|"), with a space between operators and gene names or IDs.

Name-Value Arguments

originalGenes : cell: the original gene list from the model. If supplied, the genes parsed from grRules must match it as a set, otherwise an error is thrown, and the returned genes list follows the order of originalGenes.

Returns

genes : cell: a unique, sorted list of all gene IDs that appear in grRules (in the order of originalGenes when supplied).
rxnGeneMat : double: (optional) a sparse binary matrix indicating which genes participate in each reaction, where rows correspond to reactions (entries in grRules) and columns correspond to genes. Only computed when requested.

Examples

[genes, rxnGeneMat] = getGenesFromGrRules(grRules, originalGenes);

getIndexes#

function indexes=getIndexes(model, objects, type, varargin)

Retrieve the indexes for a list of reactions or metabolites.

Parameters

model : struct: a model structure.
objects : cell or logical or double: either a cell array of IDs, a logical vector with the same number of elements as objects of the given type in the model, or a vector of indexes. An error is raised if an ID is not found in the model, except for type 'metnames', where a name that is not found gives an empty index vector.
type : char: 'rxns', 'mets' or 'genes', depending on what to retrieve. 'metnames' queries metabolite names and returns, for each name, the indexes of all metabolites with that name. 'metcomps' queries specific metabolites and their compartments in the format metaboliteName[comp]. An error is raised if such a name matches no metabolite, or more than one. If a model.ec structure exists (GECKO 3), 'ecenzymes', 'ecrxns' and 'ecgenes' are also allowed.

Name-Value Arguments

returnLogical : logical: sets whether to return a logical array or an array with the indexes (default false). It cannot be true for type 'metnames', which raises the error RAVEN:badInput.

Returns

indexes : logical or double: a logical array if returnLogical is true, otherwise a double array. For 'metnames' with several names, a cell array of double vectors.

Notes

If 'ecenzymes', 'ecrxns' or 'ecgenes' are used with a GECKO 3 model, then the indexes are from the model.ec.enzymes, model.ec.rxns or model.ec.genes fields, respectively.

Examples

indexes = getIndexes(model, objects, type, returnLogical);

getRxnsInComp#

function [I, rxnNames]=getRxnsInComp(model,comp,varargin)

Get the reactions in a specified compartment.

Parameters

model : struct: a model structure.
comp : char: the compartment id (case insensitive). An error is thrown if the id does not match exactly one compartment.

Name-Value Arguments

includePartial : logical: true if reactions with metabolites in several compartments (for example transport reactions) are included (default false).

Returns

I : double: indexes of the reactions in the compartment.
rxnNames : cell: the names of these reactions.

Examples

[I, rxnNames] = getRxnsInComp(model, comp, includePartial);

getTransportRxns#

function transportRxns=getTransportRxns(model)

Retrieve the transport reactions from a model.

Parameters

model : struct: a model structure.

Returns

transportRxns : logical: logical array with true if the corresponding reaction is a transport reaction.

Examples

transportRxns = getTransportRxns(model);

Notes

Transport reactions are defined as reactions involving (at least) one metabolite name in more than one compartment. Exchange reactions, as identified by getExchangeRxns, are not transport reactions.

modelSummary#

function modelSummary(model, varargin)

Print an overview of a RAVEN model and its flux state.

Prints the model dimensions and the objective function. When a flux vector is supplied, it also prints the objective value and the net exchange fluxes, partitioned into uptake and secretion.

Parameters

model : struct: RAVEN model structure.

Name-Value Arguments

fluxes : double: flux vector with numel(model.rxns) elements. When provided, the objective value and the exchange-flux summary are printed (default []).
cutoff : double: minimum absolute net exchange flux to include (default 1e-8).
nMax : double: maximum number of exchange reactions displayed per direction, in descending order of absolute flux (default 20).

Examples

modelSummary(model)
modelSummary(model, 'fluxes', sol.x)
modelSummary(model, 'fluxes', sol.x, 'nMax', 10)

parseFormulas#

function [elements, useMat, exitFlag, MW]=parseFormulas(formulas, varargin)

Get the elemental composition from formulas.

Parameters

formulas : cell: a cell array with formulas.

Name-Value Arguments

noPolymers : logical: treat polymers as a single unit: everything between (...)n is counted with n equal to one. Only one set of parentheses is allowed. If this is false, polymers get exitFlag -1, "Could not parse formula" (default false).
isInchi : logical: true if the formulas are in the InChI format (default false).
ignoreRX : logical: set the atomic weight of R-groups and bound protein to 0, which allows MW to be calculated for formulas that contain them. The atoms are still counted in useMat (default false).

Returns

elements : struct

struct with fields:

abbrevs : cell array with abbreviations for all used elements
names : cell array with the names for all used elements

Elements that occur in none of the formulas are not included.

useMat : double

MxN matrix with the number of atoms for each formula (M) and each element (N).

exitFlag : double

array with the exit flags:

1 : successful parsing
0 : no formula found
-1 : could not parse formula

MW : double

predicted molecular weight (g/mol). This is only calculated when requested, and only for formulas which can be successfully parsed; its calculation does not affect the exitFlag variable. NaN is returned if the weight cannot be calculated, for example for formulas that contain R-groups or bound protein while ignoreRX is false.

Examples

[elements, useMat, exitFlag, MW] = ...
    parseFormulas(formulas, noPolymers, isInchi, ignoreRX);

parseRxnEqu#

function metabolites=parseRxnEqu(equations)

Get all metabolite names from a cell array of equations.

Parameters

equations : cell: a cell array with equation strings.

Returns

metabolites : cell: a unique, sorted cell array with the involved metabolites.

Examples

metabolites = parseRxnEqu(equations);

Notes

The equations are written like:

1 A + 3 B (=> or <=>) 5 C + 2 D

with a space around each arrow and plus sign and between a coefficient and its metabolite name. If the equation is expressed as for example '... + (n-1) starch', '(n-1) starch' is interpreted as one metabolite.

printFluxes#

function printFluxes(model, fluxes, varargin)

Print reactions and fluxes to the screen or to a file.

Parameters

model : struct: a model structure.
fluxes : double: a vector with fluxes, or a matrix with one row per reaction and one column per flux distribution.

Name-Value Arguments

onlyExchange : logical: only print exchange fluxes (default true).
cutOffFlux : double: only print fluxes with absolute values above or equal to this value (default 10^-8).
outputFile : char: a file to save the print-out to (default is output to the command window).
outputString : char: a string that specifies the output of each reaction (default "%rxnID\t(%rxnName):\t%flux\n").
metaboliteList : cell: cell array of metabolite names (case insensitive). Only reactions involving any of these metabolites are printed.

Notes

The following codes are available for user-defined output strings:

names
not be parsed
right-hand sides are lumped

Examples

printFluxes(model, fluxes, 'onlyExchange', false, 'cutOffFlux', 10^-6, ...
            'outputFile', 'fluxes.txt', 'metaboliteList', {'glucose'});

printModelStats#

function printModelStats(model, varargin)

Print statistics about a model to the screen.

Prints the numbers of genes, reactions and metabolites in total and per compartment, the number of unique EC codes (if the eccodes field exists), the number of biochemically unique reactions and the number of unique metabolite names.

Parameters

model : struct: a model structure.

Name-Value Arguments

printModelIssues : logical: true if information about unused metabolites, empty reactions, dead-end reactions and metabolites, and elemental balancing is printed (default false).
printDetails : logical: true if the individual metabolites and reactions of each issue are listed. Used only if printModelIssues is true (default true).

Examples

printModelStats(model, printModelIssues, printDetails);