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
2 changes: 2 additions & 0 deletions docs/01-m1-genome.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
BV-BRC is used. Specialty genes, subsystems, coordinates, contigs and the taxonomy tree are
recorded under `not_available`, never as empty lists, and `genome.annotation_route` is
`"fasta"`. The organism comes only from `--organism`; FASTA headers are never parsed for one.
M2 then lists the score components nothing could measure under `not_available` in
`m2_pdb/run.json`, the runner prints them, and the full report shows them in its header (#90).

## Outputs

Expand Down
20 changes: 20 additions & 0 deletions s2f/full_report/render.py
Original file line number Diff line number Diff line change
Expand Up @@ -749,6 +749,7 @@ def build_page(report: dict[str, Any], m2_run: dict[str, Any] | None = None) ->
out.append(f"<span class='sourcenote'>{esc(note)}</span>")
elif note:
out.append(f"<div class='sourcenote' style='margin-top:12px'>{esc(note)}</div>")
out.extend(_not_available_note(genome, m2_run))
out.append("</header>")

out.append("<nav class='tabs' role='tablist'>")
Expand All @@ -767,6 +768,25 @@ def build_page(report: dict[str, Any], m2_run: dict[str, Any] | None = None) ->
return "".join(out)


def _not_available_note(genome: dict[str, Any], m2_run: dict[str, Any]) -> list[str]:
"""What nobody looked at on this run (#90), so a sequence-only report never passes for a
genome report. "Not available" is not "none found": an empty specialty list on a genome
route means BV-BRC looked; here it did not."""
sources = _mapping(genome.get("not_available"))
components = _mapping(m2_run.get("not_available"))
if not sources and not components:
return []
out = ["<div class='note warn' style='margin-top:12px'><b>Not available on this run</b> "
"&mdash; never looked at, which is not the same as none found."]
if sources:
out.append("<br>Inputs: " + "; ".join(f"{esc(k)} ({esc(v)})" for k, v in sources.items()))
if components:
out.append("<br>Score components contributing 0 because nothing could measure them: "
+ "; ".join(f"<code>{esc(k)}</code> ({esc(v)})" for k, v in components.items()))
out.append("</div>")
return ["".join(out)]


def render_run(run_dir: str | Path) -> str:
"""Build the page for a run directory, reading M2's manifest when it is there."""
run_dir = Path(run_dir)
Expand Down
9 changes: 9 additions & 0 deletions s2f/m2_triage/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
from ..common.http import CachedJsonClient, JsonCache
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 .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 @@ -781,6 +782,7 @@ def run(args: argparse.Namespace) -> int:
run_dir, "kg", kg_section(graph.to_dict(caps=builder.caps()), path=str(kg_path))
)

