Tuned parameter defaults#
Every RAVEN parameter with a non-trivial default has been through one of three processes: matched to a literature value from the method's original paper, measured empirically on real or synthetic models, or kept for consistency with an existing convention (a widely-used underlying tool's own default, or a value already established elsewhere in RAVEN). This page gives the short version (current default and a one-line reason) grouped by capability, covering both the MATLAB and Python (raven-toolbox) implementations. For the full measurements and methodology, follow the linked study.
Note
Where the two implementations still differ RAVEN has existed as MATLAB since 2013 and gained a Python implementation (raven-toolbox) from 2026; a handful of parameters have only been re-measured on one side and haven't yet been ported to the other. Neither implementation's un-measured default was assumed correct going in; where the two disagreed, the answer was to measure, not to defer to whichever came first. Every row below states today's actual value(s); where the two genuinely still differ, both are given, with which side is pending. Cross-toolbox parity decisions below is the full accounting, including the cases that are deliberately kept different because the two implementations rest on different solvers or algorithms.
Flux sampling#
RAVEN MATLAB: randomSampling (method='achr'|'chrr'|'random_objective'),
sampleACHR, sampleCHRR, sampleMaxVolEllipse, sampleChebyshevCenter.
raven-toolbox: random_sampling, find_good_reactions, max_volume_ellipsoid.
Both implementations expose all three sampling methods through one entry point.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Literature: ACHR gives near-uniform interior sampling; the random-objective method draws polytope vertices instead. Both algorithms are implemented and selectable on both sides; only which one is the default differs. |
|
|
Upstream convention (cobrapy's own ACHR default, which RAVEN's Python side inherited). Measured insufficient at genome scale: yeast-GEM gives only ~12 effective samples from 300 stored (ESS), and independent chains frequently disagree entirely (median Gelman-Rubin R-hat fails the convergence threshold). No cheap fix found; see the convergence study. |
|
|
Upstream convention (cobrapy). |
|
|
Literature: Bordel et al. 2010. |
|
|
Measured: applying the alternative ( |
|
|
Measured more correct than the alternative fixed-threshold (±999) heuristic, which over-excludes reactions that legitimately reach capacity. The proper technique is implemented on the Python side only so far; porting it is a bigger project than a default flip. |
|
|
Same on both sides / no evidence favoured a different value. |
|
|
Python-only helper (supports the random-objective method's target selection); no cross-implementation comparison. |
|
|
Literature: Zhang & Gao 2003. |
|
|
Same on both sides. |
Full detail: sampling convergence study (the primary measurement)
FSEOF#
RAVEN MATLAB: FSEOF. raven-toolbox: fseof.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Literature: Choi et al. 2010. |
|
|
Literature: Choi et al. 2010; measured: values below 0.9 pick up spurious targets on iJO1366. |
|
|
Literature: Choi et al. 2010; measured: 0.7 adds 4 spurious amplification targets on iJO1366. |
|
|
Measured: an explicit |
Full detail: Parameter benchmarks
INIT / ftINIT#
RAVEN MATLAB: runINIT, scoreModel, getINITModel, ftINIT, prepINITModel,
ftINITInternalAlg, getINITSteps. raven-toolbox:
score_reactions_from_genes, gene_scores_from_expression, ftinit,
prep_init_model, run_ftinit, get_init_steps, classify_reactions.
Only the MATLAB side has tINIT (runINIT, getINITModel); raven-toolbox
implements ftINIT alone; see
14. Context-specific models. Rows below that were measured
across both algorithms say so.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Literature: Ågren et al. 2012 (the original INIT paper). |
|
|
Measured zero effect at the default |
|
|
Measured on genome-scale Human-GEM: the solver's own gap (~1e-4 on Gurobi) is already at least as tight as the measured-good value, so Python's |
|
|
The same genome-scale study found the MATLAB value too tight by orders of magnitude (real solves took 42–901s+) but also a real >75-minute uncapped runaway case on degraded input on the Python side; |
|
|
Literature: Gustafsson et al. 2023 (the ftINIT paper). |
|
|
RAVEN's original value; measured near-insensitive across a 0.02–0.5 range. |
|
|
RAVEN's original value; confirmed as an intentional LP-relaxation tightener (not a flux cap); see the linked study for why. |
|
|
Same on both sides. |
|
|
Measured on genome-scale Human-GEM: the MILP is degenerate (99.7% of removable reactions tied), so the default escalation is both non-deterministic across seeds and, separately, silently suboptimal (351 kept reactions vs. the true optimum's 349). |
|
|
RAVEN's own formula; previously attributed to "Wang et al. 2012" here, which was checked and could not be confirmed; no source in either implementation cites a paper for it. |
|
various |
Same on both sides / standard practice. |
Full detail: INIT parameter calibration study
(the primary measurement, genome-scale Human-GEM) ·
INIT solver benchmark ·
ftINIT reproducibility
(recommend resolve_ties=True, prove_abs_gap=1.0 for determinism; add
reference_reactions for stability under a curated template, 13x less spurious
essential-gene drift, measured) ·
Human-GEM validation vs MATLAB RAVEN
(Jaccard 0.975–0.980 across 5 cell lines)
Gap-filling#
RAVEN MATLAB: fillGaps (connectivity mode), ported as connect_blocked_reactions.
fill_gaps_fast_lp and fill_gaps_milp are the counterparts of RAVEN's
gapFillFastLP and gapFillMILP.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Literature: Thiele et al. 2014 (the fastGapFill paper). |
|
|
Measured on a synthetic supply-limited model; reliable noise filter for RAVEN-convention (±1000-bound) models; lower it for tightly-constrained exchanges. |
|
|
Measured / standard practice for reconstruction (vs. curation) use. |
|
|
Matches RAVEN's ±1000 bound convention. It caps an unbounded template reaction only when the merged model has no finite bound; otherwise the largest finite bound does. |
Full detail: Parameter benchmarks
Homology-based reconstruction#
RAVEN MATLAB: getModelFromHomology, getBlast, getDiamond. raven-toolbox:
get_model_from_homology, run_blast, run_diamond.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Matches MATLAB's |
|
|
Matches MATLAB's |
|
|
Measured deterministic across thread counts, pure performance change, ~1.9–4× speedup. Not treated as a "value" that needs unifying, since both sides already mean "use the available cores". |
|
|
Measured inert from |
|
|
Measured against independent KEGG and OMA ortholog references across a 4-organism relatedness series: recovers 3–4 points of recall over |
|
|
Same study: the binding filter and the measured optimum, weighting a wrongly-transferred reaction as worse than a missing one. |
|
|
Same on both sides. |
An earlier arm of the same study tried scoring against curated GEMs (hanpo-GEM, rhto-GEM) built by this same reconstruction method, and was retired once it showed the obvious circularity directly: agreement with the curated model peaked exactly at that model's own build settings and collapsed one step past them.
Full detail: homology cut-off calibration study (the primary measurement, including the retired curated-GEM arm)
KEGG-based reconstruction#
RAVEN MATLAB: getKEGGModelForOrganism (the KO-assignment sub-step's exact internal
name hasn't been independently confirmed). raven-toolbox: assign_kos,
run_hmmsearch, build_ko_hmm, and the get_kegg_model_* family.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Measured against real KEGG gene→KO annotations across 4 organisms of varying study depth: the tighter value sits inside the tail of real matches (~20 orders of magnitude above the noise floor), discarding genuine hits for no gain. MATLAB's port is still pending. |
|
|
Same study: the real precision lever (0.8→0.95 lifts precision ~0.07–0.10 for ~0.02 recall). MATLAB's port is still pending. |
|
|
Same study: measured empirically inert (varying it changes precision/recall by ≤0.02); kept at the original value since it does nothing either way. |
|
|
Literature: CD-HIT's own recommendation for protein clustering. |
|
|
Performance-only; HMMER is deterministic (to within insignificant float noise) across thread counts. |
|
|
Same on both sides / standard draft-reconstruction practice. |
Full detail: KEGG HMM cut-off calibration study (the primary measurement, 4 organisms against real KEGG annotations)
Sub-cellular localisation#
RAVEN MATLAB: predictLocalization. raven-toolbox: predict_localization.
These solve the problem with different algorithms: MATLAB uses simulated
annealing, a stochastic heuristic with no optimality guarantee, while the Python
side solves a deterministic MILP. Several parameters below are therefore not a
question of which value is right; the same number means something different in
a heuristic's search budget than in a solver's optimality gap.
Compartment assignment is in development on the Python side and is not at parity with MATLAB. The defaults below are current, but the method they configure is still changing.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Convenience default: cytosol is correct for the vast majority of reactions. Not a value disagreement, since MATLAB has no default to compare against. |
|
|
Not independently benchmarked; same on both sides. Calibration note: for real (non-integer-scale) predictor scores, this typically needs dialing down; see the linked study. |
|
|
Not a value to unify: MATLAB's number is a simulated-annealing search budget (more time generally means a better heuristic answer, not a proof of optimality), while Python's is a MILP solver cutoff (returns a proven-bounded incumbent). Python's |
|
|
Python-side-only; MATLAB's heuristic has no analogous optimality-gap concept. |
Full detail: the measurements behind these values (the yeast-GEM benchmark,
the head-to-head against MATLAB's predictLocalization, the predictor
benchmarks across four organisms, and the design documents) are in
raven-gecko-parity,
with the rest of the work in progress on this method.
Model manipulation#
RAVEN MATLAB: removeGenes, mergeModels, addRxns, addTransport, simplifyModel
(reversibility-constraining and duplicate-removal modes). raven-toolbox:
remove_genes, merge_models, add_reactions_from_equations,
add_transport_reactions, constrain_reversible_reactions, find_duplicate_reactions.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Measured on e_coli_core: keeping the reaction gives false-positive growth after an essential gene is removed (it survives with an empty gene rule). |
|
|
Matches Gurobi's own default primal feasibility tolerance. |
|
|
Same semantic field (metabolite display name), different schema field name, not a value disagreement to resolve. |
|
various |
Python-side additions/refinements; no direct MATLAB equivalent to compare against. |
Full detail: Parameter benchmarks
Tasks#
RAVEN MATLAB: checkTasks. raven-toolbox: check_tasks, find_task_essential_reactions.
Parameter |
Default |
How determined |
|---|---|---|
|
|
Matches RAVEN's |
Full detail: Parameter benchmarks
Cross-toolbox parity decisions#
Policy: where Python and MATLAB RAVEN disagree on a default, pick one value for both rather than let them diverge, except where the divergence is forced by a real implementation difference (different solver stack, different algorithm, different data schema), in which case forcing identical values would change correct behaviour into incorrect behaviour. Every row below either says which side has to change, or explains why it stays split.
Unify: one value, both toolboxes converge#
Parameter |
Python now |
MATLAB now |
Unify at |
Side that changes |
Confidence |
Evidence |
|---|---|---|---|---|---|---|
|
|
|
|
~~Python~~ done |
High |
No downstream effect measured either way ( |
|
|
|
|
Python done; MATLAB pending |
High |
Directly measured: homology cut-off calibration study |
|
|
|
|
MATLAB |
High |
Directly measured: KEGG HMM cut-off calibration study |
|
|
|
|
MATLAB |
High |
Directly measured, same study |
|
|
implicit |
|
MATLAB (needs exposing as a tunable first) |
High |
Measured: |
|
|
|
|
MATLAB |
High |
Measured on e_coli_core: |
|
|
|
|
~~Python~~ done (2026-06-20) |
High |
Zero effect at default |
Resolved without unifying: run_init/run_ftinit mip_gap/time_limit#
These were listed as gated pending a genome-scale test with real expression data. That test already existed (INIT parameter calibration study, Human-GEM HCT116/Hart2015); it just hadn't been connected to this question. It resolves both parameters, but not by matching MATLAB's numbers:
mip_gap: solve time is flat across the gap at single-step scale (model build dominates), so a tight gap is nearly free there; the full genome-scale pipeline does benefit from loosening to0.01(~37% faster, Jaccard 0.995). Neither number is MATLAB's0.0004specifically, and the right choice depends on single-step vs. full-pipeline use, so this stays a documented choice rather than a new hardcoded default. KeepNone(Gurobi's own~1e-4default is at least as tight as the measured-good0.001); docstring updated with the measured numbers.time_limit: the more consequential finding. MATLAB's5000 mscap is far too tight for genome scale (measured solves there took 42-901s+); Python's uncappedNonehas a real, measured failure mode, one severely-degraded-input case ran >75 minutes before being manually killed. The study's own working values are120-600 s/step(ftINIT) and400 s(tINIT). KeepNoneas the code default (still correct for clean-data / single-step use where it's never observed to run away), but the docstring now states the measured working values and the >75 min risk explicitly, so users degrading input quality know to set a cap rather than discovering the runaway case themselves.
This doesn't touch the separate, still-valid finding in the
INIT solver benchmark that GLPK
ignores configuration.timeout entirely and HiGHS doesn't work with cobra in
this stack; Gurobi remains the only backend genome-scale numbers above were
measured on, and the only one a time_limit value does anything on today.
Keep different: forcing identical values would break correctness#
Parameter |
Python |
MATLAB |
Why |
|---|---|---|---|
|
|
|
Different algorithms, not a flag. ACHR is methodologically preferred (uniform interior sampling vs vertex-biased). Unifying means porting ACHR into MATLAB RAVEN, a real implementation project, tracked separately, not a default change. |
|
|
|
Applying MATLAB's |
|
|
heuristic (exclude FVA ≥ 999) |
Different techniques, not a value. Python's is more correct; MATLAB's heuristic over-excludes reactions that legitimately reach capacity. Porting the proper technique to MATLAB is a bigger project than a default flip. |
|
|
|
Same semantic field (metabolite display name), different field name, an artifact of cobrapy vs COBRA Toolbox schemas, not a tunable behaviour. |
|
|
|
Not actually different: both already agree at |
|
|
|
Confirmed by reading |
|
|
required arg (no default) |
MATLAB has no default at all; Python's |
|
|
all cores |
Confirmed deterministic regardless of thread count; doesn't affect output, so this is a resource-policy choice (leave one core free), not a correctness-relevant value. Both are dynamic ("use available cores") in spirit. |
Changes needed in MATLAB RAVEN for parity#
All rows below were re-checked directly against core/*.m on origin/develop in
the RAVEN MATLAB repo on 2026-08-28 (not just inferred from raven-toolbox's own
prior write-ups, which is how the FSEOF and localization rows below turned out
to need correcting from an earlier version of this table).
Change |
Priority |
Evidence |
|---|---|---|
|
High |
KEGG HMM cut-off calibration study; current value confirmed directly in |
Same function, |
High |
Same study and same confirmation |
|
Medium |
homology cut-off calibration study; confirmed directly in |
|
Medium |
|
|
Medium |
|
Localisation's time-budget parameter was removed from this table: core/predictLocalization.m
confirmed MATLAB solves the problem with simulated annealing (maxTime, default 15 minutes,
a search budget), not the deterministic MILP raven-toolbox uses (time_limit, a solver
cutoff), different algorithms, not a value to port. See the "Keep different" table above.
Still open#
Genome-scale ACHR sampling convergence has no cheap fix. investigated, no cheap fix found. At genome scale (yeast-GEM, default ACHR settings) the median reaction fails the R-hat>1.1 threshold. Neither follow-up tried fixes it cheaply: reallocating the same step budget onto a bigger
thinningmakes no measurable difference;method='chrr'genuinely converges on a small model but its genome-scale cost (a fixed per-chain rounding step alone costing ~80 min in a trivial probe) makes it impractical as a drop-in fix today. See the sampling convergence calibration study for the full investigation, including a possible future unblock (caching CHRR's rounding transform across calls, an engineering change, not a parameter default, so out of scope here).The
gene_scores_from_expressionscoring constants (factor=5.0,max_score=10.0,min_score=-5.0) have no confirmed literature source on either side; see the INIT section above.
References#
Choi HS, Lee SY, Kim TY, Woo HM (2010). In silico identification of gene amplification targets for improvement of lycopene production. Appl Environ Microbiol 76(10):3097–3105. https://doi.org/10.1128/AEM.00115-10
Bordel S, Ågren R, Nielsen J (2010). Sampling the solution space in genome-scale metabolic networks reveals transcriptional regulation in key enzymes. PLoS Comput Biol 6(7):e1000859. https://doi.org/10.1371/journal.pcbi.1000859
Zhang Y, Gao L (2003). On numerical solution of the maximum volume ellipsoid problem. SIAM J Optim 14(1):53–76. https://doi.org/10.1137/S1052623401397230
Ågren R, Bordel S, Mardinoglu A, Pornputtapong N, Nookaew I, Nielsen J (2012). Reconstruction of genome-scale active metabolic networks for 69 human cell types and 16 cancer types using INIT. PLoS Comput Biol 8(5):e1002518. https://doi.org/10.1371/journal.pcbi.1002518
Gustafsson J, Anton M, Roshanzamir F, et al. (2023). Generation and analysis of context-specific genome-scale metabolic models derived from single-cell RNA-Seq data. Proc Natl Acad Sci USA 120(6):e2217868120. https://doi.org/10.1073/pnas.2217868120
Thiele I, Vlassis N, Fleming RMT (2014). fastGapFill: efficient gap filling in metabolic networks. Bioinformatics 30(17):2529–2531. https://doi.org/10.1093/bioinformatics/btu321
Not listed: the gene_scores_from_expression constants (factor, max_score,
min_score) were previously attributed to "Wang et al. 2012" in this and
raven-toolbox's own docs. That attribution was checked against RAVEN's and
raven-toolbox's own source (neither cites a paper) and against the one 2012
Wang metabolic-modelling paper findable (mCADRE, a categorical method
unrelated to this continuous formula), and could not be confirmed. Treat the
scoring constants as RAVEN's own choice with no confirmed literature source
until a real citation turns up.