# SOURCES — where the bundled data came from

Every table shipped in `src/tcren/data/` and loaded by the library. Each entry gives the origin, how
to re-fetch or regenerate it, and whether the values are **published** (transcribed from a paper or
database), **derived** (computed by us from structures), or **unresolved**.

The authoritative per-value detail lives in the loader docstrings in `src/tcren/potential/model.py`
— including the cross-checks. This file exists so the provenance question can be answered without
reading the code, and so an unrecorded origin is visible as such rather than assumed.

Structure datasets (`Native2022`, `Native2026`, `Canonical2026`, the modelled sets) are not here:
they are not bundled, they are fetched from Hugging Face, and `DATASETS.md` covers them.

---

## `TCRen_potential.csv` — derived

The classic TCRen TCR↔peptide potential. **Directed**: rows are the TCR side, columns the peptide
side, so it must not be symmetrised or decomposed.

- Origin: derived by us from the Native2022 TCR:pMHC contact statistics (Karnaukhov et al. 2024).
- Regenerate: `tcren derive-potential -s <structures> -o TCRen_potential.csv`; the current file is
  the published 2024 derivation, not a re-run.
- Loader: `tcren.potential.tcren()`.

## `TCRen_potential_rederived.csv` — derived

The same quantity re-derived on Native2026. Shipped for comparison; no scoring path defaults to it.

- Regenerate: `tcren derive-potential` over Native2026.

## `MJ_Keskin_potentials.csv` — published (identified 2026-08-29)

Loaded as both `mj()` and `keskin()`. **Every score in the package is built on this file.**

- Origin: carried over from the original R implementation with no record, and **identified against
  AAindex3 on 2026-08-29** by `tcren.potential.identify()`, which compares a matrix cell by cell
  against all 47 AAindex3 entries:
  - the `MJ` column is **`MIYS990106`** — Miyazawa S, Jernigan RL, *Proteins.* 1999;34(1):49–68,
    doi:10.1002/(SICI)1097-0134(19990101)34:1<49::AID-PROT5>3.0.CO;2-L (PMID 10336383). **400 of
    400 cells match exactly** (max |Δ| = 0); the next-closest AAindex3 entry is off by 0.65, and
    every other Miyazawa–Jernigan matrix in the file — `MIYS850102`, `MIYS850103`, `MIYS960101`,
    `MIYS960102`, `MIYS990107` — is off by 0.66 to 6.53. So it is **MJ 1999, not 1985 and not
    1996**, and the citation risk recorded here since 2026-08-11 is closed.
  - the `Keskin` column is **`KESO980101`**, the solvent-mediated form — 400 of 400 cells exactly,
    next-closest off by 2.77.
- Re-verify: `python -c "from tcren.potential import identify, mj, keskin; print(identify(mj())[:2], identify(keskin())[:2])"`
- What was established earlier and still holds: it is **not** MJ 1996 Table 3 — that table is
  attractive everywhere (Ala–Ala −2.72, range −7.37 to −0.12) while this one takes both signs
  (Ala–Ala −0.12, range −1.19 to +0.76). It correlates with Table 3 at r = 0.89 but is not its
  double-centred pair part either (r = 0.51).
- Status: left byte-for-byte untouched, since changing it would change every published number. It
  can now be cited as Miyazawa & Jernigan 1999.
- **The two potentials in this one file are in different reference states** (2026-08-29): the `MJ`
  side is mixed-sign with mean −0.079, the `Keskin` side is negative everywhere with mean −3.547.
  Swapping one for the other therefore changes the reference state as well as the derivation. The
  like-for-like partners are `MJ` ↔ `BT1999` and `Keskin` ↔ `MJ1996`.

## `MJ1996_contact_energies.csv` — published

Miyazawa–Jernigan 1996 inter-residue contact energies `e_ij` (RT units), Table 3.

- Origin: AAindex accession `MIYS960101`, transcribed from a published copy of Table 3 and
  cross-checked against a second independent copy — agreeing on the alphabet order
  `CMFILVWYAGTSNQDEHRKP`, on Ala–Ala (−2.72), and on the full range (−7.37 to −0.12).
- Re-fetch: <https://www.genome.jp/dbget-bin/www_bget?aaindex:MIYS960101>
- Excluded on purpose: the companion repulsive packing-density term of the same paper, which is a
  function of coordination number rather than of a residue pair.
- **Five cells disagree with AAindex's own `MIYS960101` (2026-08-29)**, by 0.04 to 0.28: M–V, D–M,
  E–M, H–R and A–P. 205 of the 210 unique pairs agree exactly and the two matrices correlate at
  0.99978. Four of the five involve Met, Arg or His, which reads like a transcription slip on our
  side rather than a different edition. **Left byte-for-byte untouched** under the same rule as the
  MJ/Keskin file, and pinned by `tests/unit/test_aaindex.py`. It feeds no manuscript number:
  `\PotPinGenericFoldMax` takes the max over three generic potentials and that max is `mj`, not
  this one. `aaindex("MIYS960101")` is the curated alternative when one is wanted.
