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"]