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
23 changes: 23 additions & 0 deletions docs/02a-m2-pdb-evidence.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,29 @@ Written to `runs/<run_id>/m2_pdb/`:
| `no_pdb_hit.tsv` | proteins with no qualifying hit — the input to the Foldseek step (issue #9) |
| `run.json` | timestamps, parameters, weights, endpoints, counts, cache path, and every failed query with its error |

## Scoring profiles

The weights above are one policy, **`bacterial-target`**: antibacterial target selection. The
section before this one shows they do not even transfer between bacterial genomes, and they are
wrong for other questions, such as a viral protein, a single hypothetical, or a human target. So the
policy is a choice (#93):

- `--profile bacterial-target` (default) is exactly `WEIGHTS`; this change log governs it.
- `--profile evidence-only` ranks by structural evidence alone (`pdb_evidence` 0.40,
`ligandable_homolog` 0.10) with no penalties and no human-homolog disqualification.
**Provisional and uncalibrated.**
- `--weights FILE` takes `{"name": ..., "weights": {...}, "disqualify_human_homologs": bool}`.
Every component must be named, so a typo cannot silently drop one to 0.

`run.json` records the profile and its weights, and each protein's `weights_version` reads
`<profile>@<version>`. To compare policies on recorded evidence without re-querying anything:

python -m s2f.m2_triage.rescore --run runs/<id> --profile evidence-only

This writes `m2_pdb/rescored/<profile>.tsv` and leaves the run's own ranking untouched. Rescoring
under the default profile reproduces M2's ranking exactly. Runs that predate per-component output
(missing `surface_bonus`, `ligandable_homolog` or `membrane_penalty`) are refused, not guessed.

## Weight change log

| Date | Change | Reason |
Expand Down
25 changes: 21 additions & 4 deletions s2f/m2_triage/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
import argparse
import csv
import json
import sys
import time
from datetime import datetime, timezone
from pathlib import Path
Expand All @@ -19,6 +20,7 @@
from ..common.ids import IdMapper
from ..common.io import init_report, read_report, update_proteins, update_section
from .availability import annotation_route, not_available
from .profiles import DEFAULT_PROFILE, PROFILES, load_profile
from .report_adapter import kg_section, protein_enrichment, seed_proteins
from .afdb import AlphaFoldClient
from .human_homology import DEFAULT_MIN_COVERAGE, DiamondMissing, fetch_human_proteome
Expand Down Expand Up @@ -65,7 +67,6 @@
ANNOTATION_BONUS,
OPTIONAL_COMPONENTS,
best_hit,
WEIGHTS_VERSION,
LIGAND_BONUS,
MIN_EVALUE,
MIN_QUERY_COVERAGE,
Expand Down Expand Up @@ -325,6 +326,13 @@ def _load_annotation_providers(
def run(args: argparse.Namespace) -> int:
from .score import hit_score # local import keeps the module import list readable

# Fail before any network work if the profile or weights file is wrong (#93).
try:
profile = load_profile(args.profile, args.weights or None)
except (OSError, ValueError) as exc:
print(f"scoring profile: {exc}", file=sys.stderr)
return 2

run_dir = Path(args.run)
m1_dir = FIXTURE_DIR if args.dry_run else (Path(args.m1) if args.m1 else run_dir / "m1")
out_dir = run_dir / "m2_pdb"
Expand Down Expand Up @@ -543,6 +551,7 @@ def run(args: argparse.Namespace) -> int:
if xrefs_by_id.get(protein.feature_id)
else ()
),
weights=profile.weights,
)
)
hit_rows.extend(_hit_rows(protein.feature_id, hits, hit_score))
Expand Down Expand Up @@ -631,7 +640,8 @@ def run(args: argparse.Namespace) -> int:
),
}

ranked = rank_and_select(scores, top_n=args.top)
ranked = rank_and_select(scores, top_n=args.top,
disqualify_human_homologs=profile.disqualify_human_homologs)

