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
57 changes: 52 additions & 5 deletions docs/guide/proteomics-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ flowchart TB
classDef opt stroke-dasharray: 5 4
classDef ctx fill:transparent,stroke-dasharray: 2 3
PV(["Previous: Growth-rate tuning"]):::ctx
PV --> A["loadProtData<br/>fillEnzConcs"] --> B["levelComplexConcs<br/>constrainEnzConcs"] --> C["calculateFfactor, setProtPoolSize"] --> D["loadFluxData, constrainFluxData"]:::opt
PV --> A["loadProtData<br/>fillEnzConcs"] --> B["levelComplexConcs<br/>constrainEnzConcs"] --> I["getIsozymeCoverage<br/>zeroUnmeasuredIsozymes"]:::opt --> C["calculateFfactor, setProtPoolSize"] --> D["loadFluxData, constrainFluxData"]:::opt
NX(["Next: Relaxing overconstrained proteomics"]):::ctx
D --> NX
```
Expand All @@ -47,7 +47,7 @@ flowchart TB
classDef opt stroke-dasharray: 5 4
classDef ctx fill:transparent,stroke-dasharray: 2 3
PV(["Previous: Growth-rate tuning"]):::ctx
PV --> A["load_prot_data<br/>fill_enz_concs"] --> B["level_complex_concs<br/>constrain_enz_concs"] --> C["calculate_f_factor, set_prot_pool_size"] --> D["load_flux_data, apply_flux_data_constraints"]:::opt
PV --> A["load_prot_data<br/>fill_enz_concs"] --> B["level_complex_concs<br/>constrain_enz_concs"] --> I["get_isozyme_coverage<br/>zero_unmeasured_isozymes"]:::opt --> C["calculate_f_factor, set_prot_pool_size"] --> D["load_flux_data, apply_flux_data_constraints"]:::opt
NX(["Next: Relaxing overconstrained proteomics"]):::ctx
D --> NX
```
Expand All @@ -64,13 +64,15 @@ flowchart TB
| `levelComplexConcs` | `level_complex_concs` | give the subunits of each complex one abundance |
| `getComplexFamilies` | `complex_families` | group the enzymes of multi-subunit reactions into complexes |
| `constrainEnzConcs` | `constrain_enz_concs` | apply the concentrations as upper bounds of the `usage_prot_<id>` reactions |
| `getIsozymeCoverage` | `get_isozyme_coverage` | list the reactions with a measured and an unmeasured isozyme |
| `zeroUnmeasuredIsozymes` | `zero_unmeasured_isozymes` | lower the usage upper bound of the unmeasured isozymes of such a reaction |
| `calculateFfactor` + `setProtPoolSize` | `calculate_f_factor` + `set_prot_pool_size` | recompute the protein pool constraint from the proteomics data |
| `loadFluxData` | `load_flux_data` | read `fluxData.tsv` (exchange fluxes and growth rate of the same experiment) |
| `constrainFluxData` | `apply_flux_data_constraints` | apply the exchange flux and growth rate constraints |

## Setup

The data are in `data/proteomics.tsv` and `data/fluxData.tsv` of the project (see [Files in the data folder](data-folder-files.md)). An ecModel is loaded or built as described in [Building an empty ecModel](building-ec-model.md). The order of the functions is `loadProtData`, `fillEnzConcs`, `levelComplexConcs` (optional), `constrainEnzConcs`.
The data are in `data/proteomics.tsv` and `data/fluxData.tsv` of the project (see [Files in the data folder](data-folder-files.md)). An ecModel is loaded or built as described in [Building an empty ecModel](building-ec-model.md). The order of the functions is `loadProtData`, `fillEnzConcs`, `levelComplexConcs` (optional), `constrainEnzConcs`, and optionally `zeroUnmeasuredIsozymes`.

Constraining individual enzyme concentrations usually overconstrains the ecModel, because the uncertainty comes from two sources at once: the enzyme levels and the $k_{cat}$ values. Proteomics data need to be of high quality, with low-certainty measurements discarded, or the ecModel does not reach its intended growth rate.

Expand All @@ -88,7 +90,7 @@ Proteomics measurements are not always performed with external standards for abs

## Load the proteomics data

`loadProtData` / `load_prot_data` takes the number of replicates of each condition, in the order of the columns of the file. The sum of these numbers must equal the number of replicate columns of the file; otherwise the function raises an error (`loadProtData:replicateMismatch` in MATLAB, `ValueError` in Python). It returns the mean over the replicates of each condition. The filtering is controlled by these parameters:
`loadProtData` / `load_prot_data` takes the number of replicates of each condition, in the order of the columns of the file. The sum of these numbers must equal the number of replicate columns of the file; otherwise the function raises an error (`loadProtData:replicateMismatch` in MATLAB, `ValueError` in Python). It returns the mean over the replicates of each condition. An abundance of 0 is read as not measured (NaN) before any filter, also when `filterData` is false, unless `zerosAsMeasured` is true. The filtering is controlled by these parameters:

