Gap-filling (Python)

raven-toolbox objects in raven_toolbox.gapfilling.

Functions

Function	Summary
analyse_topology	BFS metabolite-producibility analysis.
connect_blocked_reactions	Add template reactions so blocked draft reactions can carry flux.
FastLPResult	Outcome of an LP-based gap-fill.
fill_gaps_fast_lp	LP-based gap-filling (fastGapFill / swiftGapFill).
fill_gaps_milp	Gap-fill to make the model objective (biomass) >= min_growth.
find_leak_metabolite	Find a metabolite that can be freely produced or consumed.
gap_report	Run a gap analysis on model.
GapFillResult	Outcome of a connectivity gap-fill.
GapReportResult	Outcome of a gap analysis.
LeakMetaboliteResult	Outcome of a leak search.
MILPGapFillResult	Outcome of a growth-floor MILP gap-fill.
MinToConnect	One entry of the minimal set of metabolites to connect.
print_gap_report	Print gap_report's result and return it.
TopologicalAnalysisResult	Outcome of a topological gap analysis.

Reference

analyse_topology

analyse_topology(model: cobra.Model, templates: cobra.Model | Iterable[cobra.Model], *, seeds: Iterable[str] | None=None, targets: Iterable[str] | None=None, verbose: bool=True)

BFS metabolite-producibility analysis.

Starting from seed metabolites (metabolites available in the medium), identifies which metabolites in model cannot be produced using any sequence of draft reactions. For each unreachable target metabolite, lists candidate template reactions that produce it directly.

Parameters

model:

Draft model to analyse.

templates:

Universal database model(s) containing candidate reactions. Metabolite identifiers must match those in model.

seeds:

Metabolite IDs available from the medium. Default: metabolites involved in exchange reactions (one-metabolite reactions) where lower_bound < 0 (uptake is allowed).

targets:

Metabolite IDs that should be reachable. Default: all metabolites in model.

verbose:

Print a summary of the results.

Returns

TopologicalAnalysisResult :

connect_blocked_reactions

connect_blocked_reactions(model: cobra.Model, templates: cobra.Model | Iterable[cobra.Model], *, scores: dict[str, float] | None=None, penalty: float=1.0, allow_net_production: bool=False, eps: float=1.0)

Add template reactions so blocked draft reactions can carry flux.

Finds reactions that cannot carry flux in model under its current bounds, then adds the minimum-penalty set of template reactions that lets the (irreversible) ones carry flux, and returns the filled model. Like RAVEN, only irreversible blocked reactions are forced — reversible ones can carry flux trivially in the split formulation, so forcing them is uninformative.

For the other gap-filling flavour — adding reactions to make the model's objective feasible — use cobra.flux_analysis.gapfill after aligning the template's metabolite ids to the draft.

The draft is expected to have exchange reactions for its nutrients (otherwise most reactions are trivially blocked).

eps is the minimum flux a blocked reaction must be able to carry to count as rescuable, and the flux forced through it while solving. allow_net_production relaxes the steady-state balance from S @ v == 0 to S @ v >= 0 (metabolites may accumulate), which can rescue reactions whose real fix is a missing consumption route rather than a genuine connectivity gap.

FastLPResult

Outcome of an LP-based gap-fill.

Parameters

added_reactions:

Template reaction IDs selected by the LP solver (union across all per-blocked-reaction LP solves).

newly_connected:

Draft reaction IDs that were blocked in the draft and appear in the returned model (not guaranteed to carry flux until verified by FVA).

cannot_connect:

Blocked draft reaction IDs that remain blocked even with the full template database added.

candidates_per_reaction:

Per blocked-reaction template reaction candidates (as returned by each individual LP solve). Useful for greedy post-processing.

model:

Draft model with added_reactions incorporated.

fill_gaps_fast_lp

fill_gaps_fast_lp(model: cobra.Model, templates: cobra.Model | Iterable[cobra.Model], *, epsilon: float=0.0001, variant: Literal['fast', 'swift']='fast', verbose: bool=True, n_proc: int | None=None)

LP-based gap-filling (fastGapFill / swiftGapFill).

For each blocked draft reaction, runs a single LP that activates that reaction using a minimal (or maximal) set of template reactions. The union of all activated template reactions is returned.

Parameters

model:

Draft model to gap-fill.

templates:

Universal reaction database model(s).

epsilon:

Minimum flux threshold for a reaction to be considered active.

variant:

"fast" — FASTCORE L1-norm LP (minimises L1 norm of template fluxes). "swift" — SWIFTCORE single LP (maximises template flux sum; faster but stochastic).

verbose:

Print progress messages.

n_proc:

Worker processes for solving each blocked reaction's LP in parallel. Defaults to cobra.Configuration().processes; set to 1 to solve serially in this process. Each blocked reaction's LP only depends on the merged draft+template model (reverted after each solve via with working as m:), never on another blocked reaction's result, so this parallelises via cobra.util.ProcessPool — the same pool ec_fva/flux_variability_analysis use.

Returns

FastLPResult :

fill_gaps_milp

fill_gaps_milp(model: cobra.Model, templates: cobra.Model | Iterable[cobra.Model], *, min_growth: float | None=None, big_m: float=1000.0, verbose: bool=True)

Gap-fill to make the model objective (biomass) >= min_growth.

Solves a global MILP that selects the fewest template reactions that make the model's objective reaction feasible at min_growth. The draft reactions keep their bounds.

Parameters

model:

Draft model to gap-fill. Must have a non-zero objective (biomass reaction).

templates:

Universal reaction database model(s).

min_growth:

Minimum required objective value. If None, runs FBA on the merged model and uses 10% of the maximum as the floor.