kg_summary: dict[str, object] = {"enabled": False}
if args.kg:
Expand Down Expand Up @@ -772,7 +782,7 @@ def run(args: argparse.Namespace) -> int:
if annotation_run is not None
else None
),
weights_version=WEIGHTS_VERSION,
weights_version=f"{profile.name}@{profile.version}" if profile.version else profile.name,
)
for score in ranked
},
Expand Down Expand Up @@ -811,7 +821,10 @@ def run(args: argparse.Namespace) -> int:
"annotation": ANNOTATION_BONUS,
},
},
"weights": WEIGHTS,
# Which policy produced this ranking (#93): two runs under different profiles
# must never be confused, and the weights are recorded, not just named.
"profile": profile.as_dict(),
"weights": profile.weights,
# Which components actually had evidence behind them. A component that measured
# nothing contributed 0 to every protein, which is indistinguishable from "absent"
# in the score alone — so a reader can tell a genome with no membrane proteins from
Expand Down Expand Up @@ -940,6 +953,10 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument("--m1", default="", help="override the M1 input directory")
parser.add_argument("--limit", type=int, default=0, help="score only the first N proteins")
parser.add_argument("--top", type=int, default=50, help="how many proteins to select")
parser.add_argument("--profile", default=DEFAULT_PROFILE, choices=sorted(PROFILES),
help=f"scoring profile (default {DEFAULT_PROFILE}); see s2f/m2_triage/profiles.py")
parser.add_argument("--weights", default="", metavar="JSON",
help="custom weights file; overrides --profile (#93)")
parser.add_argument("--rows", type=int, default=ROWS_PER_QUERY, help="hits requested per search")
parser.add_argument("--workers", type=int, default=4, help="concurrent RCSB searches")
parser.add_argument("--cache", default="", help="override the SQLite cache path")
Expand Down
91 changes: 91 additions & 0 deletions s2f/m2_triage/profiles.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
"""Scoring profiles: the triage policy is a choice, not a constant (issue #93).

``WEIGHTS`` in ``score.py`` encodes an antibacterial target-selection policy — human homology is
a penalty, essentiality a bonus, membrane proteins deprioritised. That is right for bacterial
drug targets and wrong for other questions (a viral protein, a single hypothetical, a human
target). The weights are not portable between genomes either: G37 and HS11286 put 32 and 10
uncharacterised proteins in the top 50 under identical weights (#61).

So the weights become a named profile, or a JSON file, and ``run.json`` records which one
produced a ranking so two runs cannot be confused. ``bacterial-target`` stays the default and is
exactly ``WEIGHTS``; changing it still needs a dated row in the change log in
``docs/02a-m2-pdb-evidence.md`` (pitfall #12). Other profiles are provisional and uncalibrated.
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

from .score import WEIGHTS, WEIGHTS_VERSION

DEFAULT_PROFILE = "bacterial-target"


@dataclass(frozen=True)
class Profile:
name: str
weights: dict[str, float]
description: str
#: Whether a close human homolog removes a protein from selection. An antibacterial policy;
#: meaningless when the question is not "is this a safe drug target in a pathogen".
disqualify_human_homologs: bool = True
version: str = ""
source: str = "builtin"
extra: dict[str, Any] = field(default_factory=dict)

def as_dict(self) -> dict[str, Any]:
return {"name": self.name, "version": self.version, "source": self.source,
"description": self.description, "weights": dict(self.weights),
"disqualify_human_homologs": self.disqualify_human_homologs}


def _zeroed(**weights: float) -> dict[str, float]:
return {name: float(weights.get(name, 0.0)) for name in WEIGHTS}


PROFILES: dict[str, Profile] = {
DEFAULT_PROFILE: Profile(
name=DEFAULT_PROFILE, weights=dict(WEIGHTS), version=WEIGHTS_VERSION,
description="antibacterial target selection: structural evidence, virulence/AMR, "
"essentiality and drug-target bonuses, membrane and human-homolog "
"penalties (docs/02a-m2-pdb-evidence.md)"),
"evidence-only": Profile(
name="evidence-only",
weights=_zeroed(pdb_evidence=0.40, ligandable_homolog=0.10),
version="provisional-2026-10-08", disqualify_human_homologs=False,
description="ranks by structural evidence alone (PDB hit quality, ligand-bound "
"homolog); no target-selection policy, no penalties. Provisional."),
}


def load_profile(name: str = DEFAULT_PROFILE, weights_file: str | None = None) -> Profile:
"""A built-in profile, or one read from a JSON file.

