Gap-filling (Python)

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

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_kumar_milp	Gap-fill to make the model objective (biomass) >= min_growth.
GapFillResult	Outcome of a connectivity gap-fill.
KumarGapFillResult	Outcome of a Kumar 2007 MILP gap-fill.
TopologicalAnalysisResult	Outcome of a topological gap analysis.

Reference

analyse_topology

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:

Name	Type	Description	Default
model	Model	Draft model to analyse.	required
templates	Model | Iterable[Model]	Universal database model(s) containing candidate reactions. Metabolite identifiers must match those in model.	required
seeds	Iterable[str] | None	Metabolite IDs available from the medium. Default: metabolites involved in exchange reactions (one-metabolite reactions) where lower_bound < 0 (uptake is allowed).	None
targets	Iterable[str] | None	Metabolite IDs that should be reachable. Default: all metabolites in model.	None
verbose	bool	Print a summary of the results.	True

Returns:

Type	Description
TopologicalAnalysisResult

connect_blocked_reactions

Add template reactions so blocked draft reactions can carry flux.

Finds reactions that cannot carry flux in model, 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).

FastLPResult

Outcome of an LP-based gap-fill.

Parameters:

Name	Type	Description	Default
added_reactions	list[str]	Template reaction IDs selected by the LP solver (union across all per-blocked-reaction LP solves).	list()
newly_connected	list[str]	Draft reaction IDs that were blocked in the draft and appear in the returned model (not guaranteed to carry flux until verified by FVA).	list()
cannot_connect	list[str]	Blocked draft reaction IDs that remain blocked even with the full template database added.	list()
candidates_per_reaction	dict[str, list[str]]	Per blocked-reaction template reaction candidates (as returned by each individual LP solve). Useful for greedy post-processing.	dict()
model	Model	Draft model with added_reactions incorporated.	Model()

fill_gaps_fast_lp

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:

Name	Type	Description	Default
model	Model	Draft model to gap-fill.	required
templates	Model | Iterable[Model]	Universal reaction database model(s).	required
epsilon	float	Minimum flux threshold for a reaction to be considered active.	0.0001
variant	Literal['fast', 'swift']	"fast" — FASTCORE L1-norm LP (minimises L1 norm of template fluxes). "swift" — SWIFTCORE single LP (maximises template flux sum; faster but stochastic).	'fast'
verbose	bool	Print progress messages.	True

Returns:

Type	Description
FastLPResult

fill_gaps_kumar_milp

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

Solves a global MILP that selects the minimum-weight combination of directionality reversals and template reactions to make the model's objective reaction feasible at min_growth.

Parameters:

Name	Type	Description	Default
model	Model	Draft model to gap-fill. Must have a non-zero objective (biomass reaction).	required
templates	Model | Iterable[Model]	Universal reaction database model(s).	required
min_growth	float | None	Minimum required objective value. If None, runs FBA on the merged model and uses 10% of the maximum as the floor.	None
weights	tuple[float, float]	(w_rev, w_db) — cost per reversed draft reaction and cost per added template reaction. Lower-weight repairs are preferred.	(1.0, 2.0)
big_m	float	Big-M constant for coupling constraints. Must exceed any expected flux magnitude in the model.	1000.0
verbose	bool	Print progress messages.	True

Returns:

Type	Description
KumarGapFillResult

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.

KumarGapFillResult

Outcome of a Kumar 2007 MILP gap-fill.

Parameters:

Name	Type	Description	Default
added_reactions	list[str]	Template reaction IDs selected by the MILP.	list()
reversed_reactions	list[str]	Draft reaction IDs whose directionality is reversed (lower_bound changed to allow negative flux).	list()
model	Model	Draft model with added_reactions incorporated and reversed_reactions bounds updated.	Model()
exit_status	str	Solver status string (e.g. "optimal", "infeasible").	'not_solved'

TopologicalAnalysisResult

Outcome of a topological gap analysis.

Parameters:

Name	Type	Description	Default
reachable_metabolites	set[str]	Set of metabolite IDs that can be produced from seeds using the draft reactions.	set()
blocked_metabolites	set[str]	Subset of targets that could not be reached from seeds.	set()
candidate_reactions	dict[str, list[str]]	Mapping of blocked metabolite ID → list of template reaction IDs that produce that metabolite directly (matching by metabolite id).	dict()
pruning_fraction	float	Fraction of template reactions that are NOT candidates for any blocked metabolite. Higher values mean the template was pruned more.	0.0