big_m:

Big-M constant for coupling constraints. Must exceed any expected flux magnitude in the model.

verbose:

Print progress messages.

Returns

MILPGapFillResult :

find_leak_metabolite

find_leak_metabolite(model: cobra.Model, direction: Literal['produce', 'consume'], *, ignore_mets: Iterable[str] | None=None, is_names: bool=False, min_nr_fluxes: bool=False, allow_excretion: bool=True, ignore_int_bounds: bool=False)

Find a metabolite that can be freely produced or consumed.

Parameters

model:

Model to test. Never modified; the search runs on an internal copy. Its boundary reactions are used as they are: close every exchange, sink and demand reaction first (for r in model.boundary: r.bounds = (0, 0) on a copy), or an open uptake or excretion counts as a leak. Positive lower bounds (such as on a maintenance reaction) still apply and can make the search infeasible; the result then has status "infeasible", which does not show that the model is leak-free.

direction:

"produce" to look for freely excreted metabolites, or "consume" to look for freely consumed metabolites.

ignore_mets:

Metabolite ids (or names, with is_names=True) to exclude from the search. Unlike findLeakMetabolite.m, this only accepts ids/names, not a logical or index vector — there is no positional model-array equivalent to index into in cobrapy.

is_names:

If True, ignore_mets holds metabolite names rather than ids; every metabolite sharing one of those names, in any compartment, is excluded.

min_nr_fluxes:

Solve for the minimum number of active fluxes (raven_toolbox.analysis.get_min_nr_fluxes) instead of the minimum sum. Slower, but can be used if the sum gives too many active reactions to interpret.

allow_excretion:

Allow every metabolite to freely accumulate. Only used when direction is "produce" (default True).

ignore_int_bounds:

Relax every non-boundary reaction to [-1000, 1000] before searching, to find leaks that are only possible once internal bounds (including reversibility) are ignored.

Returns

LeakMetaboliteResult :

gap_report

gap_report(model: cobra.Model, *, template_models: cobra.Model | Iterable[cobra.Model] | None=None)

Run a gap analysis on model.

Parameters

model:

Model to analyse. Never modified.

template_models:

Model(s) to gap-fill blocked reactions from (raven_toolbox.gapfilling.connect_blocked_reactions). If omitted, result.gap_fill is None and that step is skipped.

Returns

GapReportResult :

Raises

ValueError

If model is infeasible under its own bounds, or once its boundary reactions are closed for can_produce_without_input and can_consume_without_output. The usual cause is a reaction with a forced flux, such as ATP maintenance with a positive lower bound; set its bounds to zero before calling gap_report.

GapFillResult

Outcome of a connectivity gap-fill.

added_reactions are the template reaction ids added to model; newly_connected are draft reactions that were blocked but can now carry flux; cannot_connect are blocked reactions left unconnectable.

GapReportResult

Outcome of a gap analysis.

Parameters

no_flux_reactions:

Reactions that cannot carry flux under the model's own constraints.

no_flux_reactions_relaxed:

Reactions that still cannot carry flux even if every metabolite is allowed unconstrained net production.

subgraphs:

Metabolite ids in each isolated sub-network (two metabolites are connected if they share a reaction), largest first.

not_produced_metabolites:

Metabolites that cannot have net production.

needed_for_production:

Metabolite id → ids of every not-produced metabolite that a free source of it would, directly or transitively, also make producible (see MinToConnect on when that includes the metabolite itself).

min_to_connect:

A minimal set of metabolites to give a free source, chosen greedily (most newly-connected metabolites first), that together account for every entry in not_produced_metabolites.

can_produce_without_input:

Metabolites that can be produced with every boundary reaction closed.

can_consume_without_output:

Metabolites that can be consumed with every boundary reaction closed.

gap_fill:

Result of gap-filling against template_models, or None if none were given.

LeakMetaboliteResult

Outcome of a leak search.

Parameters

fluxes:

Flux for every reaction in the original model (empty if no leak was found).

metabolites:

Ids of the metabolite(s) implicated. Usually one; more than one means those metabolites could only be exchanged together.

status:

"optimal" if a leak was found, "infeasible" otherwise.

MILPGapFillResult

Outcome of a growth-floor MILP gap-fill.

Parameters

added_reactions:

Template reaction IDs selected by the MILP.

model:

Draft model with added_reactions incorporated.

exit_status:

Solver status string (e.g. "optimal", "infeasible"), or "not_restored" when the solver reported a solution but the selected repairs do not bring the objective to min_growth in model. The selection is still returned for inspection.

MinToConnect

One entry of the minimal set of metabolites to connect.

connects counts every not-produced metabolite that giving this one a free source would, directly or transitively, also make producible. That can include the metabolite itself, but only if the rest of the network can actually drain it once it has a source (e.g. some other reaction consumes it on net) — a metabolite with no other route at all never connects itself.

print_gap_report

print_gap_report(model: cobra.Model, *, print_fn=print, **kwargs)

Print gap_report's result and return it.

A simpler, Pythonic rendering of gapReport.m's console report — not a literal reproduction of its text; the structured result is what's compared for parity.

TopologicalAnalysisResult

Outcome of a topological gap analysis.

Parameters

reachable_metabolites:

Set of metabolite IDs that can be produced from seeds using the draft reactions.

blocked_metabolites:

Subset of targets that could not be reached from seeds.

candidate_reactions:

Mapping of blocked metabolite ID → list of template reaction IDs that produce that metabolite directly (matching by metabolite id).

pruning_fraction:

Fraction of template reactions that are NOT candidates for any blocked metabolite. Higher values mean the template was pruned more.