Metabolic tasks#

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

Functions#

Function	Summary
`checkTasks`	Perform a set of simulations as defined in a task file.
`parseTaskList`	Parse a task list file.

Reference#

checkTasks#

function [taskReport, essentialRxns, taskStructure, essentialFluxes]=checkTasks(model,inputFile,varargin)

Perform a set of simulations as defined in a task file.

This function is used for defining a set of tasks for a model to perform. The tasks are defined by defining constraints on the model, and if the problem is feasible, then the task is considered successful. In general, each row can contain one constraint on uptakes, one constraint on outputs, one new equation, and one change of reaction bounds. If more bounds are needed to define the task, then several rows can be used for each task.

The task inputs and outputs are applied to the boundary metabolites of the model. The model's own exchange reactions are not closed: they keep their bounds, so in a model without boundary metabolites they stay open during every task. To let the task define the whole boundary, run checkTasks on closeModel(model).

Parameters

model : struct: a model structure.
inputFile : char: a task list in Excel format. See the function parseTaskList for details (optional if taskStructure is supplied).

Name-Value Arguments

printOutput : logical: true if the results of the test should be displayed (default true).
printOnlyFailed : logical: true if only tasks that failed should be displayed (default false).
getEssential : logical: true if the essential reactions should be calculated for all the tasks. This option is used with runINIT (default false).
taskStructure : struct: structure with the tasks, as from parseTaskList. If this is supplied then inputFile is ignored.
runParallel : logical: true to evaluate tasks in parallel workers, since each task is independent of the others (see parallelWorkersRAVEN). Gurobi is automatically pinned to one thread per worker by optimizeProb, so this does not oversubscribe cores. Default false, matching the previous (serial) behaviour, since checkTasks is often called on small task lists where starting a pool would only add overhead.

Returns

taskReport : struct

structure with the results, with fields:

id : cell array with the id of the task
description : cell array with the description of the task
ok : boolean array with true if the task was successful

essentialRxns : logical

MxN matrix with the essential reactions (M) for each task (N). An element is true if the corresponding reaction is essential in the corresponding task. Failed tasks and SHOULD FAIL tasks are ignored. This is used by the INIT algorithm (if tasks are supplied). If getEssential=false then essentialRxns=false(nRxns,nTasks).

taskStructure : struct

structure with the tasks, as from parseTaskList.

essentialFluxes : double

the fluxes of the essential rxns - same structure as essentialRxns.

Examples

[taskReport, essentialRxns, taskStructure] = checkTasks(model, inputFile, ...
    printOutput, printOnlyFailed, getEssential, taskStructure);

parseTaskList#

function taskStruct=parseTaskList(inputFile)

Parse a task list file.

Parameters

inputFile : char

a task list in either Excel (.xlsx, with a sheet named TASKS with all relevant content) or tab-delimited (.txt) format. The file may contain the following column headers (note, all rows starting with a non-empty cell are removed; the first row after that is considered the headers):

ID : the only required header. Each task must have a unique id (string or numeric). Tasks can span multiple rows, only the first row in each task should have an id
DESCRIPTION : description of the task
IN : allowed input(s) for the task. Metabolite names should be on the form "model.metName[model.comps]". Several inputs can be delimited by ";". If so, then the same bounds are used for all inputs. If that is not wanted, then use several rows for the task
IN LB : lower bound for the uptake of the metabolites in the row (optional, default 0 which corresponds to a minimal uptake of 0 units)
IN UB : upper bound for the uptake of the metabolites in the row (optional, default 1000 which corresponds to a maximal uptake of 1000 units)
OUT : allowed output(s) for the task (see IN)
OUT LB : lower bound for the production of the metabolites in the row (optional, default 0 which corresponds to a minimal production of 0 units)
OUT UB : upper bound for the production of the metabolites in the row (optional, default 1000 which corresponds to a maximal production of 1000 units)
EQU : equation to add. The equation should be on the form "0.4 A + 2 B <=> (or =>) C" and the metabolites should be on the form "model.metName[model.comps]" (optional)
EQU LB : lower bound for the equation (optional, default -1000 for reversible and 0 for irreversible)
EQU UB : upper bound for the equation (optional, default 1000)
CHANGED RXN : reaction ID for which to change the bounds for. Several IDs can be delimited by ";". If so, then the same bounds are used for all reactions. If that is not wanted, then use several rows for the task
CHANGED LB : lower bound for the reaction. If empty, the lower bound of the reaction is left as it is
CHANGED UB : upper bound for the reaction. If empty, the upper bound of the reaction is left as it is
SHOULD FAIL : true if the correct behavior of the model is to not have a feasible solution given the constraints. Any non-empty value except 0, false and no (any case) counts as true (optional, default false)
PRINT FLUX : true if the function should print the corresponding flux distribution for a task. Can be useful for testing. Read in the same way as SHOULD FAIL (optional, default false)

Headers are matched ignoring case and surrounding whitespace. In the ";"-delimited cells, items are trimmed and empty items are dropped.

Returns

taskStruct : struct

array of structures with the following fields:

id : the id of the task
description : the description of the task
shouldFail : true if the task should fail
printFluxes : true if the fluxes should be printed
comments : string with comments
inputs : cell array with input metabolites (in the form metName[comps])
LBin : array with lower bounds on inputs (default, 0)
UBin : array with upper bounds on inputs (default, 1000)
outputs : cell array with output metabolites (in the form metName[comps])
LBout : array with lower bounds on outputs (default, 0)
UBout : array with upper bounds on outputs (default, 1000)
equations : cell array with equations (with mets in the form metName[comps])
LBequ : array with lower bounds on equations (default, -1000 for reversible and 0 for irreversible)
UBequ : array with upper bounds on equations (default, 1000)
changed : cell array with reactions to change bounds for
LBrxn : array with lower bounds on changed reactions (NaN if empty, meaning the bound is left unchanged)
UBrxn : array with upper bounds on changed reactions (NaN if empty, meaning the bound is left unchanged)

Examples

taskStruct = parseTaskList(inputFile);

Notes

This function is used for defining a set of tasks for a model to perform. The tasks are defined by defining constraints on the model, and if the problem is feasible, then the task is considered successful. In general, each row can contain one constraint on uptakes, one constraint on outputs, one new equation, and one change of reaction bounds. If more bounds are needed to define the task, then several rows can be used for each task. To perform the task use checkTasks or fitTasks.

The general metabolites "ALLMETS" and "ALLMETSIN[comps]" can be used as inputs or outputs in the similar manner to normal metabolites. This is a convenient way to, for example, allow excretion of all metabolites to check whether it is the synthesis of some metabolite that is limiting or whether it is the degradation of some byproduct. One important difference is that only the upper bounds are used for these general metabolites. That is, you can only say that uptake or excretion is allowed, not that it is required. This is to avoid conflicts where the constraints for the general metabolites overwrite those of the real ones.