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"| {esc(k.replace('_', ' '))} | " for k in keys)
+ "
"]
for row in structures:
- out.append("" + "".join(
- f"| {esc(_fmt(row.get(k)) if not isinstance(row.get(k), (dict, list)) else json.dumps(row.get(k))[:120])} | "
- for k in keys) + "
")
+ cells = []
+ for key in keys:
+ value = row.get(key)
+ if key == "pockets":
+ cells.append(f"{_pocket_cell(row)} | ")
+ elif isinstance(value, (dict, list)):
+ cells.append(f"{esc(json.dumps(value)[:120])} | ")
+ else:
+ cells.append(f"{esc(_fmt(value))} | ")
+ out.append("" + "".join(cells) + "
")
out.append("
")
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"]