From 0ecb068c8187044067513807b9ed8ba1d1fdce66 Mon Sep 17 00:00:00 2001 From: Jiahui Chen Date: Wed, 18 Nov 2026 22:35:12 -0600 Subject: [PATCH] M3: define binding sites from what the homolog actually binds (#14) Part A of #14: pockets. Receptor preparation stays for a second change. The site needs no external tool and no network, because the evidence is already in hand. M2 names the ligands and metals bound in every qualifying PDB entry and M3 downloads that entry, so a pocket is the residues of our entity's chains within 4.5 A of the named component. - M2 now records the best qualifying homolog that binds something, which is often not the best-identity one, and carries metals into report.json at last: they were computed all along and stopped at the adapter, though pitfalls.md #2 is about exactly them. - M3 prefers that holo entry over a marginally closer apo one and records the swap and its identity cost in template_preference. On runs/mgen_G37 this is the difference between 14 and 42 of 50 selected proteins having a site to read. - A metal site is a site, flagged cofactor_required, because a predicted model will not carry the Mg or Zn and M4 must be told so. - A pocket whose own residues are poorly modelled is rejected on the pocket's mean pLDDT, not the model's global mean. Only for AlphaFold models, where B_iso holds pLDDT; in an experimental entry the same column is a B-factor and no confidence is claimed. - No site is invented. A protein whose homolog binds nothing gets no pocket and a stated reason, which is uncovered rather than pocket-free. P2Rank is where those go, discovered on PATH, and is not built yet. mmcif.py replaces quality.py's private atom-site parser so M3 reads coordinates in one place. Pocket records keep the key names 00-architecture.md fixed, with each residue carrying chain and author numbering, since a bare residue number is ambiguous across chains. Fixture 6MU0 is a real entry: M. genitalium ribose-5-phosphate isomerase B at 1.1 A with its substrate bound, trimmed to a 12 A shell. The site M3 reads from it is RpiB's active site, so the test checks against the literature rather than against our own output. Co-Authored-By: Claude Opus 5 --- docs/03-m3-fold.md | 37 +++- fixtures/m3/6MU0.cif | 369 ++++++++++++++++++++++++++++++++ fixtures/m3/README.md | 40 ++++ fixtures/report.fixture.json | 71 ++++++ s2f/common/schema.py | 56 ++++- s2f/full_report/render.py | 50 ++++- s2f/m2_triage/report_adapter.py | 26 +++ s2f/m2_triage/score.py | 19 ++ s2f/m3_fold/__main__.py | 28 +++ s2f/m3_fold/collect.py | 50 ++++- s2f/m3_fold/mmcif.py | 170 +++++++++++++++ s2f/m3_fold/pockets.py | 345 +++++++++++++++++++++++++++++ s2f/m3_fold/quality.py | 74 +------ tests/test_common_schema_io.py | 2 +- tests/test_m2_score.py | 59 +++++ tests/test_m3_collect.py | 53 +++++ tests/test_m3_dry_run.py | 35 ++- tests/test_m3_pockets.py | 197 +++++++++++++++++ 18 files changed, 1598 insertions(+), 83 deletions(-) create mode 100644 fixtures/m3/6MU0.cif create mode 100644 fixtures/m3/README.md create mode 100644 s2f/m3_fold/mmcif.py create mode 100644 s2f/m3_fold/pockets.py create mode 100644 tests/test_m3_pockets.py diff --git a/docs/03-m3-fold.md b/docs/03-m3-fold.md index 8adccea..94b62cd 100644 --- a/docs/03-m3-fold.md +++ b/docs/03-m3-fold.md @@ -21,18 +21,51 @@ | Pockets | **P2Rank** (fast, ML-based) and/or fpocket; align the holo template with US-align or TM-align to transfer its ligand site | | Optional biophysics | ProDy normal modes (flexibility), APBS for electrostatic surface — both cheap, both go in `analyses[]` | +## Pockets (issue #14) + +The primary method needs no external tool and no network, because the evidence is already in +hand. M2 names the ligands and metals bound in every qualifying PDB entry, and M3 downloads +that entry's coordinates, so the site is read out of the file M3 already has: the residues of +*our* entity's chains within **4.5 Å** of the named component's atoms. + +| Rule | Why | +| --- | --- | +| Only the components M2 named define a site | M2 already dropped waters, cryoprotectants and glycans (`classify_components`). M3 re-filters nothing by name. | +| At least 3 lining residues | Fewer is a surface brush, not a pocket. | +| Only our entity's chains line it | An entry can hold dozens of chains; a ligand bound to a neighbour is not our homolog's site. Chains come from `_struct_asym`. | +| A metal site is a site, flagged `cofactor_required` | pitfalls #2. A predicted model will not contain the Mg²⁺ or Zn²⁺, so M4 must be told the site is incomplete rather than dock into a hole. | +| A drug-like ligand outranks a metal | Both mark a real site; only the ligand shows the site takes a drug-sized molecule. | +| Reject a pocket whose own residues are poorly modelled | A pocket in a low-confidence region is not a pocket. Mean pLDDT over the pocket's residues, not the model's global mean. Only applied to AlphaFold models, where `B_iso_or_equiv` holds pLDDT; in an experimental entry the same column is a B-factor and no confidence is claimed. | + +**The template M3 collects is the one it reads the site from.** M2 records the best +qualifying hit *and* the best hit that binds something (`flags.holo_template`); these are +often not the same entry. M3 prefers the holo one, because a site to transfer is worth more +than the last points of sequence identity (pitfalls #2), and records the swap and its +`identity_drop` in `template_preference`. On `runs/mgen_G37` this is the difference between +14 and 42 of 50 selected proteins having anything to transfer. + +**No site is invented.** A site is only ever read from the entry that binds the component, so +no superposition is involved and `aligned_to_known_site` is true exactly when the collected +structure *is* that entry. A protein whose homolog binds nothing gets no pocket and a stated +reason — uncovered, not "no pocket exists", the distinction issue #90 draws. Those proteins +are what a detector such as P2Rank is for; `find_pockets` is where it plugs in, discovered on +`PATH` like M2's annotation providers rather than required. + ## Steps 1. `collect_existing()` — copy or download PDB/AFDB structures; prefer experimental, prefer holo. 2. `predict_missing()` — one job per protein; record model, version, seed. 3. `quality_gate()` — mean pLDDT and per-region confidence; trim or mask low-confidence tails; if the whole model is poor, set `usable_for_docking: false`. -4. `find_pockets()` — P2Rank; then, where a holo template exists, superpose and mark the pocket that matches the known ligand site. +4. `find_pockets()` — read the holo template's own site (above). P2Rank for the rest, and superposition for a site held in an entry other than the collected one, are not built yet. 5. `prep_receptors()` — protonation and PDBQT for M4, saved per protein. ## Acceptance checks - Every selected protein has a structure record or an explicit `usable_for_docking: false` with a reason. -- Pocket residues are written out, not just a score — M4 needs a box or residue list. +- Pocket residues are written out, not just a score — M4 needs a box or residue list. Each + residue carries chain and author numbering, because a bare residue number is ambiguous + once an entry has more than one chain. +- A protein with no pocket says which case it fell into, in `pocket_search.reason`. - 50 proteins complete within one working session; log wall-clock per protein. ## Pitfalls diff --git a/fixtures/m3/6MU0.cif b/fixtures/m3/6MU0.cif new file mode 100644 index 0000000..04c2c98 --- /dev/null +++ b/fixtures/m3/6MU0.cif @@ -0,0 +1,369 @@ +data_6MU0 +# +_entry.id 6MU0 +# +loop_ +_struct_asym.id +_struct_asym.entity_id +A 1 +B 2 +# +loop_ +_atom_site.group_PDB +_atom_site.id +_atom_site.label_atom_id +_atom_site.label_comp_id +_atom_site.label_asym_id +_atom_site.label_seq_id +_atom_site.auth_seq_id +_atom_site.auth_asym_id +_atom_site.Cartn_x +_atom_site.Cartn_y +_atom_site.Cartn_z +_atom_site.B_iso_or_equiv +_atom_site.pdbx_PDB_model_num +ATOM 1 N ALA A 16 8 A -16.556 12.314 11.076 7.19 1 +ATOM 2 CA ALA A 16 8 A -17.020 13.018 12.259 7.87 1 +ATOM 3 C ALA A 16 8 A -18.533 13.172 12.186 7.41 1 +ATOM 4 O ALA A 16 8 A -19.159 12.926 11.152 7.72 1 +ATOM 5 CB ALA A 16 8 A -16.334 14.373 12.434 8.19 1 +ATOM 6 N SER A 17 9 A -19.117 13.618 13.293 8.05 1 +ATOM 7 CA SER A 17 9 A -20.552 13.849 13.356 7.96 1 +ATOM 8 C SER A 17 9 A -20.809 14.973 14.344 8.00 1 +ATOM 9 O SER A 17 9 A -19.881 15.527 14.934 9.26 1 +ATOM 10 CB SER A 17 9 A -21.287 12.579 13.799 8.69 1 +ATOM 11 OG SER A 17 9 A -21.029 12.267 15.159 9.12 1 +ATOM 12 N ASP A 18 10 A -22.080 15.315 14.539 7.78 1 +ATOM 13 CA ASP A 18 10 A -22.461 15.976 15.775 8.60 1 +ATOM 14 C ASP A 18 10 A -23.056 14.942 16.729 8.24 1 +ATOM 15 O ASP A 18 10 A -22.997 13.728 16.488 8.14 1 +ATOM 16 CB ASP A 18 10 A -23.363 17.193 15.535 8.22 1 +ATOM 17 CG ASP A 18 10 A -24.776 16.827 15.100 7.83 1 +ATOM 18 OD1 ASP A 18 10 A -25.059 15.626 14.885 7.99 1 +ATOM 19 OD2 ASP A 18 10 A -25.603 17.769 14.966 8.43 1 +ATOM 20 N HIS A 19 11 A -23.636 15.432 17.827 8.19 1 +ATOM 21 CA HIS A 19 11 A -24.209 14.569 18.853 8.89 1 +ATOM 22 C HIS A 19 11 A -25.272 13.616 18.327 8.98 1 +ATOM 23 O HIS A 19 11 A -25.573 12.632 19.008 11.29 1 +ATOM 24 CB HIS A 19 11 A -24.840 15.419 19.959 9.58 1 +ATOM 25 CG HIS A 19 11 A -25.853 16.410 19.464 9.06 1 +ATOM 26 ND1 HIS A 19 11 A -25.519 17.699 19.105 9.46 1 +ATOM 27 CD2 HIS A 19 11 A -27.188 16.299 19.261 9.43 1 +ATOM 28 CE1 HIS A 19 11 A -26.605 18.340 18.704 9.93 1 +ATOM 29 NE2 HIS A 19 11 A -27.632 17.511 18.788 9.43 1 +ATOM 30 N THR A 20 12 A -25.872 13.890 17.164 8.18 1 +ATOM 31 CA THR A 20 12 A -26.940 13.026 16.668 8.82 1 +ATOM 32 C THR A 20 12 A -26.420 11.740 16.047 9.59 1 +ATOM 33 O THR A 20 12 A -27.221 10.838 15.785 11.04 1 +ATOM 34 CB THR A 20 12 A -27.810 13.738 15.615 9.10 1 +ATOM 35 OG1 THR A 20 12 A -27.071 13.892 14.396 8.68 1 +ATOM 36 CG2 THR A 20 12 A -28.294 15.095 16.100 10.53 1 +ATOM 37 N GLY A 21 13 A -25.122 11.640 15.783 9.74 1 +ATOM 38 CA GLY A 21 13 A -24.641 10.584 14.916 9.85 1 +ATOM 39 C GLY A 21 13 A -23.568 9.667 15.468 9.32 1 +ATOM 40 O GLY A 21 13 A -22.869 9.016 14.687 9.83 1 +ATOM 41 N LEU A 22 14 A -23.435 9.573 16.797 9.91 1 +ATOM 42 CA LEU A 22 14 A -22.308 8.831 17.361 10.45 1 +ATOM 43 C LEU A 22 14 A -22.397 7.334 17.083 10.07 1 +ATOM 44 O LEU A 22 14 A -21.375 6.693 16.804 10.37 1 +ATOM 45 CB LEU A 22 14 A -22.204 9.079 18.860 11.90 1 +ATOM 46 CG LEU A 22 14 A -22.039 10.547 19.249 16.00 1 +ATOM 47 CD1 LEU A 22 14 A -21.873 10.669 20.756 17.80 1 +ATOM 48 CD2 LEU A 22 14 A -20.859 11.159 18.520 17.82 1 +ATOM 49 N LEU A 24 16 A -23.973 5.736 14.580 10.17 1 +ATOM 50 CA LEU A 24 16 A -23.696 5.507 13.168 9.80 1 +ATOM 51 C LEU A 24 16 A -22.220 5.710 12.856 8.68 1 +ATOM 52 O LEU A 24 16 A -21.631 4.943 12.085 9.00 1 +ATOM 53 CB LEU A 24 16 A -24.557 6.437 12.323 9.44 1 +ATOM 54 CG LEU A 24 16 A -24.318 6.321 10.820 10.38 1 +ATOM 55 CD1 LEU A 24 16 A -24.675 4.931 10.300 10.82 1 +ATOM 56 CD2 LEU A 24 16 A -25.069 7.402 10.068 11.12 1 +ATOM 57 N PRO A 44 36 A -17.250 13.688 17.610 10.07 1 +ATOM 58 CA PRO A 44 36 A -17.006 13.645 19.056 10.97 1 +ATOM 59 C PRO A 44 36 A -16.890 12.218 19.588 9.92 1 +ATOM 60 O PRO A 44 36 A -17.350 11.263 18.964 10.09 1 +ATOM 61 CB PRO A 44 36 A -18.232 14.354 19.648 13.72 1 +ATOM 62 CG PRO A 44 36 A -19.259 14.294 18.625 14.03 1 +ATOM 63 CD PRO A 44 36 A -18.622 14.108 17.289 11.04 1 +ATOM 64 N PHE A 47 39 A -21.094 11.899 24.158 10.44 1 +ATOM 65 CA PHE A 47 39 A -22.329 12.580 23.804 10.22 1 +ATOM 66 C PHE A 47 39 A -22.475 13.906 24.546 10.04 1 +ATOM 67 O PHE A 47 39 A -22.393 13.959 25.781 10.92 1 +ATOM 68 CB PHE A 47 39 A -23.520 11.681 24.120 10.65 1 +ATOM 69 CG PHE A 47 39 A -24.836 12.306 23.781 10.23 1 +ATOM 70 CD1 PHE A 47 39 A -25.281 12.347 22.468 10.57 1 +ATOM 71 CD2 PHE A 47 39 A -25.627 12.869 24.771 10.44 1 +ATOM 72 CE1 PHE A 47 39 A -26.495 12.930 22.150 10.70 1 +ATOM 73 CE2 PHE A 47 39 A -26.836 13.464 24.455 10.36 1 +ATOM 74 CZ PHE A 47 39 A -27.270 13.493 23.141 10.41 1 +ATOM 75 N ASP A 48 40 A -22.737 14.964 23.781 9.69 1 +ATOM 76 CA ASP A 48 40 A -23.078 16.286 24.301 10.36 1 +ATOM 77 C ASP A 48 40 A -24.272 16.764 23.488 10.00 1 +ATOM 78 O ASP A 48 40 A -24.111 17.148 22.326 9.91 1 +ATOM 79 CB ASP A 48 40 A -21.899 17.245 24.137 11.60 1 +ATOM 80 CG ASP A 48 40 A -22.239 18.691 24.496 13.31 1 +ATOM 81 OD1 ASP A 48 40 A -23.403 19.005 24.820 12.85 1 +ATOM 82 OD2 ASP A 48 40 A -21.317 19.527 24.439 17.22 1 +ATOM 83 N ALA A 49 41 A -25.458 16.749 24.103 9.88 1 +ATOM 84 CA ALA A 49 41 A -26.707 17.034 23.398 10.15 1 +ATOM 85 C ALA A 49 41 A -26.704 18.383 22.694 10.12 1 +ATOM 86 O ALA A 49 41 A -27.521 18.591 21.791 10.39 1 +ATOM 87 CB ALA A 49 41 A -27.879 17.005 24.376 12.32 1 +ATOM 88 N ASN A 50 42 A -25.828 19.303 23.098 10.03 1 +ATOM 89 CA ASN A 50 42 A -25.832 20.666 22.582 10.31 1 +ATOM 90 C ASN A 50 42 A -24.689 20.974 21.624 10.18 1 +ATOM 91 O ASN A 50 42 A -24.559 22.131 21.208 10.63 1 +ATOM 92 CB ASN A 50 42 A -25.818 21.647 23.746 12.71 1 +ATOM 93 CG ASN A 50 42 A -26.909 21.347 24.729 14.07 1 +ATOM 94 OD1 ASN A 50 42 A -28.072 21.219 24.344 15.03 1 +ATOM 95 ND2 ASN A 50 42 A -26.542 21.157 25.993 16.54 1 +ATOM 96 N ASP A 51 43 A -23.866 19.989 21.257 9.25 1 +ATOM 97 CA ASP A 51 43 A -22.688 20.316 20.453 9.53 1 +ATOM 98 C ASP A 51 43 A -23.074 20.715 19.028 8.50 1 +ATOM 99 O ASP A 51 43 A -24.213 20.543 18.587 9.00 1 +ATOM 100 CB ASP A 51 43 A -21.584 19.251 20.558 9.80 1 +ATOM 101 CG ASP A 51 43 A -21.898 17.943 19.840 9.30 1 +ATOM 102 OD1 ASP A 51 43 A -22.854 17.872 19.042 9.75 1 +ATOM 103 OD2 ASP A 51 43 A -21.135 16.980 20.089 10.35 1 +ATOM 104 N ASP A 52 44 A -22.100 21.280 18.315 8.49 1 +ATOM 105 CA ASP A 52 44 A -22.355 22.081 17.120 9.26 1 +ATOM 106 C ASP A 52 44 A -21.706 21.436 15.899 8.70 1 +ATOM 107 O ASP A 52 44 A -20.475 21.397 15.795 9.63 1 +ATOM 108 CB ASP A 52 44 A -21.807 23.501 17.305 9.63 1 +ATOM 109 CG ASP A 52 44 A -22.562 24.307 18.351 10.36 1 +ATOM 110 OD1 ASP A 52 44 A -23.672 23.908 18.766 10.13 1 +ATOM 111 OD2 ASP A 52 44 A -22.031 25.367 18.744 13.03 1 +ATOM 112 N TYR A 53 45 A -22.533 21.002 14.946 8.19 1 +ATOM 113 CA TYR A 53 45 A -22.020 20.322 13.756 8.53 1 +ATOM 114 C TYR A 53 45 A -20.939 21.087 12.990 7.97 1 +ATOM 115 O TYR A 53 45 A -20.050 20.423 12.436 8.63 1 +ATOM 116 CB TYR A 53 45 A -23.164 19.874 12.822 8.80 1 +ATOM 117 CG TYR A 53 45 A -23.898 21.040 12.232 8.97 1 +ATOM 118 CD1 TYR A 53 45 A -23.439 21.669 11.079 9.14 1 +ATOM 119 CD2 TYR A 53 45 A -25.016 21.564 12.868 9.38 1 +ATOM 120 CE1 TYR A 53 45 A -24.069 22.794 10.583 9.17 1 +ATOM 121 CE2 TYR A 53 45 A -25.670 22.678 12.368 9.91 1 +ATOM 122 CZ TYR A 53 45 A -25.190 23.294 11.225 9.53 1 +ATOM 123 OH TYR A 53 45 A -25.810 24.418 10.712 10.67 1 +ATOM 124 N PRO A 54 46 A -20.937 22.426 12.885 8.47 1 +ATOM 125 CA PRO A 54 46 A -19.864 23.051 12.092 8.88 1 +ATOM 126 C PRO A 54 46 A -18.484 22.742 12.617 8.87 1 +ATOM 127 O PRO A 54 46 A -17.541 22.608 11.827 9.55 1 +ATOM 128 CB PRO A 54 46 A -20.169 24.552 12.177 9.65 1 +ATOM 129 CG PRO A 54 46 A -21.623 24.606 12.409 9.97 1 +ATOM 130 CD PRO A 54 46 A -21.905 23.452 13.338 9.07 1 +ATOM 131 N ASP A 55 47 A -18.331 22.626 13.937 9.04 1 +ATOM 132 CA ASP A 55 47 A -17.010 22.366 14.490 9.53 1 +ATOM 133 C ASP A 55 47 A -16.440 21.078 13.926 10.02 1 +ATOM 134 O ASP A 55 47 A -15.270 21.018 13.528 11.06 1 +ATOM 135 CB ASP A 55 47 A -17.095 22.306 16.017 10.81 1 +ATOM 136 CG ASP A 55 47 A -17.457 23.651 16.634 12.39 1 +ATOM 137 OD1 ASP A 55 47 A -16.984 24.690 16.123 14.93 1 +ATOM 138 OD2 ASP A 55 47 A -18.191 23.670 17.642 14.55 1 +ATOM 139 N PHE A 56 48 A -17.274 20.049 13.837 8.95 1 +ATOM 140 CA PHE A 56 48 A -16.829 18.751 13.357 9.19 1 +ATOM 141 C PHE A 56 48 A -16.733 18.703 11.840 8.54 1 +ATOM 142 O PHE A 56 48 A -15.831 18.046 11.298 9.07 1 +ATOM 143 CB PHE A 56 48 A -17.741 17.686 13.957 9.93 1 +ATOM 144 CG PHE A 56 48 A -17.634 17.645 15.451 10.96 1 +ATOM 145 CD1 PHE A 56 48 A -16.539 17.034 16.045 13.32 1 +ATOM 146 CD2 PHE A 56 48 A -18.552 18.300 16.264 13.07 1 +ATOM 147 CE1 PHE A 56 48 A -16.381 17.029 17.416 14.96 1 +ATOM 148 CE2 PHE A 56 48 A -18.400 18.292 17.647 15.41 1 +ATOM 149 CZ PHE A 56 48 A -17.312 17.656 18.216 15.82 1 +ATOM 150 N ALA A 57 49 A -17.625 19.413 11.144 8.48 1 +ATOM 151 CA ALA A 57 49 A -17.518 19.505 9.694 8.05 1 +ATOM 152 C ALA A 57 49 A -16.191 20.123 9.291 8.24 1 +ATOM 153 O ALA A 57 49 A -15.530 19.635 8.369 8.61 1 +ATOM 154 CB ALA A 57 49 A -18.677 20.325 9.132 8.95 1 +ATOM 155 N LEU A 75 67 A -19.318 12.852 6.935 7.08 1 +ATOM 156 CA LEU A 75 67 A -19.881 13.725 7.955 7.20 1 +ATOM 157 C LEU A 75 67 A -21.349 13.386 8.164 7.21 1 +ATOM 158 O LEU A 75 67 A -22.094 13.171 7.201 7.79 1 +ATOM 159 CB LEU A 75 67 A -19.744 15.197 7.568 7.19 1 +ATOM 160 CG LEU A 75 67 A -18.332 15.746 7.753 7.90 1 +ATOM 161 CD1 LEU A 75 67 A -18.166 17.067 7.000 8.12 1 +ATOM 162 CD2 LEU A 75 67 A -18.020 15.896 9.235 8.90 1 +ATOM 163 N ILE A 76 68 A -21.754 13.356 9.433 7.13 1 +ATOM 164 CA ILE A 76 68 A -23.091 12.941 9.825 7.50 1 +ATOM 165 C ILE A 76 68 A -23.753 14.007 10.695 7.33 1 +ATOM 166 O ILE A 76 68 A -23.158 14.473 11.666 8.05 1 +ATOM 167 CB ILE A 76 68 A -23.035 11.617 10.619 7.99 1 +ATOM 168 CG1 ILE A 76 68 A -22.418 10.479 9.800 8.30 1 +ATOM 169 CG2 ILE A 76 68 A -24.406 11.245 11.136 9.19 1 +ATOM 170 CD1 ILE A 76 68 A -21.713 9.443 10.666 9.72 1 +HETATM 171 N CSD A 77 69 A -24.987 14.385 10.366 7.30 1 +HETATM 172 CA CSD A 77 69 A -25.800 15.188 11.260 7.62 1 +HETATM 173 CB CSD A 77 69 A -25.514 16.693 11.138 8.15 1 +HETATM 174 SG CSD A 77 69 A -25.853 17.385 9.550 8.42 1 +HETATM 175 C CSD A 77 69 A -27.262 14.798 11.047 7.05 1 +HETATM 176 O CSD A 77 69 A -27.545 13.892 10.270 7.62 1 +HETATM 177 OD1 CSD A 77 69 A -25.421 18.786 9.715 9.87 1 +HETATM 178 OD2 CSD A 77 69 A -27.512 17.407 9.542 9.69 1 +ATOM 179 N GLY A 78 70 A -28.199 15.450 11.740 7.22 1 +ATOM 180 CA GLY A 78 70 A -29.602 15.058 11.676 7.37 1 +ATOM 181 C GLY A 78 70 A -30.127 14.800 10.271 7.41 1 +ATOM 182 O GLY A 78 70 A -30.717 13.743 10.008 7.42 1 +ATOM 183 N THR A 79 71 A -29.919 15.759 9.366 7.75 1 +ATOM 184 CA THR A 79 71 A -30.391 15.654 7.988 7.98 1 +ATOM 185 C THR A 79 71 A -29.264 15.532 6.972 7.37 1 +ATOM 186 O THR A 79 71 A -29.530 15.176 5.819 7.84 1 +ATOM 187 CB THR A 79 71 A -31.211 16.890 7.607 8.14 1 +ATOM 188 OG1 THR A 79 71 A -30.367 18.035 7.764 8.08 1 +ATOM 189 CG2 THR A 79 71 A -32.475 17.017 8.453 8.83 1 +ATOM 190 N GLY A 80 72 A -28.025 15.833 7.367 7.60 1 +ATOM 191 CA GLY A 80 72 A -26.905 15.976 6.463 7.97 1 +ATOM 192 C GLY A 80 72 A -26.688 17.383 5.938 7.28 1 +ATOM 193 O GLY A 80 72 A -25.626 17.662 5.378 8.08 1 +ATOM 194 N VAL A 81 73 A -27.662 18.280 6.102 6.83 1 +ATOM 195 CA VAL A 81 73 A -27.598 19.586 5.446 7.18 1 +ATOM 196 C VAL A 81 73 A -26.495 20.457 6.031 7.19 1 +ATOM 197 O VAL A 81 73 A -25.735 21.091 5.292 8.14 1 +ATOM 198 CB VAL A 81 73 A -28.961 20.291 5.530 7.90 1 +ATOM 199 CG1 VAL A 81 73 A -28.830 21.755 5.124 8.57 1 +ATOM 200 CG2 VAL A 81 73 A -29.980 19.583 4.670 9.04 1 +ATOM 201 N GLY A 82 74 A -26.441 20.561 7.359 7.15 1 +ATOM 202 CA GLY A 82 74 A -25.532 21.512 7.978 8.19 1 +ATOM 203 C GLY A 82 74 A -24.074 21.205 7.703 7.25 1 +ATOM 204 O GLY A 82 74 A -23.295 22.093 7.334 7.83 1 +ATOM 205 N VAL A 83 75 A -23.684 19.939 7.876 7.50 1 +ATOM 206 CA VAL A 83 75 A -22.303 19.559 7.592 7.64 1 +ATOM 207 C VAL A 83 75 A -21.977 19.740 6.120 7.60 1 +ATOM 208 O VAL A 83 75 A -20.831 20.037 5.769 8.03 1 +ATOM 209 CB VAL A 83 75 A -21.993 18.123 8.066 8.11 1 +ATOM 210 CG1 VAL A 83 75 A -22.080 18.010 9.580 8.43 1 +ATOM 211 CG2 VAL A 83 75 A -22.886 17.090 7.365 8.41 1 +ATOM 212 N CYS A 84 76 A -22.967 19.571 5.236 7.49 1 +ATOM 213 CA CYS A 84 76 A -22.742 19.776 3.807 7.73 1 +ATOM 214 C CYS A 84 76 A -22.490 21.249 3.496 7.53 1 +ATOM 215 O CYS A 84 76 A -21.563 21.580 2.745 8.28 1 +ATOM 216 CB CYS A 84 76 A -23.934 19.224 3.023 8.23 1 +ATOM 217 SG CYS A 84 76 A -23.824 19.359 1.253 11.75 1 +ATOM 218 N MET A 85 77 A -23.308 22.148 4.061 7.91 1 +ATOM 219 CA MET A 85 77 A -23.077 23.584 3.888 8.15 1 +ATOM 220 CA MET A 85 77 A -23.068 23.573 3.859 8.17 1 +ATOM 221 C MET A 85 77 A -21.690 23.966 4.371 8.03 1 +ATOM 222 O MET A 85 77 A -20.938 24.670 3.682 9.24 1 +ATOM 223 CB MET A 85 77 A -24.085 24.383 4.715 9.08 1 +ATOM 224 CB MET A 85 77 A -24.149 24.405 4.550 9.02 1 +ATOM 225 CG MET A 85 77 A -25.523 24.333 4.270 9.50 1 +ATOM 226 CG MET A 85 77 A -25.563 24.116 4.089 9.78 1 +ATOM 227 SD MET A 85 77 A -26.531 25.194 5.494 9.18 1 +ATOM 228 SD MET A 85 77 A -26.746 25.355 4.659 9.23 1 +ATOM 229 CE MET A 85 77 A -28.107 25.272 4.642 10.36 1 +ATOM 230 CE MET A 85 77 A -26.505 25.277 6.432 9.61 1 +ATOM 231 N ALA A 86 78 A -21.348 23.525 5.579 7.89 1 +ATOM 232 CA ALA A 86 78 A -20.075 23.892 6.185 8.67 1 +ATOM 233 C ALA A 86 78 A -18.900 23.318 5.404 8.25 1 +ATOM 234 O ALA A 86 78 A -17.955 24.042 5.067 8.84 1 +ATOM 235 CB ALA A 86 78 A -20.046 23.415 7.637 8.72 1 +ATOM 236 N ALA A 87 79 A -18.943 22.020 5.090 8.16 1 +ATOM 237 CA ALA A 87 79 A -17.817 21.404 4.396 8.15 1 +ATOM 238 C ALA A 87 79 A -17.569 22.061 3.046 8.43 1 +ATOM 239 O ALA A 87 79 A -16.417 22.236 2.638 8.57 1 +ATOM 240 CB ALA A 87 79 A -18.043 19.903 4.243 8.74 1 +ATOM 241 N LEU A 97 89 A -24.516 15.524 -0.246 7.34 1 +ATOM 242 CA LEU A 97 89 A -25.499 14.985 0.683 7.53 1 +ATOM 243 CA LEU A 97 89 A -25.508 14.994 0.679 7.23 1 +ATOM 244 C LEU A 97 89 A -26.246 13.850 -0.009 7.07 1 +ATOM 245 O LEU A 97 89 A -26.891 14.057 -1.043 7.61 1 +ATOM 246 CB LEU A 97 89 A -26.459 16.081 1.145 8.73 1 +ATOM 247 CB LEU A 97 89 A -26.482 16.107 1.062 7.62 1 +ATOM 248 CG LEU A 97 89 A -27.633 15.638 2.025 9.80 1 +ATOM 249 CG LEU A 97 89 A -27.128 16.017 2.445 8.52 1 +ATOM 250 CD1 LEU A 97 89 A -27.188 14.745 3.175 10.51 1 +ATOM 251 CD1 LEU A 97 89 A -28.015 17.228 2.696 8.95 1 +ATOM 252 CD2 LEU A 97 89 A -28.394 16.847 2.559 11.22 1 +ATOM 253 CD2 LEU A 97 89 A -27.909 14.726 2.635 9.09 1 +ATOM 254 N VAL A 98 90 A -26.144 12.649 0.555 7.14 1 +ATOM 255 CA VAL A 98 90 A -26.771 11.461 -0.011 7.41 1 +ATOM 256 C VAL A 98 90 A -27.629 10.823 1.070 7.63 1 +ATOM 257 O VAL A 98 90 A -27.119 10.469 2.141 7.57 1 +ATOM 258 CB VAL A 98 90 A -25.733 10.451 -0.530 8.21 1 +ATOM 259 CG1 VAL A 98 90 A -26.426 9.220 -1.078 8.81 1 +ATOM 260 CG2 VAL A 98 90 A -24.826 11.075 -1.581 8.43 1 +ATOM 261 N VAL A 99 91 A -28.921 10.645 0.775 8.87 1 +ATOM 262 CA VAL A 99 91 A -29.869 10.021 1.689 8.97 1 +ATOM 263 C VAL A 99 91 A -30.502 8.762 1.109 10.18 1 +ATOM 264 O VAL A 99 91 A -31.378 8.174 1.737 12.83 1 +ATOM 265 CB VAL A 99 91 A -30.932 11.008 2.213 9.78 1 +ATOM 266 CG1 VAL A 99 91 A -30.273 12.079 3.061 10.98 1 +ATOM 267 CG2 VAL A 99 91 A -31.748 11.620 1.071 11.54 1 +ATOM 268 N CYS A 117 109 A -21.910 13.359 2.967 7.20 1 +ATOM 269 CA CYS A 117 109 A -22.723 13.846 4.073 7.13 1 +ATOM 270 C CYS A 117 109 A -23.970 12.984 4.200 7.27 1 +ATOM 271 O CYS A 117 109 A -24.641 12.701 3.196 7.77 1 +ATOM 272 CB CYS A 117 109 A -23.106 15.308 3.852 7.46 1 +ATOM 273 SG CYS A 117 109 A -21.647 16.379 3.704 8.50 1 +ATOM 274 N LEU A 118 110 A -24.272 12.583 5.439 6.85 1 +ATOM 275 CA LEU A 118 110 A -25.290 11.591 5.744 7.06 1 +ATOM 276 C LEU A 118 110 A -26.216 12.106 6.837 6.63 1 +ATOM 277 O LEU A 118 110 A -25.824 12.907 7.695 7.48 1 +ATOM 278 CB LEU A 118 110 A -24.655 10.294 6.261 7.32 1 +ATOM 279 CG LEU A 118 110 A -23.615 9.636 5.358 8.03 1 +ATOM 280 CD1 LEU A 118 110 A -22.973 8.454 6.057 8.57 1 +ATOM 281 CD2 LEU A 118 110 A -24.232 9.211 4.040 8.78 1 +ATOM 282 N SER A 119 111 A -27.438 11.589 6.810 6.74 1 +ATOM 283 CA SER A 119 111 A -28.474 11.874 7.793 7.14 1 +ATOM 284 C SER A 119 111 A -28.524 10.790 8.865 7.03 1 +ATOM 285 O SER A 119 111 A -28.674 9.605 8.549 8.22 1 +ATOM 286 CB SER A 119 111 A -29.823 11.909 7.081 7.38 1 +ATOM 287 OG SER A 119 111 A -30.900 11.960 8.001 7.92 1 +ATOM 288 N SER A 120 112 A -28.473 11.205 10.129 7.31 1 +ATOM 289 CA SER A 120 112 A -28.636 10.297 11.254 8.06 1 +ATOM 290 C SER A 120 112 A -30.091 10.095 11.658 8.48 1 +ATOM 291 O SER A 120 112 A -30.406 9.070 12.270 9.19 1 +ATOM 292 CB SER A 120 112 A -27.892 10.845 12.469 8.76 1 +ATOM 293 OG SER A 120 112 A -28.419 12.113 12.796 8.96 1 +ATOM 294 N ARG A 121 113 A -30.977 11.052 11.363 7.44 1 +ATOM 295 CA ARG A 121 113 A -32.347 11.017 11.862 8.04 1 +ATOM 296 C ARG A 121 113 A -33.361 10.509 10.847 8.46 1 +ATOM 297 O ARG A 121 113 A -34.474 10.151 11.247 9.18 1 +ATOM 298 CB ARG A 121 113 A -32.776 12.407 12.343 8.28 1 +ATOM 299 CG ARG A 121 113 A -32.188 12.786 13.680 8.88 1 +ATOM 300 CD ARG A 121 113 A -32.538 14.215 14.070 9.66 1 +ATOM 301 NE ARG A 121 113 A -32.157 14.487 15.451 9.74 1 +ATOM 302 CZ ARG A 121 113 A -31.823 15.675 15.934 9.00 1 +ATOM 303 NH1 ARG A 121 113 A -31.773 16.738 15.139 9.52 1 +ATOM 304 NH2 ARG A 121 113 A -31.534 15.787 17.223 9.68 1 +ATOM 305 N PHE A 122 114 A -33.014 10.472 9.557 8.16 1 +ATOM 306 CA PHE A 122 114 A -33.983 10.189 8.508 8.67 1 +ATOM 307 C PHE A 122 114 A -33.596 9.019 7.622 9.24 1 +ATOM 308 O PHE A 122 114 A -34.358 8.673 6.710 10.64 1 +ATOM 309 CB PHE A 122 114 A -34.232 11.450 7.670 9.38 1 +ATOM 310 CG PHE A 122 114 A -34.942 12.514 8.437 8.92 1 +ATOM 311 CD1 PHE A 122 114 A -36.329 12.527 8.498 10.53 1 +ATOM 312 CD2 PHE A 122 114 A -34.234 13.477 9.147 8.92 1 +ATOM 313 CE1 PHE A 122 114 A -36.995 13.485 9.224 11.59 1 +ATOM 314 CE2 PHE A 122 114 A -34.906 14.437 9.887 9.78 1 +ATOM 315 CZ PHE A 122 114 A -36.289 14.437 9.925 10.84 1 +ATOM 316 N VAL A 123 115 A -32.449 8.400 7.873 8.62 1 +ATOM 317 CA VAL A 123 115 A -31.934 7.297 7.074 8.91 1 +ATOM 318 C VAL A 123 115 A -31.459 6.229 8.049 9.50 1 +ATOM 319 O VAL A 123 115 A -30.872 6.551 9.087 9.11 1 +ATOM 320 CB VAL A 123 115 A -30.791 7.784 6.155 8.90 1 +ATOM 321 CG1 VAL A 123 115 A -30.175 6.632 5.375 9.60 1 +ATOM 322 CG2 VAL A 123 115 A -31.299 8.859 5.196 9.20 1 +ATOM 323 N ASN A 128 120 A -27.419 3.767 5.347 8.84 1 +ATOM 324 CA ASN A 128 120 A -26.206 4.579 5.377 8.70 1 +ATOM 325 C ASN A 128 120 A -24.958 3.753 5.068 8.16 1 +ATOM 326 O ASN A 128 120 A -24.061 4.226 4.366 8.78 1 +ATOM 327 CB ASN A 128 120 A -26.108 5.334 6.700 8.39 1 +ATOM 328 CG ASN A 128 120 A -26.849 6.654 6.650 8.36 1 +ATOM 329 OD1 ASN A 128 120 A -26.812 7.340 5.629 9.00 1 +ATOM 330 ND2 ASN A 128 120 A -27.532 7.012 7.741 9.13 1 +HETATM 331 C2 5RP B . 201 A -28.072 20.142 10.919 11.20 1 +HETATM 332 C3 5RP B . 201 A -28.671 19.028 11.753 10.64 1 +HETATM 333 C5 5RP B . 201 A -28.254 18.950 13.230 9.19 1 +HETATM 334 O13 5RP B . 201 A -27.845 17.638 13.565 8.66 1 +HETATM 335 C6 5RP B . 201 A -29.514 19.352 14.000 9.17 1 +HETATM 336 O14 5RP B . 201 A -29.876 20.675 13.609 9.32 1 +HETATM 337 C7 5RP B . 201 A -29.322 19.281 15.499 9.32 1 +HETATM 338 O8 5RP B . 201 A -30.614 19.436 16.114 9.00 1 +HETATM 339 P9 5RP B . 201 A -30.726 19.456 17.714 9.02 1 +HETATM 340 O12 5RP B . 201 A -32.192 19.625 17.994 9.82 1 +HETATM 341 O11 5RP B . 201 A -30.169 18.128 18.215 9.19 1 +HETATM 342 O10 5RP B . 201 A -29.880 20.608 18.222 9.67 1 +HETATM 343 O4 5RP B . 201 A -29.489 18.246 11.315 10.49 1 +HETATM 344 O1 5RP B . 201 A -28.558 20.086 9.583 12.51 1 +# diff --git a/fixtures/m3/README.md b/fixtures/m3/README.md new file mode 100644 index 0000000..e9c7d33 --- /dev/null +++ b/fixtures/m3/README.md @@ -0,0 +1,40 @@ +# M3 structure fixtures + +Real files, trimmed. Nothing here is synthetic, so a test that passes against them is a test +against the mmCIF the RCSB actually serves. + +| File | Entry | What it is | Trimming | +| --- | --- | --- | --- | +| `1YDX.cif` | [1YDX](https://www.rcsb.org/structure/1YDX) | Type-I restriction-modification S subunit, *M. genitalium*. Apo: the entry binds nothing. | Header only. It exists so the collector has a file to fetch; no geometry is read from it. | +| `7P6Z.cif` | [7P6Z](https://www.rcsb.org/structure/7P6Z) | *M. pneumoniae* ribosome. Supplies two ribosomal-protein entities. | Header only, as above. | +| `6MU0.cif` | [6MU0](https://www.rcsb.org/structure/6MU0) | Probable ribose-5-phosphate isomerase B, *M. genitalium* G37, 1.1 Å, with ribose-5-phosphate (`5RP`) bound. The holo case issue #14 turns on. | Atoms within 12 Å of the ligand, waters dropped. 344 atoms of 1,447. | + +`6MU0_1` is a real hit for `fig|243273.25.peg.463` in `runs/mgen_G37`: 100% identity over full +coverage. The pocket M3 reads from it — Asp10, His11, Thr12 and the rest of the lining — +is RpiB's active site, so the expected result in `tests/test_m3_pockets.py` is checkable +against the literature rather than against our own output. + +## Regenerating `6MU0.cif` + +A 12 Å shell is enough for a 4.5 Å contact cutoff and keeps the fixture small. To rebuild it: + +```python +from math import sqrt +from s2f.m3_fold.mmcif import read_atoms + +payload = open("6MU0.cif", "rb").read() # from https://files.rcsb.org/download/6MU0.cif +atoms = [a for a in read_atoms(payload) if a.has_coordinates and a.comp_id != "HOH"] +ligand = [a for a in atoms if a.comp_id == "5RP"] +near = lambda a: min(sqrt((a.x - l.x) ** 2 + (a.y - l.y) ** 2 + (a.z - l.z) ** 2) for l in ligand) +keep = {(a.chain, a.seq_id, a.auth_seq_id) for a in atoms if near(a) <= 12.0} +``` + +then write the kept atoms back as an `_atom_site` loop, with the `_struct_asym` loop that +says which chains belong to which entity. The trimmed file keeps author numbering, so the +residue numbers in the tests are the ones the PDB entry uses. + +## What these fixtures cannot test + +They are single-model, single-conformer excerpts. Alternate locations, multiple models and +assembly generation are untested here, and a structure whose site spans a crystallographic +symmetry mate would need the full entry. diff --git a/fixtures/report.fixture.json b/fixtures/report.fixture.json index d99c261..2f94adf 100644 --- a/fixtures/report.fixture.json +++ b/fixtures/report.fixture.json @@ -391,6 +391,77 @@ "selected": false, "reason": "no qualifying PDB hit; uncharacterized product" } + }, + { + "feature_id": "fig|243273.25.peg.463", + "locus_tag": "MG_438", + "product": "Ribose-5-phosphate isomerase B (EC 5.3.1.6)", + "aa_length": null, + "xrefs": { + "uniprot": "Q49434", + "uniparc": null, + "route": "proteome_checksum", + "afdb": "AF-Q49434-F1", + "pdb": [ + "6MU0" + ], + "chembl_target": [], + "refseq": [], + "gene_name": null, + "related_uniprot": [] + }, + "flags": { + "virulence": false, + "amr": false, + "essential_ortholog": false, + "human_homolog": false, + "human_homolog_identity": null, + "secreted": null, + "membrane": null, + "experimental_homolog": { + "pdb_entity": "6MU0_1", + "identity": 1.0, + "coverage": 1.0, + "resolution": 1.1, + "method": "X-ray", + "holo": true, + "ligands": [ + "5RP" + ], + "metals": [], + "organism": "Mycoplasmoides genitalium G37" + }, + "holo_template": { + "pdb_entity": "6MU0_1", + "identity": 1.0, + "coverage": 1.0, + "resolution": 1.1, + "method": "X-ray", + "holo": true, + "ligands": [ + "5RP" + ], + "metals": [], + "organism": "Mycoplasmoides genitalium G37", + "is_best_hit": true, + "identity_drop": 0.0 + } + }, + "triage": { + "score": 0.65, + "components": { + "pdb_evidence": 0.875, + "virulence_amr": 0.0, + "essential": 0.0, + "drug_target": 0.0, + "annotation_gap": 1.0, + "human_homolog_penalty": 0.0 + }, + "weights_version": "2026-09-16", + "rank": 1, + "selected": true, + "reason": "PDB 1YDX_1 identity 100%, coverage 100%, 2.30 A; uncharacterized product" + } } ], "kg": { diff --git a/s2f/common/schema.py b/s2f/common/schema.py index ea70ea3..453b888 100644 --- a/s2f/common/schema.py +++ b/s2f/common/schema.py @@ -245,7 +245,61 @@ "path": {"type": ["string", "null"]}, "confidence": {"type": ["number", "string", "null"]}, "holo_template": {"type": ["object", "null"]}, - "pockets": {"type": "array"}, + # One binding site for M4 (#14). `residues` is the contract: M4 needs a + # residue list or a box, never a score alone. `cofactor_required` carries + # pitfalls.md #2 forward -- a site whose cofactor a model lacks is incomplete. + "pockets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": {"type": "string", "minLength": 1}, + "method": {"type": "string", "minLength": 1}, + "component": {"type": ["string", "null"]}, + "component_kind": { + "type": ["string", "null"], + "enum": ["ligand", "metal", None], + }, + # M3 writes one object per residue, because a bare number is + # ambiguous once an entry has more than one chain. Plain + # integers remain valid for records written before #14. + "residues": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "chain": {"type": "string"}, + "seq_id": {"type": ["integer", "null"]}, + "auth_seq_id": {"type": ["string", "null"]}, + "comp_id": {"type": "string"}, + }, + "required": ["chain"], + "additionalProperties": True, + }, + {"type": "integer"}, + ] + }, + }, + "score": {"type": ["number", "null"]}, + "center": { + "type": ["array", "null"], + "items": {"type": "number"}, + "minItems": 3, + "maxItems": 3, + }, + "aligned_to_known_site": {"type": "boolean"}, + "cofactor_required": {"type": "boolean"}, + "usable": {"type": "boolean"}, + "reason": {"type": ["string", "null"]}, + "confidence": {"type": ["number", "null"]}, + }, + "required": ["id", "method", "residues", "aligned_to_known_site"], + "additionalProperties": True, + }, + }, + "pocket_search": {"type": ["object", "null"]}, "usable_for_docking": {"type": ["boolean", "null"]}, "reason": {"type": ["string", "null"]}, }, diff --git a/s2f/full_report/render.py b/s2f/full_report/render.py index 6dc6710..175c9ec 100644 --- a/s2f/full_report/render.py +++ b/s2f/full_report/render.py @@ -561,18 +561,33 @@ def tab_structures(report: dict[str, Any]) -> str: if key not in keys: keys.append(key) usable = sum(1 for row in structures if row.get("usable") is True) + with_pocket = sum(1 for row in structures if row.get("pockets")) + cofactor = sum(1 for row in structures for pocket in _rows(row.get("pockets")) + if pocket.get("cofactor_required")) out = ["

Structures

", f"

{len(structures)} collected" + (f", {usable} passing the quality gate" if usable else "") + + f", {with_pocket} with a defined pocket" + ". Existing PDB and AlphaFold models are reused; nothing here is a new " - "prediction unless a row says so.

", + "prediction unless a row says so." + + (f" {cofactor} pocket(s) need a cofactor the structure may not carry, so the " + "site is incomplete without it." if cofactor else "") + + " A protein with no pocket has not been shown to lack one: the reason column " + "says which case it fell into.

", "
" + "".join(f"" for k in keys) + ""] for row in structures: - out.append("" + "".join( - f"" - for k in keys) + "") + cells = [] + for key in keys: + value = row.get(key) + if key == "pockets": + cells.append(f"") + elif isinstance(value, (dict, list)): + cells.append(f"") + else: + cells.append(f"") + out.append("" + "".join(cells) + "") out.append("
{esc(k.replace('_', ' '))}
{esc(_fmt(row.get(k)) if not isinstance(row.get(k), (dict, list)) else json.dumps(row.get(k))[:120])}
{_pocket_cell(row)}{esc(json.dumps(value)[:120])}{esc(_fmt(value))}
") return "".join(out) @@ -837,3 +852,30 @@ def render_run(run_dir: str | Path) -> str: def _genome_length(genome: dict) -> object: """Top-level since #71; runs written before that only carry it under quality.""" return genome.get("genome_length") or _mapping(genome.get("quality")).get("genome_length") + + +def _pocket_cell(structure: dict[str, Any]) -> str: + """Pockets as something a reader can act on, not a truncated JSON dump (#14).""" + pockets = _rows(structure.get("pockets")) + if not pockets: + reason = _mapping(structure.get("pocket_search")).get("reason") + return f"none — {esc(str(reason))}" if reason else "" + parts = [] + for pocket in pockets: + residues = _rows(pocket.get("residues")) + label = esc(str(pocket.get("component") or pocket.get("id") or "site")) + bits = [f"{label}", f"{len(residues)} residues"] + if pocket.get("cofactor_required"): + bits.append("needs cofactor") + if pocket.get("usable") is False: + bits.append("rejected") + lining = ", ".join( + f"{residue.get('comp_id', '')}{residue.get('auth_seq_id', '')}" + for residue in residues[:6] + ) + line = " · ".join(bits) + if lining: + line += f"
{esc(lining)}" + line += "…" if len(residues) > 6 else "" + parts.append(line) + return "
" + "
".join(parts) + "
" diff --git a/s2f/m2_triage/report_adapter.py b/s2f/m2_triage/report_adapter.py index 024980e..3de786f 100644 --- a/s2f/m2_triage/report_adapter.py +++ b/s2f/m2_triage/report_adapter.py @@ -211,6 +211,7 @@ def protein_enrichment( ) -> dict[str, Any]: """The `xrefs` / `annotations` / `flags` / `triage` fields for one protein.""" top = score.best_hit + holo = score.holo_hit retrieved = _now() annotations: list[dict[str, Any]] = [] @@ -289,11 +290,36 @@ def protein_enrichment( "method": top.experimental_method or None, "holo": bool(top.ligands), "ligands": list(top.ligands), + # Metals are not a ligand bonus, but a metal in the homolog's site is + # what M3 must flag as a cofactor the model lacks (pitfalls.md #2). + # They were computed all along and stopped here, never reaching M3. + "metals": list(top.metals), "organism": top.organism or None, } if top is not None else None ), + # The best qualifying homolog that binds something, which is not always the + # best-identity one. M3 transfers a site from this entry's own coordinates + # (#14); `identity_drop` is what preferring it costs in sequence match. + "holo_template": ( + { + "pdb_entity": holo.entity_id, + "identity": round(holo.identity, 4), + "coverage": round(holo.query_coverage, 4), + "resolution": holo.resolution, + "method": holo.experimental_method or None, + "ligands": list(holo.ligands), + "metals": list(holo.metals), + "organism": holo.organism or None, + "is_best_hit": top is not None and holo.entity_id == top.entity_id, + "identity_drop": ( + round(top.identity - holo.identity, 4) if top is not None else None + ), + } + if holo is not None + else None + ), "predicted_model": ( { "source": "afdb", diff --git a/s2f/m2_triage/score.py b/s2f/m2_triage/score.py index 4af9213..8ec8a69 100644 --- a/s2f/m2_triage/score.py +++ b/s2f/m2_triage/score.py @@ -110,6 +110,21 @@ def best_hit(hits: list[SequenceHit]) -> SequenceHit | None: return max(qualifying, key=lambda hit: (hit_score(hit), hit.bitscore)) +def best_holo_hit(hits: list[SequenceHit]) -> SequenceHit | None: + """Best qualifying hit whose entry binds something, or None. + + M3 transfers a binding site from this entry's own coordinates (issue #14), so what + matters is that *some* qualifying homolog is holo, not that the best-identity one is. + A drug-like ligand outranks a metal: both mark a real site, but only the ligand shows + the site accommodates a drug-sized molecule. Metal-only entries are still returned, + because a cofactor site is what pitfalls.md #2 asks M3 to flag rather than discard. + """ + qualifying = [hit for hit in hits if hit_qualifies(hit) and (hit.ligands or hit.metals)] + if not qualifying: + return None + return max(qualifying, key=lambda hit: (bool(hit.ligands), hit_score(hit), hit.bitscore)) + + @dataclass class TriageComponents: """The scored components, written to proteins.tsv so scoring is reproducible.""" @@ -138,6 +153,8 @@ class ProteinScore: score: float retrieval_status: str best_hit: SequenceHit | None = None + #: Best qualifying hit that binds a ligand or metal, for M3's site transfer (#14). + holo_hit: SequenceHit | None = None distinct_entries: int = 0 qualifying_hits: int = 0 flags: dict[str, object] = field(default_factory=dict) @@ -187,6 +204,7 @@ def score_protein( """ qualifying = [hit for hit in hits if hit_qualifies(hit)] top = best_hit(hits) + holo = best_holo_hit(hits) pdb_evidence = (hit_score(top) / MAX_HIT_SCORE) if top is not None else 0.0 if human_identity is None: @@ -302,6 +320,7 @@ def score_protein( score=triage_score_from_components(components, weights), retrieval_status=retrieval_status, best_hit=top, + holo_hit=holo, distinct_entries=len({hit.entry_id for hit in qualifying}), qualifying_hits=len(qualifying), flags=flags, diff --git a/s2f/m3_fold/__main__.py b/s2f/m3_fold/__main__.py index edef361..6415d43 100644 --- a/s2f/m3_fold/__main__.py +++ b/s2f/m3_fold/__main__.py @@ -162,6 +162,34 @@ def _write_manifest( "quality_pending": sum( record.get("usable_for_docking") is None for record in summary.structures ), + # #14: how many selected proteins M3 could define a site for, and how many it + # could not. A protein with no pocket is uncovered, not pocket-free. + "with_pocket": sum(1 for record in summary.structures if record.get("pockets")), + "pockets": sum(len(record.get("pockets") or []) for record in summary.structures), + "usable_pockets": sum( + 1 + for record in summary.structures + for pocket in record.get("pockets") or [] + if pocket.get("usable") + ), + "cofactor_required_pockets": sum( + 1 + for record in summary.structures + for pocket in record.get("pockets") or [] + if pocket.get("cofactor_required") + ), + "no_pocket": dict( + sorted( + Counter( + (record.get("pocket_search") or {}).get("reason", "") + for record in summary.structures + if not record.get("pockets") + ).items() + ) + ), + "holo_template_preferred": sum( + 1 for record in summary.structures if record.get("template_preference") + ), }, "failures": [ {"feature_id": record["feature_id"], "reason": record.get("reason")} diff --git a/s2f/m3_fold/collect.py b/s2f/m3_fold/collect.py index 734004b..26c4bb3 100644 --- a/s2f/m3_fold/collect.py +++ b/s2f/m3_fold/collect.py @@ -14,6 +14,7 @@ from urllib.parse import urlparse from ..common.http import DownloadedFile +from .pockets import find_pockets from .quality import QualityThresholds, assess_structure PDB_DOWNLOAD_URL = "https://files.rcsb.org/download/{entry_id}.cif" @@ -35,6 +36,12 @@ class StructureCandidate: confidence_metric: str experimental_homolog: dict[str, Any] | None = None predicted_model: dict[str, Any] | None = None + #: M2's best ligand- or metal-bearing qualifying homolog, which M3 reads a binding site + #: from when it is the entry collected here (#14). + holo_template: dict[str, Any] | None = None + #: Set when the holo template was preferred over the best-identity hit, with what the + #: swap cost in sequence identity. + template_preference: dict[str, Any] | None = None @property def suffix(self) -> str: @@ -70,17 +77,36 @@ def choose_existing(protein: dict[str, Any]) -> StructureCandidate | None: flags = protein.get("flags") or {} experimental = flags.get("experimental_homolog") + holo = flags.get("holo_template") + holo = dict(holo) if isinstance(holo, dict) and holo.get("pdb_entity") else None + if isinstance(experimental, dict) and experimental.get("pdb_entity"): - entity = str(experimental["pdb_entity"]) - entry_id = _pdb_entry_id(entity) + chosen, preference = dict(experimental), None + # A pocket can only be read from an entry that binds something, so a holo homolog is + # worth more here than the last few points of sequence identity (pitfalls.md #2). + # The swap is recorded, never silent: it trades sequence match for site evidence. + if holo is not None and not holo.get("is_best_hit"): + chosen = holo + preference = { + "policy": "prefer_holo_over_best_identity", + "best_identity_entity": experimental.get("pdb_entity"), + "best_identity": experimental.get("identity"), + "chosen_entity": holo.get("pdb_entity"), + "chosen_identity": holo.get("identity"), + "identity_drop": holo.get("identity_drop"), + "binds": [*(holo.get("ligands") or []), *(holo.get("metals") or [])], + } + entity = str(chosen["pdb_entity"]) return StructureCandidate( feature_id=feature_id, source="pdb", accession=entity, - url=PDB_DOWNLOAD_URL.format(entry_id=entry_id), - confidence=_number_or_none(experimental.get("resolution")), + url=PDB_DOWNLOAD_URL.format(entry_id=_pdb_entry_id(entity)), + confidence=_number_or_none(chosen.get("resolution")), confidence_metric="resolution_angstrom", - experimental_homolog=dict(experimental), + experimental_homolog=chosen, + holo_template=holo, + template_preference=preference, ) predicted = flags.get("predicted_model") @@ -93,6 +119,7 @@ def choose_existing(protein: dict[str, Any]) -> StructureCandidate | None: confidence=_number_or_none(predicted.get("mean_plddt")), confidence_metric="mean_plddt", predicted_model=dict(predicted), + holo_template=holo, ) # The richer flags above are preferred, but tolerate a report containing only xrefs. @@ -176,6 +203,15 @@ def collect_existing( ) quality = assess_structure(candidate.source, evidence, payload, quality_thresholds) record["params"]["confidence_gate_applied"] = True + pockets, pocket_summary = find_pockets( + payload, + source=candidate.source, + holo_template=candidate.holo_template, + structure_accession=candidate.accession, + min_plddt=quality_thresholds.min_local_plddt, + ) + record["pockets"] = pockets + record["pocket_search"] = pocket_summary record.update( path=str(destination.relative_to(run_dir)), sha256=hashlib.sha256(payload).hexdigest(), @@ -218,9 +254,11 @@ def _candidate_record(candidate: StructureCandidate) -> dict[str, Any]: "format": candidate.suffix.lstrip("."), "confidence_gate_applied": False, }, - "holo_template": None, + "holo_template": candidate.holo_template, "pockets": [], } + if candidate.template_preference is not None: + record["template_preference"] = candidate.template_preference if candidate.experimental_homolog is not None: record["experimental_homolog"] = candidate.experimental_homolog if candidate.predicted_model is not None: diff --git a/s2f/m3_fold/mmcif.py b/s2f/m3_fold/mmcif.py new file mode 100644 index 0000000..7002fc9 --- /dev/null +++ b/s2f/m3_fold/mmcif.py @@ -0,0 +1,170 @@ +"""A small read-only mmCIF loop reader, shared by M3's quality gate and pocket finder. + +Deliberately not a structure library. It reads the two loops M3 needs — ``_atom_site`` for +coordinates and confidence, ``_struct_asym`` for the chains an entity owns — and returns +rows of strings. A file it cannot parse yields no rows, so the caller fails an auditable +check rather than silently passing on a structure nobody read. +""" + +from __future__ import annotations + +import shlex +from dataclasses import dataclass + + +@dataclass(frozen=True) +class Loop: + """One mmCIF ``loop_`` as column names plus rows of raw string values.""" + + headers: list[str] + rows: list[list[str]] + + def column(self, name: str) -> int | None: + try: + return self.headers.index(name) + except ValueError: + return None + + def value(self, row: list[str], name: str) -> str | None: + index = self.column(name) + if index is None or index >= len(row): + return None + token = row[index] + return None if token in {".", "?"} else token + + +def read_loop(payload: bytes, required_column: str) -> Loop: + """The first ``loop_`` carrying ``required_column``, or an empty loop. + + ``required_column`` is a full mmCIF tag, for example ``_atom_site.Cartn_x``. A tag ending + in ``.`` matches any column in that category, which is how the atom-site loop is found + whether or not the file carries coordinates. Values are returned exactly as written; + quoting is resolved and numbers are not converted, because which columns are numeric + differs between the loops this reads. + """ + lines = payload.decode("utf-8", errors="replace").splitlines() + index = 0 + while index < len(lines): + if lines[index].strip() != "loop_": + index += 1 + continue + + index += 1 + headers: list[str] = [] + while index < len(lines) and lines[index].lstrip().startswith("_"): + headers.append(lines[index].split()[0]) + index += 1 + if required_column.endswith("."): + if not any(header.startswith(required_column) for header in headers): + continue + elif required_column not in headers: + continue + + tokens: list[str] = [] + while index < len(lines): + line = lines[index].strip() + if line in {"#", "loop_"} or line.startswith("_") or line.startswith("data_"): + break + if line: + try: + tokens.extend(shlex.split(line, comments=False, posix=True)) + except ValueError: + return Loop([], []) + index += 1 + + width = len(headers) + if not width or len(tokens) % width: + return Loop([], []) + rows = [tokens[start : start + width] for start in range(0, len(tokens), width)] + return Loop(headers, rows) + return Loop([], []) + + +@dataclass(frozen=True) +class Atom: + """One atom-site row, reduced to what M3 asks of it.""" + + is_hetatm: bool + chain: str + auth_chain: str + comp_id: str + seq_id: int | None + auth_seq_id: str | None + atom_id: str + #: None when the file carries no coordinate columns; geometry skips such atoms. + x: float | None + y: float | None + z: float | None + b_factor: float | None + + @property + def has_coordinates(self) -> bool: + return None not in (self.x, self.y, self.z) + + +def read_atoms(payload: bytes, *, first_model_only: bool = True) -> list[Atom]: + """Every atom of the first model, or an empty list if the file cannot be read.""" + loop = read_loop(payload, "_atom_site.") + if not loop.rows: + return [] + + atoms: list[Atom] = [] + for row in loop.rows: + if first_model_only: + model = loop.value(row, "_atom_site.pdbx_PDB_model_num") + if model is not None and model != "1": + continue + coordinates: list[float | None] = [] + for axis in ("Cartn_x", "Cartn_y", "Cartn_z"): + token = loop.value(row, f"_atom_site.{axis}") + try: + coordinates.append(float(token) if token is not None else None) + except ValueError: + coordinates.append(None) + x, y, z = coordinates + chain = loop.value(row, "_atom_site.label_asym_id") or "" + auth_chain = loop.value(row, "_atom_site.auth_asym_id") or chain + seq_token = loop.value(row, "_atom_site.label_seq_id") + try: + seq_id = int(seq_token) if seq_token is not None else None + except ValueError: + seq_id = None + b_token = loop.value(row, "_atom_site.B_iso_or_equiv") + try: + b_factor = float(b_token) if b_token is not None else None + except ValueError: + b_factor = None + atoms.append( + Atom( + is_hetatm=(loop.value(row, "_atom_site.group_PDB") or "ATOM").upper() == "HETATM", + chain=chain, + auth_chain=auth_chain, + comp_id=(loop.value(row, "_atom_site.label_comp_id") or "").upper(), + seq_id=seq_id, + auth_seq_id=loop.value(row, "_atom_site.auth_seq_id"), + atom_id=loop.value(row, "_atom_site.label_atom_id") or "", + x=x, + y=y, + z=z, + b_factor=b_factor, + ) + ) + return atoms + + +def entity_chains(payload: bytes, entity_id: str) -> set[str]: + """``label_asym_id`` values belonging to one entity, from ``_struct_asym``. + + An RCSB entry often holds many copies and many different chains; a ligand bound to a + neighbouring entity is not our homolog's site. An empty set means the file does not say, + and the caller must decide whether to fall back to every chain. + """ + loop = read_loop(payload, "_struct_asym.entity_id") + if not loop.rows or not entity_id: + return set() + return { + asym + for row in loop.rows + if (loop.value(row, "_struct_asym.entity_id") or "") == str(entity_id) + and (asym := loop.value(row, "_struct_asym.id")) + } diff --git a/s2f/m3_fold/pockets.py b/s2f/m3_fold/pockets.py new file mode 100644 index 0000000..ca2551a --- /dev/null +++ b/s2f/m3_fold/pockets.py @@ -0,0 +1,345 @@ +"""Binding sites for M4, transferred from what the homolog entry actually binds (issue #14). + +The primary method needs no external tool and no network. M2 names the ligands and metals +bound in each qualifying PDB entry, and M3 has already downloaded that entry's coordinates, +so the site is read straight out of the file: the residues of *our* entity's chains within a +cutoff of the named component's atoms. + +What this deliberately does not do: + +- It does not invent a pocket. A protein whose homolog binds nothing gets no pocket from + here and is reported as uncovered, never as "no pocket exists" (the distinction issue #90 + draws). P2Rank fills that gap when it is installed; `find_pockets` is where it plugs in. +- It does not transfer a site between different coordinate frames. A site is only read from + the structure M3 collected, so no superposition is involved and none is implied. The + `aligned_to_known_site` flag the contract asks for is therefore true exactly when the + collected structure *is* the entry that binds the component. +- It does not treat a metal as a drug site. A metal marks a real site, and a predicted model + will not contain the metal, which is the failure pitfalls.md #2 is about: those pockets + carry `cofactor_required` so M4 and M6 can say so rather than dock into a hole. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from math import sqrt +from typing import Any, Iterable + +from .mmcif import Atom, entity_chains, read_atoms + +#: Residues with any atom within this distance of a bound component line its site. 4.5 A is +#: the usual first-shell contact distance; it is recorded in every pocket's `params`. +CONTACT_DISTANCE = 4.5 + +#: Fewer contacts than this is a surface brush, not a pocket. +MIN_POCKET_RESIDUES = 3 + +#: Below this mean pLDDT over the pocket's own residues the site is not trustworthy, whatever +#: the model's global score says: pitfalls.md says a pocket in a low-confidence region is not +#: a pocket. Matches QualityThresholds.min_local_plddt. +MIN_POCKET_PLDDT = 70.0 + + +@dataclass(frozen=True) +class PocketResidue: + chain: str + seq_id: int | None + auth_seq_id: str | None + comp_id: str + min_distance: float + #: The mmCIF B_iso_or_equiv column as written: a real B-factor in an experimental entry, + #: pLDDT in an AlphaFold model. Named for the column, not for either meaning. + b_iso: float | None + + def as_dict(self) -> dict[str, Any]: + record = { + "chain": self.chain, + "seq_id": self.seq_id, + "auth_seq_id": self.auth_seq_id, + "comp_id": self.comp_id, + "min_distance": round(self.min_distance, 2), + } + if self.b_iso is not None: + record["b_iso"] = round(self.b_iso, 2) + return record + + +@dataclass +class Pocket: + """One binding site, with the evidence that produced it.""" + + pocket_id: str + method: str + component: str + component_kind: str + residues: list[PocketResidue] + center: tuple[float, float, float] | None + aligned_to_known_site: bool + cofactor_required: bool + cofactor_present: bool + usable: bool = True + reason: str = "" + #: A detector's own score, where the method has one. Site transfer does not: the site is + #: observed in the entry, not predicted, so there is nothing to score. + score: float | None = None + confidence: float | None = None + params: dict[str, Any] = field(default_factory=dict) + + def as_dict(self) -> dict[str, Any]: + return { + # `id`, `method`, `residues`, `score` and `aligned_to_known_site` are the keys + # docs/00-architecture.md fixed for this record; the rest is added evidence. + "id": self.pocket_id, + "method": self.method, + "score": self.score, + "component": self.component, + "component_kind": self.component_kind, + "residues": [residue.as_dict() for residue in self.residues], + "residue_count": len(self.residues), + "center": ( + [round(value, 3) for value in self.center] if self.center is not None else None + ), + "aligned_to_known_site": self.aligned_to_known_site, + "cofactor_required": self.cofactor_required, + "cofactor_present": self.cofactor_present, + "usable": self.usable, + "reason": self.reason, + "confidence": round(self.confidence, 2) if self.confidence is not None else None, + "params": dict(self.params), + } + + +def _residue_key(atom: Atom) -> tuple[str, int | None, str | None, str]: + return (atom.chain, atom.seq_id, atom.auth_seq_id, atom.comp_id) + + +def _distance(left: Atom, right: Atom) -> float: + return sqrt( + (left.x - right.x) ** 2 + (left.y - right.y) ** 2 + (left.z - right.z) ** 2 + ) + + +def _component_groups( + atoms: Iterable[Atom], names: set[str] +) -> dict[tuple[str, int | None, str | None, str], list[Atom]]: + """Group the atoms of each named component copy, keyed by its residue identity.""" + groups: dict[tuple[str, int | None, str | None, str], list[Atom]] = {} + for atom in atoms: + if atom.is_hetatm and atom.comp_id in names and atom.has_coordinates: + groups.setdefault(_residue_key(atom), []).append(atom) + return groups + + +def find_holo_sites( + payload: bytes, + *, + ligands: Iterable[str] = (), + metals: Iterable[str] = (), + entity_id: str = "", + contact_distance: float = CONTACT_DISTANCE, + min_residues: int = MIN_POCKET_RESIDUES, + structure_is_template: bool = True, +) -> list[Pocket]: + """Sites lining the components M2 named, strongest first. + + `ligands` and `metals` come from `report.json`, where M2 already dropped waters, + cryoprotectants and glycans, so nothing here re-filters chemistry by name. + + `entity_id` restricts the lining residues to the chains of our homolog's entity. Without + it every chain is eligible, which on a large assembly can return a neighbour's site. + + `structure_is_template` is false when the coordinates are a predicted model rather than + the entry that binds the component. The site is then not present in the file at all, so + no pocket can be read from it; the caller gets an empty list rather than a guess. + """ + ligand_names = {name.upper() for name in ligands if name} + metal_names = {name.upper() for name in metals if name} + if not structure_is_template or not (ligand_names | metal_names): + return [] + + atoms = read_atoms(payload) + if not atoms: + return [] + + chains = entity_chains(payload, entity_id) if entity_id else set() + polymer = [ + atom + for atom in atoms + if not atom.is_hetatm and atom.has_coordinates and (not chains or atom.chain in chains) + ] + if not polymer: + return [] + + groups = _component_groups(atoms, ligand_names | metal_names) + metals_in_file = { + key[3] for key in _component_groups(atoms, metal_names) + } + + pockets: list[Pocket] = [] + for key, component_atoms in groups.items(): + chain, _, auth_seq_id, comp_id = key + kind = "ligand" if comp_id in ligand_names else "metal" + + nearest: dict[tuple[str, int | None, str | None, str], tuple[float, Atom]] = {} + for atom in polymer: + best = None + for other in component_atoms: + distance = _distance(atom, other) + if best is None or distance < best: + best = distance + if best is None or best > contact_distance: + continue + residue_key = _residue_key(atom) + if residue_key not in nearest or best < nearest[residue_key][0]: + nearest[residue_key] = (best, atom) + + if len(nearest) < min_residues: + continue + + residues = sorted( + ( + PocketResidue( + chain=atom.auth_chain or atom.chain, + seq_id=atom.seq_id, + auth_seq_id=atom.auth_seq_id, + comp_id=atom.comp_id, + min_distance=distance, + b_iso=atom.b_factor, + ) + for distance, atom in nearest.values() + ), + key=lambda residue: (residue.chain, residue.seq_id or 0, residue.auth_seq_id or ""), + ) + center = ( + sum(atom.x for atom in component_atoms) / len(component_atoms), + sum(atom.y for atom in component_atoms) / len(component_atoms), + sum(atom.z for atom in component_atoms) / len(component_atoms), + ) + # A metal site needs its metal; a ligand site whose entry also holds a metal may need + # that too. Either way the question is whether a model would carry it (pitfalls #2). + needs_cofactor = kind == "metal" or bool(metals_in_file) + pockets.append( + Pocket( + pocket_id=f"{comp_id}_{chain}{auth_seq_id or ''}", + method="holo_site_transfer", + component=comp_id, + component_kind=kind, + residues=residues, + center=center, + # True because the site was read from the entry that binds the component, + # not aligned from somewhere else. + aligned_to_known_site=True, + cofactor_required=needs_cofactor, + cofactor_present=True, + params={ + "contact_distance": contact_distance, + "min_residues": min_residues, + "entity_id": entity_id or None, + "entity_chains": sorted(chains) or None, + "metals_in_entry": sorted(metals_in_file) or None, + }, + ) + ) + + pockets.sort( + key=lambda pocket: (pocket.component_kind != "ligand", -len(pocket.residues)) + ) + return pockets + + +def reject_low_confidence( + pockets: list[Pocket], + *, + source: str, + min_plddt: float = MIN_POCKET_PLDDT, +) -> list[Pocket]: + """Mark pockets whose own residues are poorly modelled as unusable. + + Only meaningful where the B-factor column holds pLDDT, which is AlphaFold's convention; + for an experimental entry the column is a real B-factor and no confidence claim is made. + """ + for pocket in pockets: + scored = [ + residue.b_iso for residue in pocket.residues if residue.b_iso is not None + ] + if source != "afdb" or not scored: + continue + mean_plddt = sum(scored) / len(scored) + pocket.confidence = mean_plddt + pocket.params["min_pocket_plddt"] = min_plddt + if mean_plddt < min_plddt: + pocket.usable = False + pocket.reason = ( + f"mean pLDDT {mean_plddt:.1f} over the pocket's own residues is below " + f"{min_plddt:.0f}; a pocket in a low-confidence region is not a pocket" + ) + return pockets + + +def find_pockets( + payload: bytes, + *, + source: str, + holo_template: dict[str, Any] | None, + structure_accession: str = "", + contact_distance: float = CONTACT_DISTANCE, + min_plddt: float = MIN_POCKET_PLDDT, +) -> tuple[list[dict[str, Any]], dict[str, Any]]: + """Every pocket M3 can define for one collected structure, plus how it got there. + + Returns the pocket records for `structures[].pockets` and a summary naming the method + used and why, so a protein with no pocket says which case it fell into rather than + looking like one nobody looked at. + """ + template = holo_template or {} + entity = str(template.get("pdb_entity") or "") + # Only the entry that binds the component holds the site. M3 collects one structure per + # protein, so this is true when that structure is the holo entry itself. + is_template = bool(entity) and _same_entry(entity, structure_accession) + + pockets = find_holo_sites( + payload, + ligands=template.get("ligands") or (), + metals=template.get("metals") or (), + entity_id=entity.split("_", 1)[1] if "_" in entity else "", + contact_distance=contact_distance, + structure_is_template=is_template, + ) + reject_low_confidence(pockets, source=source, min_plddt=min_plddt) + + usable = [pocket for pocket in pockets if pocket.usable] + summary: dict[str, Any] = { + "method": "holo_site_transfer", + "pockets": len(pockets), + "usable": len(usable), + "holo_template": entity or None, + "template_is_collected_structure": is_template, + } + if not pockets: + summary["status"] = "no_pocket" + summary["reason"] = _no_pocket_reason(template, entity, is_template) + else: + summary["status"] = "ok" if usable else "all_rejected" + return [pocket.as_dict() for pocket in pockets], summary + + +def _same_entry(entity_id: str, accession: str) -> bool: + """Whether an entity such as ``1YDX_1`` names the same entry as a collected accession.""" + if not accession: + return False + return entity_id.split("_", 1)[0].upper() == accession.split("_", 1)[0].upper() + + +def _no_pocket_reason(template: dict[str, Any], entity: str, is_template: bool) -> str: + if not entity: + return ( + "no qualifying homolog binds a ligand or metal; a pocket detector such as " + "P2Rank is required for this protein and none ran" + ) + if not is_template: + return ( + f"the binding site is in {entity}, which is not the structure collected here; " + "transferring it needs a superposition M3 does not yet do" + ) + bound = ", ".join([*(template.get("ligands") or []), *(template.get("metals") or [])]) + return f"no residue of our entity lines {bound or 'the bound components'} in this entry" diff --git a/s2f/m3_fold/quality.py b/s2f/m3_fold/quality.py index c45b24a..e143c72 100644 --- a/s2f/m3_fold/quality.py +++ b/s2f/m3_fold/quality.py @@ -8,10 +8,10 @@ from __future__ import annotations -import shlex from dataclasses import asdict, dataclass from typing import Any +from .mmcif import read_atoms POLICY_VERSION = "provisional-2026-09-17" @@ -242,71 +242,15 @@ def _maximum_check(metric: str, value: float | None, threshold: float) -> dict[s def _mmcif_residue_plddt(payload: bytes) -> list[tuple[str, int, float]]: """Read one pLDDT value per residue from an AlphaFold mmCIF atom-site loop. - AlphaFold stores pLDDT in ``_atom_site.B_iso_or_equiv``. CA atoms are used so each residue - appears once. The small parser is intentionally limited to this standard atom-site loop; - malformed or non-AlphaFold files return no values and fail the auditable local-confidence - check instead of silently passing. + AlphaFold stores pLDDT in ``_atom_site.B_iso_or_equiv``. CA atoms are used so each + residue appears once. A file the shared reader cannot parse yields no values and fails + the auditable local-confidence check instead of silently passing. """ - lines = payload.decode("utf-8", errors="replace").splitlines() - index = 0 - while index < len(lines): - if lines[index].strip() != "loop_": - index += 1 - continue - - index += 1 - headers: list[str] = [] - while index < len(lines) and lines[index].lstrip().startswith("_"): - headers.append(lines[index].split()[0]) - index += 1 - if "_atom_site.B_iso_or_equiv" not in headers: - continue - - data_tokens: list[str] = [] - while index < len(lines): - line = lines[index].strip() - if line == "#" or line == "loop_" or line.startswith("_"): - break - if line: - try: - data_tokens.extend(shlex.split(line, comments=False, posix=True)) - except ValueError: - return [] - index += 1 - return _atom_site_plddt_rows(headers, data_tokens) - return [] - - -def _atom_site_plddt_rows( - headers: list[str], tokens: list[str] -) -> list[tuple[str, int, float]]: - width = len(headers) - if not width or len(tokens) % width: - return [] - - positions = {name: index for index, name in enumerate(headers)} - atom_column = positions.get("_atom_site.label_atom_id") - sequence_column = positions.get("_atom_site.label_seq_id") - chain_column = positions.get("_atom_site.label_asym_id") - confidence_column = positions.get("_atom_site.B_iso_or_equiv") - model_column = positions.get("_atom_site.pdbx_PDB_model_num") - if None in {atom_column, sequence_column, chain_column, confidence_column}: - return [] - - residues: list[tuple[str, int, float]] = [] - for start in range(0, len(tokens), width): - row = tokens[start : start + width] - if model_column is not None and row[model_column] not in {"1", ".", "?"}: - continue - if row[atom_column].upper() != "CA": - continue - try: - sequence_id = int(row[sequence_column]) - confidence = float(row[confidence_column]) - except (TypeError, ValueError): - continue - residues.append((row[chain_column], sequence_id, confidence)) - return residues + return [ + (atom.chain, atom.seq_id, atom.b_factor) + for atom in read_atoms(payload) + if atom.atom_id.upper() == "CA" and atom.seq_id is not None and atom.b_factor is not None + ] def _low_confidence_regions( diff --git a/tests/test_common_schema_io.py b/tests/test_common_schema_io.py index 27e6a35..297b41a 100644 --- a/tests/test_common_schema_io.py +++ b/tests/test_common_schema_io.py @@ -41,7 +41,7 @@ def test_fixture_validates() -> None: def test_fixture_has_the_shape_the_issue_asks_for() -> None: report = load_fixture() - assert len(report["proteins"]) == 5 + assert len(report["proteins"]) == 6 assert len(report["structures"]) == 1 assert len(report["ligands"]) == 3 assert len(report["docking"]) == 2 diff --git a/tests/test_m2_score.py b/tests/test_m2_score.py index c7ee6fb..2f48587 100644 --- a/tests/test_m2_score.py +++ b/tests/test_m2_score.py @@ -404,3 +404,62 @@ def test_ligandability_is_tractability_not_potency() -> None: assert "ligand bound in" in scored.flags["ligandable_basis"] ranked = rank_and_select([scored], top_n=1) assert "ligandable homolog" in ranked[0].reason + + +# --- #14: the holo template M3 transfers a binding site from ----------------------------- + + +def test_the_best_holo_hit_is_not_always_the_best_hit() -> None: + from s2f.m2_triage.score import best_holo_hit + + apo = make_hit(entity_id="1APO_1", identity=1.0, bitscore=400.0) + holo = make_hit(entity_id="2HOL_1", identity=0.80, bitscore=300.0, ligands=["ATP"]) + + assert best_holo_hit([apo, holo]) is holo + assert best_holo_hit([apo]) is None + + +def test_a_drug_like_ligand_outranks_a_metal_as_a_template() -> None: + from s2f.m2_triage.score import best_holo_hit + + metal = make_hit(entity_id="1MET_1", identity=1.0, bitscore=400.0, metals=["ZN"]) + ligand = make_hit(entity_id="2LIG_1", identity=0.85, bitscore=320.0, ligands=["ATP"]) + + assert best_holo_hit([metal, ligand]) is ligand + # A metal-only entry is still a template: the site is real, and M3 flags the cofactor. + assert best_holo_hit([metal]) is metal + + +def test_a_hit_that_does_not_qualify_is_never_a_template() -> None: + from s2f.m2_triage.score import best_holo_hit, hit_qualifies + + poor = make_hit(entity_id="3BAD_1", identity=0.05, evalue=1.0, bitscore=20.0, + ligands=["ATP"]) + assert hit_qualifies(poor) is False + assert best_holo_hit([poor]) is None + + +def test_the_report_carries_the_template_and_its_metals_to_m3() -> None: + """Metals were computed all along and never reached M3 (pitfalls.md #2).""" + from s2f.m2_triage.report_adapter import protein_enrichment + + apo = make_hit(entity_id="1APO_1", identity=1.0, bitscore=400.0, metals=["MG"]) + holo = make_hit(entity_id="2HOL_1", identity=0.90, bitscore=300.0, + ligands=["ATP"], metals=["MG"]) + score = score_protein(make_protein(), [apo, holo], "found") + + flags = protein_enrichment(score)["flags"] + assert flags["experimental_homolog"]["pdb_entity"] == "1APO_1" + assert flags["experimental_homolog"]["metals"] == ["MG"] + template = flags["holo_template"] + assert template["pdb_entity"] == "2HOL_1" + assert template["ligands"] == ["ATP"] + assert template["is_best_hit"] is False + assert template["identity_drop"] == pytest.approx(0.10) + + +def test_no_holo_template_when_nothing_binds() -> None: + from s2f.m2_triage.report_adapter import protein_enrichment + + score = score_protein(make_protein(), [make_hit()], "found") + assert protein_enrichment(score)["flags"]["holo_template"] is None diff --git a/tests/test_m3_collect.py b/tests/test_m3_collect.py index 413dc2f..f0179d8 100644 --- a/tests/test_m3_collect.py +++ b/tests/test_m3_collect.py @@ -14,12 +14,14 @@ def _protein( selected: bool = True, experimental: dict | None = None, predicted: dict | None = None, + holo_template: dict | None = None, ) -> dict: return { "feature_id": feature_id, "flags": { "experimental_homolog": experimental, "predicted_model": predicted, + "holo_template": holo_template, }, "triage": {"selected": selected}, } @@ -186,3 +188,54 @@ def test_limit_applies_to_selected_proteins_only(tmp_path: Path) -> None: assert summary.selected == 1 assert [record["feature_id"] for record in summary.structures] == ["first-selected"] + + +# --- #14: which entry the site is read from ---------------------------------------------- + +HOLO_TEMPLATE = { + "pdb_entity": "2xyz_1", + "identity": 0.78, + "coverage": 0.93, + "resolution": 1.9, + "method": "X-ray", + "ligands": ["ATP"], + "metals": ["MG"], + "is_best_hit": False, + "identity_drop": 0.13, +} + + +def test_a_holo_homolog_is_preferred_over_the_best_identity_apo_one() -> None: + """pitfalls.md #2: a site to transfer is worth more than the last points of identity.""" + apo = {**EXPERIMENTAL, "pdb_entity": "1apo_1", "holo": False, "ligands": []} + + candidate = choose_existing( + _protein("fig|1.1.peg.1", experimental=apo, holo_template=HOLO_TEMPLATE)) + + assert candidate.accession == "2xyz_1" + assert candidate.url.endswith("2XYZ.cif") + # The swap is recorded, never silent: it costs sequence match. + preference = candidate.template_preference + assert preference["best_identity_entity"] == "1apo_1" + assert preference["chosen_entity"] == "2xyz_1" + assert preference["identity_drop"] == 0.13 + assert preference["binds"] == ["ATP", "MG"] + + +def test_the_best_hit_is_kept_when_it_is_already_holo() -> None: + template = {**HOLO_TEMPLATE, "pdb_entity": "1abc_2", "is_best_hit": True, + "identity_drop": 0.0} + + candidate = choose_existing( + _protein("fig|1.1.peg.1", experimental=EXPERIMENTAL, holo_template=template)) + + assert candidate.accession == "1abc_2" + assert candidate.template_preference is None + + +def test_nothing_is_swapped_when_no_homolog_binds_anything() -> None: + candidate = choose_existing(_protein("fig|1.1.peg.1", experimental=EXPERIMENTAL)) + + assert candidate.accession == "1abc_2" + assert candidate.template_preference is None + assert candidate.holo_template is None diff --git a/tests/test_m3_dry_run.py b/tests/test_m3_dry_run.py index 1844695..3ab4fd3 100644 --- a/tests/test_m3_dry_run.py +++ b/tests/test_m3_dry_run.py @@ -17,7 +17,7 @@ def test_dry_run_collects_fixture_structures_without_network(tmp_path: Path) -> report = read_report(run_dir) structures = report["structures"] - assert len(structures) == 3 + assert len(structures) == 4 assert {record["source"] for record in structures} == {"pdb"} assert all(record["collection_status"] == "collected" for record in structures) assert all(record["usable_for_docking"] is True for record in structures) @@ -31,9 +31,9 @@ def test_dry_run_collects_fixture_structures_without_network(tmp_path: Path) -> manifest = json.loads((run_dir / "m3_fold" / "run.json").read_text()) assert manifest["module"] == "m3_fold" assert manifest["command"][-2:] == ["--run", str(run_dir)] - assert manifest["counts"]["selected"] == 3 - assert manifest["counts"]["collected"] == 3 - assert manifest["counts"]["usable_for_docking"] == 3 + assert manifest["counts"]["selected"] == 4 + assert manifest["counts"]["collected"] == 4 + assert manifest["counts"]["usable_for_docking"] == 4 assert manifest["counts"]["not_usable_for_docking"] == 0 assert manifest["counts"]["quality_pending"] == 0 assert manifest["parameters"]["confidence_gate_applied"] is True @@ -48,3 +48,30 @@ def test_dry_run_collects_fixture_structures_without_network(tmp_path: Path) -> assert "proteins" in report assert "kg" in report assert "ligands" in report + + +def test_the_dry_run_defines_a_site_from_the_holo_fixture(tmp_path: Path) -> None: + """#14, offline: 6MU0 binds ribose-5-phosphate, and its site reaches report.json.""" + run_dir = tmp_path / "run" + assert main(["--dry-run", "--run", str(run_dir)]) == 0 + + structures = read_report(run_dir)["structures"] + holo = [record for record in structures if record["accession"] == "6MU0_1"] + assert len(holo) == 1 + pockets = holo[0]["pockets"] + assert len(pockets) == 1 + assert pockets[0]["component"] == "5RP" + assert pockets[0]["aligned_to_known_site"] is True + assert len(pockets[0]["residues"]) >= 5 + validate("structures", structures) + + # The three apo proteins get no pocket, and each says why rather than looking unexamined. + apo = [record for record in structures if not record["pockets"]] + assert len(apo) == 3 + assert all(record["pocket_search"]["status"] == "no_pocket" for record in apo) + assert all("P2Rank" in record["pocket_search"]["reason"] for record in apo) + + counts = json.loads((run_dir / "m3_fold" / "run.json").read_text())["counts"] + assert counts["with_pocket"] == 1 + assert counts["usable_pockets"] == 1 + assert counts["cofactor_required_pockets"] == 0 diff --git a/tests/test_m3_pockets.py b/tests/test_m3_pockets.py new file mode 100644 index 0000000..ea55056 --- /dev/null +++ b/tests/test_m3_pockets.py @@ -0,0 +1,197 @@ +"""Binding sites transferred from what the homolog entry binds (issue #14). + +The geometry cases use a small hand-built mmCIF so the expected answer can be read off the +coordinates. The last tests use `fixtures/m3/6MU0.cif`, a real entry, so the module is also +exercised against a file nobody wrote for it. +""" + +from __future__ import annotations + +from pathlib import Path + +from s2f.m3_fold.pockets import (CONTACT_DISTANCE, find_holo_sites, find_pockets, + reject_low_confidence) + +FIXTURE = Path(__file__).resolve().parents[1] / "fixtures/m3/6MU0.cif" + +HEADER = """data_T +# +loop_ +_struct_asym.id +_struct_asym.entity_id +A 1 +B 2 +D 3 +# +loop_ +_atom_site.group_PDB +_atom_site.id +_atom_site.label_atom_id +_atom_site.label_comp_id +_atom_site.label_asym_id +_atom_site.label_seq_id +_atom_site.auth_seq_id +_atom_site.auth_asym_id +_atom_site.Cartn_x +_atom_site.Cartn_y +_atom_site.Cartn_z +_atom_site.B_iso_or_equiv +_atom_site.pdbx_PDB_model_num +""" + + +def _cif(rows: list[str]) -> bytes: + return (HEADER + "\n".join(rows) + "\n#\n").encode("utf-8") + + +def _atom(serial, atom, comp, chain, seq, x, y, z, b=90.0, het=False, model=1): + group = "HETATM" if het else "ATOM" + return (f"{group} {serial} {atom} {comp} {chain} {seq} {seq} {chain} " + f"{x} {y} {z} {b} {model}") + + +#: Three residues line the ligand, one sits far away, one belongs to another entity. +CONTACT_CASE = _cif([ + _atom(1, "CA", "ASP", "A", 1, 0.0, 0.0, 0.0), + _atom(2, "CA", "HIS", "A", 2, 3.0, 0.0, 0.0), + _atom(3, "CA", "THR", "A", 3, 0.0, 3.0, 0.0), + _atom(4, "CA", "LEU", "A", 4, 30.0, 30.0, 30.0), + _atom(5, "CA", "VAL", "B", 1, 1.0, 1.0, 1.0), + _atom(6, "MG", "MG", "D", 101, 1.0, 1.0, 0.0, b=20.0, het=True), +]) + + +def test_a_site_is_the_residues_that_line_the_bound_component() -> None: + pockets = find_holo_sites(CONTACT_CASE, metals=["MG"], entity_id="1") + + assert len(pockets) == 1 + pocket = pockets[0] + assert [residue.seq_id for residue in pocket.residues] == [1, 2, 3] + assert pocket.component == "MG" + assert pocket.component_kind == "metal" + # Read from the entry that binds it, so no superposition was involved. + assert pocket.aligned_to_known_site is True + assert pocket.center == (1.0, 1.0, 0.0) + + +def test_only_our_entity_lines_the_site() -> None: + """Chain B is a different entity: its residue is near the metal but not our pocket.""" + pockets = find_holo_sites(CONTACT_CASE, metals=["MG"], entity_id="1") + assert {residue.chain for residue in pockets[0].residues} == {"A"} + + both = find_holo_sites(CONTACT_CASE, metals=["MG"], entity_id="") + assert {residue.chain for residue in both[0].residues} == {"A", "B"} + + +def test_a_metal_site_says_a_cofactor_is_required() -> None: + pocket = find_holo_sites(CONTACT_CASE, metals=["MG"], entity_id="1")[0] + + assert pocket.cofactor_required is True + assert pocket.cofactor_present is True + assert pocket.params["metals_in_entry"] == ["MG"] + + +def test_a_component_nobody_reported_is_not_a_site() -> None: + """The ligand list comes from M2, which already dropped waters and additives.""" + assert find_holo_sites(CONTACT_CASE, ligands=[], metals=[], entity_id="1") == [] + assert find_holo_sites(CONTACT_CASE, ligands=["ATP"], entity_id="1") == [] + + +def test_a_brush_of_one_residue_is_not_a_pocket() -> None: + sparse = _cif([ + _atom(1, "CA", "ASP", "A", 1, 0.0, 0.0, 0.0), + _atom(2, "CA", "LEU", "A", 2, 30.0, 0.0, 0.0), + _atom(3, "MG", "MG", "D", 101, 1.0, 0.0, 0.0, het=True), + ]) + assert find_holo_sites(sparse, metals=["MG"], entity_id="1") == [] + + +def test_a_predicted_model_carries_no_site_to_read() -> None: + """The site is in the holo entry, not in a model of our protein (#14, pitfalls #2).""" + assert find_holo_sites(CONTACT_CASE, metals=["MG"], structure_is_template=False) == [] + + +def test_a_pocket_in_a_low_confidence_region_is_rejected() -> None: + poor = _cif([ + _atom(1, "CA", "ASP", "A", 1, 0.0, 0.0, 0.0, b=40.0), + _atom(2, "CA", "HIS", "A", 2, 3.0, 0.0, 0.0, b=35.0), + _atom(3, "CA", "THR", "A", 3, 0.0, 3.0, 0.0, b=30.0), + _atom(4, "MG", "MG", "D", 101, 1.0, 1.0, 0.0, het=True), + ]) + pockets = reject_low_confidence( + find_holo_sites(poor, metals=["MG"], entity_id="1"), source="afdb") + + assert pockets[0].usable is False + assert "below 70" in pockets[0].reason + + # The same B-factor column in an experimental entry is not a confidence claim. + experimental = reject_low_confidence( + find_holo_sites(poor, metals=["MG"], entity_id="1"), source="pdb") + assert experimental[0].usable is True + assert experimental[0].confidence is None + + +def test_a_drug_like_ligand_outranks_a_metal() -> None: + both = _cif([ + _atom(1, "CA", "ASP", "A", 1, 0.0, 0.0, 0.0), + _atom(2, "CA", "HIS", "A", 2, 3.0, 0.0, 0.0), + _atom(3, "CA", "THR", "A", 3, 0.0, 3.0, 0.0), + _atom(4, "MG", "MG", "D", 101, 1.0, 1.0, 0.0, het=True), + _atom(5, "C1", "5RP", "B", 201, 1.0, 1.0, 2.0, het=True), + ]) + pockets = find_holo_sites(both, ligands=["5RP"], metals=["MG"], entity_id="1") + + assert [pocket.component for pocket in pockets] == ["5RP", "MG"] + # The entry holds a metal, so even the ligand site may be incomplete without it. + assert all(pocket.cofactor_required for pocket in pockets) + + +# --- against a real entry --------------------------------------------------------------- + + +def test_the_real_entry_gives_the_known_active_site() -> None: + """6MU0 is ribose-5-phosphate isomerase B with its substrate bound.""" + payload = FIXTURE.read_bytes() + + pockets, summary = find_pockets( + payload, + source="pdb", + holo_template={"pdb_entity": "6MU0_1", "ligands": ["5RP"], "metals": []}, + structure_accession="6MU0_1", + ) + + assert summary["status"] == "ok" + assert summary["template_is_collected_structure"] is True + assert len(pockets) == 1 + pocket = pockets[0] + assert pocket["component"] == "5RP" + assert pocket["cofactor_required"] is False + # The catalytic aspartate and histidine of RpiB line the substrate. + lining = {(residue["auth_seq_id"], residue["comp_id"]) for residue in pocket["residues"]} + assert {("10", "ASP"), ("11", "HIS")} <= lining + assert all(residue["min_distance"] <= CONTACT_DISTANCE for residue in pocket["residues"]) + assert pocket["residues"] == sorted( + pocket["residues"], key=lambda residue: int(residue["auth_seq_id"])) + + +def test_a_protein_with_no_holo_homolog_says_why_it_has_no_pocket() -> None: + """Uncovered is not the same claim as "no pocket exists" (the #90 distinction).""" + pockets, summary = find_pockets( + FIXTURE.read_bytes(), source="pdb", holo_template=None, structure_accession="6MU0_1") + + assert pockets == [] + assert summary["status"] == "no_pocket" + assert "P2Rank" in summary["reason"] + + +def test_a_site_in_another_entry_is_not_silently_transferred() -> None: + pockets, summary = find_pockets( + FIXTURE.read_bytes(), + source="afdb", + holo_template={"pdb_entity": "6MU0_1", "ligands": ["5RP"], "metals": []}, + structure_accession="AF-P47543-F1", + ) + + assert pockets == [] + assert summary["template_is_collected_structure"] is False + assert "superposition" in summary["reason"]