From 5a75c188461f4d4bbcd98fd7d531bd1615873358 Mon Sep 17 00:00:00 2001 From: Eduard Kerkhoven Date: Mon, 8 Jun 2026 00:40:41 +0200 Subject: [PATCH] docs: update RAVEN cross-references for the post-reorg folder layout RAVEN moved its functions out of the core/ catch-all into purpose-based top-level folders (SysBioChalmers/RAVEN#614). Repoint every RAVEN file path in the cross-reference docs (IMPROVEMENTS.md, docs/reference/matlab_raven_backports.md): - FSEOF / randomSampling / reporterMetabolites -> analysis/ - parseTaskList / checkTasks -> tasks/ - fillGaps -> gapfilling/ - addRxns / changeRxns / standardizeGrRules -> manipulation/ - getIndexes / checkModelStruct / getElementalBalance -> queries/ - getModelFromHomology -> reconstruction/homology/ - getKEGGModelForOrganism -> reconstruction/kegg/ - runINIT / ftINIT -> INIT/ Also corrects references that were stale even before the reorg (getKEGGModelForOrganism was in external/kegg/) and points the proposed GPR-lint back-port findPotentialErrors at manipulation/, alongside standardizeGrRules. Doc-only: raven-python's module layout already matches RAVEN's new structure (it was the template the reorg mirrored), so no code changes are needed. --- IMPROVEMENTS.md | 20 ++++++++++---------- docs/reference/matlab_raven_backports.md | 24 ++++++++++++------------ 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index 825d551..9fa9096 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -103,7 +103,7 @@ and `taxonomy.py` (3b.3). Maintainer-side, build-time tooling (PLAN.md §2.3b). ## FSEOF (Phase 5 — implemented, redesigned) -RAVEN `core/FSEOF.m` → `analysis/fseof.py` (`fseof`). User was unhappy with RAVEN's +RAVEN `analysis/FSEOF.m` → `analysis/fseof.py` (`fseof`). User was unhappy with RAVEN's output; redesigned substantially. | # | Cat | Target | Status | Improvement | @@ -115,7 +115,7 @@ output; redesigned substantially. ## randomSampling (Phase 5 — implemented) -RAVEN `core/randomSampling.m` → `analysis/sampling.py` (`random_sampling`). The +RAVEN `analysis/randomSampling.m` → `analysis/sampling.py` (`random_sampling`). The random-objective / extreme-point method of Bordel et al. (2010) — **not** what `cobra.sampling` (OptGP/ACHR) does (those draw a near-uniform MCMC sample of the polytope interior), so it is a genuine addition, and it was wrongly listed as @@ -131,7 +131,7 @@ combination of reactions. ## reporterMetabolites (Phase 5 — implemented) -RAVEN `core/reporterMetabolites.m` → `analysis/reporter.py` (`reporter_metabolites`). +RAVEN `analysis/reporterMetabolites.m` → `analysis/reporter.py` (`reporter_metabolites`). | # | Cat | Target | Status | Improvement | |---|---|---|---|---| @@ -170,7 +170,7 @@ RAVEN `INIT/ftINITInternalAlg.m` (+ orchestration) → `init/ftinit.py` (`run_ft ## parseTaskList / checkTasks (Phase 4a — implemented) -RAVEN `core/parseTaskList.m` + `core/checkTasks.m` → `tasks/tasklist.py` + `tasks/check.py`. +RAVEN `tasks/parseTaskList.m` + `tasks/checkTasks.m` → `tasks/tasklist.py` + `tasks/check.py`. | # | Cat | Target | Status | Improvement | |---|---|---|---|---| @@ -180,7 +180,7 @@ RAVEN `core/parseTaskList.m` + `core/checkTasks.m` → `tasks/tasklist.py` + `ta ## fillGaps (Phase 4b — implemented) -RAVEN `core/fillGaps.m`. Only the **connectivity** mode is ported, as +RAVEN `gapfilling/fillGaps.m`. Only the **connectivity** mode is ported, as `connect_blocked_reactions` ([gapfilling/fill.py](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/gapfilling/fill.py)) — MILP via cobra/optlang (GLPK). RAVEN's other mode (fill to make the objective feasible) is `cobra.flux_analysis.gapfill` and is **cheatsheeted, not re-wrapped** (PLAN §1). @@ -192,7 +192,7 @@ is `cobra.flux_analysis.gapfill` and is **cheatsheeted, not re-wrapped** (PLAN ## addRxns -RAVEN `core/addRxns.m` — add reactions from equation strings (or mets+coeffs), auto-creating +RAVEN `manipulation/addRxns.m` — add reactions from equation strings (or mets+coeffs), auto-creating metabolites/genes. Ported as `add_reactions_from_equations` ([manipulation/add.py](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/manipulation/add.py)). @@ -246,7 +246,7 @@ and `get_elemental_balance` ([utils/balance.py](https://github.com/SysBioChalmer |---|---|---|---|---| | ~~P1~~ | ERGONOMICS | — | ↩ revised | A 6-mode keyword `set_parameters` was built then **trimmed** (review: not Pythonic — it re-wrapped cobra one-liners for `lb`/`ub`/`eq`/`obj`/`unc`). Only the `var` ±% band, which cobra has no idiom for, is kept as `set_variance_bounds`; the rest are documented as cobra idioms in the §1 cheatsheet. | | B1 | ERGONOMICS (correctness) | raven-python 🔨 | 🔨 | **getElementalBalance: report `unknown` for missing formulas.** cobra's `check_mass_balance` silently treats a metabolite with no formula as contributing nothing, so the reaction can read as (un)balanced on incomplete data. raven-python flags those as `unknown` rather than guessing — preserving RAVEN's distinction (its `-1` status). | -| B2 | CORRECTNESS | raven-python 🔨 + MATLAB RAVEN 💡 | 🔨 | **Empty-stoichiometry reactions report `unknown`, not vacuous `balanced`.** A reaction with no metabolites used to fall through to `balanced` (any-over-empty is False; the zero-imbalance dict is empty). Same bug in MATLAB `core/getElementalBalance.m`: with no entries in `model.S(:,j)`, `balanceStatus` stays NaN through both loops and the final `isnan→1` step labels it `balanced`. **Proposed back-port:** add an `emptyRxns = full(sum(model.S~=0,1))==0` mask and `balanceStatus(emptyRxns) = min(-1, balanceStatus(emptyRxns))` before the `isnan→1` line, so empty reactions are marked "missing information". | +| B2 | CORRECTNESS | raven-python 🔨 + MATLAB RAVEN 💡 | 🔨 | **Empty-stoichiometry reactions report `unknown`, not vacuous `balanced`.** A reaction with no metabolites used to fall through to `balanced` (any-over-empty is False; the zero-imbalance dict is empty). Same bug in MATLAB `queries/getElementalBalance.m`: with no entries in `model.S(:,j)`, `balanceStatus` stays NaN through both loops and the final `isnan→1` step labels it `balanced`. **Proposed back-port:** add an `emptyRxns = full(sum(model.S~=0,1))==0` mask and `balanceStatus(emptyRxns) = min(-1, balanceStatus(emptyRxns))` before the `isnan→1` line, so empty reactions are marked "missing information". | ## getRxnsInComp / getMetsInComp — not ported @@ -288,7 +288,7 @@ value is preserving `metaData` identity and RAVEN-only per-entry fields, which i ## changeRxns -RAVEN `core/changeRxns.m` — change reaction equations. Ported as +RAVEN `manipulation/changeRxns.m` — change reaction equations. Ported as `change_reaction_equations` ([manipulation/change.py](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/manipulation/change.py)). | # | Cat | Target | Status | Improvement | @@ -297,7 +297,7 @@ RAVEN `core/changeRxns.m` — change reaction equations. Ported as ## getIndexes -RAVEN `core/getIndexes.m` — resolve a list of IDs / logical mask / index vector into positional +RAVEN `queries/getIndexes.m` — resolve a list of IDs / logical mask / index vector into positional indexes (or a logical array) for `rxns` / `mets` / `genes` / `metNames` / `metcomps` (and GECKO `ec.*` fields). @@ -325,7 +325,7 @@ batch, and substring/regex matching — all already provided by `get_by_any` / ` ## standardizeGrRules -RAVEN `core/standardizeGrRules.m` — normalize grRule syntax + flag rules not in simple +RAVEN `manipulation/standardizeGrRules.m` — normalize grRule syntax + flag rules not in simple OR-of-AND-complex (DNF) form (`findPotentialErrors`). **Decision (raven-python): port the lint half only.** cobra auto-normalizes a GPR on assignment diff --git a/docs/reference/matlab_raven_backports.md b/docs/reference/matlab_raven_backports.md index 0c96f00..5187f9e 100644 --- a/docs/reference/matlab_raven_backports.md +++ b/docs/reference/matlab_raven_backports.md @@ -15,7 +15,7 @@ fix is identical in spirit; the patch shape just differs. --- -## `core/getModelFromHomology.m` +## `reconstruction/homology/getModelFromHomology.m` Implemented in raventoolbox as [`reconstruction.homology.get_model_from_homology`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/reconstruction/homology/homology.py). @@ -34,7 +34,7 @@ Implemented in raventoolbox as [`reconstruction.homology.get_model_from_homology preference can flip the chosen template when the database grows. Keep E-value as an option. -## `core/getKEGGModelForOrganism.m` and the KEGG pipeline +## `reconstruction/kegg/getKEGGModelForOrganism.m` and the KEGG pipeline Implemented across [`reconstruction.kegg`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/reconstruction/kegg/). @@ -87,7 +87,7 @@ Implemented across [`reconstruction.kegg`](https://github.com/SysBioChalmers/rav rose from 0.84 → 0.94 (reaction recall 0.87 → 0.97) with no precision loss. Full numbers in [docs/kegg_hmm_cutoff_calibration.md](../studies/kegg_hmm_cutoff_calibration.md). -## `core/FSEOF.m` +## `analysis/FSEOF.m` Implemented in raventoolbox as [`analysis.fseof`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/analysis/fseof.py). @@ -121,7 +121,7 @@ Implemented in raventoolbox as [`analysis.fseof`](https://github.com/SysBioChalm matches the selection criterion. The amplify/knockdown/knockout label (after FS2) should use the slope of `|flux|`, not endpoint comparison. -## `core/randomSampling.m` +## `analysis/randomSampling.m` Implemented in raventoolbox as [`analysis.random_sampling`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/analysis/sampling.py). @@ -140,7 +140,7 @@ Implemented in raventoolbox as [`analysis.random_sampling`](https://github.com/S "unbounded objective". Scope `replaceBoundsWithInf` to sampling only, after the goodRxns set is found. -## `core/reporterMetabolites.m` +## `analysis/reporterMetabolites.m` Implemented in raventoolbox as [`analysis.reporter_metabolites`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/analysis/reporter.py). @@ -152,7 +152,7 @@ Implemented in raventoolbox as [`analysis.reporter_metabolites`](https://github. metabolite Z is just `(metZ − √n·μ) / σ`. This removes both the slow sampling step and its run-to-run randomness (results become deterministic). -## `core/runINIT.m` +## `INIT/runINIT.m` Implemented in raventoolbox as [`init.run_init`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/init/init.py). @@ -162,7 +162,7 @@ Implemented in raventoolbox as [`init.run_init`](https://github.com/SysBioChalme fits ±1000-bounded models with O(1) scores — flagged in RAVEN as scale-dependent and tunable, but no API knobs are exposed. -## `core/ftINIT.m` and the ftINIT pipeline +## `INIT/ftINIT.m` and the ftINIT pipeline Implemented across [`init.ftinit`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/init/ftinit.py), [`init.taskfill`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/init/taskfill.py), [`init.merge`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/init/merge.py), [`init.prep`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/init/prep.py). @@ -184,14 +184,14 @@ Implemented across [`init.ftinit`](https://github.com/SysBioChalmers/raven-pytho to test. Make the all-negative tie-break **deterministic** (sort + take the least-negative) instead of random. -## `core/addRxns.m` +## `manipulation/addRxns.m` Implemented in raventoolbox as [`manipulation.add_reactions_from_equations`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/manipulation/add.py). * **A1** 🧹 — Accept a string keyword (`metsBy = 'id'` / `'name'`) instead of the opaque `eqnType = 1 / 2 / 3` integer. Call-sites become self-documenting. -## `core/checkModelStruct.m` (or its curation subset) +## `queries/checkModelStruct.m` (or its curation subset) Implemented in raventoolbox as [`utils.check_model`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/utils/validate.py). @@ -199,7 +199,7 @@ Implemented in raventoolbox as [`utils.check_model`](https://github.com/SysBioCh `category` / `target` / `message` fields) instead of printing warnings or throwing on the first problem. Programmatically filterable. -## `core/getElementalBalance.m` +## `queries/getElementalBalance.m` Implemented in raventoolbox as [`utils.get_elemental_balance`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/utils/balance.py). @@ -217,7 +217,7 @@ Implemented in raventoolbox as [`utils.get_elemental_balance`](https://github.co Empty reactions then report `-1` ("missing information") rather than vacuously balanced. -## `core/findPotentialErrors.m` (GPR linting) +## `manipulation/findPotentialErrors.m` (GPR linting) Implemented in raventoolbox as [`utils.find_non_dnf_grrules`](https://github.com/SysBioChalmers/raven-python/blob/develop/src/raven_python/utils/gpr.py). @@ -229,7 +229,7 @@ Implemented in raventoolbox as [`utils.find_non_dnf_grrules`](https://github.com to spacing and bracketing and to gene IDs containing those characters; the tree walk (no OR beneath any AND) is exact. -## `core/getIndexes.m` +## `queries/getIndexes.m` * **G1** ⚡ — Build a `containers.Map` `{id: position}` once per call and use hashed lookup (O(1)) instead of looping `find(strcmp(obj(i), searchIn))`