Skip to content

docs: update RAVEN cross-references for the post-reorg folder layout #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
edkerk merged 1 commit into from
Jun 8, 2026
Merged

docs: update RAVEN cross-references for the post-reorg folder layout #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions IMPROVEMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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
Expand All @@ -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 |
|---|---|---|---|---|
Expand Down Expand Up @@ -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 |
|---|---|---|---|---|
Expand All @@ -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).
Expand All @@ -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)).

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand All @@ -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).

Expand Down Expand Up @@ -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
Expand Down
24 changes: 12 additions & 12 deletions docs/reference/matlab_raven_backports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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/).

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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).

Expand All @@ -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).

Expand All @@ -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).

Expand All @@ -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).

Expand All @@ -184,22 +184,22 @@ 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).

* **V2** 🧹 — Return a struct array of issues (one per finding, with
`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).

Expand All @@ -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).

Expand All @@ -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))`
Expand Down
Loading