| MATLAB | Python | Default | Effect |
|---|---|---|---|
Expand All @@ -98,6 +100,7 @@ Proteomics measurements are not always performed with external standards for abs
| `addStdevs` | `add_stdevs` | 1 | number of standard deviations added to the mean of the replicates |
| `minVal` | `min_val` | 0 | minimum value after `addStdevs`; a protein below it is discarded for that condition |
| `cutLowest` | `cut_lowest` | 5 | percentage of the lowest values per condition that is discarded |
| `zerosAsMeasured` | `zeros_as_measured` | false | whether an abundance of 0 is a measurement (see [Measured zeros](#measured-zeros-and-unmeasured-enzymes)) |

::::{tab-set}
:::{tab-item} Ⓜ️ MATLAB
Expand Down Expand Up @@ -141,6 +144,17 @@ fill_enz_concs(ec_model, prot_data, data_col=0)

`fillEnzConcs` / `fill_enz_concs` replaces `ec.concs` with the concentrations of the selected experiment. An enzyme without a measurement has `NaN`. A negative abundance of an enzyme of the model raises the error `fillEnzConcs:negativeAbundance` in MATLAB and a `ValueError` in Python. In Python, a `data_col` outside the columns of the abundances raises an `IndexError`.

### Measured zeros and unmeasured enzymes

`ec.concs` distinguishes two cases of an enzyme without a positive concentration:

- **NaN:** the enzyme is not measured. Its usage reaction draws from the protein pool without a bound of its own.
- **0:** the enzyme was measured as absent. `constrainEnzConcs` sets the upper bound of its usage reaction to 0, which removes every flux through the enzyme.

Proteomics reports a protein below the detection limit as 0 or as missing, so a 0 is not always an absent protein. By default (`zerosAsMeasured` false), `loadProtData` reads every 0 as NaN: the mean of a protein over its replicates leaves the zeros out, and a protein whose replicates are all 0 is removed. With `zerosAsMeasured` true, a 0 counts as a measured replicate and is kept in the mean. A protein whose replicates are all 0 is returned as 0, and neither `minVal` nor `cutLowest` removes it. A measured 0 constrains the model more than an unmeasured enzyme does and can lower the growth rate or make the model infeasible. `levelComplexConcs` keeps a subunit with a concentration of 0 at 0.

An enzyme with a concentration of 0 is not raised by `flexibilizeEnzConcs`, because the bound is raised as a factor of the concentration (see [Relaxing overconstrained proteomics](relaxing-constraints.md)).

## Level the concentrations of complexes

Absolute proteomics recovers the subunits of a complex unevenly, so the subunits of one complex can disagree several fold about the amount of it that is present. When each subunit is capped by its own measurement, the complex carries no more flux than its least abundant subunit allows. `levelComplexConcs` / `level_complex_concs` gives each complex one abundance. It runs after `fillEnzConcs` and before `constrainEnzConcs`.
Expand Down Expand Up @@ -176,7 +190,7 @@ A model with levelled complexes is relaxed with the option `perComplex` of `flex

## Apply the concentrations as bounds

Each `usage_prot_<id>` reaction of an enzyme with a measured concentration receives that concentration as its upper bound. Every usage reaction keeps drawing from the protein pool, with or without a bound.
Each `usage_prot_<id>` reaction of an enzyme with a measured concentration receives that concentration as its upper bound. Every usage reaction keeps drawing from the protein pool, with or without a bound. A concentration of 0 gives an upper bound of 0 (see [Measured zeros](#measured-zeros-and-unmeasured-enzymes)), and an enzyme with a NaN concentration keeps the default upper bound.

::::{tab-set}
:::{tab-item} Ⓜ️ MATLAB
Expand Down Expand Up @@ -205,6 +219,37 @@ Raises `ValueError` on a light ecModel: light ecModels have no `usage_prot_*` re
Enzyme concentrations must be in mg/gDCW. Relative proteomics data loaded with the wrong units produces an ecModel with nonsensical constraints and raises no error.
:::

## Limit unmeasured isozymes

A reaction with several isozymes can have a measured isozyme and an unmeasured one. The unmeasured isozyme then draws from the protein pool without a bound, although the reaction is already catalysed by the measured one. `getIsozymeCoverage` / `get_isozyme_coverage` lists these reactions without changing the ecModel. The entries of `ec.rxns` that share an identifier once the suffix `_EXP_<n>` is removed are the isozymes of one reaction. An entry is measured when one of its enzymes has a concentration above 0, and unmeasured when all its enzymes are NaN; the kcat is not considered. An enzyme of an unmeasured entry that also catalyses an entry outside the unmeasured entries of partially covered reactions is listed as shared and is not changed.

`zeroUnmeasuredIsozymes` / `zero_unmeasured_isozymes` lowers the upper bound of the `usage_prot_<id>` reaction of the other enzymes of the unmeasured entries. It runs after `constrainEnzConcs`, which resets the bounds, and no other function calls it. It does not change `ec.concs` and never raises a bound. The `method` is `'zero'` (Python: `"zero"`, default), which sets the bound to 0, or `'detectionLimit'` (Python: `"detection_limit"`), which sets it to `limit` in mg/gDCW (default: the smallest concentration above 0 in `ec.concs`). A protein below the detection limit is missing from the data as well as an absent protein, so `'zero'` can remove a flux that exists and lower the growth rate. An enzyme that was lowered is a candidate for `relaxProteomicsGreedy` like any enzyme with a bound below the default.

::::{tab-set}
:::{tab-item} Ⓜ️ MATLAB
:sync: matlab

```matlab
[coverage, zeroable] = getIsozymeCoverage(ecModel);
[ecModel, changed] = zeroUnmeasuredIsozymes(ecModel, 'method', 'detectionLimit');
```

`coverage` is a table with one row per partially covered reaction and the variables `rxn`, `nEntries`, `nMeasured`, `nUnmeasured`, `measuredEnzymes`, `unmeasuredEnzymes` and `sharedEnzymes`. `zeroable` holds the enzymes that `zeroUnmeasuredIsozymes` acts on. `changed` is a table with one row per enzyme and the variables `uniprot` and `newUpperBound`.
:::
:::{tab-item} 🐍 Python
:sync: python

```python
from geckopy import get_isozyme_coverage, zero_unmeasured_isozymes

coverage, zeroable = get_isozyme_coverage(ec_model)
changed = zero_unmeasured_isozymes(ec_model, method="detection_limit")
```

`coverage` is a `DataFrame` with the columns `rxn`, `n_entries`, `n_measured`, `n_unmeasured`, `measured_enzymes`, `unmeasured_enzymes` and `shared_enzymes`, and `zeroable` is a list of enzymes. `zero_unmeasured_isozymes` lowers the bounds of `ec_model` in place and returns a `DataFrame` with the columns `uniprot` and `new_upper_bound`. Both functions raise `NotImplementedError` on a light ecModel.
:::
::::

## Set the protein pool from the proteomics data

A proteomics experiment may reflect a physiology different from the default assumption. The pool size is recomputed from a sample-specific total protein content (for example 0.5 g/gDCW) in place of the adapter default `Ptot` (Python: `p_tot`), and from the f-factor of the proteomics data, the fraction of the measured protein mass that is accounted for by enzymes of the model. With several experiments in `protData`, `calculateFfactor` averages the abundance of each protein over the experiments in which it is measured. `updateProtPool` is a function of GECKO 4 that raises an error when a usage reaction with an upper bound other than 1000 draws from the protein pool, which is the case for every ecModel with concentration-bounded usage reactions from GECKO 3.2 on; `setProtPoolSize` sizes the pool for such ecModels.
Expand Down Expand Up @@ -299,6 +344,8 @@ With `max` and loose constraints, FBA reaches a solution unless too many exchang
| The growth rate that is reached is below the intended one | the enzyme levels, the $k_{cat}$ values or the exchange flux data are overconstrained | Relax the enzyme concentrations (see [Relaxing overconstrained proteomics](relaxing-constraints.md)), or loosen the flux constraints |
| `calculate_f_factor` returns 0 with a warning | none of the UniProt identifiers of the proteomics data matches an enzyme of the model | Use the same identifier namespace in `proteomics.tsv` and `ec.enzymes` |
| A complex is still limited by one subunit | the subunit is shared between complexes or catalyses a reaction on its own, and stays as measured | Check the `shared` field of the result of `levelComplexConcs` |
| The growth rate drops or the ecModel is infeasible after `constrainEnzConcs` | enzymes with a concentration of 0 (`zerosAsMeasured` true) or unmeasured isozymes limited to 0 (`zeroUnmeasuredIsozymes` with `'zero'`) have an upper bound of 0 | Load with `zerosAsMeasured` false, use `'detectionLimit'`, or relax with `relaxProteomicsGreedy` |
| A protein with a replicate of 0 is missing from `protData` or has a higher mean than in the file | the 0 is read as not measured by default | Set `zerosAsMeasured` (Python: `zeros_as_measured`) to true when the 0 is a measurement |
| `ValueError` from `constrain_enz_concs` | the ecModel is a light ecModel, or `ec.concs` has a negative value | Use a full ecModel; correct the proteomics data |

## See also
Expand Down
5 changes: 3 additions & 2 deletions docs/guide/relaxing-constraints.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ flowchart TB

## Setup

The ecModel has `ec.concs` filled and applied as bounds on the `usage_prot_<id>` reactions (`fillEnzConcs` and `constrainEnzConcs`, see [Proteomics integration](proteomics-integration.md)), and an intended growth rate is known. `flexibilizeEnzConcs` reads the growth rate from `gR_exp` of the model adapter when `expGrowth` is not given (Python: `gr_exp` and `exp_growth`).
The ecModel has `ec.concs` filled and applied as bounds on the `usage_prot_<id>` reactions (`fillEnzConcs` and `constrainEnzConcs`, see [Proteomics integration](proteomics-integration.md)), and an intended growth rate is known. An enzyme with a concentration of 0 (see [Measured zeros](proteomics-integration.md#measured-zeros-and-unmeasured-enzymes)) is not raised by `flexibilizeEnzConcs`, because the upper bound is raised as a factor of the concentration. The function warns and lists the enzymes (MATLAB warning `flexibilizeEnzConcs:measuredZero`, Python: logged warning). `relaxProteomicsGreedy` treats such an enzyme as any other enzyme with a bound below the default and can set its bound back to the default. `flexibilizeEnzConcs` reads the growth rate from `gR_exp` of the model adapter when `expGrowth` is not given (Python: `gr_exp` and `exp_growth`).

## Choice of algorithm

Expand Down Expand Up @@ -178,7 +178,7 @@ If the conventional GEM reaches the same ceiling, the exchange flux data are the

## Relaxation of complexes

When the concentrations were levelled with `levelComplexConcs` / `level_complex_concs` (see [Proteomics integration](proteomics-integration.md)), all subunits of a complex have one abundance and bind at once, so raising a single subunit does not raise growth. The option `perComplex` of `flexibilizeEnzConcs` (Python: `per_complex`, default false) treats every complex, as grouped by `getComplexFamilies` / `complex_families`, as one enzyme. Enzymes and complexes are ranked by the growth gained when all their usage upper bounds are raised together, every measured subunit of the selected complex is raised by the same factor, iterations are counted per complex, and the final pass keeps one factor per complex, which keeps levelled concentrations levelled. An upper bound is never lowered below its current value. The number of times that a complex was selected is recorded in `frequence` on its first measured subunit.
When the concentrations were levelled with `levelComplexConcs` / `level_complex_concs` (see [Proteomics integration](proteomics-integration.md)), all subunits of a complex have one abundance and bind at once, so raising a single subunit does not raise growth. The option `perComplex` of `flexibilizeEnzConcs` (Python: `per_complex`, default false) treats every complex, as grouped by `getComplexFamilies` / `complex_families`, as one enzyme. Enzymes and complexes are ranked by the growth gained when all their usage upper bounds are raised together, every measured subunit of the selected complex is raised by the same factor, iterations are counted per complex, and the final pass keeps one factor per complex, which keeps levelled concentrations levelled. An upper bound is never lowered below its current value. The number of times that a complex was selected is recorded in `frequence` on its first subunit with a concentration above 0.

::::{tab-set}
:::{tab-item} Ⓜ️ MATLAB
Expand Down Expand Up @@ -247,6 +247,7 @@ flex_result = relax_enz_concs(ec_model, exp_growth=0.1)
| `relaxProteomicsGreedy` raises an error (Python: `RuntimeError`) | `maxIterations` (Python: `max_iterations`, default 100) was reached while candidates remained | Raise `maxIterations`, or use `flexibilizeEnzConcs` |
| The ecModel is less constrained than the proteomics data require | `relaxProteomicsGreedy` has no tighten-back pass | Use `flexibilizeEnzConcs` / `flexibilize_enz_concs` |
| Warning that an enzyme or complex reached its iteration limit (MATLAB: "seems to be problematic") | the same enzyme or complex was picked more often than `iterPerEnzyme` allows | Check the $k_{cat}$ of the enzyme |
| `flexibilizeEnzConcs` warns about enzymes with a concentration of 0 and the growth rate is not reached | the enzymes have an upper bound of 0 that is never raised | Use `relaxProteomicsGreedy`, or load the proteomics data with `zerosAsMeasured` false |
| `flexibilize_enz_concs` raises `ValueError` | no enzyme has a measured concentration, or `exp_growth` is not given and `gr_exp` is not set | Run `fill_enz_concs` and `constrain_enz_concs`, or pass `exp_growth` |

## See also
Expand Down
Loading