# README: Analysis provenance for "A coarse helix-geometry null accounts for the apparent membrane-centering of transmembrane coordination-number maxima"

This file lists, for every table and figure in the manuscript and its Supplement, the analysis step that produced it, and records the software versions and random seeds used throughout.

## Software versions

- Python 3.11.15
- numpy 2.4.6
- scipy 1.17.1
- pandas 3.0.3
- matplotlib 3.11.0
- gemmi 0.7.5 (structure parsing)
- biopython 1.87 (pairwise sequence alignment, BLOSUM62 substitution matrix)

## Random seeds

- Family-clustered permutation test, balanced resampling, and family-cluster bootstrap (GPCR-vs-non-GPCR secondary comparison, Fig 4/5, Table in Methods "Statistical tests"): `np.random.seed(42)` for the permutation test; `np.random.default_rng(123)` for balanced resampling; bootstrap resamples drawn with a fixed-seed `np.random.default_rng` call per analysis.
- Figure point-jitter (scatter-plot horizontal spread in Fig 4): `np.random.default_rng(1)`.
- All other analyses (coordination-number computation, surrogate construction, orientation determination, contact-source decomposition) are deterministic given the input structures and contain no random component.

## Main-text figures

| Figure | Content | Source data / script step |
|---|---|---|
| Fig 1 | Pipeline schematic (one GPCR + one non-GPCR example) | Manual figure construction from per-residue coordination-number profiles of PDB 4NTJ and 4H33 |
| Fig 2 | Observed coordination-number-maximum depth distribution (n=96) | S1_Table_v8.csv, column `pivot_packing_geomTM_strict` |
| Fig 3 | Surrogate reproduces aggregate centering; observed-vs-surrogate correlation | S1_Table_v8.csv (`pivot_surrogate_*` columns) and S3_Table_v8_surrogate_sensitivity.csv |
| Table 1 | Family-resolved paired comparison (observed vs. 30-point surrogate) | S2_Table_v8_family_resolved_comparison.csv |
| Fig 4 | GPCR-vs-non-GPCR coordination-number-maximum depth, full-chain metric | Full-chain pivot computation (pre-restriction), grouped by GPCR/non-GPCR |
| Fig 5 | GPCR-vs-non-GPCR effect-size attenuation under progressive restriction | Four-level restriction gradient: full-chain/all-TM, full-chain/geom-TM, TM-only-pool/all-TM, TM-only-pool/geom-TM (strictest) |
| Fig 6 | Contact-source decomposition (TM-TM fraction by family) | S5_Table_v8_contact_decomposition.csv |

## Supplementary tables

| File | Content |
|---|---|
| S1_Table_v8.csv | Per-structure results for all 96 analyzed structures: observed coordination-number-maximum depth and clarity; all four surrogate point-density variants (exact residue count, 20/30/40 points per segment); orientation source and three confidence dimensions (axis, center, sign); structure-audit outcome (identity/topology/family/assembly verified) |
| S2_Table_v8_family_resolved_comparison.csv | Family-resolved paired comparison: n, observed within +/-6 A %, surrogate (30-point) within +/-6 A %, median/mean paired depth difference, per family |
| S3_Table_v8_surrogate_sensitivity.csv | Surrogate point-density sensitivity: n, within +/-6/+/-9 A %, Spearman rho vs. observed, for each of the four point-density variants |
| S4_Table_v8_orientation_calibration.csv | PCA-vs-PDBTM orientation calibration: per-structure pivot depth under both orientation sources, absolute difference, family, group, for all structures with PDBTM coverage |
| S5_Table_v8_contact_decomposition.csv | Contact-source decomposition: TM-TM/TM-loop/TM-ECD/TM-ICD/TM-fusion contact fractions at the full-chain coordination-number maximum, per structure |
| S6_Table_v8_residual_exploratory.csv | Exploratory within-structure residual analysis (real coordination-number profile minus a per-structure geometric baseline, both z-scored); reported as exploratory only (Limitations), not used to support any claim in the main text |
| S6b_Table_v8_residual_missing.csv | The 12 structures excluded from the residual analysis (9 K_2TM, 3 VGIC_6TM) and the reason (insufficient common depth bins between the real and surrogate coordinate grids) |
| S_Audit_v8.csv | Complete structure identity/topology/family/assembly audit for all 97 originally assembled structures, including RCSB polymer-entity ID, assembly ID, resolution, experimental method, deposition date, and audit outcome |
| identity_matrix.csv | Full within-family pairwise sequence-identity matrix (599 pairs across 9 families), computed post hoc via global alignment (BLOSUM62, gap open -10, gap extend -0.5), percent identity = matches / aligned-length |
| identity_matrix_family_summary.csv | Per-family summary of the identity matrix: n pairs, mean/median/max identity, fraction of pairs exceeding 30% identity |
| selection_log.csv | Per-structure selection log: PDB ID, family, receptor/protein name, UniProt accession, experimental method, resolution, and family median sequence identity |

## Analysis pipeline overview

1. **Structure assembly and audit**: 97 structures assembled from RCSB PDB Pfam-clustered searches (see Methods, Structure set); systematic identity/topology/assembly audit (Methods, Structure identity and topology audit) corrected 10 errors, yielding the 96-structure analyzed set (one structure, 4G7V, excluded as an incomplete domain).
2. **Membrane orientation**: PDBTM/TMDET external placement where available (72/96), UniProt-topology-verified PCA fallback otherwise (24/96); PCA-vs-PDBTM calibration on the overlapping subset.
3. **Coordination-number computation**: Ca coordination number (10 A radius) computed per residue restricted to UniProt-annotated TM residues within a physically plausible +/-22 A window; depth-binned (3 A bins) to locate the coordination-number maximum.
4. **Straight-rod surrogate**: for each TM segment, fit a straight line (PCA first component) through its Ca coordinates; generate idealized points along this line under four point-density choices (exact residue count; fixed 20/30/40 points); recompute the coordination-number profile and its maximum on the surrogate point set.
5. **Family-resolved and sensitivity analysis**: paired observed-vs-surrogate comparison, tabulated per family (Table 1) and across the four point-density choices (Fig 3A, S3 Table).
6. **GPCR-specific secondary comparison**: full-chain (all-residue) coordination-number maximum computed for the same 96 structures; family-mean |depth| contrast (non-GPCR minus GPCR) computed under four progressively restricted definitions (full-chain/all-TM, full-chain/geom-TM, TM-only-pool/all-TM, TM-only-pool/geom-TM); family-cluster bootstrap 95% intervals (10,000 resamples) computed for each.
7. **Contact-source decomposition**: for the full-chain metric, every neighbor contact of a TM residue at its coordination-number maximum classified into TM-TM/TM-loop/TM-ECD/TM-ICD/TM-fusion categories using UniProt topological annotations and fusion/auxiliary-chain identification.
8. **Sequence-identity matrix**: post hoc computation (BLOSUM62 global alignment) of all within-family pairwise sequence identities, for full transparency about the structure set's actual sequence diversity.

## Reproducible analysis code

See `scripts/` (also archived as `analysis_code.zip`) for the full pipeline as standalone, runnable Python scripts (01_fetch_structures_and_audit.py through 06_stats_and_figures.py); see `scripts/SCRIPTS_README.md` for run order and requirements.