Add user guide page 16: combining and simplifying models - #37
Merged
Conversation
Merging, contracting, simplifying against the current bounds, and collapsing compartments -- MATLAB and Python side by side. Merging two copies of the same model states the behaviour more clearly than prose can: 53 reactions become 106 while 52 metabolites stay 52. Metabolites are matched on name and compartment, genes on name, and reactions are added with no check at all, so de-duplicating is a separate step. 16.4 documents a raven-toolbox bug rather than working around it. merge_compartments deletes every reaction left holding one metabolite, including the exchanges that had one all along, and drops the objective when it rebuilds the model -- together taking smallYeast from growth 0.1222 to 0.0000 silently. RAVEN reserves those reactions and keeps 50 where raven-toolbox keeps 42. Fix filed as SysBioChalmers/raven-toolbox#96; the page says plainly which tab to trust until it lands.
13.2 documented "1 added, 11 newly connected, 23 still unconnectable". Two CI runs on identical input -- same RAVEN commit, same model -- reported 11 and 9. fillGaps solves a MILP, several solutions are equally optimal, and which one is returned varies with the machine and the thread count, so those two counts were never a stable result to document. Print the identity of the added reaction instead. Both toolboxes return ADH1, the reaction the setup removed, which is the claim the section is actually making and is reproducible. The instability itself is now described on the page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds user guide page 16, Combining and simplifying models — merging,
contracting, simplifying against the current bounds, and collapsing
compartments. MATLAB and Python side by side, every example executed.
Merging two copies says it better than prose
53 reactions become 106 while 52 metabolites stay 52. Metabolites are
matched on name and compartment (not identifier), genes on name, and reactions
are added with no check at all — so de-duplication is a separate step, and
merging models from different databases is a claim about naming consistency.
Both tabs agree exactly on merge, contract and simplify. Simplifying the
shipped-shut
smallYeastleaves 2 reactions of 53 in both toolboxes, whichmakes the "simplify against the condition you mean to simulate" warning concrete.
16.4 documents a bug rather than working around it
This is the one place the tabs disagree: RAVEN keeps 50 reactions, raven-
toolbox keeps 42. That gap is a defect, filed as
raven-toolbox#96:
merge_compartmentsdeletes every reaction left holding a single metabolite,including the exchanges, which had a single metabolite all along. Of the 11
reactions it drops, 3 are genuine transports; the other 8 are every boundary
reaction in the model,
biomassOUTincluded.over, so it optimises to
0.0.Together: growth
0.1222→0.0000, no error, no warning. RAVEN avoids it byrecording single-metabolite reactions before merging and refusing to delete
them. The page states which tab to trust and what to check until the fix ships.
Checks
check_names.pyclean (three argument names added to the allowlist)The guide is now 16 pages, 167 examples, no skips.
Also: a flaky example on page 13, now stabilised
CI failed on this PR in
gap-filling.md, not on the new page. 13.2 documented1 added, 11 newly connected, 23 still unconnectable; the run reported 9 and22 — same RAVEN commit, same model, same inputs as the run half an hour before.
fillGapssolves a MILP, several solutions are equally optimal, and which onecomes back varies with the machine and thread count. Those counts were never a
stable thing to document.
The section now prints the identity of what was added —
1 added: ADH1, thereaction the setup removed, in both toolboxes. That is the claim the section is
really making, it is reproducible, and it is better documentation. The
instability is described on the page rather than hidden.
Both jobs green.