bio-metabolomics-isotope-tracing

What this skill does

## Version Compatibility

Reference examples tested with: isocor 2.2+, numpy 1.26+

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures
- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# Isotope Tracing / Stable-Isotope-Resolved Metabolomics

**"What is this pathway actually doing, not just how much metabolite is there?"** -> Feed a labeled tracer, then measure how label propagates into downstream metabolites as a mass-isotopomer distribution (MID) over time.
- Python: `isocor.mscorrectors.MetaboliteCorrectorFactory().correct()` (IsoCor) for natural-abundance correction
- R: `accucor::natural_abundance_correction()` (AccuCor) for high-resolution correction
- Modeling layer (separate discipline): `INCA`, `13CFLUX2`, `OpenFLUX` for 13C-MFA / INST-MFA flux fitting

## The Single Most Important Insight -- Labeling Reports Flux; Pool Size Does Not

A metabolite's concentration is *how much* is there; its labeling pattern (MID) is *where the carbon came from and how fast it got there*. These are independent measurements and frequently move in OPPOSITE directions: block a downstream-consuming enzyme and the intermediate pool rises (it backs up) while the labeling of downstream products falls (flux through them dropped). Reading the pool alone reports the opposite of the biology. An isotope-tracing experiment therefore answers a fundamentally different question than untargeted or targeted abundance profiling, and its analysis is dominated by two mandatory corrections that fabricate flux if skipped: natural-abundance / tracer-purity correction (raw isotopologue areas are NOT the labeling), and the steady-state assumption (a single MID is a snapshot whose meaning depends on whether labeling has plateaued). Fractional enrichment is concentration-independent (it is a ratio within one pool), which is why it survives the recovery/matrix problems that plague absolute quant -- but it says nothing about amount.

## Core Concepts

| Term | Meaning | Why it matters |
|---|---|---|
| Tracer / tracee | The labeled substrate fed (tracer, e.g. U-13C6-glucose) vs the unlabeled endogenous pool (tracee) | The experiment measures how tracer atoms replace tracee atoms over time |
| Isotopologue | A molecule differing only in number of heavy atoms (M+0, M+1, M+2 ...) | Resolved by MASS; this is what MS measures and what an MID counts |
| Isotopomer | Same number of heavy atoms but at different POSITIONS (e.g. 1-13C vs 6-13C lactate) | Resolved by POSITION; needs NMR or positional tracers, NOT mass spectra alone |
| MID (mass-isotopomer distribution) | The fractional vector of M+0, M+1, ... for one metabolite | The primary readout; its shape encodes which route carbon took |
| Fractional / mean enrichment | Weighted-mean labeled-atom fraction = sum(i * MID_i) / n_atoms | One-number summary of how labeled a pool is; concentration-independent |
| Atom transitions | The map of which substrate carbons land on which product carbons per reaction | Defines the expected MID for each pathway; the basis of flux models |
| Metabolic steady state | Pool sizes constant in time | Required for classical MFA; if pools drift, plateau MIDs do not give fluxes |
| Isotopic steady state | Labeling has equilibrated to a stable plateau | Classical MFA reads fluxes from the plateau; sampling before it is invalid |

## Decision Tree by Scenario

| Goal / situation | Do | Why |
|---|---|---|
| Want amount/concentration, units, biomarker level | Use abundance profiling -> metabolomics/targeted-analysis | Pool size is not flux; tracing cannot give a concentration |
| Want pathway ACTIVITY/route, central carbon metabolism | 13C tracing (U-13C6-glucose, 13C5-glutamine); measure MIDs | Labeling reports flux through the route the carbon took |
| Trace nitrogen handling (transamination, urea, nucleotides) | 15N tracer (e.g. 15N2-glutamine, 15N-ammonia) | N-flux is invisible to a 13C tracer |
| Distinguish two carbon entry points into one pool | Positional / partially-labeled tracer (e.g. 1,2-13C2-glucose) | The M+1 vs M+2 split of products separates PPP from glycolysis |
| Fast-labeling small pools, cultured cells, clear metabolic steady state | Steady-state 13C-MFA from plateau MIDs (INCA, 13CFLUX2) | Plateau labeling + atom transitions -> flux estimates |
| Slow labeling, large pools, autotrophs, primary/quiescent cells | INST-MFA from the labeling TIME COURSE (INCA) | Drops the isotopic-steady-state assumption; fits transient + pool sizes |
| Have raw isotopologue areas (low-res QqQ / high-res Orbitrap) | Natural-abundance + purity correction FIRST (IsoCor / AccuCor) | Uncorrected MID is wrong by construction; see below |
| Want genome-scale predicted flux without a tracer | systems-biology/flux-balance-analysis | FBA is constraint-based prediction, NOT empirical label measurement |

## Natural-Abundance + Tracer-Purity Correction (mandatory)

**Goal:** Turn raw measured isotopologue areas into a true MID that reflects only tracer-derived label.

**Approach:** Even a fully unlabeled molecule shows an M+1, M+2 ladder because ~1.07% of carbon is naturally 13C (plus 15N, 2H, 18O, 34S, and derivatization Si). Build the natural-abundance ladder from the molecular (and derivative) formula, deconvolve it out, then correct for the tracer not being 100% isotopically pure. Feeding uncorrected areas to a flux model is the equivalent of reporting an uncalibrated peak area as a concentration.

```python
import isocor

# corrector knows the formula's natural-abundance ladder and the tracer
corrector = isocor.mscorrectors.MetaboliteCorrectorFactory(
    'C6H12O6', tracer='13C',
    correct_NA_tracer=True,           # also strip the labeled element's own natural abundance
    tracer_purity=[0.01, 0.99])       # [unlabeled, labeled] per-position purity of the tracer

# raw measured areas M+0..M+6 for a partially labeled glucose pool
corrected_area, iso_fraction, residuum, mean_enrichment = corrector.correct(
    [50000., 8000., 12000., 3000., 1500., 6000., 25000.])
# iso_fraction is the corrected MID; mean_enrichment is fractional enrichment
```

High-resolution Orbitrap data resolves 13C from 15N/2H by exact mass, enabling a different (often simpler) correction; AccuCor (R) is tuned for that case:

```r
library(accucor)
# El-MAVEN / MAVEN isotopologue table; Resolution is the instrument resolving power
corrected <- natural_abundance_correction(path = 'elmaven_export.xlsx',
                                          resolution = 100000, purity = 0.99)
```

Pick the corrector by tracer count and resolution: IsoCor handles any tracer at any resolution; AccuCor (single tracer) and AccuCor2 (dual 13C-15N / 13C-2H) target high-res. Verify the chosen tool's current argument names before running -- both APIs drift across versions.

## Computing and Plotting an MID / Fractional Enrichment

**Goal:** Summarize a corrected isotopologue vector as an MID and one fractional-enrichment number, comparably across conditions.

**Approach:** Normalize corrected areas to sum 1 (the MID), then take the atom-weighted mean over isotopologue index divided by the number of tracer atoms.

```python
import numpy as np

corrected = np.array([26000., 2200., 5600., 1200., 500., 2300., 12500.])
mid = corrected / corrected.sum()                              # M+0..M+n fractions
fractional_enrichment = np.sum(np.arange(len(mid)) * mid) / (len(mid) - 1)
# stacked-bar MID per condition is the standard visualization; never plot raw (uncorrected) areas
```

## Steady-State Check (does the labeling number mean anything yet?)

**Goal:** Decide whether a measured MID may be read as flux-informative or is still a kinetic transient.

**Approach:** Sample labeling at several