Metabolic tasks (Python)#

raven-toolbox objects in raven_toolbox.tasks.

Functions#

Function	Summary
`apply_task_constraints`	Apply the inputs, outputs, equations and bound changes of a task to `model` in place.
`check_tasks`	Run a task list against `model` and return a `TaskResult` per task.
`EssentialReactionsResult`	Reactions a model must use to perform a task list (RAVEN `essentialRxns`).
`find_task_essential_reactions`	Find the reactions a model must use to satisfy a task list.
`parse_task_list`	Parse a task-list file into `Task` objects.
`Task`	One metabolic task. Bounds are `(metabolite_or_reaction, lb, ub)` triples.
`task_name_maps`	Build lookups from `name[comp]` to metabolite ids and from `comp` to metabolite ids.
`TaskResult`	Result of one task: `passed` is the verdict (accounts for `should_fail`).

Reference#

apply_task_constraints#

apply_task_constraints(model: cobra.Model, task: Task, name_to_id, comp_to_ids)

Apply the inputs, outputs, equations and bound changes of a task to model in place.

Sets a feasibility (zero) objective. Returns (task_metabolite_ids, error); task_metabolite_ids are the model metabolites the task references (RAVEN's essentialMetsForTasks). On error the model may be partially modified.

check_tasks#

check_tasks(model: cobra.Model, tasks: str | Iterable[Task], *, close_boundaries: bool=False)

Run a task list against model and return a TaskResult per task.

Parameters

model : cobra.Model: Model to test. It is copied, so the model is not modified.
tasks : str or Iterable[Task]: A parsed list of Task or a path to a task-list file.
close_boundaries : bool: By default (False), existing exchange, sink and demand reactions are left open, so the inputs and outputs of a task add to what the boundary of the model already allows, as RAVEN's checkTasks does on a model without boundary metabolites. With True, the inputs and outputs are defined only by the tasks, as with RAVEN's checkTasks(closeModel(model), ...).

EssentialReactionsResult#

Reactions a model must use to perform a task list (RAVEN essentialRxns).

reactions maps reaction id to forced flux direction (+1 forward, -1 reverse): the reaction must carry flux of that sign in every feasible solution of at least one task. per_task is the same, split by task id. task_metabolites are the model metabolites the tasks reference (RAVEN essentialMetsForTasks, protected from removal). failed_tasks are the ids of tasks that were infeasible or malformed and thus skipped (RAVEN drops these from the task list); failed_indices are their positions in the task list, which stay distinct when several tasks share an id.

find_task_essential_reactions#

find_task_essential_reactions(model: cobra.Model, tasks: str | Iterable[Task], *, close_boundaries: bool=False, cache_path: str | Path | None=None, verbose: bool=False, processes: int=1, checkpoint_every: int=10)

Find the reactions a model must use to satisfy a task list.

Ports RAVEN's checkTasks(getEssential=true) and getEssentialRxns: each task is constrained as in check_tasks, then _task_essential_reactions finds the reactions it must use (min-flux solve, shrink loop, constrain-to-0 test). This is the prepINITModel step that feeds (ft)INIT: essential reactions are kept regardless of expression score and made irreversible in their forced direction. When a reaction is essential in several tasks with conflicting directions, the direction of the majority is used (ties give forward), matching RAVEN's pos < neg.

The solver is configured per task to match RAVEN's solveLP (FeasibilityTol = 1e-9, single-threaded with a fixed seed), so the degenerate min-flux vertex, and thus the discovered essential set, is reproducible. Threads=1 applies to each solve; the tasks are independent of each other. Tasks with should_fail set are skipped.

Each task needs a min-flux solve and a feasibility LP per candidate reaction.

Parameters

model : cobra.Model: Model to analyse. It is copied, so the model is not modified.
tasks : str or Iterable[Task]: A parsed list of Task or a path to a task-list file.
close_boundaries : bool: Default False: the inputs and outputs of a task add to what the open exchanges of the model already allow, as in check_tasks. RAVEN's prepINITModel calls closeModel first, which corresponds to close_boundaries=True.
cache_path : str or Path or None: File that makes the run resumable. The accumulated results are written there (atomically, as JSON) every checkpoint_every tasks, in sequential and parallel execution, and once more after the last task, and a rerun skips tasks already cached. An existing file is read at the start. A file that is not a JSON cache of the current version, such as a pickle written by an earlier release, is ignored with a warning and overwritten by the first checkpoint. Default None, which writes no cache.
verbose : bool: Prints one line per task as it completes or is skipped because it is cached. In parallel, lines print in completion order, not task order. Default False.
processes : int: Number of worker processes. Default 1, which runs the tasks sequentially. A larger value runs the tasks in parallel with a ProcessPoolExecutor. Each worker solves single-threaded, so the results equal those of the sequential run. Each worker holds its own copy of model, sent once at pool startup and not per task.
checkpoint_every : int: Number of finished tasks between two writes to cache_path. Default 10. Writing the whole accumulated result after every task would make the total checkpoint I/O grow quadratically with the number of tasks; with checkpoint_every it scales with n_tasks / checkpoint_every, and fewer than checkpoint_every completed tasks are redone after an interruption. A value below 1 raises ValueError, with or without cache_path; without cache_path the value has no other effect.

parse_task_list#

parse_task_list(path: str | Path)

Parse a task-list file into Task objects.

Parameters

path : str or Path: Task-list file. A .xlsx or .xlsm file is read from its TASKS sheet and needs the [excel] extra (openpyxl); a .xls file raises ValueError. Any other extension is read as tab-delimited UTF-8 text. The file needs a header row with an ID column that is not the first column, otherwise ValueError is raised; rows whose first cell is not empty are skipped as comments.

Task#

One metabolic task. Bounds are (metabolite_or_reaction, lb, ub) triples.

In changed, a bound is None when the cell was empty, meaning "leave that bound of the reaction as it is" (RAVEN reads it as NaN).

task_name_maps#

task_name_maps(model: cobra.Model)

Build lookups from name[comp] to metabolite ids and from comp to metabolite ids.

name[comp] maps to a list because a model can contain several metabolites with the same name and compartment. A task referencing it constrains all of them. RAVEN's checkTasks constrains only the first match; both implementations warn when a task matches several metabolites.

TaskResult#

Result of one task: passed is the verdict (accounts for should_fail).