Skip to content

Add user guide page 19: reconstruction from KEGG - #40

Merged
edkerk merged 1 commit into
mainfrom
guide/kegg
Aug 28, 2026
Merged

Add user guide page 19: reconstruction from KEGG#40
edkerk merged 1 commit into
mainfrom
guide/kegg

Conversation

@edkerk

@edkerk edkerk commented Aug 28, 2026

Copy link
Copy Markdown
Owner

Adds user guide page 19, Reconstruction from KEGG — the route to a draft with
no template model, where orthology groups carry the reactions.

This page is not executed by CI

It carries skip-file, as the ftINIT page does. A KEGG reconstruction fetches
47 MB of artefacts and then takes about six minutes to assemble the draft —
and the download is not the slow part, so caching does not help. That is too much
for a per-commit check. Every number on the page was measured on a real run, and
the page says in its second paragraph that it is not executed, rather than
letting a reader assume the guide's usual guarantee holds.

The MATLAB tab documents a failure

getKEGGModelForOrganism cannot currently complete, so the tab shows the error
instead of a model:

Downloading the HMM library file... COMPLETE
Error: keggModel.mat not found at <ravenRoot>/reconstruction/kegg/keggModel.mat.
Generate it with the raven-toolbox Python package or download it via downloadRavenBinaries.

Neither remedy the message names exists: downloadRavenBinaries fetches only
{'blast+','diamond','hmmer'} by its own help, and raven-toolbox has no
reference to keggModel anywhere in src/ or docs/. The file is not in the
repository and updateDocumentation deletes it if present. Filed as
RAVEN#704, together with
two things met on the way: the 129 MB HMM library downloads even on this route,
which performs no homology search at all; and findRAVENroot prefers a stored
RAVEN.ravenPath preference over the copy actually executing, so on a machine
with two checkouts the error names a directory the user is not working in.

What the Python route gives

1357 rxns, 1502 mets, 838 genes
compartments:  1 — everything in 's'
exchange rxns: 0
objective:     none

One compartment, because KEGG describes reactions rather than cell biology. 19.3
is about that gap and about the keepIncomplete / keepUndefinedStoich /
keepGeneral flags — turning the first two off drops the draft to 1348 reactions
and 827 genes, a smaller change than most people expect.

Checks

  • page correctly skipped by the runner in both languages
  • check_names.py clean (eleven argument names added to the allowlist)
  • site builds

The guide is now 19 pages. 185 examples still execute on every commit; pages 10
and 19 are the two that cannot.

The second route to a draft with no template model: KEGG's orthology
groups are already tied to reactions, so annotating a genome with KOs
gives a draft directly.

This page is marked skip-file, like the ftINIT one. A KEGG
reconstruction downloads 47 MB of artefacts and takes about six minutes
to assemble even once they are cached, which is too much for a
per-commit check. Every number quoted was measured, and the page says
plainly that it is not executed by CI.

The MATLAB tab documents a failure rather than a model.
getKEGGModelForOrganism cannot complete: keggModel.mat is not in the
repository and neither remedy its error message names provides it --
downloadRavenBinaries fetches only the three executables, and
raven-toolbox has no reference to keggModel at all. It also downloads
the 129 MB HMM library first, on a route that performs no homology
search. Filed as SysBioChalmers/RAVEN#704.

The Python route works and gives 1357 reactions, 1502 metabolites and
838 genes for sce -- in a single compartment, with no exchanges and no
objective, which is what 19.3 is about.
@edkerk
edkerk merged commit 44e8dbb into main Aug 28, 2026
2 checks passed
@edkerk
edkerk deleted the guide/kegg branch August 28, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant