Replace decides, carries, picked, ships and handles in the guide and migration pages

.github/dependabot.yml

@@ -2,9 +2,11 @@ version: 2
 updates:
   - package-ecosystem: pip
     directory: /
+    target-branch: develop
     schedule:
       interval: weekly
   - package-ecosystem: github-actions
     directory: /
+    target-branch: develop
     schedule:
       interval: weekly

CONTRIBUTING.md

@@ -14,7 +14,7 @@ The standard for this site is the `docs-site` plugin of [CompMetEng/skills](http
 
 ## Branches
 
-`develop` is the default branch. It documents the `develop` branches of GECKO and geckopy, which the submodules track, and the daily submodule update opens a pull request against it. Pull requests target `develop`. `main` documents the released versions: a release of GECKO and geckopy is followed by a pull request from `develop` to `main` that is merged with a merge commit and pins the submodules to the released commits.
+`develop` is the integration branch. It documents the `develop` branches of GECKO and geckopy, which the submodules track, and the daily submodule update opens a pull request against it. Pull requests target `develop`. `main` documents the released versions: a release of GECKO and geckopy is followed by a pull request from `develop` to `main` that is merged with a merge commit and pins the submodules to the released commits.
 
 ## Building and checking
 

docs/gecko3-to-gecko4.md

@@ -22,7 +22,7 @@ A GECKO 3 script keeps running after each change in this box and returns a diffe
 | --- | --- | --- | --- |
 | Direction of protein reactions | `usage_prot_<id>` and `prot_pool_exchange` run in reverse and carry negative flux | both run forward, and the usage of an enzyme is the positive flux of its usage reaction | Reverse the sign of bounds and fluxes read from these reactions. `upgradeEcModel` turns a GECKO 3 ecModel (see [Upgrade a GECKO 3 project](gecko3-upgrade-project.md)) |
 | Substrate of a BRENDA kcat | the kcat is divided by the smallest coefficient in the reaction | the kcat is divided by the coefficient of the substrate that matched | Rebuild the kcat list. Reactions that are not written per the measured substrate get a lower kcat |
-| Default kcat assignment | `selectKcatValue` (`assignKcatValues` in GECKO 4) merges a DLKcat list and a BRENDA list | `assignKcats` decides from the kcat source files in `data/kcats` with the preset `brenda_ec_tree` | Set `preset = "gecko_classic"` in `[kcat_assignment]` to keep the GECKO 3 order (see [Kcat assignment](gecko4-kcat-assignment.md)) |
+| Default kcat assignment | `selectKcatValue` (`assignKcatValues` in GECKO 4) merges a DLKcat list and a BRENDA list | `assignKcats` determines the kcat from the kcat source files in `data/kcats` with the preset `brenda_ec_tree` | Set `preset = "gecko_classic"` in `[kcat_assignment]` to keep the GECKO 3 order (see [Kcat assignment](gecko4-kcat-assignment.md)) |
 | Protein fraction `f` | `calculateFfactor` averages over all samples, so a protein missing in one sample is left out of both totals | the average is over the samples in which the protein is measured | Recalculate `f` when the proteomics file has missing values |
 | Sigma fit | `sigmaFitter` returns the sigma with the smallest error | it returns the smallest sigma whose percent error is within a relative 1e-9 of the smallest error (geckopy `fit_sigma`: no tolerance in the default grid) | Refit when the growth rate is flat over a range of sigma |
 

docs/gecko3-upgrade-project.md

@@ -1,6 +1,6 @@
 # Upgrade a GECKO 3 project
 
-An existing GECKO 3 project is converted to [project format 4](gecko4-project-format.md) in one call that first lists its steps and then carries them out. The function is `upgradeGECKOproject` in MATLAB and `geckopy upgrade` (`upgrade_project`) in Python.
+An existing GECKO 3 project is converted to [project format 4](gecko4-project-format.md) in one call that first lists its steps and then performs them. The function is `upgradeGECKOproject` in MATLAB and `geckopy upgrade` (`upgrade_project`) in Python.
 
 ## Functions
 
@@ -13,10 +13,10 @@ An existing GECKO 3 project is converted to [project format 4](gecko4-project-fo
 
 ## Steps of the upgrade
 
-`upgradeGECKOproject` carries out these steps for a project made with GECKO 3 or with an earlier GECKO 4:
+`upgradeGECKOproject` performs these steps for a project made with GECKO 3 or with an earlier GECKO 4:
 
-1. Adapter: in MATLAB, an adapter class without `model_adapter.toml` gets one (`convertAdapterToToml`), and the methods that the class overrides are listed, because they need to be carried over by hand. The class stays. `geckopy upgrade` lists the adapter as a step to do by hand and skips steps 2 and 3 for such a project.
-2. Custom kcats: `data/customKcats.tsv` becomes `data/kcats/custom.tsv` (`convertCustomKcats`). The kcats are those that `applyCustomKcats` gives the ecModel, including which of two entries for the same reaction applies. The column `stoicho` is not carried over, because the complex stoichiometry comes from `applyComplexData`.
+1. Adapter: in MATLAB, an adapter class without `model_adapter.toml` gets one (`convertAdapterToToml`), and the methods that the class overrides are listed, because they need to be converted by hand. The class stays. `geckopy upgrade` lists the adapter as a step to do by hand and skips steps 2 and 3 for such a project.
+2. Custom kcats: `data/customKcats.tsv` becomes `data/kcats/custom.tsv` (`convertCustomKcats`). The kcats are those that `applyCustomKcats` gives the ecModel, including which of two entries for the same reaction applies. The column `stoicho` is not copied, because the complex stoichiometry comes from `applyComplexData`.
 3. Stored predictions: `data/DLKcat.tsv` and stored OpenKineticsPredictor results become kcat source files (`kcatsFromDLKcat`, and `kcatsFromOKP` with `'useStored'`). No prediction is run.
 4. Saved ecModels: The ecModels in `models/*.yml` made with GECKO 3 get their protein usage and pool reactions turned forward (`upgradeEcModel`).
 5. Project format: `project_format = 4` is written to `model_adapter.toml`.

docs/gecko4-kcat-assignment.md

@@ -2,13 +2,13 @@
 
 <!-- docs-site: concept-page -->
 
-GECKO 4 assigns the kcat of each reaction from kcat source files, in an order that `model_adapter.toml` sets. `collectKcats` decides the kcats and does not change the model. `assignKcats` applies the decisions and the kcat constraints. [Gathering kcats](guide/gathering-kcats.md) describes how the sources are gathered, and [Applying kcats](guide/applying-kcats.md) the steps after the assignment.
+GECKO 4 assigns the kcat of each reaction from kcat source files, in an order that `model_adapter.toml` sets. `collectKcats` determines the kcats and does not change the model. `assignKcats` applies the decisions and the kcat constraints. [Gathering kcats](guide/gathering-kcats.md) describes how the sources are gathered, and [Applying kcats](guide/applying-kcats.md) the steps after the assignment.
 
 ## Functions
 
 | MATLAB | Python | Note |
 | --- | --- | --- |
-| `collectKcats` | `collect_kcats` | decides one kcat per reaction and writes `output/<model id>_kcatDecisions.tsv` |
+| `collectKcats` | `collect_kcats` | determines one kcat per reaction and writes `output/<model id>_kcatDecisions.tsv` |
 | `assignKcats` | `assign_kcats` | applies the decisions and the kcat constraints. Kcats that the model had are replaced |
 | `updateKcatSources` | `update_kcat_sources` | gathers the source files that the configuration needs and that are missing or outdated |
 | `kcatAssignmentConfig` | `kcat_assignment_config` | returns the settings with the preset expanded into stages |
@@ -28,7 +28,7 @@ A source is the name of a file in `data/kcats` (`custom`, `ec_tree`, `homologs`,
 
 ## Stages
 
-A stage decides the reactions that are still open. The action `select` takes the first listed source that has a value. The action `combine` takes all listed sources that have a value, corrects each for the bias of the source and weights it by 1 divided by its error variance. The error variance depends on the evidence of the source for the reaction: for the EC tree the measurements of the EC number and of its EC class, for an OKP method the similarity of the enzyme to the training sequences of the method. The parameters are in `kcatCombineParams.tsv` of the BRENDA files. `model.ec.source` reads `combined (sd=<log10 sd>, n=<sources>)` for a combined value.
+A stage determines the kcat of the reactions that are still open. The action `select` takes the first listed source that has a value. The action `combine` takes all listed sources that have a value, corrects each for the bias of the source and weights it by 1 divided by its error variance. The error variance depends on the evidence of the source for the reaction: for the EC tree the measurements of the EC number and of its EC class, for an OKP method the similarity of the enzyme to the training sequences of the method. The parameters are in `kcatCombineParams.tsv` of the BRENDA files. `model.ec.source` reads `combined (sd=<log10 sd>, n=<sources>)` for a combined value.
 
 After the stages, `collectKcats` applies `data/customKcats.tsv` when a stage lists `custom` and `data/kcats/custom.tsv` does not exist. With `isozymes = true`, a reaction without a kcat in a full ecModel takes one from its isozymes. With `standard = true`, the remaining reactions get the standard kcat.
 

docs/gecko4-project-format.md

@@ -34,7 +34,7 @@ The file holds the parameters that an adapter class sets in GECKO 3. Paths are r
 | `[matlab]` | names of MATLAB functions for the anaerobic model and the protein content of the biomass. GECKO alone reads this section |
 | `[matlab.params]` | parameters that GECKO uses and geckopy does not use |
 
-`ModelAdapterManager.getAdapter` and `ModelAdapterManager.setDefault` take the project folder or the TOML file and return a `TomlAdapter`. A class that needs more code can subclass `TomlAdapter`. In geckopy, `ModelAdapter.from_folder` reads the folder. An adapter class of GECKO 3 keeps working, and `convertAdapterToToml` writes it as `model_adapter.toml` and lists the methods it cannot carry over.
+`ModelAdapterManager.getAdapter` and `ModelAdapterManager.setDefault` take the project folder or the TOML file and return a `TomlAdapter`. A class that needs more code can subclass `TomlAdapter`. In geckopy, `ModelAdapter.from_folder` reads the folder. An adapter class of GECKO 3 keeps working, and `convertAdapterToToml` writes it as `model_adapter.toml` and lists the methods it cannot convert.
 
 ## Kcat source files
 
@@ -59,7 +59,7 @@ A kcat source file stores the kcats of one source. Each row is keyed by the conv
 
 ## BRENDA data
 
-GECKO does not ship BRENDA data. `fetchBrendaAsset` downloads the files `kcat.tsv`, `sa.tsv`, `mw.tsv` and `measurements.tsv` of the toolbox-assets release `brenda-2026.1-1` (BRENDA 2026.1, CC BY 4.0) on first use, checks them against the checksums of the toolbox-assets manifest, and unpacks them into `databases/brenda-2026.1-1` in the GECKO folder. The release also holds `sequences.fasta`, `substrates.tsv` and `kcatCombineParams.tsv`. geckopy reads the same release (`fetch_brenda_asset`).
+GECKO does not include BRENDA data. `fetchBrendaAsset` downloads the files `kcat.tsv`, `sa.tsv`, `mw.tsv` and `measurements.tsv` of the toolbox-assets release `brenda-2026.1-1` (BRENDA 2026.1, CC BY 4.0) on first use, checks them against the checksums of the toolbox-assets manifest, and unpacks them into `databases/brenda-2026.1-1` in the GECKO folder. The release also holds `sequences.fasta`, `substrates.tsv` and `kcatCombineParams.tsv`. geckopy reads the same release (`fetch_brenda_asset`).
 
 `kcat.tsv` and `sa.tsv` record a maximum and a median per EC number, substrate and organism. `kcat_aggregate_brenda = "max"` (default) or `"median"` selects the value for `fuzzyKcatMatching` and `loadBRENDAdata`, and `'kcatAggregation'` sets it for one call.
 

docs/guide/applying-kcats.md

@@ -63,8 +63,8 @@ flowchart TB
 
 | MATLAB | Python | Note |
 |---|---|---|
-| `assignKcats` | `assign_kcats` | decide one kcat per reaction from the kcat source files and apply the kcat constraints |
-| `collectKcats` | `collect_kcats` | decide the kcats without changing the model |
+| `assignKcats` | `assign_kcats` | determine one kcat per reaction from the kcat source files and apply the kcat constraints |
+| `collectKcats` | `collect_kcats` | determine the kcats without changing the model |
 | `convertCustomKcats` | `convert_custom_kcats` | convert `data/customKcats.tsv` into `data/kcats/custom.tsv` |
 | `applyCustomKcats` | `apply_custom_kcats` | apply the kcats of `data/customKcats.tsv` |
 | `getKcatAcrossIsozymes` | `fill_kcats_from_isozymes` | fill missing kcats with the mean of their isozymes |
@@ -115,7 +115,7 @@ Without `data/kcats/custom.tsv`, `collectKcats` applies `data/customKcats.tsv` i
 [ecModel, rxnUpdated, notMatch] = applyCustomKcats(ecModel);
 ```
 
-This overwrites existing values in `ecModel.ec.kcat` for matching reactions, on the assumption that custom values carry higher confidence. The stoichiometry changes when `applyKcatConstraints` runs.
+This overwrites existing values in `ecModel.ec.kcat` for matching reactions, on the assumption that custom values have higher confidence. The stoichiometry changes when `applyKcatConstraints` runs.
 
 Custom values that fail to match: if `notMatch` contains reactions, their values were not successfully applied, because the gene association between the model and the input file is a partial match: at least 50 %, but not 100 %. A gene association that matches less than 50 % is skipped and does not appear in `notMatch`. Inspect which enzymes are associated with the reaction in the ecModel and curate the input file to resolve it.
 :::
@@ -134,7 +134,7 @@ The same overwrite behaviour and the same gene-match threshold of 50 % apply her
 
 ## Assign kcats from the source files
 
-`assignKcats` decides one kcat per reaction from the kcat source files, writes `ec.kcat` and `ec.source`, and applies the kcat constraints with `applyKcatConstraints`. The order of the sources follows the preset or the stages of `[kcat_assignment]`; [Kcat assignment](../gecko4-kcat-assignment.md) describes the presets, the stages and the gathering of missing source files with `updateKcatSources`. Kcats that the model had are replaced, because the source files are the input of the assignment. After the stages, `assignKcats` fills reactions without a kcat from their isozymes for full ecModels when `isozymes` is true, and gives the remaining reactions the standard kcat when `standard` is true; both options are true by default.
+`assignKcats` determines one kcat per reaction from the kcat source files, writes `ec.kcat` and `ec.source`, and applies the kcat constraints with `applyKcatConstraints`. The order of the sources follows the preset or the stages of `[kcat_assignment]`; [Kcat assignment](../gecko4-kcat-assignment.md) describes the presets, the stages and the gathering of missing source files with `updateKcatSources`. Kcats that the model had are replaced, because the source files are the input of the assignment. After the stages, `assignKcats` fills reactions without a kcat from their isozymes for full ecModels when `isozymes` is true, and gives the remaining reactions the standard kcat when `standard` is true; both options are true by default.
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -221,7 +221,7 @@ This step does not apply to light ecModels, where the most efficient isozyme set
 
 ## Assign a standard kcat value (optional)
 
-Reactions without genes associated in the starting GEM (empty gene-reaction rules) cannot carry enzyme constraints, for lack of enzyme data. For such reactions, excluding exchange, spontaneous, transport and pseudo-reactions (reaction names that contain `pseudoreaction` or `SLIME rxn`, and the reactions in `data/pseudoRxns.tsv`), a standard kcat and a standard pseudo-enzyme (`prot_standard`) constrain catalytic capacity instead. The standard kcat is the median of the kcat values of the reactions in the same subsystem, when the subsystem has at least 10 reactions with a kcat (the option `threshold`), and the median of every kcat in `ec.kcat` otherwise. The standard molecular weight is the median across every protein in the organism, and a `usage_prot_standard` reaction is added.
+Reactions without genes associated in the starting GEM (empty gene-reaction rules) cannot get enzyme constraints, for lack of enzyme data. For such reactions, excluding exchange, spontaneous, transport and pseudo-reactions (reaction names that contain `pseudoreaction` or `SLIME rxn`, and the reactions in `data/pseudoRxns.tsv`), a standard kcat and a standard pseudo-enzyme (`prot_standard`) constrain catalytic capacity instead. The standard kcat is the median of the kcat values of the reactions in the same subsystem, when the subsystem has at least 10 reactions with a kcat (the option `threshold`), and the median of every kcat in `ec.kcat` otherwise. The standard molecular weight is the median across every protein in the organism, and a `usage_prot_standard` reaction is added.
 
 Reactions that are annotated with an enzyme but have a kcat of 0 or `NaN` receive the standard kcat as well and keep their enzyme. Earlier standard assignments (`standard` in `ec.source`) are removed when the function runs again.
 

docs/guide/basic-model-operations.md

@@ -183,7 +183,7 @@ print(sol.fluxes[exchange_ids][sol.fluxes[exchange_ids] != 0])
 
 ## Export results and models
 
-Export the results to a spreadsheet. The file does not carry content from the `ec` structure and helps to find reaction identifiers quickly:
+Export the results to a spreadsheet. The file does not contain content from the `ec` structure and helps to find reaction identifiers quickly:
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB