Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion docs/guide/biomass.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/guide/combining.md
Original file line number Diff line number Diff line change
@@ -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

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

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

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/comparing.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/curation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/engineering.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
:::

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/fba.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Flux balance analysis (FBA) sets an objective, limits the uptake rates, solves t
| `printFluxes` | `Model.summary` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | show the fluxes that carry material |
| `solveLP` (`minFlux`) | `pfba` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | select a parsimonious solution among the optima |

Every Python simulation step on this page comes from cobrapy and carries the {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` 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 <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` badge in the functions table. In MATLAB, `solveLP` does not need the COBRA Toolbox or any other package outside RAVEN.

## Setup

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/gap-filling.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::
::::

Expand Down Expand Up @@ -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.
:::
Expand Down
10 changes: 5 additions & 5 deletions docs/guide/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

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