[edkerk]

Third round of the behaviour parity review of raven-toolbox against RAVEN. The matching RAVEN changes are in CompMetEng/RAVEN#15 and the scenarios and ledger rows in CompMetEng/raven-gecko-parity#143; the previous round is #182.

Defaults and behaviour

Function	Before	After
manipulation.remove_genes default blocked_reactions	"remove"	"constrain", as removeGenes: a reaction whose rule loses its last enzyme stays, with the rule dropped and bounds (0, 0)
manipulation.remove_genes genes	the requested genes were removed	when at least one requested gene is in the model, every gene that no remaining reaction named before the removal is removed as well; a gene kept by a constrained reaction stays; when none is in the model, nothing changes
manipulation.merge_compartments surviving id	first member with its suffix rewritten to the merged compartment (ACCOA_s)	the copy already in the merged compartment, otherwise the id that sorts first (ACCOA_c for ACCOA_c and ACCOA_m), as mergeCompartments
manipulation.merge_compartments annotation	dropped	kept from the surviving copy
manipulation.merge_compartments default drop_single_metabolite_reactions	True	False, as deleteRxnsWithOneMet
default metabolite key of localization.assign_compartments, apply_assignment, relocate_reactions, curation_priority	the id without the suffix of the metabolite's own compartment	notes["merged_base_id"] when merge_compartments stored it, otherwise as before, so a merged ACCOA_c in s and a universal ACCOA_m share the key ACCOA
two metabolites with one key in one compartment (same four functions)	one of them stood for both	ValueError
default threads of reconstruction.homology.run_blast, run_diamond, run_supporth and reconstruction.kegg.run_hmmsearch, get_kegg_model_from_sequences, build_ko_hmm, build_hmm_library	the machine's CPU count minus one	every CPU the process may run on, as getBlast, getDiamond, runSuppOrth and getKEGGModelForOrganism
gapfilling.analyse_topology default seeds	one-metabolite reactions with lower_bound < 0	metabolites of every reaction without products and with lower_bound < 0, or without substrates and with upper_bound > 0; UserWarning when there is none
gapfilling.analyse_topology default targets	every metabolite of the model	substrates and products of the first objective reaction; ValueError without an objective
init.merge_linear group numbers	merge order	order of the first reaction of each group in the original model, as mergeLinear
io.read_yaml_model notes written as a notes mapping	nested under notes["note"]	back in notes

Gene rules

New utils.parse_gr_rule reads a rule in the grammar of RAVEN's parseGrRule (and/or in any case, &, &&, |, ||, operators as whole words, whitespace as MATLAB's isspace), so G1&G2 is one gene id; a malformed rule raises ValueError with the message of RAVEN:badGrRule. manipulation.gpr_to_dnf and utils.is_dnf take a rule string and read it with this parser. utils.gpr.set_gene_rule sets a rule from a GPR object or a string read with parse_gr_rule, and io.read_yaml_model, curation.batch_curate (and batch_curate_from_tsv) and the functions that copy or build a rule (manipulation.merge_compartments, copy_to_compartment, convert_to_irreversible, merge_models, add_reactions_from_model, expand_model, change_gene_reaction_rules, add_reactions_from_equations, localization.apply_assignment, init.fill_tasks, init.remove_low_score_genes, reconstruction.homology.get_model_from_homology, reconstruction.kegg.assemble_model_from_ko_genes, io.read_matlab_model) set rules through it, so G1&G2 or G3 has the genes G1&G2 and G3, as in RAVEN; a rule that parse_gr_rule refuses is read by cobra. cobra's JSON reader still splits G1&G2.

merge_compartments stores the base id of each merged metabolite in notes["merged_base_id"] (ACCOA for the kept ACCOA_c, the own id when two would coincide). The note survives raven-toolbox YAML, copy(), cobra JSON and SBML; RAVEN's readYAMLmodel shows it in metNotes and no RAVEN function reads it, and a round trip through RAVEN YAML or a .mat file loses it, after which the localization functions key a merged ACCOA_c in s as ACCOA_c without an error.

ftINIT tie resolution

With resolve_ties, init.ftinit and init.run_ftinit take each step's fluxes from the least-total-flux solution for the tie-broken on set (phase 2c, gap 1e-6, full time_limit) and, among those, from the one with the least id-rank-weighted backward flux (phase 2d), so the directions the next step forces no longer depend on the solver. The id-rank phases rank a merged reaction by the smallest original reaction id in its group (new run_ftinit argument rank_keys), and a merged reaction prefers its forward direction as written. The last step of ftinit skips phases 2c and 2d, as no step reads its fluxes, and reports the fluxes of the id-rank phase; the reaction set does not change. A phase that finds no solution raises a UserWarning naming it (phase2c-minflux, phase2d-direction) and the fluxes of the phase before it are kept; a phase that stops at the time limit is adopted with a UserWarning.

With CompMetEng/RAVEN#15, the 88 RAVEN scenarios of CompMetEng/raven-gecko-parity#143 give 86 MATCH and 2 DIFFER, both documented in its ledger: in fseof_toy, solveLP relaxes EX_S to 0.999999 of its maximum, and in edge_model_toy, writeYAMLmodel refuses two metabolites with one name in one compartment where raven-toolbox warns and writes the file. On Human-GEM with HCT116 (series 1+1), both tools find 204 task-essential reactions and give identical final reaction sets (7,752 reactions); 28 forced directions of step 2 differ, as the ledger records. For Human-GEM's gene-essentiality baseline, the template-bounds output already on develop (c3a2130) means the complex III and IV genes no longer block growth in the growth-ratio score (139 growth-lethal flips summed over five lines against about 18 from run-to-run noise), matching RAVEN, because Human-GEM's own succinate dehydrogenase direction is reversible; viability and task MCCs are unchanged within noise.

Not checked: GECKO scenarios and geckopy, CI on Python 3.11 to 3.15, RAVEN test classes outside tUtils, tManipulation, tINIT, tGapfilling, tAnalysis and tReconstruction, gene essentiality on Human-GEM beyond one run per variant.