Queries¶

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

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.
`printModel`	Print reactions to the screen or to a file.
`printModelStats`	Print some statistics about a model to the screen.

Reference¶

buildEquation¶

Construct single equation string for a given reaction.

Input arguments:

Name	Type	Description	Default
`mets`	`cell`	metabolites involved in the reaction.	required
`stoichCoeffs`	`double`	vector with corresponding stoichiometric coeffs.	required
`isrev`	`logical`	indicates if the reaction is reversible or not.	required

Output arguments:

Name	Type	Description
`equationString`	`char`	equation as a string.

Examples:

equationString = buildEquation(mets, stoichCoeffs, isrev);

checkModelStruct¶

Report one issue: accumulate in collect mode, or warn/error. severity: "error" | "warning" When items is supplied (3 args) but is empty, silently do nothing.

constructEquations¶

Construct equation strings for reactions.

Input arguments:

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

Output arguments:

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

Construct a stoichiometric matrix from a cell array of equations.

Input arguments:

Name	Type	Description	Default
`equations`	`cell`	cell array of equations on the form "A + 2 B <=> 3 C", where <=> indicates reversible and => irreversible reactions.	required

Name-value arguments:

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

Output arguments:

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

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.

Input arguments:

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

Output arguments:

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

Check whether the reactions of a model are balanced.

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

Input arguments:

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

Output arguments:

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

Retrieve the exchange reactions from a model.

Exchange reactions are identified by having either no substrates or no products.

Input arguments:

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

Name-value arguments:

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

Output arguments:

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

Extract gene list and rxnGeneMat from grRules array.

Input arguments:

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

Name-value arguments:

Name	Type	Description	Default
`originalGenes`	`cell`	the original gene list from the model as reference.

Output arguments:

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

Retrieve the indexes for a list of reactions or metabolites.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`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.	required
`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]. If a model.ec structure exists (GECKO 3), then also 'ecenzymes', 'ecrxns' and 'ecgenes' are allowed.	required

Name-value arguments:

Name	Type	Description	Default
`returnLogical`	`logical`	sets whether to return a logical array or an array with the indexes (default false).

Output arguments:

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

Get the reactions in a specified compartment.

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`comp`	`char`	string with the compartment id.	required

Name-value arguments:

Name	Type	Description	Default
`includePartial`	`logical`	true if reactions with metabolites in several compartments (normally transport reactions) should be included (default false).

Output arguments:

Name	Type	Description
`I`	`double`	boolean vector of the reactions.
`rxnNames`	`cell`	the names of the reactions.

Examples:

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

getTransportRxns¶

Retrieve the transport reactions from a model.

Input arguments:

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

Output arguments:

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

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. Inspired by COBRApy's model.summary().

Input arguments:

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

Name-value arguments:

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

Get the elemental composition from formulas.

Input arguments:

Name	Type	Description	Default
`formulas`	`cell`	a cell array with formulas.	required

Name-value arguments:

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

Output arguments:

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

Get all metabolite names from a cell array of equations.

Input arguments:

Name	Type	Description	Default
`equations`	`cell`	a cell array with equation strings.	required

Output arguments:

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

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

Input arguments:

Name	Type	Description	Default
`model`	`struct`	a model structure.	required
`fluxes`	`double`	a vector with fluxes.	required

Name-value arguments:

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

%rxnID : reaction ID
%rxnName : reaction name
%lower : lower bound
%upper : upper bound
%obj : objective coefficient
%eqn : equation
%flux : flux
%element : equation using the metabolite formulas rather than metabolite names
%unbalanced : "(*)" if the reaction is unbalanced and "(-)" if it could not be parsed
%lumped : equation where the elemental compositions for the left/right hand sides are lumped

Examples:

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

printModel¶

Print reactions to the screen or to a file.

This is a wrapper around printFluxes, intended for use when there is no flux distribution.

Input arguments:

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

Name-value arguments:

Name	Type	Description
`rxnList`	`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 print (default model.rxns).
`outputString`	`char`	a string that specifies the output of each reaction (default '%rxnID (%rxnName)\n\t%eqn [%lower %upper]\n').
`outputFile`	`char`	a file to save the print-out to (default is output to the command window).
`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:

%rxnID : reaction ID
%rxnName : reaction name
%lower : lower bound
%upper : upper bound
%obj : objective coefficient
%eqn : equation
%element : equation using the metabolite formulas rather than metabolite names
%unbalanced : "(*)" if the reaction is unbalanced and "(-)" if it could not be parsed
%lumped : equation where the elemental compositions for the left/right hand sides are lumped

Examples:

printModel(model, rxnList, outputString, outputFile, metaboliteList);

printModelStats¶

Print some statistics about a model to the screen.

Input arguments:

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

Name-value arguments:

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