Initialization (Python)¶

raven-toolbox objects in raven_toolbox.init, collected from the source of the tracked branch.

Functions¶

Function	Summary
`classify_reactions`	Classify reactions into the ftINIT `toIgnore` categories (`prepINITModel`).
`fill_tasks`	Add minimum-cost reference reactions so every task is feasible in `model`.
`ftinit`	Run the full ftINIT pipeline on prepData and return the context-specific model.
`FtInitResult`	Result of :func:`run_ftinit`.
`gene_scores_from_expression`	Gene scores from RNA-seq/array expression, RAVEN's `5·ln(level/reference)`.
`get_init_model`	Extract a context-specific model with tINIT.
`get_init_steps`	Return the step schedule for a named ftINIT `series` (RAVEN `getINITSteps`).
`group_rxn_scores`	Sum original reaction scores over merged groups (RAVEN `groupRxnScores`).
`InitModelResult`	Result of :func:`get_init_model`.
`InitResult`	Result of :func:`run_init`.
`InitStep`	One ftINIT MILP step.
`merge_linear`	Merge linearly-dependent reactions; return `(reduced, orig_ids, group_ids, reversed)`.
`prep_init_model`	Build :class:`PrepData` from a template model — the once-per-template work shared
`PrepData`	One-time ftINIT preprocessing of a template model (RAVEN `prepData`).
`ReactionMasks`	Reaction-category id sets (RAVEN's `toIgnore*`), in 8-bit-pattern order.
`remove_low_score_genes`	Remove negative-scoring genes from GPRs (RAVEN `removeLowScoreGenes`).
`rescale_for_init`	Compress each reaction's stoichiometric dynamic range.
`run_ftinit`	Run the single-step ftINIT MILP and return the extracted model.
`run_init`	Run the INIT MILP and return the extracted model.
`score_reactions_from_genes`	Return `{reaction_id: score}` from per-gene scores via each reaction's GPR.
`TaskFillResult`	Result of :func:`fill_tasks`: the gap-filled model and what was added.

Reference¶

classify_reactions¶

Classify reactions into the ftINIT toIgnore categories (prepINITModel).

ext_comp is the extracellular compartment. spontaneous/custom are reaction-id lists. A reaction is "GPR-less" when its gene rule is empty.

fill_tasks¶

Add minimum-cost reference reactions so every task is feasible in model.

reference_model supplies the candidate reactions (those not already in model, excluding exchange/boundary reactions). rxn_scores (original reaction id → score) sets the cost of adding each candidate as −min(score, −0.1) (missing → cost 1). Tasks already feasible are skipped; should_fail tasks are ignored. The model is carried forward, so later tasks see earlier additions. Returns the gap-filled model and the reactions added.

Boundary reactions are closed while testing/solving each task, so task inputs and outputs come solely from the task's ranged metabolite bounds (RAVEN gap-fills the exchange-free model). The returned model keeps its boundary reactions.

ftinit¶

Run the full ftINIT pipeline on prepData and return the context-specific model.

prep is a :class:raven_toolbox.init.PrepData. rxn_scores maps original reaction id → score (e.g. from :func:score_reactions_from_genes on the template). Each step (:func:raven_toolbox.init.get_init_steps) regroups scores under its ignore_mask, fixes the reactions turned on by earlier steps as essential (in their flux direction), and solves :func:run_ftinit on the merged model. Reactions never turned on (and not essential or left-in) are removed from the reference model; exchange reactions are always kept (RAVEN re-adds them).

If fill_gaps and prep carries tasks, reactions are added back so every task is feasible (:func:raven_toolbox.init.fill_tasks). If gene_scores is given, negative-scoring genes are pruned from the GPRs at the end (:func:raven_toolbox.init.remove_low_score_genes).

Essential reactions are forced to carry force_on (default 0.1) of flux in the forced direction. On genome-scale models a stricter regime is needed (the previous step's actual carried flux instead of a flat 0.1) — exposed via per-reaction essential_force on :func:run_ftinit.

metabolomics (a list of detected metabolite names to reward producing) is not yet implemented: the linear merge eliminates degree-2 detected metabolites, so it needs a producer-group-mapping + negative-producer force-flux block — the most intricate MILP piece, for the least-used input. Passing a non-empty value raises NotImplementedError.

mip_gap/time_limit are forwarded to each :func:run_ftinit solve. On genome-scale models they are essential for tractability — see docs/init_param_calibration.md for the calibration table.

FtInitResult¶

Result of :func:run_ftinit.

gene_scores_from_expression¶

Gene scores from RNA-seq/array expression, RAVEN's 5·ln(level/reference).

This is tINIT's usual entry point (RNA-seq is the common case; single-cell and HPA are alternative upstream sources). reference is either a per-gene reference level (e.g. the cross-sample mean) or a single threshold for all genes: a gene expressed above its reference scores positive, below it negative. The score is clamped to [min_score, max_score]; non-positive level/reference (and missing reference) → min_score (RAVEN maps these NaNs to -5).

get_init_model¶

Extract a context-specific model with tINIT.

Provide either rxn_scores (reaction id → score) or gene_scores (gene id → score, converted via the GPR with :func:score_reactions_from_genes). Reactions that cannot carry flux (with exchanges open) are removed first unless remove_dead_ends=False; essential_rxns are kept regardless. The remaining model is passed to :func:run_init.

get_init_steps¶

Return the step schedule for a named ftINIT series (RAVEN getINITSteps).

'1+1' (default, step 1+2 merged), '2+1' (3-step), '1+0'/'2+0' (skip the final GPR-less step), 'full' (single MILP). mets_to_ignore are metabolite names removed from the stoichiometry in each step (e.g. H2O, H+).

group_rxn_scores¶

Sum original reaction scores over merged groups (RAVEN groupRxnScores).

orig_scores maps original reaction id → score; to_zero are reactions to drop from the problem (the toIgnore masks) — their score becomes 0. Genuine zeros and groups cancelling to zero become 0.01 so the MILP never sees an exactly zero score. Returns {reduced_reaction_id: score}.

InitModelResult¶

Result of :func:get_init_model.

InitResult¶

Result of :func:run_init.

InitStep¶

One ftINIT MILP step.

merge_linear¶

Merge linearly-dependent reactions; return (reduced, orig_ids, group_ids, reversed).

no_merge reaction ids are never merged. The reduced model carries no genes (merging makes GPRs meaningless); scores are remapped with :func:group_rxn_scores.

Each pass recomputes the metabolite→reaction incidence fresh, then merges over the degree-2 metabolites found at the start of the pass. A metabolite that only becomes degree-2 mid-pass (because one of its reactions was just merged into a survivor) is therefore picked up on the next pass rather than immediately — linear merging is confluent, so the final grouping is the same regardless, it just takes a few extra passes on long chains. (RAVEN re-finds incidence per metabolite and so finishes a chain in one pass; the end result is equivalent.)

prep_init_model¶

Build :class:PrepData from a template model — the once-per-template work shared by every ftINIT sample on this model.

With tasks, discovers the task-essential reactions (kept regardless of score), orients them irreversibly in their required direction, and drops tasks that are infeasible. Then classifies reactions into the omics-independent categories, linearly merges, and (unless scale=False) rescales the merged model's stoichiometry (:func:rescale_for_init) so a single MILP big-M is valid across all reactions — without this, genome-scale ftINIT is infeasible / intractable.

essential_cache_path makes the (slow, genome-scale) essential-reaction discovery resumable across interruptions — see :func:find_task_essential_reactions.

PrepData¶

One-time ftINIT preprocessing of a template model (RAVEN prepData).

Built once per template, reused across samples. min_model is the merged model the MILP runs on; orig_rxn_ids/group_ids map its reactions back to the ref_model (the simplified, pre-merge reference). essential_rxns are in merged ids and pre-oriented irreversibly (so the MILP forces flux forward). masks is on ref_model (= original) ids.

ReactionMasks¶

Reaction-category id sets (RAVEN's toIgnore*), in 8-bit-pattern order.

ignored(pattern) returns the union of the categories whose bit is set — the reactions held out of (left untouched by) that MILP step.

remove_low_score_genes¶

Remove negative-scoring genes from GPRs (RAVEN removeLowScoreGenes).

gene_scores maps gene id → score; genes absent from it are treated as unscored (never removed). Returns (new_model, removed_gene_ids) — genes dropped from every rule they were in (and thus from the model). isozyme_scoring / complex_scoring aggregate alternative/subunit scores (max/min default).

When all isozyme alternatives are negative the least-negative one is kept deterministically (first on a tie), unlike RAVEN's random tie-break — same quality, reproducible.

rescale_for_init¶

Compress each reaction's stoichiometric dynamic range.

Large spreads in stoichiometric coefficients (e.g. a biomass/pool reaction with coefficients from 1e-3 to 1e2) force correspondingly extreme flux magnitudes, so no single MILP big-M fits all reactions. RAVEN, per reaction: caps every |coeff| at max_stoich_diff × min|coeff| (keeping signs), then scales the whole reaction so its mean |coeff| is 1. Bounds are reset to ±1000 afterwards. Modifies model in place; only the merged MILP model is scaled (the final output maps back to the unscaled ref_model by reaction id, so reaction selection is unaffected).

run_ftinit¶

Run the single-step ftINIT MILP and return the extracted model.

rxn_scores maps reaction id → score (default 0 → reaction left free in the model, not scored or removable). essential_rxns are forced to carry flux (≥ force_on_ess); essential_directions maps an essential reaction id to +1 (forward) or -1 (reverse) for the forced direction (default forward). ignore_mets are metabolite names whose mass balance is dropped (RAVEN's per-step "simple metabolite" removal, e.g. H2O/H+). See the module docstring for the formulation. This is the single-step variant; the staged schedule (:func:raven_toolbox.init.ftinit) calls it per step.

run_init¶

Run the INIT MILP and return the extracted model.

rxn_scores maps reaction id → score (default 0). essential_rxns must be kept (forced to carry flux). present_mets are metabolite names that the network should be able to produce; each is tested and reported in met_production. See the module docstring for the formulation.

Note on score 0 (classic INIT vs. ftINIT divergence): in classic INIT a reaction with score exactly 0 receives an include-indicator with zero reward, so the optimiser is free to drop it. This matches RAVEN's runINIT semantics. ftINIT inverts that — score-0 reactions stay in the model unless they actively hurt feasibility — so a score of exactly 0 means different things in the two variants. If you want score-0 reactions kept here, pass a small positive value (e.g. min_score from gene_scores_from_expression) instead of 0.

score_reactions_from_genes¶

Return {reaction_id: score} from per-gene scores via each reaction's GPR.

TaskFillResult¶

Result of :func:fill_tasks: the gap-filled model and what was added.