Queries#

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

Functions#

Function	Summary
`buildEquation`	Construct single equation string for a given reaction.
`checkModelStruct`	Perform a number of checks to ensure a model structure is ok.
`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 a concise 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 some 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 corresponding stoichiometric coeffs.
isrev : logical: indicates if the reaction is reversible or not.

Returns

equationString : char: equation as a string.

Examples

equationString = buildEquation(mets, stoichCoeffs, isrev);

checkModelStruct#

function issues=checkModelStruct(model,varargin)

Perform a number of checks to ensure a model structure is ok.

Parameters

model : struct: a model structure.

Name-Value Arguments

throwErrors : logical: true if structural problems (wrong types, missing required fields, duplicate IDs, etc.) 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 only a maximum of 10 items should be displayed in a given warning or error (default true).

Returns

issues : struct

When called with an output argument, returns a struct array with one element per finding (does not throw or print) instead of the default print/throw behaviour. Fields:

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

Notes

This is typically performed after importing or constructing a model, or before attempting to export 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. Uses compartment even if useComps is false (default false).
useMetID : logical: use metabolite ID in generated equations (default false).
useFormula : logical: use metabolite formula in generated equations (default false).
useRevField : logical: use the model.rev field to indicate reaction reversibility, alternatively this is determined from the model.ub and model.lb fields (default true).

Returns

equationStrings : cell: a cell array with equations.

Examples

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

Notes

If useRevField is false, then reactions should be organized in their forward direction (e.g. ub = 1000 and lb = -1000/0) for the reversibility to be correctly determined.

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 on 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 (default generated from the equations).
rxns : cell: cell array of reaction ids. This is only used for printing reaction ids instead of equations in warnings/errors (default []).

Returns

S : double: the resulting stoichiometric matrix.
mets : cell: cell array with metabolites that corresponds to the order in the S matrix.
badRxns : logical: boolean vector with the reactions that have one or more metabolites as both substrate and product. An example would be the phosphotransferase ATP + ADP <=> ADP + ATP. In the stoichiometric matrix this equals to an empty reaction which can be problematic.
reversible : logical: boolean 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.

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: 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, dependent on the format of rxns.

Examples

allRxns = getAllRxnsFromGenes(model, rxns);

getElementalBalance#

function balanceStructure=getElementalBalance(model,varargin)

Check whether the reactions of a model are balanced.

Checks a model to see if the reactions are elementally balanced.

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 will be checked (default model.rxns).
printUnbalanced : logical: print warnings about the reactions that were unbalanced (default false).
printUnparsable : logical: print warnings about the reactions that cannot be parsed (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, -2 if it could not be balanced due to an error. Elemental only; charge is reported separately below
chargeStatus : 1 if the reaction is charge balanced, 0 if it is not, -1 if any participating metabolite has no charge (or the model has no metCharges field), in which case the charge balance is unknown rather than zero
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.

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 metabolite index for each exchange reaction (one metabolite per exchange reaction). 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. NOTE: Boolean operators can be text ("and", "or") or symbolic ("&", "|"), but there must be a space between operators and gene names/IDs.

Name-Value Arguments

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

Returns

genes : cell: a unique list of all gene IDs that appear in grRules.
rxnGeneMat : double: (optional) a binary matrix indicating which genes participate in each reaction, where rows correspond to reactions (entries in grRules) and columns correspond to genes.

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 metabolites in the model, or a vector of indexes.
type : char: 'rxns', 'mets', or 'genes' depending on what to retrieve. 'metnames' queries metabolite names, while 'metcomps' allows providing 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), then also 'ecenzymes', 'ecrxns' and 'ecgenes' are allowed.

Name-Value Arguments

returnLogical : logical: sets whether to return a logical array or an array with the indexes (default false).

Returns

indexes : logical or double: can be a logical array or a double array depending on the value of returnLogical.

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: string with the compartment id.

Name-Value Arguments

includePartial : logical: true if reactions with metabolites in several compartments (normally transport reactions) should be included (default false).

Returns

I : double: boolean vector of the reactions.
rxnNames : cell: the names of the 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.

modelSummary#

function modelSummary(model, varargin)

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

Prints model dimensions, the objective function, and — when a flux vector is supplied — the objective value plus all net exchange fluxes partitioned into uptake and secretion.

Parameters

model : struct: RAVEN model structure.

Name-Value Arguments

fluxes : double: flux vector (length = numel(model.rxns)). When provided, shows the objective value and the exchange-flux summary (default []).
cutoff : double: minimum absolute net exchange flux to include (default 1e-8).
nMax : double: maximum exchange reactions displayed per direction (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: assume that all polymers consist of one element. Corresponds to counting everything between (...)n as n being equal to one. Only one set of parentheses is allowed. If this is false then polymers are returned as "Could not parse formula" (default false).
isInchi : logical: true if the formulas are in the InChI format (default false).
ignoreRX : logical: ignore R-groups and bound protein. This can be useful since they are often used only as intermediates (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

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 returned for formulas which can be successfully parsed, and its calculation doesn't affect the exitFlag variable. NaN is returned if the weight couldn't be calculated.

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 cell array with the involved metabolites.

Examples

metabolites = parseRxnEqu(equations);

Notes

The equations should be written like:

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

If the equation is expressed as for example '... + (n-1) starch' then '(n-1) starch' will be 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.

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. Only reactions involving any of these metabolites will be printed.

Notes

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

names
not be parsed
hand sides are lumped

Examples

printFluxes(model, fluxes, onlyExchange, cutOffFlux, outputFile, ...
            outputString, metaboliteList);

printModelStats#

function printModelStats(model, varargin)

Print some statistics about a model to the screen.

Parameters

model : struct: a model structure.

Name-Value Arguments

printModelIssues : logical: true if information about unconnected reactions/metabolites and elemental balancing should be printed (default false).
printDetails : logical: true if detailed information should be printed about model issues. Only used if printModelIssues is true (default true).

Examples

printModelStats(model, printModelIssues, printDetails);