Skip to content

M3: define binding sites from what the homolog actually binds (#14, part A) - #114

Merged
Jiahuic merged 1 commit into
mainfrom
feat/14-pockets
Nov 19, 2026
Merged

Jiahuic merged 1 commit into
mainfrom
feat/14-pockets

Conversation

@Jiahuic

@Jiahuic Jiahuic commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Part A of #14: pockets. Receptor preparation (PDBFixer/PDB2PQR/Meeko, Vina boxes) follows in a second PR — it is M4's input and needs an external toolchain CI cannot exercise.

The approach

Every tool #14 names is external and non-pip (P2Rank is Java, so are PDBFixer, PDB2PQR, Meeko, US-align), and the repo requires fixtures and an offline --dry-run for every module. But the evidence is already in hand: M2 names the ligands and metals bound in each qualifying PDB entry, and M3 downloads that entry. So a pocket is read straight out of the file M3 already has — the residues of our entity's chains within 4.5 Å of the named component — with no Java, no network and no superposition.

Rule Why
Only the components M2 named define a site M2 already dropped waters, cryoprotectants and glycans. M3 re-filters nothing by name.
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.
≥3 lining residues Fewer is a surface brush.
A metal site is a site, flagged cofactor_required pitfalls #2: a predicted model will not carry 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 it takes a drug-sized molecule.
Reject a pocket whose own residues are poorly modelled Mean pLDDT over the pocket's residues, not the model's global mean. Only for AlphaFold models — in an experimental entry the same B_iso column is a B-factor, and no confidence is claimed.

Template choice. M2 now records the best qualifying hit that binds something (flags.holo_template), which is often not the best-identity one. M3 prefers it, because a site to transfer is worth more than the last points of identity (pitfalls #2), and records the swap and its identity_drop in template_preference rather than switching silently. On runs/mgen_G37 that is the difference between 14 and 42 of 50 selected proteins having anything to read.

Nothing is invented. A site is only read from the entry that binds the component, so 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 #90 distinction). Those are what P2Rank is for; find_pockets is where it plugs in, and it is not built yet.

Also here

  • metals finally reach report.json. They were computed all along and stopped at the adapter, though pitfalls common: report.json schema, fixtures, and section writer #2 is about exactly them.
  • mmcif.py replaces quality.py's private atom-site parser, so M3 reads coordinates in one place.
  • Pocket records keep the key names 00-architecture.md fixed (id, method, residues, score, aligned_to_known_site); each residue carries chain and author numbering, since a bare number is ambiguous across chains. The schema still accepts the old bare-integer form.
  • The full report renders pockets as 5RP · 10 residues · ASP10, HIS11, THR12… instead of truncated JSON, and prints the no-pocket reason.

Verification

498 tests pass, no network. The new tests/test_m3_pockets.py checks the geometry on a hand-built mmCIF where the answer is readable off the coordinates, then against a real entry.

fixtures/m3/6MU0.cif is real: M. genitalium ribose-5-phosphate isomerase B at 1.1 Å with ribose-5-phosphate bound, a 100%-identity hit for peg.463 in runs/mgen_G37, trimmed to a 12 Å shell (344 of 1,447 atoms) and documented in fixtures/m3/README.md. The site M3 reads from it is RpiB's active site — Asp10, His11, Thr12, Tyr45, Gly70… — so the test checks against the literature rather than against our own output. python -m s2f.m3_fold --run <dir> --dry-run writes that pocket offline, and the three apo fixtures each say why they have none.

Still open from #14

  • Pockets for apo structures (P2Rank), and transferring a site held in an entry other than the collected one (superposition). Both are stated as gaps in pocket_search.reason, never as absence of a pocket.
  • Receptor preparation.

🤖 Generated with Claude Code

Part A of #14: pockets. Receptor preparation stays for a second change.

The site needs no external tool and no network, because the evidence is
already in hand. M2 names the ligands and metals bound in every
qualifying PDB entry and M3 downloads that entry, so a pocket is the
residues of our entity's chains within 4.5 A of the named component.

- M2 now records the best qualifying homolog that binds something, which
  is often not the best-identity one, and carries metals into
  report.json at last: they were computed all along and stopped at the
  adapter, though pitfalls.md #2 is about exactly them.
- M3 prefers that holo entry over a marginally closer apo one and
  records the swap and its identity cost in template_preference. On
  runs/mgen_G37 this is the difference between 14 and 42 of 50 selected
  proteins having a site to read.
- A metal site is a site, flagged cofactor_required, because a predicted
  model will not carry the Mg or Zn and M4 must be told so.
- A pocket whose own residues are poorly modelled is rejected on the
  pocket's mean pLDDT, not the model's global mean. Only for AlphaFold
  models, where B_iso holds pLDDT; in an experimental entry the same
  column is a B-factor and no confidence is claimed.
- No site is invented. A protein whose homolog binds nothing gets no
  pocket and a stated reason, which is uncovered rather than pocket-free.
  P2Rank is where those go, discovered on PATH, and is not built yet.

mmcif.py replaces quality.py's private atom-site parser so M3 reads
coordinates in one place. Pocket records keep the key names
00-architecture.md fixed, with each residue carrying chain and author
numbering, since a bare residue number is ambiguous across chains.

Fixture 6MU0 is a real entry: M. genitalium ribose-5-phosphate isomerase
B at 1.1 A with its substrate bound, trimmed to a 12 A shell. The site
M3 reads from it is RpiB's active site, so the test checks against the
literature rather than against our own output.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Jiahuic
Jiahuic merged commit de4d935 into main Nov 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant