edkerk · Sep 9, 2026 · Sep 9, 2026
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -25,6 +25,9 @@ signature, parameters and returns:
   `Manipulation`, `Input / output`, …).
 - **Python API (raven-toolbox)**: one page per package, mirroring the same
   categories.
+- **[MATLAB vs Python](../matlab-vs-python.md)**: a third page pairing every
+  function that exists in both, generated at build time from both toolboxes'
+  sources.
 
 Every page opens with a *Functions* table you can scan, followed by the full
 help for each function.
@@ -60,4 +63,5 @@ Use the navigation to browse either tree, or start from the
 
 matlab/index
 python/index
+../matlab-vs-python
 ```
diff --git a/docs/data/README.md b/docs/data/README.md
@@ -52,7 +52,7 @@ numbers unreproducible for a reader who takes the model from RAVEN instead.
 
 ## Proteomes, for the homology page
 
-`hanpo.faa` and `sce-template.faa` back [18. Reconstruction from
+`hanpo.faa` and `sce-template.faa` back [12. Reconstruction from
 homology](../guide/homology.md).
 
 | file | what it is |

diff --git a/docs/guide/biomass.md b/docs/guide/biomass.md
@@ -1,4 +1,4 @@
-# 22. Biomass composition and annotation
+# 11. Biomass composition and annotation
 
 The biomass pseudoreaction is where a model states what a cell is made of, and it
 sets the units of every growth rate the model reports. This page is about reading
@@ -113,7 +113,7 @@ polymerised, two hydrogens or a water, which is what makes a protein weigh less
 than the sum of its amino acids. `grams` takes the coefficients as already being
 in g/gDW, which is how the lipid backbone is written.
 
-## 22.1 What is the cell made of?
+## 11.1 What is the cell made of?
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -174,7 +174,7 @@ same mass, so counting both would double it; the
 [lipid curation](../protocol/lipid-curation.md) step in the protocol explains the
 representation.
 
-## 22.2 Change one component
+## 11.2 Change one component
 
 Measured a different protein content? Set it, and specify which other component
 absorbs the change. A biomass that no longer sums to 1 is worse than one with the
@@ -219,7 +219,7 @@ protein 0.5000, carbohydrate 0.3384, total 1.0000
 
 `scale_biomass` edits the model **in place** and returns `None`, while
 `scaleBiomassFraction` returns a new struct and leaves its input alone. That is
-the same split as in [16. Combining and simplifying](combining.md), and it is why
+the same split as in [20. Combining and simplifying](combining.md), and it is why
 the Python tab copies the model first.
 
 `balanceOut` names the component that absorbs the change, so the total stays
@@ -231,7 +231,7 @@ a single pseudoreaction rather than a named component, and rebalance the protons
 afterwards using the `proton_met` from the configuration. That is what keeps the
 reaction charge balanced when its coefficients move.
 
-## 22.3 Annotation: SBO terms
+## 11.3 Annotation: SBO terms
 
 An SBO term says what a reaction or metabolite *is*: a transport reaction, an
 exchange, a metabolite rather than a pseudo-species. Solvers ignore them;
@@ -275,7 +275,7 @@ only by compartment is a transport, and so on. Nothing is inferred that the
 stoichiometry does not already support, so running it on a model with mislabelled
 compartments propagates that mistake rather than catching it.
 
-## 22.4 Annotation: cross-references and thermodynamics
+## 11.4 Annotation: cross-references and thermodynamics
 
 Database cross-references travel in MIRIAM form: a namespace and an identifier,
 such as `chebi/CHEBI:15589`. RAVEN keeps them in `metMiriams` and `rxnMiriams`
@@ -312,5 +312,5 @@ separately from the model, and re-applied after the model changes.
 - [4. Simulating growth with FBA](fba.md), where the growth rate these units
   belong to comes from.
 - [8. Editing an existing model](editing.md), changing a pseudoreaction by hand.
-- [Worked protocol: biomass composition](../protocol/biomass.md), building the
-  pseudoreactions from measurements for a new organism.
+- [GEM reconstruction protocol: biomass composition](../protocol/biomass.md),
+  building the pseudoreactions from measurements for a new organism.
diff --git a/docs/guide/combining.md b/docs/guide/combining.md
@@ -1,4 +1,4 @@
-# 16. Combining and simplifying models
+# 20. Combining and simplifying models
 
 This page covers two operations that look like simple bookkeeping but carry real
 risk. **Merging** puts models
@@ -62,7 +62,7 @@ print(f"{len(model.reactions)} rxns, {len(model.metabolites)} mets, "
 :::
 ::::
 
-## 16.1 Merging
+## 20.1 Merging
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -122,7 +122,7 @@ halves that happen to live in the same struct. Merging is a claim that the
 naming is consistent; check it before you make it, not after.
 :::
 
-## 16.2 Merging does not de-duplicate
+## 20.2 Merging does not de-duplicate
 
 Every reaction from both models survived, so the merged model now describes each
 conversion twice. Collapsing those is a separate step.
@@ -179,7 +179,7 @@ alone. The Python side is not uniform:
 in Python. Copy the model first to keep the original.
 :::
 
-## 16.3 Dropping what cannot carry flux
+## 20.3 Dropping what cannot carry flux
 
 `smallYeast` ships with its medium shut, so almost nothing in it can carry flux
 at all, the state [9. Quality control](quality-control.md) measures. That makes
@@ -226,7 +226,7 @@ medium, not of the organism. Open the conditions you intend to simulate
 **before** simplifying, or you will delete the pathways you were about to study;
 see [5. Growth media and conditions](media.md).
 
-## 16.4 Collapsing compartments
+## 20.4 Collapsing compartments
 
 Sometimes the compartments are the problem: a draft with unreliable
 localisation, or a comparison against a model that has none.
@@ -313,7 +313,7 @@ Flatten a copy, for a specific question, and keep the original.
 ## See also
 
 - [9. Quality control](quality-control.md), deciding what *should* be removed.
-- [13. Gap-filling](gap-filling.md), the opposite operation, and the usual
+- [17. Gap-filling](gap-filling.md), the opposite operation, and the usual
   reason for having a template model to merge from.
-- [10. Context-specific models](init.md), cutting a model down by evidence
+- [14. Context-specific models](init.md), cutting a model down by evidence
   rather than by connectivity.
diff --git a/docs/guide/comparing.md b/docs/guide/comparing.md
@@ -1,4 +1,4 @@
-# 17. Comparing models
+# 21. Comparing models
 
 Curation produces several versions of one model: a draft and a curated
 version, the model before and after gap-filling, a local build and a
@@ -55,7 +55,7 @@ good 53 rxns, bad 54 rxns
 :::
 ::::
 
-## 17.1 What exactly is different?
+## 21.1 What exactly is different?
 
 `diffModels` matches by identifier and compares what it finds: stoichiometry,
 bounds, objective coefficients, gene rules, formulas, charges. It answers a yes
@@ -107,7 +107,7 @@ This is the comparison to put in a test. `DiffReport` is falsy when the models
 differ, so `assert diff_models(before, after)` is a working regression test for a
 curation script, and in MATLAB, `report.equal` does the same job.
 
-## 17.2 How alike are they?
+## 21.2 How alike are they?
 
 The other question is coarser: across the whole reaction set, how much do two
 models overlap? `compare_models` builds a presence matrix, one row per
@@ -159,13 +159,13 @@ similarity: 0.945
 
 :::{warning} A high similarity does not mean the models agree
 These two models are **0.945** alike on the reaction set, and one of them is
-broken. The differences 17.1 lists are a doubled stoichiometric coefficient
+broken. The differences 21.1 lists are a doubled stoichiometric coefficient
 and a reaction made irreversible, changes that alter what the model
 *predicts* while barely moving a set-overlap score. Similarity is for
 grouping models, not for validating one.
 :::
 
-## 17.3 Compare what they do, not what they contain
+## 21.3 Compare what they do, not what they contain
 
 Two models with the same reactions can behave differently, and two models with
 different reactions can behave identically. The comparison that settles it is of
@@ -218,7 +218,7 @@ RAVEN can also run this comparison for you. `compareMultipleModels` takes
 `funcCompare` and a `taskFile`, and then compares the models by which
 metabolic tasks each one passes rather than by which reactions each one has.
 That is the same shift from contents to behaviour made by hand above, and
-[12. Metabolic tasks](tasks.md) is where the task file comes from.
+[15. Metabolic tasks](tasks.md) is where the task file comes from.
 `groupVector` labels the models, by tissue or by condition, so the similarity
 matrix is reported per group.
 
@@ -232,7 +232,7 @@ answer the same question, but you index them in opposite directions.
 - **Comparing on identifiers alone.** Both functions match by id. Two models
   from different databases share few ids and will look unrelated even when
   they describe the same metabolism; see
-  [16. Combining and simplifying](combining.md), where merging matches on
+  [20. Combining and simplifying](combining.md), where merging matches on
   names instead.
 - **Reading similarity as quality.** It measures overlap, not correctness.
 - **Forgetting the medium.** A flux comparison compares conditions as much as
@@ -247,7 +247,7 @@ answer the same question, but you index them in opposite directions.
 ## See also
 
 - [9. Quality control](quality-control.md), checking one model rather than two.
-- [16. Combining and simplifying](combining.md), putting models together, and
+- [20. Combining and simplifying](combining.md), putting models together, and
   what has to line up first.
 - [4. Simulating growth with FBA](fba.md), the simulation a flux comparison
   rests on.
diff --git a/docs/guide/curation.md b/docs/guide/curation.md
@@ -1,4 +1,4 @@
-# 21. Table-driven curation
+# 10. Table-driven curation
 
 Curation done one function call at a time is hard to review and harder to repeat.
 Both toolboxes can instead take the curation as **tables**: one row per
@@ -44,7 +44,7 @@ metNames	comps	formula	charge	metNotes
 3-phospho-D-glycerate	c	C3H7O7P	-3	charge assigned at pH 7.3
 ```
 
-## 21.1 Apply a table
+## 10.1 Apply a table
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -137,7 +137,7 @@ the table was applied in full, and note that this is a divergence between the
 two toolboxes rather than a difference in the tables.
 :::
 
-## 21.2 Adding rather than updating
+## 10.2 Adding rather than updating
 
 A row whose name matches nothing in the model adds a new entity, and the
 identifier is minted rather than taken from the file. Both toolboxes find the

diff --git a/docs/guide/deletions.md b/docs/guide/deletions.md
@@ -1,4 +1,4 @@
-# 11. Deletions and essentiality
+# 16. Deletions and essentiality
 
 Which genes can the organism lose and still grow? Knock each one out, re-solve,
 and compare. The same machinery answers "which reactions are essential", "what
@@ -56,7 +56,7 @@ wild type: 0.1222 /h
 :::
 ::::
 
-## 11.1 Knock out one gene
+## 16.1 Knock out one gene
 
 The question underneath every deletion study: with this gene gone, can the model
 still reach its objective? A gene knockout is not a reaction knockout: the GPR
@@ -102,7 +102,7 @@ block.
 :::
 ::::
 
-## 11.2 Knock out every gene
+## 16.2 Knock out every gene
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -149,7 +149,7 @@ because the same function shape serves the double-deletion case.
 :::
 ::::
 
