Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions docs/03-m3-fold.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
369 changes: 369 additions & 0 deletions fixtures/m3/6MU0.cif

Large diffs are not rendered by default.

40 changes: 40 additions & 0 deletions fixtures/m3/README.md
Original file line number Diff line number Diff line change
@@ -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.
71 changes: 71 additions & 0 deletions fixtures/report.fixture.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
56 changes: 55 additions & 1 deletion s2f/common/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]},
},
Expand Down
50 changes: 46 additions & 4 deletions s2f/full_report/render.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 = ["<div class='card'><h2>Structures</h2>",
f"<p class='lead'><b>{len(structures)}</b> collected"
+ (f", <b>{usable}</b> passing the quality gate" if usable else "")
+ f", <b>{with_pocket}</b> with a defined pocket"
+ ". Existing PDB and AlphaFold models are reused; nothing here is a new "
"prediction unless a row says so.</p>",
"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.</p>",
"<div class='tablewrap'><table><thead><tr>"
+ "".join(f"<th>{esc(k.replace('_', ' '))}</th>" for k in keys)
+ "</tr></thead><tbody>"]
for row in structures:
out.append("<tr>" + "".join(
f"<td>{esc(_fmt(row.get(k)) if not isinstance(row.get(k), (dict, list)) else json.dumps(row.get(k))[:120])}</td>"
for k in keys) + "</tr>")
cells = []
for key in keys:
value = row.get(key)
if key == "pockets":
cells.append(f"<td>{_pocket_cell(row)}</td>")
elif isinstance(value, (dict, list)):
cells.append(f"<td>{esc(json.dumps(value)[:120])}</td>")
else:
cells.append(f"<td>{esc(_fmt(value))}</td>")
out.append("<tr>" + "".join(cells) + "</tr>")
out.append("</tbody></table></div></div>")
return "".join(out)

Expand Down Expand Up @@ -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"<span class='muted'>none &mdash; {esc(str(reason))}</span>" 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"<b>{label}</b>", 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 = " &middot; ".join(bits)
if lining:
line += f"<br><span class='muted'>{esc(lining)}"
line += "&hellip;</span>" if len(residues) > 6 else "</span>"
parts.append(line)
return "<div>" + "</div><div>".join(parts) + "</div>"
26 changes: 26 additions & 0 deletions s2f/m2_triage/report_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]] = []
Expand Down Expand Up @@ -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",
Expand Down
19 changes: 19 additions & 0 deletions s2f/m2_triage/score.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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,
Expand Down
Loading
Loading