The file is ``{"name": ..., "weights": {...}, "disqualify_human_homologs": bool}``. Every
component must be named, so a typo cannot silently drop one to 0.
"""
if not weights_file:
if name not in PROFILES:
raise ValueError(f"unknown profile {name!r}; choose from {', '.join(PROFILES)}")
return PROFILES[name]
payload = json.loads(Path(weights_file).read_text(encoding="utf-8"))
weights = payload.get("weights") if isinstance(payload, dict) else None
if not isinstance(weights, dict):
raise ValueError(f"{weights_file}: expected an object with a 'weights' object")
missing = set(WEIGHTS) - set(weights)
unknown = set(weights) - set(WEIGHTS)
if missing or unknown:
raise ValueError(f"{weights_file}: weights must name exactly the components "
f"{sorted(WEIGHTS)}; missing {sorted(missing)}, unknown {sorted(unknown)}")
try:
parsed = {key: float(weights[key]) for key in WEIGHTS}
except (TypeError, ValueError) as exc:
raise ValueError(f"{weights_file}: every weight must be a number ({exc})") from None
return Profile(
name=str(payload.get("name") or Path(weights_file).stem), weights=parsed,
description=str(payload.get("description") or "custom weights"),
disqualify_human_homologs=bool(payload.get("disqualify_human_homologs", True)),
version=str(payload.get("version") or ""), source=str(weights_file))
112 changes: 112 additions & 0 deletions s2f/m2_triage/rescore.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
"""Re-rank a finished M2 run under another scoring profile, with no re-querying (issue #93).

python -m s2f.m2_triage.rescore --run runs/kp --profile evidence-only
python -m s2f.m2_triage.rescore --run runs/kp --weights my_weights.json --top 30

Every score component is written per protein in ``m2_pdb/proteins.tsv``, so another policy can
be applied to recorded evidence directly. The result goes to
``m2_pdb/rescored/<profile>.tsv`` with a small manifest; the run's own ranking, ``report.json``
and ``run.json`` are left untouched, because a rescore is a comparison, not a new run.
"""

from __future__ import annotations

import argparse
import csv
import json
import sys
from datetime import datetime, timezone
from pathlib import Path

from .profiles import DEFAULT_PROFILE, PROFILES, Profile, load_profile
from .score import DISQUALIFYING_HUMAN_HOMOLOG_IDENTITY, WEIGHTS


def _number(value: str | None) -> float:
try:
return float(value) if value not in (None, "") else 0.0
except ValueError:
return 0.0


def rescore(rows: list[dict[str, str]], profile: Profile, *, top_n: int = 50
) -> list[dict[str, str]]:
"""Rows re-ranked under ``profile``, with the same tie-breaks and disqualification as M2."""
scored = []
for row in rows:
score = round(sum(weight * _number(row.get(name))
for name, weight in profile.weights.items()), 6)
disqualified = ""
identity = row.get("human_homolog_identity")
if (profile.disqualify_human_homologs and identity not in (None, "")
and _number(identity) >= DISQUALIFYING_HUMAN_HOMOLOG_IDENTITY):
disqualified = f"human homolog {_number(identity):.1f}% identity"
scored.append((score, disqualified, row))
scored.sort(key=lambda item: (-item[0], -_number(item[2].get("pdb_evidence")),
-_number(item[2].get("distinct_entries")),
item[2].get("feature_id") or ""))
out, selected = [], 0
for rank, (score, disqualified, row) in enumerate(scored, start=1):
chosen = not disqualified and selected < top_n
selected += chosen
out.append({"rank": str(rank), "feature_id": row.get("feature_id", ""),
"product": row.get("product", ""), "score": f"{score:g}",
"original_rank": row.get("rank", ""),
"original_score": row.get("triage_score", ""),
"selected": str(chosen), "disqualified": disqualified,
**{name: row.get(name, "") for name in WEIGHTS}})
return out


def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="python -m s2f.m2_triage.rescore",
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("--run", required=True, help="run directory with m2_pdb/proteins.tsv")
parser.add_argument("--profile", default=DEFAULT_PROFILE, choices=sorted(PROFILES))
parser.add_argument("--weights", default="", metavar="JSON",
help="custom weights file; overrides --profile")
parser.add_argument("--top", type=int, default=50, help="how many proteins to select")
args = parser.parse_args(argv)

try:
profile = load_profile(args.profile, args.weights or None)
except (OSError, ValueError) as exc:
print(f"scoring profile: {exc}", file=sys.stderr)
return 2
source = Path(args.run) / "m2_pdb" / "proteins.tsv"
if not source.is_file():
print(f"no M2 output at {source}; run M2 first", file=sys.stderr)
return 2
with source.open(encoding="utf-8", newline="") as handle:
rows = list(csv.DictReader(handle, delimiter="\t"))
missing = [name for name in WEIGHTS if rows and name not in rows[0]]
if missing:
print(f"{source} lacks component columns {missing}; it predates per-component "
"output and cannot be rescored", file=sys.stderr)
return 2

ranked = rescore(rows, profile, top_n=args.top)
out_dir = source.parent / "rescored"
out_dir.mkdir(exist_ok=True)
target = out_dir / f"{profile.name}.tsv"
with target.open("w", encoding="utf-8", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=list(ranked[0]) if ranked else ["rank"],
delimiter="\t")
writer.writeheader()
writer.writerows(ranked)
chosen = {r["feature_id"] for r in ranked if r["selected"] == "True"}
before = {r.get("feature_id") for r in rows if r.get("selected") == "True"}
(out_dir / f"{profile.name}.json").write_text(json.dumps({
"profile": profile.as_dict(), "source": str(source), "top_n": args.top,
"rescored_at": datetime.now(timezone.utc).isoformat(),
"selected": len(chosen), "overlap_with_original_selection": len(chosen & before),
}, indent=2) + "\n", encoding="utf-8")
print(f"{len(rows)} proteins rescored under {profile.name!r} -> {target}")
print(f"{len(chosen)} selected; {len(chosen & before)} of them were in the original "
f"selection of {len(before)}")
return 0


if __name__ == "__main__":
raise SystemExit(main())
19 changes: 13 additions & 6 deletions s2f/m2_triage/score.py
Original file line number Diff line number Diff line change
Expand Up @@ -152,11 +152,15 @@ class ProteinScore:
error: str = ""


def triage_score_from_components(components: TriageComponents) -> float:
"""The single definition of the score; used by the pipeline and by the tests."""
def triage_score_from_components(components: TriageComponents,
weights: dict[str, float] | None = None) -> float:
"""The single definition of the score; used by the pipeline and by the tests.

``weights`` defaults to ``WEIGHTS``; a scoring profile (``profiles.py``, #93) passes its own.
"""
values = components.as_dict()
# human_homolog_penalty carries a negative weight, so one loop covers every component.
return round(sum(weight * values[name] for name, weight in WEIGHTS.items()), 6)
return round(sum(weight * values[name] for name, weight in (weights or WEIGHTS).items()), 6)


def score_protein(
Expand All @@ -173,6 +177,7 @@ def score_protein(
query_organism: str = "",
query_taxonomy: Any = None,
chembl_targets: Sequence[str] = (),
weights: dict[str, float] | None = None,
) -> ProteinScore:
"""Score one protein from its PDB hits and M1 specialty rows.

Expand Down Expand Up @@ -294,7 +299,7 @@ def score_protein(
feature_id=protein.feature_id,
product=protein.product,
components=components,
score=triage_score_from_components(components),
score=triage_score_from_components(components, weights),
retrieval_status=retrieval_status,
best_hit=top,
distinct_entries=len({hit.entry_id for hit in qualifying}),
Expand Down Expand Up @@ -382,7 +387,8 @@ def human_homolog_disqualification(score: ProteinScore) -> str:
return f"human homolog {identity:.1f}% identity ({source})"


def rank_and_select(scores: list[ProteinScore], *, top_n: int = 50) -> list[ProteinScore]:
def rank_and_select(scores: list[ProteinScore], *, top_n: int = 50,
disqualify_human_homologs: bool = True) -> list[ProteinScore]:
"""Rank every protein, mark the top N *eligible* ones, and give each one a reason.

A disqualified protein keeps its rank and its score — the ranking still records what the
Expand All @@ -402,7 +408,8 @@ def rank_and_select(scores: list[ProteinScore], *, top_n: int = 50) -> list[Prot
selected = 0
for index, score in enumerate(ordered, start=1):
score.rank = index
score.disqualified = human_homolog_disqualification(score)
score.disqualified = (human_homolog_disqualification(score)
if disqualify_human_homologs else "")
if score.disqualified:
score.selected = False
elif selected < top_n:
Expand Down
5 changes: 4 additions & 1 deletion s2f/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ def build_parser() -> argparse.ArgumentParser:
# One flag per stage (#80). --limit used to reach M3 as well, so capping structure
# downloads silently capped how many proteins M2 scored.
p.add_argument("--limit", type=int, help="M2: score only the first N proteins")
p.add_argument("--profile", help="M2: scoring profile, e.g. evidence-only (#93)")
p.add_argument("--weights", metavar="JSON", help="M2: custom weights file (#93)")
p.add_argument("--structure-limit", type=int,
help="M3: collect structures for only the first N selected proteins")
p.add_argument("--map-ids", action="store_true", help="M2: resolve UniProt/ChEMBL xrefs")
Expand Down Expand Up @@ -171,7 +173,8 @@ def stage_args(stage: str, args: argparse.Namespace) -> list[str]:
("--essentiality", args.essentiality or args.full_evidence)):
if on:
out.append(flag)
for flag, value in (("--human-proteome", args.human_proteome),
for flag, value in (("--profile", args.profile), ("--weights", args.weights),
("--human-proteome", args.human_proteome),
("--human-min-coverage", args.human_min_coverage),
("--essentiality-keyword", args.essentiality_keyword),
("--essentiality-limit", args.essentiality_limit),
Expand Down
Loading
Loading