-## 11.3 Essential reactions
+## 16.3 Essential reactions
 
 Reaction essentiality asks the same question one level down. The two functions
 below look equivalent but ask different questions, which is why their answers
@@ -198,11 +198,11 @@ tab returns none.
 
 For essentiality with respect to a *task* rather than the objective,
 raven-toolbox has `find_task_essential_reactions`; see
-[12. Metabolic tasks](tasks.md).
+[15. Metabolic tasks](tasks.md).
 :::
 ::::
 
-## 11.4 Two at a time
+## 16.4 Two at a time
 
 Double deletions find the redundancy single deletions miss: two genes that each
 look dispensable but cannot both be deleted. The number of pairs to test is
@@ -240,7 +240,7 @@ lowest growth: 0.0000 /h
 :::
 ::::
 
-## 11.5 A knockout's fluxes, not just its growth rate
+## 16.5 A knockout's fluxes, not just its growth rate
 
 FBA assumes the knockout re-optimises perfectly, which a cell that just lost a
 gene does not do. MOMA instead looks for the flux distribution closest to the
@@ -259,7 +259,7 @@ or from the COBRA Toolbox, which keeps its own.
 
 What RAVEN does offer for the same *question* (what changed in the mutant,
 rather than by how much growth fell) is `compareFluxes` on two flux
