# Kinetic model of the xanthophyll cycle

Data, model code and analysis scripts accompanying

> [AUTHORS] (YEAR). *[TITLE]*. [JOURNAL]. doi:[DOI]

The repository contains everything needed to reproduce the model comparison
and the simulations reported in the paper, and to apply the same framework to
new data.

---

## Contents

```
data/
  xc_90L_60D.csv                    xanthophyll time course, 90 min light + 60 min dark (fitting)
  xc_30L_30D_30L.csv                30 min light - 30 min dark - 30 min light (fitting)
  xc_20L_20D_40L_20D.csv            validation regime (not used for fitting)
  zep1_kcat_vs_preillumination.csv  ZEP1 turnover after different light doses
  npq_1000_20L_10D.csv              NPQ time course, 1000 umol, 20 min light + 10 min dark
  deps_npq_relation.csv             measured DEPS -> NPQ relationship
model/
  xc_model.py        the model: ODE system, light regimes, parameters
  fit_model.py       parameter estimation (multi-start weighted least squares, SciPy)
  run_analysis.py    reproduces the model comparison and the selected-model results
  npq_model.py       two-component NPQ model (qZ from DEPS, fast qE)
  npq_analysis.py    predicts NPQ from the modelled de-epoxidation state
results/             output tables of run_analysis.py
```

## Requirements

Python ≥ 3.9 with `numpy`, `scipy` and `pandas`.

```bash
pip install numpy scipy pandas
```

## Quick start

Simulate the selected model under an arbitrary light regime:

```python
from xc_model import XCModel, PARAMS_PAPER, LightRegime

regime = LightRegime([(0, 90, True), (90, 150, False)])   # 90 min light, 60 min dark
model  = XCModel(PARAMS_PAPER)
t, out = model.simulate(regime, y0={'WT': (0.939, 0.036, 0.025)}, t_end=150)

vx, zx, ax = out['WT'].T
```

Reproduce the model comparison and the selected-model results:

```bash
cd model
python run_analysis.py
```

This writes `results/table_model_selection.csv` and prints the AICc ranking, the
selected-model parameters and the validation R2. Expected result: the two-step
model with limited Vx availability is selected, and every single-step structure
is rejected by a wide margin.

Predict NPQ from the modelled de-epoxidation state:

```bash
cd model
python npq_analysis.py
```

This fits the two-component NPQ model (slow, xanthophyll-dependent qZ plus a
fast qE term) to the measured traces and prints the parameters and R2 for each
strain. The xanthophyll term alone reproduces the slow light-phase build-up,
while the fast qE term is needed for the rapid onset and dark relaxation.

## The model

Vx, Ax and Zx form a closed pool (Vx + Ax + Zx = 1) interconverted by two
enzymes following Michaelis-Menten kinetics:

```
Vx --k(t)--> Ax --g(t)--> Zx     VDE,  light only
Zx --z(t)--> Ax --a(t)--> Vx     ZEP1, light and dark
```

Three features are required to describe the measurements:

1. **VDE releases free Ax.** Single-step schemes, in which both epoxide groups
   are removed without releasing the intermediate, mispredict Ax systematically.
2. **Part of the Vx pool is inaccessible** to VDE (parameter `lVx`).
3. **ZEP1 is progressively inhibited by light.** The inhibition depends on the
   *cumulative light dose*, not on elapsed time, and is retained in darkness.
   This is implemented in `LightRegime.light_dose()`.

Strains sharing all kinetic constants but differing in enzyme content are
simulated within one system; relative contents are in `STRAIN_ENZYMES`.

## Non-photochemical quenching (NPQ)

`npq_model.py` builds NPQ on top of the modelled de-epoxidation state
DEPS = (Zx + 0.5*Ax) / (Vx + Ax + Zx) as the sum of two components:

1. **qZ**, a slow, xanthophyll-dependent component, from the empirical
   saturating DEPS -> NPQ relationship (`data/deps_npq_relation.csv`).
2. **qE**, a fast, light-driven component following first-order on/off
   kinetics (a proxy for the pH-dependent quenching).

Fitting qZ alone shows that the xanthophyll cycle accounts for the slow
build-up and the light-phase amplitude of NPQ, while the fast qE term is
required for the rapid onset and the fast dark relaxation. The relevance of
xanthophyll-cycle kinetics for the slow, memory-like component of NPQ follows
Short et al. (2023).

## Applying the model to other data

Put your measurements in a CSV with the columns of the files in `data/`:

| column | meaning |
|---|---|
| `time_min` | time from the start of the experiment |
| `strain` | must be a key of `STRAIN_ENZYMES` |
| `pigment` | `Vx`, `Zx` or `Ax` |
| `mean` | fraction of the total xanthophyll pool |
| `sd` | standard deviation across replicates (used as fitting weight) |

Then add your strains to `STRAIN_ENZYMES` (use `(1.0, 1.0)` if the enzyme
content is unknown) and estimate the parameters:

```python
from fit_model import load, fit
from xc_model import LightRegime, PARAMS_PAPER

tp, strains, obs, sd, y0 = load('my_data.csv')
regime = LightRegime([(0, 60, True), (60, 120, False)])
params, sse = fit(['vmax_VA', 'vmax_AZ', 'Km_VA', 'Km_AZ', 'lVx'],
                  PARAMS_PAPER, tp, strains, obs, sd, y0, regime)
```

**What the data need to contain.** A single light–dark regime with at least
eight time points, including a dark phase of ≥30 min, is the minimum. Two
regimes with different light durations allow one to be held out for validation.
Lines differing in the content of either enzyme constrain the parameters far
more tightly than a single genetic background, and an independent quantification
of at least one enzyme (e.g. by Western blot) is needed to give the `vmax`
values an absolute scale.

## A caveat on the parameters

Because the substrate concentrations reached in vivo stay well below the
Michaelis constants, `vmax` and `Km` are strongly correlated and are **not
separately identifiable**: refitting from different starting values can return
very different pairs that describe the data equally well. Only their ratio,
the catalytic efficiency `vmax/Km`, is constrained. Interpret the individual
constants as operational parameters, and base conclusions on efficiency ratios.
The same applies to `vmax` and the enzyme-content factor, which enter the model
only as their product.

## References

Short, A., T. P. Fay, T. Crisanto, R. Mangal, K. K. Niyogi, D. T. Limmer, and
G. R. Fleming. 2023. Kinetics of the xanthophyll cycle and its role in
photoprotective memory and response. Nature Communications 14: 6621.

## Licence

Data and code released under CC-BY-4.0 and MIT respectively.
