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.

The function runs a set of tasks for a model. Each task is defined by constraints on the model, and the task is successful if the problem is feasible. 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 by prepINITModel (ftINIT) and getINITModel (tINIT) (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, as each task is independent of the others (see parallelWorkersRAVEN). In a worker, optimizeProb sets Gurobi to one thread, so the workers do not use more cores than assigned. With false the tasks are evaluated in series, which avoids the overhead of starting a pool for small task lists (default false).

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 model reactions in the solution of each task (NaN for a task without a solution), with the same dimensions 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 binary *.xls format is not supported. The file may contain the following column headers. Rows that start with a non-empty cell are comments and are removed. The first row that starts with an empty cell is the header row, so the header row and the task rows must start with an empty cell:

ID : the only required header (string or numeric). Ids may repeat, for example as category codes. A task starts at a row with a non-empty id and can span multiple rows; only the first row of a task should have an id
DESCRIPTION : description of the task
IN : allowed input(s) for the task. Metabolite names are written in 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)
IN UB : upper bound for the uptake of the metabolites in the row (optional, default 1000)
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)
OUT UB : upper bound for the production of the metabolites in the row (optional, default 1000)
EQU : equation to add. The equation is written in the form "0.4 A + 2 B <=> (or =>) C" and the metabolites in 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 behaviour 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 checkTasks should print the corresponding flux distribution for a task. Read in the same way as SHOULD FAIL (optional, default false)
COMMENTS : comments on the task, stored in the field comments (optional)

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

The task list defines a set of tasks for a model to perform. A task is defined by constraints on the model, and the task is successful if the problem is feasible. 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 same manner as normal metabolites. They allow, for example, excretion of all metabolites, to check whether the synthesis of some metabolite or the degradation of some byproduct is limiting. Only the upper bounds are used for these general metabolites, so uptake or excretion can be allowed but not required. A lower bound would overwrite the constraints of the individual metabolites.