route = annotation_route(run_dir)
manifest = {
"module": "m2_pdb_evidence",
"docs": "docs/02a-m2-pdb-evidence.md",
Expand Down Expand Up @@ -896,6 +898,13 @@ def run(args: argparse.Namespace) -> int:
"foldseek": foldseek_summary,
"human_homology": human_summary,
"essentiality": essentiality_summary,
# Components nothing could have measured on this route (#90). Distinct from
# components_available, which counts proteins a provider that *ran* measured.
"annotation_route": route or None,
"not_available": not_available(route, {
"human_homology": bool(human_summary.get("enabled")),
"essentiality": bool(essentiality_summary.get("enabled")),
}),
"knowledge_graph": kg_summary,
"functional_annotation": (
{"enabled": True, "terms_written": terms_written, **annotation_run.summary()}
Expand Down
45 changes: 45 additions & 0 deletions s2f/m2_triage/availability.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Which score components had no possible source on this run (issue #90).

A component with no evidence contributes 0, exactly like "checked and false" (pitfall #12). On a
genome route the BV-BRC specialty table is the source for four components; on the FASTA route
(#89) there is no BV-BRC genome, so nobody looked — and the manifest has to say so rather than
let a sequence-only ranking pass for a complete one.
"""

from __future__ import annotations

import json
from pathlib import Path

#: Components whose only default source is BV-BRC's specialty table, and the M2 provider that
#: can replace it without a genome, if any. #91 adds VFDB/CARD for the first two.
SPECIALTY_COMPONENTS: dict[str, str | None] = {
"virulence_amr": None,
"drug_target": None,
"essential": "essentiality",
"human_homolog_penalty": "human_homology",
}

NO_GENOME_ROUTES = {"fasta"}


def annotation_route(run_dir: str | Path) -> str:
"""M1's route from report.json, or "" when M1 did not run here (standalone M2)."""
try:
report = json.loads((Path(run_dir) / "report.json").read_text())
except (OSError, json.JSONDecodeError):
return ""
return str((report.get("genome") or {}).get("annotation_route") or "")


def not_available(route: str, providers_enabled: dict[str, bool]) -> dict[str, str]:
"""`{component: reason}` for every component nothing could have measured on this route."""
if route not in NO_GENOME_ROUTES:
return {}
out = {}
for component, provider in SPECIALTY_COMPONENTS.items():
if provider and providers_enabled.get(provider):
continue
hint = f"; pass --{provider.replace('_', '-')}" if provider else ""
out[component] = f"no BV-BRC genome on the {route} route{hint}"
return out
7 changes: 7 additions & 0 deletions s2f/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,14 @@ def missing_evidence(run_dir: str) -> list[str]:
return []
weights = manifest.get("weights") or {}
lines = []
# Nothing could have measured these on this route (#90): say that, not "BV-BRC rows".
unavailable = manifest.get("not_available") or {}
for component, reason in unavailable.items():
if weights.get(component):
lines.append(f"{component} (weight {weights[component]:+.2f}) not available: {reason}")
for component, section, flag in EVIDENCE_COMPONENTS:
if component in unavailable:
continue
summary = manifest.get(section) or {}
if summary.get("enabled") or not weights.get(component):
continue
Expand Down
66 changes: 66 additions & 0 deletions tests/test_not_available.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
"""Sequence-only runs record what nobody looked at as not available, never as zero (#90)."""

from __future__ import annotations

import json
from pathlib import Path

from s2f.full_report.render import build_page
from s2f.m1_genome.__main__ import main as m1_main
from s2f.m2_triage.availability import not_available
from s2f.run import missing_evidence

ROOT = Path(__file__).resolve().parents[1]
QUERY = ROOT / "fixtures/m1/fasta_query/query.faa"
GENOME_REPORT = ROOT / "fixtures/report.fixture.json"


def test_a_genome_route_has_nothing_unavailable() -> None:
assert not_available("api", {}) == {}
assert not_available("cga", {}) == {}
assert not_available("", {}) == {} # standalone M2: M1 did not run here


def test_the_fasta_route_marks_every_specialty_component() -> None:
got = not_available("fasta", {})
assert set(got) == {"virulence_amr", "drug_target", "essential", "human_homolog_penalty"}
assert "--human-homology" in got["human_homolog_penalty"]


def test_a_provider_that_ran_makes_its_component_available() -> None:
got = not_available("fasta", {"human_homology": True, "essentiality": True})
assert set(got) == {"virulence_amr", "drug_target"}


def _m2_manifest(run_dir: Path, unavailable: dict) -> None:
(run_dir / "m2_pdb").mkdir(parents=True)
(run_dir / "m2_pdb/run.json").write_text(json.dumps({
"weights": {"virulence_amr": 0.2, "drug_target": 0.15, "essential": 0.15,
"human_homolog_penalty": -0.25},
"human_homology": {"enabled": False}, "essentiality": {"enabled": False},
"not_available": unavailable}))


def test_the_runner_says_not_available_instead_of_bvbrc_rows(tmp_path) -> None:
_m2_manifest(tmp_path, not_available("fasta", {}))
lines = missing_evidence(str(tmp_path))
assert len(lines) == 4
assert all("not available" in line for line in lines)
assert not any("BV-BRC's precomputed rows" in line for line in lines)


def test_a_genome_run_and_a_fasta_run_are_distinguishable_from_report_json(tmp_path) -> None:
assert m1_main(["--run", str(tmp_path / "q"), "--from-fasta", str(QUERY)]) == 0
fasta = json.loads((tmp_path / "q/report.json").read_text())
genome = json.loads(GENOME_REPORT.read_text())
assert fasta["genome"]["annotation_route"] == "fasta"
assert genome["genome"].get("annotation_route") != "fasta"
assert fasta["genome"]["not_available"] and not genome["genome"].get("not_available")


def test_the_full_report_shows_not_available_only_when_something_was(tmp_path) -> None:
assert m1_main(["--run", str(tmp_path / "q"), "--from-fasta", str(QUERY)]) == 0
fasta = json.loads((tmp_path / "q/report.json").read_text())
page = build_page(fasta, {"not_available": not_available("fasta", {})})
assert "Not available on this run" in page and "virulence_amr" in page
assert "Not available on this run" not in build_page(json.loads(GENOME_REPORT.read_text()))
Loading