From 1b551e7e511077e09f6221a13687d0fd552d4ad5 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 4 Nov 2026 05:17:35 +0000 Subject: [PATCH 1/2] build(deps): update myst-parser requirement from >=3.0 to >=5.1.0 Updates the requirements on [myst-parser](https://github.com/executablebooks/MyST-Parser) to permit the latest version. - [Release notes](https://github.com/executablebooks/MyST-Parser/releases) - [Changelog](https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md) - [Commits](https://github.com/executablebooks/MyST-Parser/compare/v3.0.0...v5.1.0) --- updated-dependencies: - dependency-name: myst-parser dependency-version: 5.1.0 dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 2c5d6e7..a5061a0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ sphinx>=9.2.0 pydata-sphinx-theme>=0.23.0 -myst-parser>=3.0 +myst-parser>=5.1.0 sphinx-design>=0.7.0 sphinx-copybutton>=0.5.2 pyyaml>=6.0.3 From 2c548fb0bf99bd255c88c4beb601ed59874890b8 Mon Sep 17 00:00:00 2001 From: Eduard Kerkhoven Date: Fri, 6 Nov 2026 23:29:39 +0100 Subject: [PATCH 2/2] Replace figurative verbs and idioms in the guide, installation and parameter-tuning pages --- docs/guide/biomass.md | 2 +- docs/guide/building.md | 2 +- docs/guide/combining.md | 10 +++++----- docs/guide/comparing.md | 4 ++-- docs/guide/curation.md | 2 +- docs/guide/engineering.md | 4 ++-- docs/guide/fba.md | 2 +- docs/guide/gap-filling.md | 4 ++-- docs/guide/getting-started.md | 10 +++++----- docs/guide/homology.md | 20 +++++++++---------- docs/guide/index.md | 2 +- docs/guide/init.md | 4 ++-- docs/guide/io.md | 2 +- docs/guide/kegg.md | 2 +- docs/guide/media.md | 2 +- docs/guide/model-structure.md | 12 +++++------ docs/guide/solvers.md | 14 ++++++------- docs/guide/tasks.md | 2 +- docs/installation/data-and-binaries.md | 4 ++-- docs/installation/index.md | 2 +- docs/installation/raven.md | 2 +- docs/installation/updating-kegg-assets.md | 4 ++-- docs/parameter-tuning/benchmarks.md | 6 +++--- docs/parameter-tuning/index.md | 2 +- .../studies/ftinit-determinism.md | 6 +++--- .../studies/init-solver-benchmark.md | 2 +- .../studies/kegg-hmm-cutoff-calibration.md | 4 ++-- .../sampling-convergence-calibration.md | 4 ++-- docs/protocol/index.md | 2 +- docs/protocol/manual-curation.md | 2 +- docs/protocol/reconstruction.md | 2 +- .../raven3-migration/backward-incompatible.md | 4 ++-- docs/raven3-migration/new-and-environment.md | 6 +++--- .../same-function-different-answer.md | 4 ++-- docs/raven3-vs-raven-toolbox/what-each-has.md | 2 +- docs/tuned-parameters.md | 4 ++-- docs/tutorials/tutorial1.md | 2 +- docs/yaml-format.md | 8 ++++---- 38 files changed, 86 insertions(+), 86 deletions(-) diff --git a/docs/guide/biomass.md b/docs/guide/biomass.md index beb3553..6bd8895 100644 --- a/docs/guide/biomass.md +++ b/docs/guide/biomass.md @@ -250,7 +250,7 @@ The terms are assigned from the content of the model: - A reaction in which one metabolite name occurs in more than one compartment is a transport (SBO:0000655). `GROWTH`, which uses acetyl-CoA in `c` and `m`, is labelled as one. - Every other reaction is a metabolic reaction (SBO:0000176), unless its name marks it as the biomass, maintenance or another pseudoreaction. -Nothing is inferred beyond what the stoichiometry supports. On a model with wrong compartments, the assignment carries the error forward and does not detect it. +Nothing is inferred beyond what the stoichiometry supports. On a model with wrong compartments, the assignment propagates the error and does not detect it. ## Cross-reference and thermodynamic annotation diff --git a/docs/guide/building.md b/docs/guide/building.md index 0bbed7b..3a4e3b5 100644 --- a/docs/guide/building.md +++ b/docs/guide/building.md @@ -130,7 +130,7 @@ bounds: [0 Inf], genes: YFR053C `eqnType` specifies how the equation is written. The value `1` or `"id"` matches the metabolites against `model.mets`. The value `2` or `"name"` matches against `model.metNames` and uses `compartment` for the location. The value `3` or `"name[comp]"` reads the compartment from the token. -`allowNewGenes` is required because `YFR053C` is not in the model. `allowNewGenes` and `allowNewMets` default to `false`, so `addRxns` raises an error for an unknown identifier unless the option is set, and a mistyped identifier does not create a new entity. `allowNewMets` also accepts a string, which becomes the prefix of the generated identifiers. Metabolites added with `addMets` first carry more annotation than `addRxns` can infer. +`allowNewGenes` is required because `YFR053C` is not in the model. `allowNewGenes` and `allowNewMets` default to `false`, so `addRxns` raises an error for an unknown identifier unless the option is set, and a mistyped identifier does not create a new entity. `allowNewMets` also accepts a string, which becomes the prefix of the generated identifiers. Metabolites added with `addMets` first have more annotation than `addRxns` can infer. ::: :::{tab-item} 🐍 Python :sync: python diff --git a/docs/guide/combining.md b/docs/guide/combining.md index 20950f2..b4a1013 100644 --- a/docs/guide/combining.md +++ b/docs/guide/combining.md @@ -1,6 +1,6 @@ # Combining and simplifying models -Merging and simplifying look like bookkeeping and carry risk. Merging puts models together, such as a draft and a template, two organisms, or a curated core and an extension. The result is sound if a metabolite in one model is the same molecule as the metabolite of that name in the other. Simplifying takes a model apart and drops what cannot carry flux, and its risk is the deletion of something that is needed. +Merging and simplifying look like bookkeeping and involve risk. Merging puts models together, such as a draft and a template, two organisms, or a curated core and an extension. The result is sound if a metabolite in one model is the same molecule as the metabolite of that name in the other. Simplifying takes a model apart and drops what cannot carry flux, and its risk is the deletion of something that is needed. ## Functions @@ -89,7 +89,7 @@ merged: 106 rxns, 52 mets, 61 genes ::: :::: -The number of reactions doubles and the number of metabolites does not. The two models describe the same 52 metabolites, which the merged model shares, and every reaction of both sources is carried over. +The number of reactions doubles and the number of metabolites does not. The two models describe the same 52 metabolites, which the merged model shares, and every reaction of both sources is copied. The asymmetry follows from the matching rules. Metabolites are matched by name and compartment (`metaboliteName[comp]`) and genes by name, so anything that the two models call by the same name becomes one entity. Reactions are matched on nothing, and the warning reports this. An identifier that exists in both models receives the identifier of the source model as a suffix (`HXK` and `HXK_second`), which keeps the identifiers unique, and the two reactions are not reconciled. Python renames in the same way and gives no warning. @@ -134,7 +134,7 @@ after contracting: 53 rxns ::: :::: -`simplifyModel` removes nothing unless the flags say what to remove, as every flag is off by default except `deleteUnconstrained`. `deleteMinMax` is the expensive flag used in the example. It minimises and maximises each reaction to find out whether the reaction can carry flux. `deleteInaccessible` drops dead ends structurally, `deleteZeroInterval` drops reactions that are fixed at zero, and `deleteDuplicates` does what `contractModel` does. `reservedRxns` protects reactions from `deleteZeroInterval`, `deleteInaccessible` and `deleteMinMax`. In Python, the same choices are `delete_no_flux` and its related arguments. `open_exchanges` decides whether the test runs on the medium as it is or with the boundary opened first. +`simplifyModel` removes nothing unless the flags say what to remove, as every flag is off by default except `deleteUnconstrained`. `deleteMinMax` is the expensive flag used in the example. It minimises and maximises each reaction to find out whether the reaction can carry flux. `deleteInaccessible` drops dead ends structurally, `deleteZeroInterval` drops reactions that are fixed at zero, and `deleteDuplicates` does what `contractModel` does. `reservedRxns` protects reactions from `deleteZeroInterval`, `deleteInaccessible` and `deleteMinMax`. In Python, the same choices are `delete_no_flux` and its related arguments. `open_exchanges` determines whether the test runs on the medium as it is or with the boundary opened first. :::{admonition} Functions that change the model in place :class: warning @@ -151,7 +151,7 @@ Every RAVEN function here returns a new model struct and leaves its input unchan ## Dropping what cannot carry flux -`smallYeast` ships with a shut medium, so almost nothing in it can carry flux, which is the state that [Quality control](quality-control.md) measures. This makes it a subject for simplification and shows its hazard. +`smallYeast` has a shut medium, so almost nothing in it can carry flux, which is the state that [Quality control](quality-control.md) measures. This makes it a subject for simplification and shows its hazard. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB @@ -232,7 +232,7 @@ print(f"{len(dropped)} transport reactions dropped") ::: :::: -Seven metabolites of this model exist in both compartments, so 52 metabolites collapse to 45. The three reactions that moved a metabolite across the mitochondrial membrane become `A -> A`, carry no information and are dropped. +Seven metabolites of this model exist in both compartments, so 52 metabolites collapse to 45. The three reactions that moved a metabolite across the mitochondrial membrane become `A -> A`, contain no information and are dropped. The merged metabolite is one of its copies, with all fields of that copy (identifier, name, formula, charge, annotation), and raven-toolbox also adds `notes["merged_base_id"]`. The copy is the one in the merged compartment if there is one, and otherwise the copy whose identifier sorts first (`ACCOA_c` before `ACCOA_m`). The identifier can therefore name a compartment that the merged model does not contain. diff --git a/docs/guide/comparing.md b/docs/guide/comparing.md index ef759b3..fdd3a82 100644 --- a/docs/guide/comparing.md +++ b/docs/guide/comparing.md @@ -1,6 +1,6 @@ # Comparing models -Curation produces several versions of one model, such as a draft and a curated version, the model before and after gap-filling, or a local build and a published one. Two questions follow. What changed is answered by an exact entry-by-entry difference, which serves review and continuous integration (CI). How alike the models are is answered by an overview over whole sets, which serves to decide whether two models describe the same organism. +Curation produces several versions of one model, such as a draft and a curated version, the model before and after gap-filling, or a local build and a published one. Two questions follow. What changed is answered by an exact entry-by-entry difference, which serves review and continuous integration (CI). How alike the models are is answered by an overview over whole sets, which serves to determine whether two models describe the same organism. ## Functions @@ -148,7 +148,7 @@ The two models have a similarity of 0.945 on the reaction set, and one of them i ## Comparison by behaviour -Two models with the same reactions can behave differently, and two models with different reactions can behave identically. A simulation of both under the same constraints decides. Growth is compared first, then flux ranges or tasks, and a single flux vector is not compared, because it is one optimum among many ([Flux variability and alternative optima](fva.md)). +Two models with the same reactions can behave differently, and two models with different reactions can behave identically. A simulation of both under the same constraints gives the answer. Growth is compared first, then flux ranges or tasks, and a single flux vector is not compared, because it is one optimum among many ([Flux variability and alternative optima](fva.md)). ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB diff --git a/docs/guide/curation.md b/docs/guide/curation.md index 3a08025..1cc3f1d 100644 --- a/docs/guide/curation.md +++ b/docs/guide/curation.md @@ -96,7 +96,7 @@ updated: ['MAL_m', 'AKG_m', 'P2G_c', 'P3G_c'] ## Adding entities and overwriting values -A row whose name matches nothing in the model adds a new entity. The identifier is generated. Both toolboxes find the largest zero-padded number that carries the prefix and continue from it, so the new identifiers continue the scheme of the model. +A row whose name matches nothing in the model adds a new entity. The identifier is generated. Both toolboxes find the largest zero-padded number that has the prefix and continue from it, so the new identifiers continue the scheme of the model. The prefixes are arguments: `metPrefix` and `rxnPrefix` in MATLAB, `met_id_prefix` and `rxn_id_prefix` in Python. The defaults are `M_` and `R_`, the BiGG convention. A model derived from yeast-GEM uses `s_` and `r_`, and other prefixes give a model with two identifier schemes. diff --git a/docs/guide/engineering.md b/docs/guide/engineering.md index 2421821..4822714 100644 --- a/docs/guide/engineering.md +++ b/docs/guide/engineering.md @@ -68,7 +68,7 @@ fprintf('%d amplification target(s) of %d reactions\n', ... The scan runs for `iterations` steps, ten by default, up to `coefficient` times the theoretical maximum product flux, `0.9` by default. `outputFile` keeps the per-reaction table out of the command window, and the table is printed there without it. -`corrThreshold` decides what counts as a target. A reaction is kept when the absolute Pearson correlation between its flux and the enforced product flux is at least this value, `0.9` by default. Alternative optima make individual fluxes change erratically between steps, and the requirement of a nearly linear response keeps this noise out of the target list. +`corrThreshold` determines what counts as a target. A reaction is kept when the absolute Pearson correlation between its flux and the enforced product flux is at least this value, `0.9` by default. Alternative optima make individual fluxes change erratically between steps, and the requirement of a nearly linear response keeps this noise out of the target list. ::: :::{tab-item} 🐍 Python :sync: python @@ -216,7 +216,7 @@ Both toolboxes compute the background correction in closed form and report the s - FSEOF is read as a prediction. It reports what the stoichiometry allows when product formation is forced, which is a hypothesis to test. - The target list contains noise. With a lowered correlation threshold, alternative optima appear as targets. When the flux of a reaction is not close to linear in the enforced product, its slope has no meaning. - A product that the model cannot make is forced. When the target exchange cannot carry flux, every step of the scan is infeasible and there is nothing to correlate. A single solve checks this first. -- Reporter metabolites are computed on an unfiltered gene list. The correction handles the size of the neighbourhood and does not handle a uniform p-value distribution that arises because nothing is differentially expressed. Inspect the distribution of the input before trusting the ranking. +- Reporter metabolites are computed on an unfiltered gene list. The correction accounts for the size of the neighbourhood and does not account for a uniform p-value distribution that arises because nothing is differentially expressed. Inspect the distribution of the input before trusting the ranking. - Currency metabolites rank at the top. ATP, NADH and water take part in many reactions and therefore tend to rank at the top. Exclude them, or read the ranking beyond them. ::: diff --git a/docs/guide/fba.md b/docs/guide/fba.md index 12f6abd..62f5a30 100644 --- a/docs/guide/fba.md +++ b/docs/guide/fba.md @@ -11,7 +11,7 @@ Flux balance analysis (FBA) sets an objective, limits the uptake rates, solves t | `printFluxes` | `Model.summary` {bdg-link-secondary}`cobrapy ` | show the fluxes that carry material | | `solveLP` (`minFlux`) | `pfba` {bdg-link-secondary}`cobrapy ` | select a parsimonious solution among the optima | -Every Python simulation step on this page comes from cobrapy and carries the {bdg-link-secondary}`cobrapy ` badge in the functions table. In MATLAB, `solveLP` does not need the COBRA Toolbox or any other package outside RAVEN. +Every Python simulation step on this page comes from cobrapy and has the {bdg-link-secondary}`cobrapy ` badge in the functions table. In MATLAB, `solveLP` does not need the COBRA Toolbox or any other package outside RAVEN. ## Setup diff --git a/docs/guide/gap-filling.md b/docs/guide/gap-filling.md index 0349a82..9e64efb 100644 --- a/docs/guide/gap-filling.md +++ b/docs/guide/gap-filling.md @@ -58,7 +58,7 @@ print(f"draft {len(draft.reactions)} rxns, template {len(template.reactions)} rx draft 52 rxns, template 53 rxns ``` -With the medium as shipped (closed), 51 of the 53 reactions of `smallYeast` are blocked, because nothing can enter. Gap-filling a model in that state asks the wrong question. +With the medium as given in the model (closed), 51 of the 53 reactions of `smallYeast` are blocked, because nothing can enter. Gap-filling a model in that state asks the wrong question. ::: :::: @@ -134,7 +134,7 @@ print(f"{len(result.added_reactions)} added: " Both toolboxes return the reaction that was removed, and this identity is the result to report. `fillGaps` also returns the newly connected reactions and the reactions that cannot be connected. Their numbers are not stable, because the problem is a MILP with several equally optimal solutions, and the returned solution can change with the machine or the number of threads. Two CI runs on identical input reported 11 and 9 newly connected reactions. -Both are MILPs. `connect_blocked_reactions` runs on the GLPK that ships with cobrapy. `fillGaps` runs on the GLPK that ships with RAVEN and warns that Gurobi is recommended (`setRavenSolver('gurobi')`). +Both are MILPs. `connect_blocked_reactions` runs on the GLPK that is included with cobrapy. `fillGaps` runs on the GLPK that is included with RAVEN and warns that Gurobi is recommended (`setRavenSolver('gurobi')`). `allow_net_production` sets how strict the test is. A reaction can be blocked because a substrate is unavailable or because a product has nowhere to go. With net production allowed, the first case counts. Turning it off asks the harder question and usually adds more reactions. ::: diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 32c6c88..621387c 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -15,7 +15,7 @@ The page covers loading a model, reporting its size and inspecting one reaction, ## Setup -The examples use `smallYeast.yml`, a model of the central carbon metabolism of yeast that ships with RAVEN. The file is [`docs/data/smallYeast.yml`](../data/smallYeast.yml), and the examples run in the directory that contains it. +The examples use `smallYeast.yml`, a model of the central carbon metabolism of yeast that is included with RAVEN. The file is [`docs/data/smallYeast.yml`](../data/smallYeast.yml), and the examples run in the directory that contains it. One of the toolboxes must be installed first ([Installation](../installation/index.md)). The Setup section of most pages names the files that the page needs. All of them are in [`docs/data/`](../data/README.md), which is also the working directory when the `raven-docs` repository is cloned. The blocks of a page build on each other and run in order in one MATLAB or Python session. @@ -105,7 +105,7 @@ Python has no equivalent of `printModelStats`. The collections are attributes, s ## Inspecting a reaction -Glucose-6-phosphate isomerase (`PGI`) is reversible, has a gene association and is expected to be mass balanced, which covers most of what a reaction carries. +Glucose-6-phosphate isomerase (`PGI`) is reversible, has a gene association and is expected to be mass balanced, which covers most of what a reaction contains. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB @@ -151,7 +151,7 @@ YBR196C ::: :::: -The bounds define the direction. A lower bound of −1000 allows the reaction to run backwards, and a lower bound of zero does not. cobrapy derives `reversibility` from the bounds whenever it is read, so the two cannot disagree. RAVEN stores a separate `model.rev` field next to the bounds, and one can be changed without the other. [Model structure and identifiers](model-structure.md) describes how to handle this. +The bounds define the direction. A lower bound of −1000 allows the reaction to run backwards, and a lower bound of zero does not. cobrapy derives `reversibility` from the bounds whenever it is read, so the two cannot disagree. RAVEN stores a separate `model.rev` field next to the bounds, and one can be changed without the other. [Model structure and identifiers](model-structure.md) describes how to keep the two fields consistent. ## Inspecting a metabolite @@ -257,14 +257,14 @@ print(pgi.check_mass_balance()) {} ``` -An empty dictionary means that the reaction balances. Each entry maps an element, or `charge`, to the difference between the two sides, so the result gives the size of an imbalance as well as its presence. cobrapy reports the charge in the same dictionary and omits what it cannot decide. An empty dictionary therefore covers both a balanced reaction and a reaction with nothing to check. +An empty dictionary means that the reaction balances. Each entry maps an element, or `charge`, to the difference between the two sides, so the result gives the size of an imbalance as well as its presence. cobrapy reports the charge in the same dictionary and omits what it cannot determine. An empty dictionary therefore covers both a balanced reaction and a reaction with nothing to check. ::: :::: :::{admonition} Troubleshooting :class: warning -- A lookup fails. Identifiers are case-sensitive and carry the compartment suffix (`G6P_c`). Neither toolbox returns a placeholder for an identifier that is absent: `getIndexes` raises the error `Could not find object 'X' in the model`, and `get_by_id` raises `KeyError`. +- A lookup fails. Identifiers are case-sensitive and have the compartment suffix (`G6P_c`). Neither toolbox returns a placeholder for an identifier that is absent: `getIndexes` raises the error `Could not find object 'X' in the model`, and `get_by_id` raises `KeyError`. - The model loads and does not grow. In `smallYeast.yml` every uptake reaction is closed (`glcIN` has bounds `[0 0]`). [Growth media and conditions](media.md) opens a medium. - Gene identifiers differ between the model and a FASTA file. RAVEN stores the systematic name (`YBR196C`) as the identifier and the standard name (`PGI1`) as the gene name, and the two are not interchangeable. ::: diff --git a/docs/guide/homology.md b/docs/guide/homology.md index 4a29186..3a8104c 100644 --- a/docs/guide/homology.md +++ b/docs/guide/homology.md @@ -2,7 +2,7 @@ Homology-based reconstruction builds a draft model for an organism without one, with a curated model of a related organism as the source of reactions. Genes of the new organism are matched to genes of the template by sequence similarity, and a template reaction is copied when its genes have an accepted match. -The reconstruction has two steps. A sequence search produces a table of hits, and a transfer step selects the hits that are sufficient to carry a reaction. The cut-offs of the transfer step determine the size and the reliability of the draft. +The reconstruction has two steps. A sequence search produces a table of hits, and a transfer step selects the hits that are sufficient to support a reaction. The cut-offs of the transfer step determine the size and the reliability of the draft. ## Functions @@ -98,11 +98,11 @@ sce hanpo 159 ::: :::: -The two directions return different counts because they answer different questions, and neither count is a count of genes, as each line of BLAST output is one alignment. The 159 alignments from the template to *H. polymorpha* come from 60 of the 61 template genes, and the 178 alignments in the other direction come from 106 *H. polymorpha* genes. Neither number is the number of orthologs. The next step decides that from the pairs that occur in both directions. +The two directions return different counts because they answer different questions, and neither count is a count of genes, as each line of BLAST output is one alignment. The 159 alignments from the template to *H. polymorpha* come from 60 of the 61 template genes, and the 178 alignments in the other direction come from 106 *H. polymorpha* genes. Neither number is the number of orthologs. The next step determines that from the pairs that occur in both directions. The result has a different shape in the two toolboxes. RAVEN returns a struct array with one entry per direction. Each entry has `fromId`, `toId`, `fromGenes`, `toGenes` and per-hit vectors `evalue`, `aligLen` and `identity`. raven-toolbox returns one `pandas` DataFrame with the columns `from_id` and `to_id`, which holds both directions and can be filtered with DataFrame operations before it is passed on. -Both call the same BLAST+ executables with the same parameters, so the hit counts agree. Neither toolbox ships the executables. RAVEN downloads them for the platform on first use and caches them. raven-toolbox uses `RAVEN_PYTHON_BLASTP` if it is set, then a `blastp` on the `PATH`, and downloads when neither exists. A first reconstruction that downloads needs network access. +Both call the same BLAST+ executables with the same parameters, so the hit counts agree. Neither toolbox includes the executables. RAVEN downloads them for the platform on first use and caches them. raven-toolbox uses `RAVEN_PYTHON_BLASTP` if it is set, then a `blastp` on the `PATH`, and downloads when neither exists. A first reconstruction that downloads needs network access. Without `threads`, `run_blast`, `run_diamond` and `run_supporth` use every CPU that the process can run on. In MATLAB, `getBlast`, `getDiamond` and `runSuppOrth` use the cores that are assigned to MATLAB (`feature('numcores')`), and `runSuppOrth` is the sole function with a `threads` option. @@ -145,7 +145,7 @@ draft: 37 rxns, 49 mets, 54 genes ::: :::: -The transfer works reaction by reaction. For each reaction of the template, the genes in its gene rule are looked up in the hit table. A template gene is replaced by its accepted counterpart in the new organism, and the reaction is carried over when the rule can be satisfied after the substitution. A reaction that needs two subunits is kept with a placeholder gene (`OLD__`) for the missing subunit under the default `complexPolicy` (`complex_policy` in Python) of `flag`, and the policy `drop` removes it. A reaction with two isozymes is kept when either has a counterpart. The metabolites that a carried reaction needs are carried with it. The draft has 49 metabolites against 52 in the template, because the three metabolites that occur in dropped reactions alone are not created. +The transfer works reaction by reaction. For each reaction of the template, the genes in its gene rule are looked up in the hit table. A template gene is replaced by its accepted counterpart in the new organism, and the reaction is transferred when the rule can be satisfied after the substitution. A reaction that needs two subunits is kept with a placeholder gene (`OLD__`) for the missing subunit under the default `complexPolicy` (`complex_policy` in Python) of `flag`, and the policy `drop` removes it. A reaction with two isozymes is kept when either has a counterpart. The metabolites that a transferred reaction needs are transferred with it. The draft has 49 metabolites against 52 in the template, because the three metabolites that occur in dropped reactions alone are not created. The line `Standardizing grRules` shows RAVEN rewriting the rules of the template in a canonical form before the substitution. One rule written in two ways is then handled identically. @@ -157,7 +157,7 @@ The line `Standardizing grRules` shows RAVEN rewriting the rules of the template RAVEN returns the draft and its hit genes as two separate outputs. -The draft is smaller than the template, because reactions whose genes have no accepted counterpart are not carried over. This is the intended behaviour and also the main source of error, as a reaction left out because no hit passed the cut-offs looks the same as a reaction that the organism lacks. +The draft is smaller than the template, because reactions whose genes have no accepted counterpart are not transferred. This is the intended behaviour and also the main source of error, as a reaction left out because no hit passed the cut-offs looks the same as a reaction that the organism lacks. ## Hit cut-offs @@ -211,7 +211,7 @@ Some of these defaults differ from the values of RAVEN 2, so the same script can ## Contents of a draft -The result of this step has reactions, metabolites and genes. It has no biomass reaction unless a template reaction carried one, no exchange reactions, and no guarantee that any reaction carries flux. +The result of this step has reactions, metabolites and genes. It has no biomass reaction unless a template reaction contained one, no exchange reactions, and no guarantee that any reaction carries flux. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB @@ -254,19 +254,19 @@ reactions that can carry flux: 0 of 37 None of the 37 reactions carries flux. This does not indicate a defect of the draft. Without exchange reactions nothing enters or leaves the model, and the draft has no internal cycle, so no flux is possible. The number says nothing about the quality of the reconstruction, and it becomes informative after a medium is defined. -A homology draft is a set of claims about the reactions of the organism. Three steps turn it into a model: a medium ([Growth media and conditions](media.md)), gap-filling to close the gaps that prevent biomass production ([Gap-filling](gap-filling.md)), and a check against the known behaviour of the organism ([Metabolic tasks](tasks.md)). The [GEM reconstruction protocol](../protocol/index.md) follows this path for *H. polymorpha* at full scale. +A homology draft is a set of claims about the reactions of the organism. Three steps turn it into a model: a medium ([Growth media and conditions](media.md)), gap-filling to fill the gaps that prevent biomass production ([Gap-filling](gap-filling.md)), and a check against the known behaviour of the organism ([Metabolic tasks](tasks.md)). The [GEM reconstruction protocol](../protocol/index.md) follows this path for *H. polymorpha* at full scale. :::{admonition} Troubleshooting :class: warning -- The identifiers do not match. The headers of the FASTA file carry the gene identifiers of the `genes` field of the template model. A mismatch gives a draft without reactions and without an error. -- One template carries the bias of one organism. Every reaction of the draft comes from the template, so the draft cannot have anything that the template lacks. Several templates, ordered with `preferredOrder`, spread the risk. +- The identifiers do not match. The headers of the FASTA file contain the gene identifiers of the `genes` field of the template model. A mismatch gives a draft without reactions and without an error. +- One template has the bias of one organism. Every reaction of the draft comes from the template, so the draft cannot have anything that the template lacks. Several templates, ordered with `preferredOrder`, spread the risk. - Absence is read as evidence. A missing reaction means that no acceptable hit was found, and it does not show that the organism lacks the capability. Sequencing gaps, divergent sequences and short proteins look the same. - Complete proteomes are slow. The example finishes in seconds because the template proteome has 61 sequences. Two complete proteomes take minutes to hours with BLASTP, and `getDiamond` and `run_diamond` are faster. ::: ## See also -- [Gap-filling](gap-filling.md): the next step, which decides what the draft lacks. +- [Gap-filling](gap-filling.md): the next step, which determines what the draft lacks. - [Context-specific models](init.md): reducing a model by evidence, where homology builds a model up. - [Comparing models](comparing.md): comparing a draft with a curated model of the same organism. diff --git a/docs/guide/index.md b/docs/guide/index.md index 05c38ec..153fa72 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -6,7 +6,7 @@ The [reconstruction protocol](../protocol/index.md) for *H. polymorpha* and the ## Functions from cobrapy -A function that comes from cobrapy carries a {bdg-link-secondary}`cobrapy ` badge that links to the cobrapy documentation, and its import line shows where it lives (`from cobra.io import read_sbml_model`). The [function mapping](../matlab-vs-python.md) lists all of these functions. +A function that comes from cobrapy has a {bdg-link-secondary}`cobrapy ` badge that links to the cobrapy documentation, and its import line shows where it lives (`from cobra.io import read_sbml_model`). The [function mapping](../matlab-vs-python.md) lists all of these functions. ## Executed examples diff --git a/docs/guide/init.md b/docs/guide/init.md index 7806171..33f302e 100644 --- a/docs/guide/init.md +++ b/docs/guide/init.md @@ -24,7 +24,7 @@ The two methods are separate implementations that share no algorithm code. In th | Task gap-filling | `fitTasks` | `fitTasks` (`gapFillMode` `'preMerged'`), `ftINITFillGaps` | | Gene pruning | inline in `getINITModel` | `removeLowScoreGenes` | -The methods share general RAVEN functions that are not specific to either. `checkTasks` and `getEssentialRxns` decide which tasks are feasible and which reactions they need. Below these are `parseTaskList`, `simplifyModel`, the solver layer, and the functions for model manipulation and input and output. +The methods share general RAVEN functions that are not specific to either. `checkTasks` and `getEssentialRxns` determine which tasks are feasible and which reactions they need. Below these are `parseTaskList`, `simplifyModel`, the solver layer, and the functions for model manipulation and input and output. `scoreModel` is one function for both methods. `getINITModel` calls it with a single operator for `and` and `or` in a gene rule and with `dataPrecedence` `'reaction'`, the settings that the original tINIT algorithm needs, and afterwards converts the score of an unmeasured gene from `NaN` to `-Inf`. `ftINIT` calls it with the general defaults. Task gap-filling is one `fitTasks` loop for both. `getINITModel` uses the default `gapFillMode` (`'merge'`, backed by `fillGaps`). `ftINIT` passes `'preMerged'`, backed by `ftINITFillGaps`, because its reference model already contains the reactions of the sample and needs no merge per task. The MILP formulation is therefore the one place where gap-filling differs: `fillGaps` merges per task, and `ftINITFillGaps` expects a model that is merged already. The difference does not lie between `getINITModel` and `ftINIT` as such. @@ -132,7 +132,7 @@ prep_init_model 2216s Reading Human-GEM from the Systems Biology Markup Language (SBML) file alone takes about 11 seconds, and the preparation takes 37 minutes in Python and 47 minutes in MATLAB. The two preparations were separate Slurm jobs on the same node type with four cores each. The MATLAB run used the default of `prepINITModel` for `runParallel`, which is serial, and the Python run used `processes = 1`, so the two times compare the complete runs. Two settings affect the run: -- `prep_init_model` takes the argument `processes`, which defaults to 1, and its `simplify_model` passes follow `cobra.Configuration().processes`, which starts worker processes by default. The Python run above used `processes = 1`. Where worker processes are not permitted (a locked-down Windows machine, some continuous integration (CI) runners), the default fails with `PermissionError: [WinError 5] Access is denied`, and `processes = 1` removes the parallelism and lets the run finish. +- `prep_init_model` takes the argument `processes`, which defaults to 1, and its `simplify_model` passes follow `cobra.Configuration().processes`, which starts worker processes by default. The Python run above used `processes = 1`. Where worker processes are not permitted (a locked-down Windows machine, some continuous integration (CI) runners), the default fails with `PermissionError: [WinError 5] Access is denied`, and `processes = 1` removes the parallelism and allows the run to finish. - `essential_cache_path` caches the slow search for task-essential reactions, so a second preparation of the same template skips it. ::: :::: diff --git a/docs/guide/io.md b/docs/guide/io.md index 048cc97..70d9523 100644 --- a/docs/guide/io.md +++ b/docs/guide/io.md @@ -114,7 +114,7 @@ cobrapy decodes the identifiers of reactions, metabolites and genes and leaves t ## Read time by format -Each toolbox reads one format quickly and the other slowly, and the ranking is reversed between them. Reading yeast-GEM takes about 17 s from SBML and 73 s from YAML in Python, and about 78 s from SBML and 17 s from YAML in MATLAB. The format follows from what the file is needed for: a readable difference between versions, or the RAVEN-specific fields that YAML preserves. A script that spends most of its time reading the file runs faster with the format that its toolbox reads quickly. +Each toolbox reads one format quickly and the other slowly, and the ranking is reversed between them. Reading yeast-GEM takes about 17 s from SBML and 73 s from YAML in Python, and about 78 s from SBML and 17 s from YAML in MATLAB. The format follows from what the file is needed for: a readable difference between versions, or the RAVEN-specific fields that YAML preserves. A script that uses most of its time to read the file runs faster with the format that its toolbox reads quickly. ## Writing a model diff --git a/docs/guide/kegg.md b/docs/guide/kegg.md index 03f4a75..05c2022 100644 --- a/docs/guide/kegg.md +++ b/docs/guide/kegg.md @@ -102,7 +102,7 @@ objective: none The draft has no compartments. KEGG describes reactions, so every metabolite is in one undifferentiated space. A KEGG draft cannot distinguish mitochondrial and cytosolic reactions until it is localised. [Combining and simplifying models](combining.md) covers the reverse operation and what it discards. -The flags decide how inclusive the draft is. `keepIncomplete` / `keep_incomplete` keeps reactions that KEGG labels incomplete, erroneous or unclear. `keepUndefinedStoich` / `keep_undefined_stoich` keeps reactions with `n` or `x` in the stoichiometry, which cannot be balanced as written. With both turned off: +The flags determine how inclusive the draft is. `keepIncomplete` / `keep_incomplete` keeps reactions that KEGG labels incomplete, erroneous or unclear. `keepUndefinedStoich` / `keep_undefined_stoich` keeps reactions with `n` or `x` in the stoichiometry, which cannot be balanced as written. With both turned off: ```python strict = get_kegg_model_for_organism_from_artefacts( diff --git a/docs/guide/media.md b/docs/guide/media.md index e9731e5..a6eb9e2 100644 --- a/docs/guide/media.md +++ b/docs/guide/media.md @@ -311,7 +311,7 @@ medium = getMinimalMedium(model, 'minGrowth', 0.9 * sol.f); The candidates are the exchange reactions with `lb < 0`, so a nutrient that the model cannot take up is never proposed. `minGrowth` defaults to 10 % of the optimum under the current bounds, a limit loose enough that most components drop out, and it is set explicitly when the question concerns a given growth rate. `verbose` set to `false` suppresses the table and returns the identifiers. -Of the 16 open uptakes, 14 are kept. Water and H+ are dropped because other reactions supply them. `getMinimalMedium` solves a mixed-integer linear programme (MILP) that minimises the number of open uptakes. The GLPK that ships with RAVEN solves it as well, with a warning that recommends Gurobi. `minimal_medium` of cobrapy solves by default an LP that minimises the summed uptake flux (in mmol/gDW/h, all metabolites weighted equally), so it returns rates. +Of the 16 open uptakes, 14 are kept. Water and H+ are dropped because other reactions supply them. `getMinimalMedium` solves a mixed-integer linear programme (MILP) that minimises the number of open uptakes. The GLPK that is included with RAVEN solves it as well, with a warning that recommends Gurobi. `minimal_medium` of cobrapy solves by default an LP that minimises the summed uptake flux (in mmol/gDW/h, all metabolites weighted equally), so it returns rates. ::: :::{tab-item} 🐍 Python :sync: python diff --git a/docs/guide/model-structure.md b/docs/guide/model-structure.md index bcdca30..06c2533 100644 --- a/docs/guide/model-structure.md +++ b/docs/guide/model-structure.md @@ -34,7 +34,7 @@ A model is a struct of parallel arrays in MATLAB and a graph of objects in Pytho In MATLAB the caller keeps the parallel arrays aligned. `removeReactions` removes the same position from every reaction-length field and the matching column of `model.S`, so a manual deletion takes more than one line. In cobrapy each object holds its own links, and `model.remove_reactions([...])` leaves no stale state. -The difference also decides where errors become visible. A RAVEN model can be left in a state that no function rejects and that later functions misread, which `checkModelStruct` detects ([Checking a model](#checking-a-model)). A `cobra.Model` cannot reach most of these states, because the class maintains the structure. +The difference also determines where errors become visible. A RAVEN model can be left in a state that no function rejects and that later functions misread, which `checkModelStruct` detects ([Checking a model](#checking-a-model)). A `cobra.Model` cannot reach most of these states, because the class maintains the structure. ## Setup @@ -96,7 +96,7 @@ genes: YBR196C also reachable as: PGI ``` -`DictList` looks up an object by identifier and the object itself is the handle, so no index is carried around. `get_by_id` raises `KeyError` when the identifier is absent. The attribute form `model.reactions.PGI` is the same lookup, and it works for identifiers that are valid Python names: `model.reactions.r_0001` resolves, and an identifier with a dot or a hyphen needs `get_by_id`. Both forms return the same object, and a reference to it stays valid across edits elsewhere in the model. +`DictList` looks up an object by identifier and the object itself is the handle, so no index is kept. `get_by_id` raises `KeyError` when the identifier is absent. The attribute form `model.reactions.PGI` is the same lookup, and it works for identifiers that are valid Python names: `model.reactions.r_0001` resolves, and an identifier with a dot or a hyphen needs `get_by_id`. Both forms return the same object, and a reference to it stays valid across edits elsewhere in the model. ::: :::: @@ -174,7 +174,7 @@ print([m.id for m in matches]) ['G6P_c'] ``` -`parse_name_comp` splits the string without access to a model, and the `query` after it is the lookup that `getIndexes` performs. The compartment is `None` when the string has no trailing bracket, so one call handles both forms and the caller decides what a missing compartment means. An empty list means that the name is absent, and more than one entry means that the name is duplicated in that compartment. The function is imported from `raven_toolbox.utils.parse`, and the namespace `raven_toolbox.utils` does not re-export it. +`parse_name_comp` splits the string without access to a model, and the `query` after it is the lookup that `getIndexes` performs. The compartment is `None` when the string has no trailing bracket, so one call accepts both forms and the caller determines what a missing compartment means. An empty list means that the name is absent, and more than one entry means that the name is duplicated in that compartment. The function is imported from `raven_toolbox.utils.parse`, and the namespace `raven_toolbox.utils` does not re-export it. ::: :::: @@ -246,7 +246,7 @@ The "subSystems" field must be a cell array of chars, *or* a cell array of cell `checkModelStruct` validates the struct: required fields are present, each field has the expected type and length, and identifiers are non-empty, unique and valid. It also reports advisory findings: metabolites and genes that nothing uses, contradicting bounds, a missing or ambiguous objective, malformed gene rules and formulas, and cross-references that point nowhere. A finding has a `category` (`missing_field`, `wrong_type`, `empty_id`, `duplicate`, `invalid_id`, `invalid_bounds`, `unused`, `objective`, `gpr`, `invalid_formula`, `cross_reference` or `other`), a `target` with the field or identifier concerned, and the full `message`. -With an output argument, the function returns the findings and neither prints nor throws. Without one, it reports while it checks, and `throwErrors` decides whether a structural problem stops the script. Advisory findings are warnings in both cases. +With an output argument, the function returns the findings and neither prints nor throws. Without one, it reports while it checks, and `throwErrors` determines whether a structural problem stops the script. Advisory findings are warnings in both cases. ::: :::{tab-item} 🐍 Python :sync: python @@ -264,7 +264,7 @@ for issue in issues[:5]: 0 issue(s) ``` -`check_model` does not check field types, because a `cobra.Model` cannot hold a misshapen field. It checks what cobrapy leaves to the caller: metabolites and genes that no reaction uses, reactions without metabolites, metabolites without a name, two metabolites with the same name in one compartment, and an objective that is missing or spread over several reactions. A `ModelIssue` has `category`, `object_id` and `message`. The function returns a list and does not raise, so a script filters by category and decides which findings are fatal. +`check_model` does not check field types, because a `cobra.Model` cannot hold a misshapen field. It checks what cobrapy leaves to the caller: metabolites and genes that no reaction uses, reactions without metabolites, metabolites without a name, two metabolites with the same name in one compartment, and an objective that is missing or spread over several reactions. A `ModelIssue` has `category`, `object_id` and `message`. The function returns a list and does not raise, so a script filters by category and determines which findings are fatal. A result of `0` means that no curation problem was found. It does not mean that the model satisfies `checkModelStruct`, because the two lists overlap in the checks for unused elements and for the objective. ::: @@ -319,7 +319,7 @@ RAVEN and the COBRA Toolbox use different field names for the same model. In MAT - Fields are out of alignment. In MATLAB, a hand edit of one reaction-length field without the others leaves a model that works and fails later, often far from the edit. `checkModelStruct` detects it. - A field has mixed contents. `model.subSystems` holds strings or cell arrays of strings, one kind per model. The whole field is converted. - `model.rev` disagrees with the bounds. RAVEN stores the reversibility explicitly, so it can contradict `lb` and `ub` after a manual edit, and different functions read different fields. Python cannot reach this state, because `reaction.reversibility` is computed from the bounds on every read. -- Subsystems are lists. Code that assumes a string in `reaction.subsystem` fails on a model imported from RAVEN. `subsystem_to_str` handles both forms. +- Subsystems are lists. Code that assumes a string in `reaction.subsystem` fails on a model imported from RAVEN. `subsystem_to_str` accepts both forms. - A name lookup returns several indices. `getIndexes` with `'metnames'` matches the name in every compartment. `'metcomps'` with the `name[comp]` form selects one metabolite. ::: diff --git a/docs/guide/solvers.md b/docs/guide/solvers.md index 064f60b..9f63131 100644 --- a/docs/guide/solvers.md +++ b/docs/guide/solvers.md @@ -1,6 +1,6 @@ # Solvers and configuration -Most simulations on this site solve a linear program (LP). Gap-filling, minimal media with a minimum number of components, `solveLP` with `minFlux` set to 3, and ftINIT solve mixed-integer linear programs (MILPs). The quadratic MOMA in [Deletions and essentiality](deletions.md) solves a quadratic program (QP). The solvers that can handle each problem type depend on the solver and on the toolbox. +Most simulations on this site solve a linear program (LP). Gap-filling, minimal media with a minimum number of components, `solveLP` with `minFlux` set to 3, and ftINIT solve mixed-integer linear programs (MILPs). The quadratic MOMA in [Deletions and essentiality](deletions.md) solves a quadratic program (QP). The solvers that can solve each problem type depend on the solver and on the toolbox. ## Functions @@ -39,7 +39,7 @@ model.reactions.get_by_id("o2IN").upper_bound = 1000.0 ::: :::: -The sign convention is the opposite of the one in yeast-GEM, where uptake is a negative flux through an exchange reaction. A model carries the convention of its author, and the direction in which the equation is written decides which bound opens the reaction. [Growth media and conditions](media.md) works with the other convention. +The sign convention is the opposite of the one in yeast-GEM, where uptake is a negative flux through an exchange reaction. A model uses the convention of its author, and the direction in which the equation is written determines which bound opens the reaction. [Growth media and conditions](media.md) works with the other convention. ## Solver in use @@ -78,7 +78,7 @@ cobrapy has two levels. `Configuration()` holds the default for models created a ## Changing the solver -Both toolboxes ship with GLPK, which solves LPs and MILPs and therefore runs every example on this site except the quadratic MOMA. RAVEN warns when it sends a MILP to GLPK and recommends Gurobi. GLPK handles problems of the size of these examples, but gap-filling and ftINIT on a genome-scale model take much longer than with Gurobi, which is free for academic use. A QP needs a solver that supports QPs, such as Gurobi or CPLEX. RAVEN has no function that solves a QP. +Both toolboxes include GLPK, which solves LPs and MILPs and therefore runs every example on this site except the quadratic MOMA. RAVEN warns when it sends a MILP to GLPK and recommends Gurobi. GLPK solves problems of the size of these examples, but gap-filling and ftINIT on a genome-scale model take much longer than with Gurobi, which is free for academic use. A QP needs a solver that supports QPs, such as Gurobi or CPLEX. RAVEN has no function that solves a QP. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB @@ -88,7 +88,7 @@ Both toolboxes ship with GLPK, which solves LPs and MILPs and therefore runs eve setRavenSolver('glpk'); % 'gurobi', 'scip', or 'cobra' to hand over to the COBRA Toolbox ``` -The accepted values are `'glpk'`, `'gurobi'`, `'scip'` and `'cobra'`. `'glpk'` uses the binaries that ship with RAVEN and needs no further installation. `'gurobi'` needs Gurobi on the MATLAB path, and `'scip'` needs the SCIP MATLAB interface. `'cobra'` translates the problem to the format of the COBRA Toolbox and uses the solver last selected with `changeCobraSolver`. It requires an initialised COBRA Toolbox, which `setRavenSolver` checks, and it raises an error without storing a preference that cannot work. +The accepted values are `'glpk'`, `'gurobi'`, `'scip'` and `'cobra'`. `'glpk'` uses the binaries that RAVEN includes and needs no further installation. `'gurobi'` needs Gurobi on the MATLAB path, and `'scip'` needs the SCIP MATLAB interface. `'cobra'` translates the problem to the format of the COBRA Toolbox and uses the solver last selected with `changeCobraSolver`. It requires an initialised COBRA Toolbox, which `setRavenSolver` checks, and it raises an error without storing a preference that cannot work. ::: :::{tab-item} 🐍 Python :sync: python @@ -106,7 +106,7 @@ Assigning to `model.solver` rebuilds the problem of this model. Assigning to `Co ## Solution objects -The two solution objects carry the same information under different names. +The two solution objects contain the same information under different names. | MATLAB `solveLP` | cobrapy `Solution` | Meaning | |---|---|---| @@ -136,7 +136,7 @@ stat 1: Optimal solution found growth 0.1222 /h ``` -`solveLP` builds a problem struct in the COBRA format and passes it to `optimizeProb`, which calls the selected solver. `optimizeProb` is called directly to solve a problem that the toolbox built, such as the MILPs inside gap-filling. It takes two name-value arguments: `'params'`, a struct that is passed to the solver, and `'verbose'`, which shows the progress of a MILP. RAVEN handles one field of `params` itself and does not pass it on. `maxRatio` applies to LPs, splits badly scaled columns through auxiliary metabolites before solving and leaves the feasible region unchanged. +`solveLP` builds a problem struct in the COBRA format and passes it to `optimizeProb`, which calls the selected solver. `optimizeProb` is called directly to solve a problem that the toolbox built, such as the MILPs inside gap-filling. It takes two name-value arguments: `'params'`, a struct that is passed to the solver, and `'verbose'`, which shows the progress of a MILP. RAVEN uses one field of `params` itself and does not pass it on. `maxRatio` applies to LPs, splits badly scaled columns through auxiliary metabolites before solving and leaves the feasible region unchanged. ::: :::{tab-item} 🐍 Python :sync: python @@ -212,5 +212,5 @@ An infeasible model is over-constrained, and no solution satisfies the constrain ## See also - [Simulating growth with FBA](fba.md): the solve. -- [Growth media and conditions](media.md): the constraints that decide whether a problem is feasible. +- [Growth media and conditions](media.md): the constraints that determine whether a problem is feasible. - [Installation](../installation/index.md): installation and test of a solver. diff --git a/docs/guide/tasks.md b/docs/guide/tasks.md index 50a9c4c..256ebf2 100644 --- a/docs/guide/tasks.md +++ b/docs/guide/tasks.md @@ -161,7 +161,7 @@ The tasks differ in the CO₂ output. With the exchange reactions of the model o ## Task-essential reactions -Essentiality here refers to a task. Each candidate reaction is removed, and the task is tested again. ftINIT uses the result to decide which reactions must remain in an extraction regardless of their expression score. +Essentiality here refers to a task. Each candidate reaction is removed, and the task is tested again. ftINIT uses the result to determine which reactions must remain in an extraction regardless of their expression score. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB diff --git a/docs/installation/data-and-binaries.md b/docs/installation/data-and-binaries.md index 64df86f..7ebd598 100644 --- a/docs/installation/data-and-binaries.md +++ b/docs/installation/data-and-binaries.md @@ -1,6 +1,6 @@ # Download data and binaries -Neither toolbox ships the large files that it needs. The KEGG reference data, the libraries of profile hidden Markov models (HMMs) and the executables of BLAST+, DIAMOND and HMMER are fetched on first use from a shared, checksummed release and cached locally. The sections below describe what is fetched, where it is kept and how each step is overridden. +Neither toolbox includes the large files that it needs. The KEGG reference data, the libraries of profile hidden Markov models (HMMs) and the executables of BLAST+, DIAMOND and HMMER are fetched on first use from a shared, checksummed release and cached locally. The sections below describe what is fetched, where it is kept and how each step is overridden. Both toolboxes read from the same [`toolbox-assets`](https://github.com/CompMetEng/toolbox-assets) repository, so RAVEN and raven-toolbox download the same files. @@ -102,7 +102,7 @@ For data artefacts, an explicit directory replaces the cache. `get_kegg_model_fo ## Platform support -Every tool is invoked as a subprocess, so the availability of a native build for the platform decides the support. The bundles in `toolbox-assets` are built for Linux on x86-64, macOS on Apple silicon (arm64) and Windows on x86-64. Intel Macs and Linux on arm64 have no bundle, and the table applies to the three bundle platforms. +Every tool is invoked as a subprocess, so the availability of a native build for the platform determines the support. The bundles in `toolbox-assets` are built for Linux on x86-64, macOS on Apple silicon (arm64) and Windows on x86-64. Intel Macs and Linux on arm64 have no bundle, and the table applies to the three bundle platforms. | Tool | Linux | macOS | Windows | |---|---|---|---| diff --git a/docs/installation/index.md b/docs/installation/index.md index b989fa6..7050259 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,6 +1,6 @@ # Installation -RAVEN is available as a MATLAB toolbox and as the Python package raven-toolbox. Both build models for the same workflows, some algorithms differ between them ([Tuned parameter defaults](../tuned-parameters.md)), and the workflow decides which to use. +RAVEN is available as a MATLAB toolbox and as the Python package raven-toolbox. Both build models for the same workflows, some algorithms differ between them ([Tuned parameter defaults](../tuned-parameters.md)), and the workflow determines which to use. ::::{grid} 1 2 2 2 diff --git a/docs/installation/raven.md b/docs/installation/raven.md index bd71122..01c3aee 100644 --- a/docs/installation/raven.md +++ b/docs/installation/raven.md @@ -66,7 +66,7 @@ The installation runs from within MATLAB and needs no separate download. The ins 2. Search for RAVEN Toolbox and select Add, then Add to MATLAB. 3. [Verify the installation](#verification). -When MATLAB does not pick up the toolbox after step 2, `matlab.addons.enableAddon("RAVEN")` enables it. +When MATLAB does not load the toolbox after step 2, `matlab.addons.enableAddon("RAVEN")` enables it. ::: :::{tab-item} {octicon}`download;1em` Release download diff --git a/docs/installation/updating-kegg-assets.md b/docs/installation/updating-kegg-assets.md index 25c22f8..dc515ea 100644 --- a/docs/installation/updating-kegg-assets.md +++ b/docs/installation/updating-kegg-assets.md @@ -8,7 +8,7 @@ The documentation build does not run these commands. The download needs a KEGG s ## Assets of one release -A release has the name `kegg`, with `N` the KEGG release number, and four assets that carry the name as a prefix. +A release has the name `kegg`, with `N` the KEGG release number, and four assets that have the name as a prefix. | Asset | Content | |---|---| @@ -91,7 +91,7 @@ python scripts/make_registry_snippet.py sync python scripts/publish_to_toolbox_assets.py release --tag manifest-v4 data/manifest.json ``` -The first command computes the URL, the SHA-256 sum and the size of each asset and writes them to the manifest. The second regenerates the baked registry of raven-toolbox from the manifest. The third publishes the manifest as a new snapshot. The number of the snapshot is the next number after the newest `manifest-v` release in `toolbox-assets`. +The first command computes the URL, the SHA-256 sum and the size of each asset and writes them to the manifest. The second regenerates the registry that raven-toolbox includes from the manifest. The third publishes the manifest as a new snapshot. The number of the snapshot is the next number after the newest `manifest-v` release in `toolbox-assets`. ### 6. Point the toolboxes to the new release diff --git a/docs/parameter-tuning/benchmarks.md b/docs/parameter-tuning/benchmarks.md index c81241d..8e371a4 100644 --- a/docs/parameter-tuning/benchmarks.md +++ b/docs/parameter-tuning/benchmarks.md @@ -30,7 +30,7 @@ The default run contains 19 noise tracks. All are knockdown targets with a stand ### `remove_genes` -The `remove_genes` benchmark ran on e_coli_core (95 reactions) from the cobrapy distribution, with the bounds as shipped, raven-toolbox commit `94f39407` and RAVEN commit `2d0630e3`. It deleted `b1779`, the only gene of GAPD (glyceraldehyde-3-phosphate dehydrogenase), with each setting of `blocked_reactions` in `remove_genes` and of `removeBlockedRxns` in `removeGenes` of RAVEN. The predicted growth is the optimal flux through the biomass reaction of the model, in h⁻¹. The unmodified model has 95 reactions and predicts a growth rate of 0.874 h⁻¹. Each call ran once. +The `remove_genes` benchmark ran on e_coli_core (95 reactions) from the cobrapy distribution, with the bounds of the distribution, raven-toolbox commit `94f39407` and RAVEN commit `2d0630e3`. It deleted `b1779`, the only gene of GAPD (glyceraldehyde-3-phosphate dehydrogenase), with each setting of `blocked_reactions` in `remove_genes` and of `removeBlockedRxns` in `removeGenes` of RAVEN. The predicted growth is the optimal flux through the biomass reaction of the model, in h⁻¹. The unmodified model has 95 reactions and predicts a growth rate of 0.874 h⁻¹. Each call ran once. ### `connect_blocked_reactions` @@ -82,9 +82,9 @@ Every swept value changes the target set. None of the added targets is a noise t | `removeGenes(model, genes, 'removeBlockedRxns', true)` | 94 | 0.000 | deleted | | unmodified model | 95 | 0.874 (MATLAB biomass flux 0.8739) | present | -`blocked_reactions` of `remove_genes` and `removeBlockedRxns` of `removeGenes` decide what happens to a reaction whose gene rule is emptied by a deletion. Both default settings keep such a reaction with bounds of zero, and the two gave the same model. After the deletion of `b1779` that model predicts no growth, because GAPD stays in the network without capacity to carry flux. With `"remove"` and with `removeBlockedRxns` true the model also predicted no growth. Both delete GAPD, which changes the number of reactions and the set of reaction identifiers. +`blocked_reactions` of `remove_genes` and `removeBlockedRxns` of `removeGenes` determine what happens to a reaction whose gene rule is emptied by a deletion. Both default settings keep such a reaction with bounds of zero, and the two gave the same model. After the deletion of `b1779` that model predicts no growth, because GAPD stays in the network without capacity to carry flux. With `"remove"` and with `removeBlockedRxns` true the model also predicted no growth. Both delete GAPD, which changes the number of reactions and the set of reaction identifiers. -The setting `"keep"` leaves GAPD with an empty gene rule and unchanged bounds, so the model predicted the growth of the unmodified model, 0.874 h⁻¹, although the only gene of GAPD was deleted. The default setting predicted no growth after the same deletion, so the growth predicted with `"keep"` is probably a false positive in this model (the bounds are those shipped with e_coli_core). The docstring of `remove_genes` states no use for `"keep"`. The documentation names the editing of gene annotations without changing the network as a use, and the code gives no source for that use. +The setting `"keep"` leaves GAPD with an empty gene rule and unchanged bounds, so the model predicted the growth of the unmodified model, 0.874 h⁻¹, although the only gene of GAPD was deleted. The default setting predicted no growth after the same deletion, so the growth predicted with `"keep"` is probably a false positive in this model (the bounds are those included with e_coli_core). The docstring of `remove_genes` states no use for `"keep"`. The documentation names the editing of gene annotations without changing the network as a use, and the code gives no source for that use. ### `connect_blocked_reactions` at four values of `threshold` diff --git a/docs/parameter-tuning/index.md b/docs/parameter-tuning/index.md index c4d211a..3deed64 100644 --- a/docs/parameter-tuning/index.md +++ b/docs/parameter-tuning/index.md @@ -12,7 +12,7 @@ The criteria apply in this order of priority: 1. Empirical correctness on real models. The function runs with each candidate default on at least one large model (yeast-GEM or Human-GEM) and one small model (iJO1366 or similar). The result is compared with a known answer: a published reconstruction, a flux distribution from the literature or a validated gene-essentiality set. The chosen default gives a result that is better than the other candidates or no worse. 2. Sensitivity envelope. The parameter is varied by ±1 order of magnitude, or by ±50 % for a value on a linear scale, and the change in the result is measured. When the result does not change across the range, the exact value matters little, and the documentation says so. When the result changes steeply, the default lies on a plateau between too loose and too tight, and the documentation gives the sensitivity profile. -3. Literature anchor. A numerical parameter of an algorithm matches the value in the original paper or in the most-cited open-source implementation (cobrapy, COBRA Toolbox). Agreement with the literature corroborates a value and does not decide it. +3. Literature anchor. A numerical parameter of an algorithm matches the value in the original paper or in the most-cited open-source implementation (cobrapy, COBRA Toolbox). Agreement with the literature corroborates a value and does not determine it. 4. Cross-implementation check. Where a raven-toolbox function ports a MATLAB RAVEN function, or the reverse, the documentation states the value of the other implementation. A difference is measured and is not assumed to be a bug in either implementation. 5. Alignment with user expectation. A default matches the value a user would supply without thinking about it, for example `verbose=True` for a long-running mixed-integer linear program (MILP) and `sort_ids=False` for an export that reads back unchanged. 6. Documented `None` behaviour. A default of `None` or empty is acceptable for an optional feature, and any change of algorithmic behaviour that follows from it is documented with the fallback. diff --git a/docs/parameter-tuning/studies/ftinit-determinism.md b/docs/parameter-tuning/studies/ftinit-determinism.md index ecb951e..ae65614 100644 --- a/docs/parameter-tuning/studies/ftinit-determinism.md +++ b/docs/parameter-tuning/studies/ftinit-determinism.md @@ -34,7 +34,7 @@ The unedited baseline build kept 1 of the 30 removed reactions and the unedited ## Set-up - **Model and data.** Human-GEM `v2.0.0-38`, Hart2015 DLD1 cell line, 57 essential tasks, series `1+1`. The `model/Human-GEM.yml` of that commit has 12877 reactions and 2848 genes. The preparation is the one of `estimateEssentialGenes.py` at that commit (removal of the drug, amino-acid-triplet and duplicate complex I reactions), followed by `prep_init_model` of raven-toolbox. This gives a reference model of 10141 reactions and a merged model of 6861 reactions that contains 206 task-essential reactions. In the merged model, chains of linked reactions are combined into one reaction. The preparation differs from the exported `raven_refModel.xml` of RAVEN, so absolute counts are not comparable to the [Human-GEM cell-type model validation against RAVEN](humangem-validation.md), which uses that export. -- **Steps.** Series `1+1` runs two extraction steps, counted from 1 in this study; the debug log counts from 0. Step 1 decides the reactions with a gene association. Step 2, the last step, adds the reactions without one and holds the reactions of step 1 on. +- **Steps.** Series `1+1` runs two extraction steps, counted from 1 in this study; the debug log counts from 0. Step 1 determines the reactions with a gene association. Step 2, the last step, adds the reactions without one and holds the reactions of step 1 on. - **Settings.** `big_m=100` (the default is 1000), `mip_gap_abs=10` and `time_limit=1800` s, the values of `estimateEssentialGenes.py` at that commit. A named series such as `1+1` ignores `mip_gap` and `mip_gap_abs`, which apply to a step without a run schedule. - **Escalation.** Each solve stops at a mixed-integer programming (MIP) gap, the distance between the objective of the best solution found and the bound of the solver on the optimum, either relative (divided by the objective) or absolute. Without `prove_abs_gap`, each step follows the run schedule of RAVEN, called the escalation in this study. The first run uses a relative gap of 0.0004. Each later run uses the larger of its relative gap and its absolute gap (10 or 20) divided by the objective, and the step stops as soon as the gap already reached meets the next target. The setting `time_limit` caps the limit of each run: step 1 has runs of 120 s and 1800 s, and the final step runs of 5 s, 120 s and 1800 s. - **`prove_abs_gap`.** Each step is one solve proven to that absolute gap. It has the 1800 s limit for the primary solve and for the two flux phases of `resolve_ties` (phases 2c and 2d), and half of it (`_TIE_BREAK_TIME_FRACTION = 0.5`) for its two on/off phases (phases 2a and 2b). The phases are defined in the section on the parameters. The task gap-fill uses a fixed 300 s per task in every setting. @@ -45,7 +45,7 @@ The unedited baseline build kept 1 of the 30 removed reactions and the unedited ## Degeneracy of the extraction MILP -The extraction mixed-integer linear program (MILP) has many optima of equal score. In the first step on Human-GEM and DLD1, 1547 merged reactions have a negative score, and these carry the 0/1 keep-or-drop variables. Of them, 98.3 % (1520) are in blocks of equal score. The largest block has 840 reactions at −5.0. The second has 420 reactions at −2.0, the default score of a reaction without gene association. Across the five Hart2015 cell lines it has 419 to 421 members, so the expression data change its size by at most 2 members. Many reaction subsets reach the same optimum, and the solver returns one of them. +The extraction mixed-integer linear program (MILP) has many optima of equal score. In the first step on Human-GEM and DLD1, 1547 merged reactions have a negative score, and these have the 0/1 keep-or-drop variables. Of them, 98.3 % (1520) are in blocks of equal score. The largest block has 840 reactions at −5.0. The second has 420 reactions at −2.0, the default score of a reaction without gene association. Across the five Hart2015 cell lines it has 419 to 421 members, so the expression data change its size by at most 2 members. Many reaction subsets reach the same optimum, and the solver returns one of them. The settings `Threads=1` and a fixed `Seed` make that choice close to reproducible on one machine, as shown by the two baseline builds at one seed differed by 2 reactions. Another seed can select another member of the tied set, or end the solve at another objective value within the gap and time limits. Both were seen in the first-step probe, and in either case the predicted essential genes change for reasons unrelated to the model or the data. Another Gurobi version or platform is expected to act the same way, which was not measured. @@ -141,7 +141,7 @@ The next table counts full builds (gap-fill included) with at least one unproven Each row counts all builds of its setting, including the edited build at 1.0 for `prove_abs_gap`. The step 2 logs cited are those of seeds 1234 and 7. -The warnings cover the adopted phases and the flux phases without a solution. A build without a warning can hold an unresolved tie-break (a dropped `phase2a-parsimony` or `phase2b-idrank`) or an unproven escalation, and the debug log is the record of what each solve reached. In the sweep, all 24 builds with `prove_abs_gap` raised at least one warning. A larger `time_limit` is the setting that can let the phases prove, and its effect was not measured. +The warnings cover the adopted phases and the flux phases without a solution. A build without a warning can hold an unresolved tie-break (a dropped `phase2a-parsimony` or `phase2b-idrank`) or an unproven escalation, and the debug log is the record of what each solve reached. In the sweep, all 24 builds with `prove_abs_gap` raised at least one warning. A larger `time_limit` is the setting that can allow the phases to prove, and its effect was not measured. ## Stability under a small template change diff --git a/docs/parameter-tuning/studies/init-solver-benchmark.md b/docs/parameter-tuning/studies/init-solver-benchmark.md index 823729b..56e66c7 100644 --- a/docs/parameter-tuning/studies/init-solver-benchmark.md +++ b/docs/parameter-tuning/studies/init-solver-benchmark.md @@ -22,7 +22,7 @@ The run log counts the steps from 0; the table counts them from 1. ## Gurobi -Gurobi completed in 92 s with the default big-M, which caps each reaction at 1000, and in 128 s with every cap at 100. The log of the `big_m=1000` run carries the warning `ftINIT step 1 hit the 900s time limit with an unproven MIP gap (0.0030)`, although the run took 92 s in total, so one scheduled solve stopped at a limit. The logged `step 1` is the second step. The warning prints the `time_limit` argument, not the limit of the run that stopped. The stopped run is a shorter scheduled run, inferred from the total time; the log does not say which. No step ran for the full 900 s. The calibration study reports 83 s for the same call with a limit of 600 s; it times `ftinit()` alone, while the 92 s here also include reading and scoring. The reaction sets of the two Gurobi runs share a Jaccard index of 0.981, with 140 differing reactions. +Gurobi completed in 92 s with the default big-M, which caps each reaction at 1000, and in 128 s with every cap at 100. The log of the `big_m=1000` run contains the warning `ftINIT step 1 hit the 900s time limit with an unproven MIP gap (0.0030)`, although the run took 92 s in total, so one scheduled solve stopped at a limit. The logged `step 1` is the second step. The warning prints the `time_limit` argument, not the limit of the run that stopped. The stopped run is a shorter scheduled run, inferred from the total time; the log does not say which. No step ran for the full 900 s. The calibration study reports 83 s for the same call with a limit of 600 s; it times `ftinit()` alone, while the 92 s here also include reading and scoring. The reaction sets of the two Gurobi runs share a Jaccard index of 0.981, with 140 differing reactions. ## GLPK diff --git a/docs/parameter-tuning/studies/kegg-hmm-cutoff-calibration.md b/docs/parameter-tuning/studies/kegg-hmm-cutoff-calibration.md index b0d30be..629196a 100644 --- a/docs/parameter-tuning/studies/kegg-hmm-cutoff-calibration.md +++ b/docs/parameter-tuning/studies/kegg-hmm-cutoff-calibration.md @@ -205,11 +205,11 @@ The setting `threads` in `run_hmmsearch` and `build_ko_hmm` defaults to every CP The setting `seq_identity` in `build_ko_hmm` is `0.9`. It is the identity at which CD-HIT collapses near-duplicate sequences within a KO before the HMM is built, and the clustering keeps a KO with many near-identical entries from giving an overfitted profile. It is the value that CD-HIT recommends for proteins and the default of `seqIdentity` in RAVEN 2.11.3. The value `seq_identity=-1` skips the clustering. The `getKEGGModelForOrganism` of RAVEN 3 uses prebuilt HMM libraries and has no clustering step. -The model-assembly flags decide which reactions a draft keeps, and they have the same defaults as in RAVEN. +The model-assembly flags determine which reactions a draft keeps, and they have the same defaults as in RAVEN. | Flag | Default | What it admits | Reason given for the default | |---|---|---|---| -| `keep_spontaneous` | `True` | Reactions marked spontaneous in KEGG, which carry no gene rule. | Excluding them breaks pathways that need them. | +| `keep_spontaneous` | `True` | Reactions marked spontaneous in KEGG, which have no gene rule. | Excluding them breaks pathways that need them. | | `keep_undefined_stoich` | `True` | Reactions with variable stoichiometry (`n` subunits), which cannot be mass-balanced as written. | Dropping them removes real chemistry from the draft. | | `keep_incomplete` | `True` | Reactions whose enzyme set is only partly known. | | | `keep_general` | `False` | Overview-map reactions that lump many specific steps into one. | Admitting them counts the same conversion twice. | diff --git a/docs/parameter-tuning/studies/sampling-convergence-calibration.md b/docs/parameter-tuning/studies/sampling-convergence-calibration.md index dbab9ed..3fb6f51 100644 --- a/docs/parameter-tuning/studies/sampling-convergence-calibration.md +++ b/docs/parameter-tuning/studies/sampling-convergence-calibration.md @@ -14,7 +14,7 @@ On e_coli_core, four chains of 300 samples agree at the R-hat threshold of 1.1 f - `thinning` is the number of steps between two stored samples. An ACHR chain with `n_samples` stored samples therefore takes `thinning × n_samples` steps after its warmup points, and a CHRR chain takes `warmup + thinning × n_samples` steps after the rounding. - `warmup` is the number of CHRR steps discarded before the first stored sample. `random_sampling` passes it to CHRR only, and the ACHR runs ignore it. - The lag-1 autocorrelation `ρ` is the correlation between consecutive stored samples of one chain. -- The effective sample size (ESS) is the number of independent samples that carry the same information as the correlated ones. Under the assumption that the chain is a first-order autoregressive process, `ESS = n × (1−ρ) / (1+ρ)` for `n` stored samples. +- The effective sample size (ESS) is the number of independent samples that contain the same information as the correlated ones. Under the assumption that the chain is a first-order autoregressive process, `ESS = n × (1−ρ) / (1+ρ)` for `n` stored samples. - The R-hat of a reaction (Gelman-Rubin statistic) compares the flux variance between chains with the variance within chains. With `m` chains of `n` samples, `W` the mean within-chain variance and `B/n` the variance of the chain means, `R-hat = sqrt(((n−1)/n × W + B/n) / W)`. R-hat is 1.0 when the chains agree and grows when the distribution of a chain depends on where it started. The script reports the share of reactions above 1.1 and above 1.01, the stricter of the two thresholds. ## Set-up @@ -170,7 +170,7 @@ One change outside the parameters was identified and not pursued: CHRR recompute Two settings of `method='random_objective'` differ from `randomSampling` of RAVEN in MATLAB on purpose. -The setting `replace_max_bound` (default `False`; `replaceBoundsWithInf` in MATLAB defaults to true) replaces the largest upper bound, the big-M value that stands for an unconstrained reaction, with infinity before sampling, and replaces the most negative lower bound, if it is below 0, with minus infinity. Models in the RAVEN convention use 1000 as the big-M for almost every reaction (4,083 of the 4,102 reactions of yeast-GEM). With `True`, the call fails after 9.6 s with `OptimizationError: Solver status is 'unbounded'`. A probe of 50 random objectives, drawn as the sampler draws them on the model with the bounds replaced, gave 49 optimal results and 1 unbounded result (one probe of 50 objectives). One unbounded objective stops all draws. The abort mechanism is read from the cobra code, where `Model.optimize` raises on the status `unbounded` (`raise_error=False` does not change this) and the retry loop of the sampler never sees the status. The sample at which the run aborted was not recorded. +The setting `replace_max_bound` (default `False`; `replaceBoundsWithInf` in MATLAB defaults to true) replaces the largest upper bound, the big-M value that stands for an unconstrained reaction, with infinity before sampling, and replaces the most negative lower bound, if it is below 0, with minus infinity. Models in the RAVEN convention use 1000 as the big-M for almost every reaction (4,083 of the 4,102 reactions of yeast-GEM). With `True`, the call fails after 9.6 s with `OptimizationError: Solver status is 'unbounded'`. A probe of 50 random objectives, drawn as the sampler draws them on the model with the bounds replaced, gave 49 optimal results and 1 unbounded result (one probe of 50 objectives). One unbounded objective stops all draws. The abort mechanism is read from the cobra code, where `Model.optimize` raises on the status `unbounded` (`raise_error=False` does not change this) and the retry loop of the sampler never receives the status. The sample at which the run aborted was not recorded. With `False`, 200 samples completed (68.2 s with 12 processes, including the loopless FVA). Counting a flux as at the bound when `|v| ≥ 1000 × (1 − 1e-9)`, the 200 × 4102 sample matrix (820,400 entries) had 54 entries at the bound (0.0066 %) in one run, with 15 samples containing at least one such reaction and 23 reactions (0.56 % of 4102) at the bound in at least one sample. A second run had 269 entries (0.033 %), 16 samples (8.0 %) and 32 reactions (0.78 %). The share of reactions at the bound was 0.56 % in one run and 0.78 % in the other, and the share of entries is 0.0066 to 0.033 %. diff --git a/docs/protocol/index.md b/docs/protocol/index.md index c494852..8dcf84c 100644 --- a/docs/protocol/index.md +++ b/docs/protocol/index.md @@ -4,7 +4,7 @@ The protocol is a complete homology-based reconstruction of `hanpo-GEM`, from th The protocol complements the [user guide](../guide/index.md). Each page of the guide covers one operation, and the protocol covers a whole reconstruction in order. -The guide covers MATLAB and Python, and the protocol steps use MATLAB. The documentation build does not run its commands, unlike the guide pages. Several steps take hours and need data that this site does not ship. +The guide covers MATLAB and Python, and the protocol steps use MATLAB. The documentation build does not run its commands, unlike the guide pages. Several steps take hours and need data that this site does not include. ## Protocol steps diff --git a/docs/protocol/manual-curation.md b/docs/protocol/manual-curation.md index 8e2f7e8..53773db 100644 --- a/docs/protocol/manual-curation.md +++ b/docs/protocol/manual-curation.md @@ -4,7 +4,7 @@ A draft GEM needs manual curation to become a high-quality model. Curation corre ## Replacing template genes with target homologs -Gap-filling adds reactions from the templates without a homology search for the associated genes, so the draft contains *S. cerevisiae* and *R. toruloides* genes that should be replaced by *H. polymorpha* homologs. List the reactions that carry an *R. toruloides* gene: +Gap-filling adds reactions from the templates without a homology search for the associated genes, so the draft contains *S. cerevisiae* and *R. toruloides* genes that should be replaced by *H. polymorpha* homologs. List the reactions that have an *R. toruloides* gene: ```matlab rhtoRxns = find(contains(model.grRules, 'RHTO')); diff --git a/docs/protocol/reconstruction.md b/docs/protocol/reconstruction.md index 89e4a72..a584b17 100644 --- a/docs/protocol/reconstruction.md +++ b/docs/protocol/reconstruction.md @@ -16,7 +16,7 @@ Measurable rates, such as the carbon uptake, constrain the model. Flux balance a ## The homology-based approach -RAVEN creates a draft GEM for an organism with well-curated models of phylogenetically related organisms as templates. The homology between the protein sequences of the two organisms, determined by bidirectional BLAST, decides whether a reaction of a template is included in the new model. +RAVEN creates a draft GEM for an organism with well-curated models of phylogenetically related organisms as templates. The homology between the protein sequences of the two organisms, determined by bidirectional BLAST, determines whether a reaction of a template is included in the new model. The protocol reconstructs a draft model for the industrially relevant methylotrophic yeast *Hansenula polymorpha* (also named *Ogataea polymorpha*), which has no published high-quality GEM. Two highly curated yeast models are the templates: diff --git a/docs/raven3-migration/backward-incompatible.md b/docs/raven3-migration/backward-incompatible.md index 0603d8a..a103eaf 100644 --- a/docs/raven3-migration/backward-incompatible.md +++ b/docs/raven3-migration/backward-incompatible.md @@ -65,14 +65,14 @@ The same call on the same model gives a different output. Positions count all ar | `simplifyModel` | Keeps the boundary constraint (`b`) of a task on a metabolite without reactions. RAVEN 2.11.3 removed such metabolites, so the task check can give a different result in RAVEN 3 (not run; see [Gap-filling and context-specific model extraction](#ftinit)) | | `simplifyModel` with `constrainReversible` on a model without a reversible reaction | The step changes nothing. RAVEN 2 raised an error, because `getAllowedBounds` takes an empty reaction list as all reactions (the error is taken from the changelog and was not reproduced) | | `ftINITInternalAlg` | With `allowExcretion` true, the metabolite balance is constrained to `S*v >= 0`. RAVEN 2 had the sense of the constraint inverted | -| `ravenCobraWrapper` | The conversion of `grRules` to the COBRA `rules` field handles gene IDs that contain regular-expression metacharacters. RAVEN 2 did not escape them (see [RAVEN⇄COBRA interoperability](#raven-cobra-interoperability)) | +| `ravenCobraWrapper` | The conversion of `grRules` to the COBRA `rules` field works on gene IDs that contain regular-expression metacharacters. RAVEN 2 did not escape them (see [RAVEN⇄COBRA interoperability](#raven-cobra-interoperability)) | | `mergeCompartments` | The merged metabolite is the copy in compartment `s` or, failing that, the copy whose ID sorts first in character code order, with every field of that copy. RAVEN 2 kept the copy that came first in `model.mets` | The changelog of RAVEN 3 lists a bug fix for each of `permuteModel`, `optimizeProb`, `getFluxZ`, `convertToIrrev`, `replaceMets`, `setExchangeBounds`, `fitParameters` and `guessComposition`. It lists further fixes that can change results, for example for `mergeLinear`, `mergeModels`, `closeModel`, `addTransport`, `getExchangeRxns`, `removeLowScoreGenes`, `getMinNrFluxes`, `reporterMetabolites`, `getElementalBalance`, `checkModelStruct` and `deleteUnusedGenes`. The effect of these fixes on results was not checked. ## Changes to error and warning identifiers -RAVEN 2 raised its errors through `dispEM` with an empty identifier (`MException('', ...)`), so no RAVEN 2 script could catch an error by `err.identifier`. RAVEN 3 replaces `dispEM` with `error()` and `warning()` calls. Not every call carries an identifier, and a script can match on `err.identifier` for the calls that do. `RAVEN:badInput` appears in 220 lines and `RAVEN:warning` in 63 lines of `src/` and the root `.m` files (non-comment lines that contain the identifier). Further identifiers in the `RAVEN:` namespace are `RAVEN:modelError`, `RAVEN:badGrRule`, `RAVEN:infeasibleModel`, `RAVEN:infeasible`, `RAVEN:sampling`, `RAVEN:grRuleTooComplex`, `RAVEN:deprecated`, `RAVEN:legacyMethod`, `RAVEN:notMainBranch`, `RAVEN:glpkMILP`, `RAVEN:fetchToolboxAsset:unverified`, `RAVEN:fetchToolboxAsset:checksum`, `RAVEN:fetchToolboxAsset:manifest`, `RAVEN:runSuppOrth:supportLv`, `RAVEN:runSuppOrth:failed`, `RAVEN:runSuppOrth:notFound` and `RAVEN:hitsFromSuppOrth:unmappedProteins`. Identifiers in other namespaces include `parseRAVENargs:tooManyArgs`, `parseRAVENargs:noSpec`, `getPhylDist:noData`, `renameModelGenes:*`, `setGAM:*` and `parseYAML:*`. The list is not exhaustive. +RAVEN 2 raised its errors through `dispEM` with an empty identifier (`MException('', ...)`), so no RAVEN 2 script could catch an error by `err.identifier`. RAVEN 3 replaces `dispEM` with `error()` and `warning()` calls. Not every call has an identifier, and a script can match on `err.identifier` for the calls that do. `RAVEN:badInput` appears in 220 lines and `RAVEN:warning` in 63 lines of `src/` and the root `.m` files (non-comment lines that contain the identifier). Further identifiers in the `RAVEN:` namespace are `RAVEN:modelError`, `RAVEN:badGrRule`, `RAVEN:infeasibleModel`, `RAVEN:infeasible`, `RAVEN:sampling`, `RAVEN:grRuleTooComplex`, `RAVEN:deprecated`, `RAVEN:legacyMethod`, `RAVEN:notMainBranch`, `RAVEN:glpkMILP`, `RAVEN:fetchToolboxAsset:unverified`, `RAVEN:fetchToolboxAsset:checksum`, `RAVEN:fetchToolboxAsset:manifest`, `RAVEN:runSuppOrth:supportLv`, `RAVEN:runSuppOrth:failed`, `RAVEN:runSuppOrth:notFound` and `RAVEN:hitsFromSuppOrth:unmappedProteins`. Identifiers in other namespaces include `parseRAVENargs:tooManyArgs`, `parseRAVENargs:noSpec`, `getPhylDist:noData`, `renameModelGenes:*`, `setGAM:*` and `parseYAML:*`. The list is not exhaustive. Whether `try/catch` blocks that match on message text match was not compared message by message. diff --git a/docs/raven3-migration/new-and-environment.md b/docs/raven3-migration/new-and-environment.md index 86023db..6ce2334 100644 --- a/docs/raven3-migration/new-and-environment.md +++ b/docs/raven3-migration/new-and-environment.md @@ -1,6 +1,6 @@ # New functionality, dependencies and error handling -RAVEN 3 changes gap-filling and the extraction of context-specific models with `ftINIT`, adds functions, depends on fewer MATLAB toolboxes, and handles errors in a different way. +RAVEN 3 changes gap-filling and the extraction of context-specific models with `ftINIT`, adds functions, depends on fewer MATLAB toolboxes, and reports errors in a different way. (ftinit)= ## Gap-filling and context-specific model extraction @@ -92,7 +92,7 @@ The function documentation of `sampleCHRR` states that the polytope is rounded b | Parallel Computing Toolbox | Optional. The `parfor` loops, for example in `getAllowedBounds` and `randomSampling`, run serially without it | Optional. `parallelWorkersRAVEN` returns 0 workers when `runParallel` is false, which runs the `parfor` loops as plain loops | | Excel I/O | Bundled Apache POI (Java) | OOXML writer without dependencies | | LP and MILP solver | Required: bundled `glpk`, or Gurobi, SCIP or COBRA | Unchanged | -| External binaries | Committed to the repository (BLAST+, DIAMOND, HMMER) and available offline after cloning | Fetched on first use as ZIP files per platform into `src/external/`. For air-gapped installs the workflow `.github/workflows/release-bundle.yml` builds `RAVEN--full.zip` with the binaries of all platforms and attaches it to a published release. Whether a given release carries it was not checked | +| External binaries | Committed to the repository (BLAST+, DIAMOND, HMMER) and available offline after cloning | Fetched on first use as ZIP files per platform into `src/external/`. For air-gapped installs the workflow `.github/workflows/release-bundle.yml` builds `RAVEN--full.zip` with the binaries of all platforms and attaches it to a published release. Whether a given release includes it was not checked | | KEGG HMM libraries and reference data | Manual download or local build | Fetched on first use and cached | | Installation self-check | `installation/checkInstallation.m` runs `importExportTests`, `solverTests` and the test files of BLAST+, DIAMOND, HMMER, CD-HIT and MAFFT to fill its table of passed and failed tests | `checkRaven` in the repository root imports `empty.xml`, exports SBML, imports and exports YAML, exports Excel, solves a two-reaction LP per solver and downloads missing binaries without a prompt. `checkInstallation` forwards to it (see [Renamed and merged functions](#renamed-merged-and-consolidated-functions)) | @@ -108,6 +108,6 @@ KEGG data, binaries and the checksum manifest come from releases of `toolbox-ass ## Error and warning handling -RAVEN 3 raises errors and issues warnings with `error()` and `warning()`. Outside `src/external` there are 411 `error` calls, counted as lines that contain `error(` and do not start with a comment. Of these, 301 carry an identifier, and 242 of those are in the `RAVEN:*` namespace. By the same rule there are 94 `warning` calls, of which 79 carry an identifier and 72 are in the `RAVEN:*` namespace. Whether the message texts of the RAVEN 2 checks are preserved was not checked. A `try/catch` block that matches message text can be replaced by a match on the identifier where one exists. [Backward-incompatible changes](#backward-incompatible-changes) describes the replacement of `dispEM`, and [Removed functionality](#removed-functionality) names the helper `utils/ravenList.m`. +RAVEN 3 raises errors and issues warnings with `error()` and `warning()`. Outside `src/external` there are 411 `error` calls, counted as lines that contain `error(` and do not start with a comment. Of these, 301 have an identifier, and 242 of those are in the `RAVEN:*` namespace. By the same rule there are 94 `warning` calls, of which 79 have an identifier and 72 are in the `RAVEN:*` namespace. Whether the message texts of the RAVEN 2 checks are preserved was not checked. A `try/catch` block that matches message text can be replaced by a match on the identifier where one exists. [Backward-incompatible changes](#backward-incompatible-changes) describes the replacement of `dispEM`, and [Removed functionality](#removed-functionality) names the helper `utils/ravenList.m`. The call `issues = checkModelStruct(model)` returns a structure array of the problems (`category`, `target` and `message`) for programmatic model QC and raises no error. Without an output argument the function raises errors or issues warnings as in RAVEN 2. The options `throwErrors` and `trimWarnings`, which are positional in RAVEN 2, can also be given as name-value pairs. diff --git a/docs/raven3-vs-raven-toolbox/same-function-different-answer.md b/docs/raven3-vs-raven-toolbox/same-function-different-answer.md index 818bcb5..eb71cd4 100644 --- a/docs/raven3-vs-raven-toolbox/same-function-different-answer.md +++ b/docs/raven3-vs-raven-toolbox/same-function-different-answer.md @@ -44,7 +44,7 @@ Four measurements quantify the differences. Compare such outputs by the overlap of the reaction sets, for example the Jaccard index. -The option `resolveTies` of the `ftINIT` of RAVEN and `resolve_ties` of the `ftinit` of raven-toolbox are off by default in both. When on, each step keeps the score optimum and picks among the tied solutions in four phases, in this order: the fewest kept removable reactions, the lowest summed ID rank of those, the least total absolute flux and the least backward flux weighted by ID rank. The last step of `ftINIT` skips the two flux phases. A step that stops at its time limit keeps the answer of the solver. +The option `resolveTies` of the `ftINIT` of RAVEN and `resolve_ties` of the `ftinit` of raven-toolbox are off by default in both. When on, each step keeps the score optimum and selects among the tied solutions in four phases, in this order: the fewest kept removable reactions, the lowest summed ID rank of those, the least total absolute flux and the least backward flux weighted by ID rank. The last step of `ftINIT` skips the two flux phases. A step that stops at its time limit keeps the answer of the solver. In raven-toolbox, runs with `resolve_ties` at the same score optimum returned identical solutions across seeds. The primary solve can end at a different objective value for a different seed, within the gap and time limits, so the final reaction sets can differ. This was not measured for RAVEN. Without `resolveTies` or `resolve_ties`, the ftINIT MILP can return any of the tied optima. @@ -54,7 +54,7 @@ The functions `getElementalBalance` in RAVEN and `get_elemental_balance` in rave The function `getElementalBalance` returns the numeric field `balanceStructure.balanceStatus` per reaction: 1 for balanced, 0 for unbalanced, -1 for missing information (no formula, or a reaction without metabolites) and -2 for a formula that cannot be parsed. The function `get_elemental_balance` returns the strings `balanced`, `unbalanced` and `unknown`. It reports `unknown` for a missing formula, for a formula that cannot be parsed and for a reaction without metabolites, so the codes -1 and -2 of RAVEN are one result in raven-toolbox. -The two parsers handle some formulas differently, so the results differ for some reactions. +The two parsers parse some formulas differently, so the results differ for some reactions. - A polymer formula such as `(C5H8)n` is counted with n equal to 1 in RAVEN. raven-toolbox reports `unknown`. - RAVEN uses the field `inchis` when `metFormulas` is absent. raven-toolbox does not. diff --git a/docs/raven3-vs-raven-toolbox/what-each-has.md b/docs/raven3-vs-raven-toolbox/what-each-has.md index 2b027b2..4f0bf70 100644 --- a/docs/raven3-vs-raven-toolbox/what-each-has.md +++ b/docs/raven3-vs-raven-toolbox/what-each-has.md @@ -14,7 +14,7 @@ cobrapy provides flux balance analysis (FBA), flux variability analysis (FVA), k raven-toolbox builds the KEGG reference artefacts. It parses a KEGG release into tables of reactions and compounds, assembles the reference model with `build_reference_model`, builds the FASTA sets and HMM libraries per KEGG Orthology (KO) entry, and derives the phylogenetic distance matrix. The download of a KEGG release requires a KEGG FTP subscription, and the artefacts can be rebuilt from a specified KEGG release. -RAVEN loads published artefacts and does not produce them. The function `buildGlobalKEGGModel` joins a downloaded bundle onto the reference model, and the phylogenetic distance matrix is a file shipped with RAVEN (`keggPhylDist.mat`). In the mapping, `getModelFromKEGG` corresponds to `build_reference_model`, which loads in RAVEN and builds in raven-toolbox. +RAVEN loads published artefacts and does not produce them. The function `buildGlobalKEGGModel` joins a downloaded bundle onto the reference model, and the phylogenetic distance matrix is a file included with RAVEN (`keggPhylDist.mat`). In the mapping, `getModelFromKEGG` corresponds to `build_reference_model`, which loads in RAVEN and builds in raven-toolbox. ### Checksum registry for binaries and data diff --git a/docs/tuned-parameters.md b/docs/tuned-parameters.md index 0ea2f96..6bf446c 100644 --- a/docs/tuned-parameters.md +++ b/docs/tuned-parameters.md @@ -18,7 +18,7 @@ RAVEN MATLAB: `randomSampling` (`method='achr'|'chrr'|'randomObjective'`), `samp | `thinning` | `100` | Upstream convention (cobrapy's own ACHR default). Measured insufficient at genome scale: on yeast-GEM one ACHR chain (seed 0) had an effective sample size (ESS) of about 10 from 300 stored samples (9.9 to 63.1 over four seeds), and 4 chains disagreed (median Gelman-Rubin R-hat 1.1020, 50.7 % of scored reactions above 1.1). At `thinning=500` the lag-1 autocorrelation of one chain was 0.825 for seed 0 (0.644 to 0.825 over four seeds, ESS 28.8 to 64.9). Agreement between chains was tested at one other setting, `thinning=300` with `n_samples=100` (the same 30,000 steps per chain), and did not improve. See [Flux sampling convergence and settings](parameter-tuning/studies/sampling-convergence-calibration.md). | | `warmup` | `1000` | Used by `method='chrr'` (the steps discarded before the first stored sample); the ACHR sampler of cobrapy has no such parameter. Same as `nBurnin` of RAVEN's `sampleCHRR` and `randomSampling`, which also applies to CHRR. Not measured. | | `n_objectives` | `2` | Literature: [Bordel et al. 2010](https://doi.org/10.1371/journal.pcbi.1000859). | -| `replace_max_bound` | `False` | Used by `method='random_objective'`. With `True` the run fails with an unbounded solver status: one probe of 50 objectives gave 49 optimal results and 1 unbounded result. From the cobra code, one unbounded objective stops all draws; the sample at which the run aborted was not recorded. With `False`, 200 samples completed. Kept different from MATLAB on purpose. Whether MATLAB's own solver path handles `True` was not tested. | +| `replace_max_bound` | `False` | Used by `method='random_objective'`. With `True` the run fails with an unbounded solver status: one probe of 50 objectives gave 49 optimal results and 1 unbounded result. From the cobra code, one unbounded objective stops all draws; the sample at which the run aborted was not recorded. With `False`, 200 samples completed. Kept different from MATLAB on purpose. Whether MATLAB's own solver path works with `True` was not tested. | | `loopless_good_reactions` | `True` | Loopless FVA excludes reactions that take part in infeasible cycles, at higher cost; the alternative fixed-threshold (±999) heuristic also excludes reactions that legitimately reach capacity. The loopless technique is implemented in Python; porting it is a larger project than changing a default. | | `n_samples`, `seed`, `min_flux`, `max_attempts` | `1000`, `None`, `False`, `100` | Same in both implementations or no evidence favoured a different value. | | `flux_tol` (in `find_good_reactions`) | `1e-9` | Python helper (supports target selection of the random-objective method); no cross-implementation comparison. | @@ -172,7 +172,7 @@ The INIT parameters `mip_gap` and `time_limit` of `run_init` and `run_ftinit` ar | Parameter | Python | MATLAB | Why | |---|---|---|---| -| `random_sampling.replace_max_bound` | `False` | `True` | With every bound of 1000 replaced by infinity, the random-objective LP becomes unbounded, because the objective can grow without limit through any reaction that is then unconstrained ([Flux sampling convergence and settings](parameter-tuning/studies/sampling-convergence-calibration.md) gives this mechanism, read from the cobra code; the run with `True` failed with an unbounded status, the sample of the abort was not recorded, and the run with `False` completed 200 samples). Whether MATLAB's own solver path handles `True` was not tested. | +| `random_sampling.replace_max_bound` | `False` | `True` | With every bound of 1000 replaced by infinity, the random-objective LP becomes unbounded, because the objective can grow without limit through any reaction that is then unconstrained ([Flux sampling convergence and settings](parameter-tuning/studies/sampling-convergence-calibration.md) gives this mechanism, read from the cobra code; the run with `True` failed with an unbounded status, the sample of the abort was not recorded, and the run with `False` completed 200 samples). Whether MATLAB's own solver path works with `True` was not tested. | | `random_sampling.loopless_good_reactions` | `True` (loopless FVA) | heuristic (exclude FVA ≥ 0.999 times the loop bound, 999 for a bound of 1000) | The two are different techniques. Loopless FVA excludes reactions that take part in infeasible cycles, and the MATLAB heuristic also excludes reactions that legitimately reach capacity. Porting the loopless technique to MATLAB is a larger project than changing a default. | | `merge_models.match_by` | `'name'` | `'metNames'` | Same semantic field (metabolite display name) under a different field name, which results from the cobrapy and COBRA Toolbox schemas; the field name is not tunable. | | `run_diamond.evalue` | `1e-3` | `1e-3` (implicit) | Both agree at `1e-3`, matching the DIAMOND default. `getDiamond` passes no `-evalue` flag, so it inherits the DIAMOND default and does not follow the explicit `1e-4` of `getBlast`. `run_blast` and `run_diamond` deliberately stay unpaired: each follows the MATLAB call of its own aligner. | diff --git a/docs/tutorials/tutorial1.md b/docs/tutorials/tutorial1.md index ed6af5d..9581892 100644 --- a/docs/tutorials/tutorial1.md +++ b/docs/tutorials/tutorial1.md @@ -21,7 +21,7 @@ The model contains 1632 reactions, 1395 metabolites and 1006 genes. ### 2. Simplifying the model -Mass balancing is done around the internal metabolites. Remove the unconstrained (boundary) metabolites that let the system take up or excrete compounds before simulation. `simplifyModel` makes models smaller, for example by grouping linear reactions and by deleting reactions that cannot carry flux. The call below deletes the unconstrained metabolites, the reactions constrained to zero flux (mainly the uptake of non-standard carbon sources) and the dead-end reactions, and leaves linear reactions ungrouped. +Mass balancing is done around the internal metabolites. Remove the unconstrained (boundary) metabolites that allow the system to take up or excrete compounds before simulation. `simplifyModel` makes models smaller, for example by grouping linear reactions and by deleting reactions that cannot carry flux. The call below deletes the unconstrained metabolites, the reactions constrained to zero flux (mainly the uptake of non-standard carbon sources) and the dead-end reactions, and leaves linear reactions ungrouped. ```matlab model = simplifyModel(model, true, false, true, true); diff --git a/docs/yaml-format.md b/docs/yaml-format.md index 3154667..f0d36b2 100644 --- a/docs/yaml-format.md +++ b/docs/yaml-format.md @@ -87,7 +87,7 @@ Three structural rules apply to the field-by-field description: | Key | Required | Source | Notes | |-----|----------|--------|-------| -| `metaData` | optional | RAVEN | Provenance block with `id`, `name`, `version`, `date`, `taxonomy`, optionally `givenName`, `familyName`, `email`, `organization`, `note` and `sourceUrl`, and `defaultLB` and `defaultUB`. cobrapy ignores the block, which carries no semantics of the core model. | +| `metaData` | optional | RAVEN | Provenance block with `id`, `name`, `version`, `date`, `taxonomy`, optionally `givenName`, `familyName`, `email`, `organization`, `note` and `sourceUrl`, and `defaultLB` and `defaultUB`. cobrapy ignores the block, which has no semantics in the core model. | | `metabolites` | yes | cobra core | Ordered list of `- !!omap` entries. | | `reactions` | yes | cobra core | Ordered list of `- !!omap` entries. | | `genes` | yes | cobra core | Ordered list; `genes: []` for a model without genes. | @@ -198,7 +198,7 @@ Empty names (`name: ''`) are not written, as in RAVEN MATLAB. - m: mitochondrion ``` -The block is an `!!omap` of `: ` pairs. Compartments carry no MIRIAM annotations of their own in the format. +The block is an `!!omap` of `: ` pairs. Compartments have no MIRIAM annotations of their own in the format. --- @@ -229,7 +229,7 @@ The block holds provenance. cobrapy ignores it. raven-toolbox keeps the verbatim ## GECKO sections -Enzyme-constrained models carry the EC layer in three additional top-level keys: +Enzyme-constrained models contain the EC layer in three additional top-level keys: ```yaml - gecko_light: false # true for the "light" formulation @@ -294,7 +294,7 @@ The characters `[`, `]`, `{` and `}` inside a value do not trigger quoting. In a double-quoted string, `\` and `"` are escaped. Other characters, including Unicode and newlines where the model permits them, are passed through. -The reader of raven-toolbox repairs three quoted shapes that are not valid YAML: `""text""`, a double-quoted scalar with an unescaped inner quote (`"a "b" c"`), and a single-quoted scalar with an inner apostrophe (`'it's'`). The values are `"text"`, `a "b" c` and `it's`, as `readYAMLmodel` reads them. The repair runs when the strict parse fails, and it does not handle a comment after the closing quote. +The reader of raven-toolbox repairs three quoted shapes that are not valid YAML: `""text""`, a double-quoted scalar with an unescaped inner quote (`"a "b" c"`), and a single-quoted scalar with an inner apostrophe (`'it's'`). The values are `"text"`, `a "b" c` and `it's`, as `readYAMLmodel` reads them. The repair runs when the strict parse fails, and it does not repair a comment after the closing quote. ---