-vectors from the same model, in [17. Comparing models](comparing.md).
+vectors from the same model, in [21. Comparing models](comparing.md).
 :::
 :::{tab-item} 🐍 Python
 :sync: python
@@ -298,5 +298,5 @@ MOMA growth: 0.0000 /h
 ## See also
 
 - [4. Simulating growth with FBA](fba.md), the solve underneath all of this.
-- [12. Metabolic tasks](tasks.md), essentiality with respect to a task.
+- [15. Metabolic tasks](tasks.md), essentiality with respect to a task.
 - [9. Quality control](quality-control.md), before trusting any of it.
diff --git a/docs/guide/editing.md b/docs/guide/editing.md
@@ -149,7 +149,7 @@ YBR196C or YLR354C
 model, so the results have to be assigned back into the struct to persist.
 Disjunctive normal form is a flat `or` of `and` groups, one group per
 alternative complex, which is the form the scoring in
-[10. Context-specific models](init.md) expects.
+[14. Context-specific models](init.md) expects.
 :::
 :::{tab-item} 🐍 Python
 :sync: python
@@ -297,7 +297,7 @@ PGI rule: 'YLR354C'
 `removeGenes` rewrites each affected GPR without the removed gene. Its
 `removeBlockedRxns` flag, off by default, additionally deletes reactions that
 lose their last catalyst, which turns a gene deletion into a reaction deletion;
-[11. Deletions and essentiality](deletions.md) covers when that is the
+[16. Deletions and essentiality](deletions.md) covers when that is the
 question being asked. `standardizeRules`, on by default, normalises the
 rewritten rules.
 

diff --git a/docs/guide/engineering.md b/docs/guide/engineering.md
@@ -1,4 +1,4 @@
-# 20. Engineering targets
+# 22. Engineering targets
 
 Two questions underlie most strain-design work. Which reactions would have to
 change for the cell to make more of something, and which metabolites are most
@@ -53,7 +53,7 @@ growth 0.1222 /h
 :::
 ::::
 
-## 20.1 Which reactions track the product?
+## 22.1 Which reactions track the product?
 
 FSEOF forces the product exchange to carry progressively more flux, maximising
 growth at each step, and records what every other reaction does. A reaction whose
@@ -131,7 +131,7 @@ zero.
 :::
 ::::
 
-## 20.2 Reading the scan
+## 22.2 Reading the scan
 
 A target's reliability depends on the trend behind it. The scan matrix is what
 distinguishes a reaction that rises steadily from one that jumps once and stops.
@@ -180,7 +180,7 @@ sign says which way to push, and its magnitude says how hard. Neither says the
 change is achievable: FSEOF works on the stoichiometry and the bounds, and knows
 nothing about regulation, enzyme capacity or toxicity.
 
-## 20.3 Reporter metabolites
+## 22.3 Reporter metabolites
 
 The other direction. Given a differential-expression result, which metabolites
 have the most transcriptionally-responsive neighbourhood? The algorithm scores
@@ -297,7 +297,7 @@ above.
 ## See also
 
 - [4. Simulating growth with FBA](fba.md), the solve each FSEOF step performs.
-- [15. Random sampling](sampling.md), the other way to ask what a network can do
+- [19. Random sampling](sampling.md), the other way to ask what a network can do
   rather than what one optimum says.
-- [11. Deletions and essentiality](deletions.md), knockouts rather than
+- [16. Deletions and essentiality](deletions.md), knockouts rather than
   amplification.