- Reference: Miyazawa S, Jernigan RL. *J Mol Biol.* 1996;256(3):623–644. doi:10.1006/jmbi.1996.0114
- Loader: `tcren.potential.mj1996()`.

## `MJ1985_partition_energies.csv` — published

Effective partition energies, one per residue — the one-body term a pairwise matrix cannot supply.
Sign convention is opposite to a contact energy: larger is more hydrophobic.

- Origin: AAindex accession `MIYS850101`, retrieved from two endpoints of the AAindex database that
  returned identical values.
- Re-fetch: <https://www.genome.jp/dbget-bin/www_bget?aaindex:MIYS850101>
- Independent check: correlates at r = +0.98 with the hydrophobicity axis
  `Potential.hydrophobicity_fit()` recovers from `MJ1996_contact_energies.csv`, which was
  transcribed from a different source — a transcription error would break that agreement.
- Reference: Miyazawa S, Jernigan RL. *Macromolecules.* 1985;18:534–552.
- Loader: `tcren.potential.mj_partition_energy()`.

## `aaindex3.txt` — published (upstream flat file, verbatim)

The whole of AAindex3, GenomeNet's section of statistical protein contact potentials: 47 records
over the 20 amino acids, each transcribed by its curators from a published table. Bundled as the
**upstream file itself** rather than a converted subset, so provenance is the record and a reader
can diff it against a fresh download.

- Origin: <https://www.genome.jp/ftp/db/community/aaindex/aaindex3> (80 kB), fetched 2026-08-29.
- Re-fetch: `curl -sL https://www.genome.jp/ftp/db/community/aaindex/aaindex3 -o src/tcren/data/aaindex3.txt`
- Contents by kind, as `potential.catalogue()` reports them: **42 contact energies**, 2 contact-count
  tables (`TANS760102`, `MIYS960103`) and 3 side-chain-distance tables (`BONM030104`–`BONM030106`).
  `potential.aaindex()` refuses the last two kinds, because scoring a contact map with a count table
  is a silent category error. Three `ZHAC*` entries are asymmetric by construction (row secondary
  structure vs column secondary structure) and must not be decomposed.
- Caveat carried in the code: **AAindex's `R` (PMID) field sometimes cites the paper that tabulated
  a matrix rather than the one that derived it** — `MIYS850102` carries Bastolla 2001. Verify before
  citing; every entry's own `A`/`T`/`J` fields are the authors, title and journal to check against.
- Licence: AAindex is distributed publicly by anonymous FTP/HTTPS from GenomeNet and its contents are
  taken from published literature. **Redistribution terms are not stated on the download page**, so
  this bundling is flagged rather than settled.
- Loaders: `tcren.potential.aaindex(accession)`, `entry()`, `catalogue()`, `identify()`.

## `BT1999_contact_energies.csv` — published

Betancourt–Thirumalai contact energies, the `B` matrix (RT units): Miyazawa–Jernigan re-referenced
with **Thr as the reference solvent**, so every Thr entry is exactly `0.00`.

- Origin: AAindex3 accession `BETM990101` ("Modified version of the Miyazawa-Jernigan transfer
  energy"), parsed from the raw record rather than retyped — lower-triangular over
  `ARNDCQEGHILKMFPSTWYV`, mirrored to a symmetric 20x20.
- Re-fetch: <https://www.genome.jp/dbget-bin/www_bget?aaindex3:BETM990101>
- Build-time checks: the Thr row is zero (the defining property of the reference state), the matrix
  is symmetric, all 400 cells present, range −1.34 (Cys–Cys) to +0.66.
- Reference state: pair-contact, mixed sign, mean −0.057 — the same kind as the bundled `MJ` matrix
  (mean −0.079) and **not** the same kind as `Keskin`/`MJ1996` (all-negative, mean ≈ −3.3). Compare
  like with like.
- Reference: Betancourt MR, Thirumalai D. *Protein Sci.* 1999;8(2):361–369. doi:10.1110/ps.8.2.361
- Loader: `tcren.potential.betancourt()`.

## `q_native_reference.csv` — derived

Native-crystal reference means and standard deviations for the Q interface-quality score, so Q is
defined for a single structure rather than only within a cohort.

- Origin: computed by us over the Canonical2026 native crystals.
- Loader: `tcren.cohort` (`q_score`).

## Kyte–Doolittle hydropathy — published (not a bundled file)

The 20 hydropathy values painted onto the ``phobic`` channel of a surface-topology map. Kept as a
literal in `src/tcren/surface.py` (`KYTE_DOOLITTLE`) rather than a CSV: twenty numbers that have not
changed since 1982.

- Origin: Kyte J, Doolittle RF. *A simple method for displaying the hydropathic character of a
  protein.* J Mol Biol. 1982;157(1):105–132. Table 1, the "hydropathy index" column.
- Independent check: r = +0.84 (n = 20) against the hydrophobicity axis
  `Potential.hydrophobicity_fit()` recovers from `MJ1996_contact_energies.csv` — the alternative
  scale `surface_map(..., scale="mj")` selects. Two unrelated derivations of the same axis, so a
  transcription slip would break the agreement rather than hide in it.
- Loader: `tcren.surface.KYTE_DOOLITTLE`.
