diff --git a/docs/02c-m2-functional-annotation.md b/docs/02c-m2-functional-annotation.md index 8465637..7f8a8b2 100644 --- a/docs/02c-m2-functional-annotation.md +++ b/docs/02c-m2-functional-annotation.md @@ -257,6 +257,15 @@ With `--report`, the flags go into `proteins[].flags` and the evidence into | `flags.localization`, `tm_helices`, `signal_peptide`, `lipoprotein`, `surface_exposed` | the rest of the topology picture | | `flags.functional_evidence` | `membrane_source`, `membrane_evidence`, `signal_source`, `signal_evidence`, `lipoprotein_source`, `lipoprotein_evidence`, `localization_source`, `confidence`, `flag_confidence` (per flag, #72), and every source that contributed | | `annotations[]` | one row per source, each with its terms, its evidence string, its confidence and `retrieved_at` — merged flags live in `flags`, but `source` is what keeps the evidence apart | +| `function` | what the protein does, for readers (issue #107): `description` (UniProt name → eggNOG → InterPro), `summary` (UniProt's free-text Function comment, with its source and evidence), `go` grouped by aspect (`process` / `function` / `component`; eggNOG and InterProScan IDs carry no aspect and go under `unclassified`), `ec`, `kegg_ko`, `cog_category`, and `status` | + +`function.status` is `not_run` when the run did no functional annotation and `none` when it +did but no provider described the protein — the full report prints the two differently, since +"not looked at" and "nothing known" are different claims. The full report shows `function` as a +column of the selected-targets table. It is descriptive only and does not enter the score. +When providers supply the same GO ID, the display prefers a term with a name and aspect +over a bare ID, regardless of provider order. Each provider's original term remains in +`annotations[]` and `function_terms.tsv` with its own source. Without `--annotate`, every one of those fields stays `null`: the adapter reserved those slots for this issue and a protein nobody annotated must not reach M3 looking like a confirmed diff --git a/s2f/common/schema.py b/s2f/common/schema.py index f04c897..ab747d5 100644 --- a/s2f/common/schema.py +++ b/s2f/common/schema.py @@ -162,6 +162,24 @@ "additionalProperties": True, } +_FUNCTION = { + "type": "object", + "properties": { + "status": {"enum": ["annotated", "none", "not_run"]}, + "description": {"type": ["string", "null"]}, + "description_source": {"type": ["string", "null"]}, + "summary": {"type": ["string", "null"]}, + "summary_source": {"type": ["string", "null"]}, + "summary_evidence": {"type": ["string", "null"]}, + "go": {"type": "object"}, + "ec": {"type": "array", "items": {"type": "string"}}, + "kegg_ko": {"type": "array", "items": {"type": "string"}}, + "cog_category": {"type": "array", "items": {"type": "string"}}, + }, + "required": ["status"], + "additionalProperties": True, +} + _PROTEIN = { "type": "object", "properties": { @@ -177,6 +195,7 @@ "specialty": {"type": "array"}, "xrefs": _XREFS, "annotations": {"type": "array", "items": _ANNOTATION}, + "function": _FUNCTION, "flags": _FLAGS, "triage": _TRIAGE, }, diff --git a/s2f/full_report/render.py b/s2f/full_report/render.py index ef90bf3..045e8ef 100644 --- a/s2f/full_report/render.py +++ b/s2f/full_report/render.py @@ -429,6 +429,38 @@ def _disqualified(triage: dict[str, Any]) -> str: return "" +def _function_cell(protein: dict[str, Any]) -> str: + """What the protein does, in words (issue #107). + + A run that never annotated function says so instead of leaving a blank a reader would + take for "nothing known". + """ + function = _mapping(protein.get("function")) + status = function.get("status") + if not function or status == "not_run": + return "not annotated in this run" + if status == "none": + return "no functional annotation found" + out = [] + if function.get("description"): + out.append(f"{esc(function['description'])} " + f"({esc(_fmt(function.get('description_source')))})") + if function.get("summary"): + out.append(f"
| Rank | Score | Product | Evidence | " - "Flags | Cross-references | Why | " + "Rank | Score | Product | Function | " + "Evidence | Flags | Cross-references | Why | " "{esc(_fmt(protein.get('product')))} " f" {esc(protein.get('feature_id'))} | "
+ f"{_function_cell(protein)} | " f"{parts or '—'} | {' '.join(pills) or '—'} | " f"{links or '—'} | " f"{esc(_fmt(triage.get('reason')))} | ") diff --git a/s2f/m2_triage/function.py b/s2f/m2_triage/function.py index 73c2a50..6af25b3 100644 --- a/s2f/m2_triage/function.py +++ b/s2f/m2_triage/function.py @@ -227,6 +227,8 @@ class ProviderResult: lipoprotein: Call = field(default_factory=Call) localization: Call = field(default_factory=Call) description: Call = field(default_factory=Call) + # UniProt's free-text "Function" comment: what the protein does, in a sentence or two. + summary: Call = field(default_factory=Call) terms: list[Term] = field(default_factory=list) # Residue spans behind ``tm_helices``, when the provider reports them. The merge uses these # to resolve the signal-peptide / N-terminal-helix ambiguity across providers. @@ -256,6 +258,9 @@ class FunctionalAnnotation: localization_source: str = "" localization_evidence: str = "" description_source: str = "" + summary: str = "" + summary_source: str = "" + summary_evidence: str = "" sources: list[str] = field(default_factory=list) terms: list[Term] = field(default_factory=list) @@ -1189,7 +1194,7 @@ def run_interproscan( UNIPROT_ENTRY = "https://rest.uniprot.org/uniprotkb/{accession}.json" UNIPROT_FIELDS = ( "accession,protein_name,gene_names,ec,go,xref_kegg,xref_pfam,xref_interpro," - "cc_subcellular_location,ft_transmem,ft_signal,ft_lipid" + "cc_function,cc_subcellular_location,ft_transmem,ft_signal,ft_lipid" ) @@ -1296,6 +1301,23 @@ def parse_uniprot_entry(feature_id: str, accession: str, payload: Any) -> Provid value=True, source=SOURCE_UNIPROT, evidence=f"UniProt {accession}: lipidation feature" ) + summaries: list[str] = [] + summary_experimental = False + for comment in payload.get("comments", []) or []: + if not isinstance(comment, dict) or comment.get("commentType") != "FUNCTION": + continue + for text in comment.get("texts", []) or []: + value = ((text or {}).get("value") or "").strip() + if value: + summaries.append(value) + summary_experimental = summary_experimental or bool(_evidence_codes(text) & EXPERIMENTAL_ECO) + if summaries: + result.summary = Call( + value=" ".join(summaries), + source=SOURCE_UNIPROT_EXP if summary_experimental else SOURCE_UNIPROT, + evidence=f"UniProt {accession}: Function comment", + ) + for comment in payload.get("comments", []) or []: if not isinstance(comment, dict) or comment.get("commentType") != "SUBCELLULAR LOCATION": continue @@ -1381,6 +1403,7 @@ def merge_annotation(feature_id: str, results: Sequence[ProviderResult]) -> Func lipo = best_call([result.lipoprotein for result in results]) localization = best_call([result.localization for result in results]) description = best_call([result.description for result in results], DESCRIPTION_RANK) + summary = best_call([result.summary for result in results], DESCRIPTION_RANK) # A signal peptide and an N-terminal TM helix have the same hydropathy profile. The # heuristic resolves that internally using its own signal call; when a better source says @@ -1415,7 +1438,7 @@ def merge_annotation(feature_id: str, results: Sequence[ProviderResult]) -> Func annotation.sources = sorted( { call.source - for call in (tm, signal, lipo, localization, description) + for call in (tm, signal, lipo, localization, description, summary) if call.source } | {term.source for result in results for term in result.terms if term.source} @@ -1444,6 +1467,9 @@ def merge_annotation(feature_id: str, results: Sequence[ProviderResult]) -> Func annotation.localization_source = localization.source annotation.localization_evidence = localization.evidence annotation.description_source = description.source + annotation.summary = str(summary.value or "") if summary.known else "" + annotation.summary_source = summary.source + annotation.summary_evidence = summary.evidence annotation.secreted = annotation.localization == LOC_EXTRACELLULAR or ( annotation.signal_peptide and annotation.tm_helices == 0 and not annotation.lipoprotein diff --git a/s2f/m2_triage/report_adapter.py b/s2f/m2_triage/report_adapter.py index ea5574d..024980e 100644 --- a/s2f/m2_triage/report_adapter.py +++ b/s2f/m2_triage/report_adapter.py @@ -18,7 +18,7 @@ from ..common.ids import Xrefs from .afdb import AlphaFoldModel from .bvbrc_input import Protein -from .function import CONFIDENCE, FunctionalAnnotation +from .function import CONFIDENCE, FunctionalAnnotation, Term from .score import ProteinScore @@ -70,6 +70,58 @@ def functional_annotations( return rows +# UniProt prefixes each GO term name with its aspect ("P:cell division"); eggNOG and +# InterProScan give bare IDs, which stay "unclassified" until a GO slim mapping exists (#107). +_GO_ASPECTS = {"P": "process", "F": "function", "C": "component"} + + +def _go_detail_rank(term: Term) -> tuple[bool, bool]: + prefix, _, name = term.name.partition(":") + return (prefix in _GO_ASPECTS and bool(name), bool(term.name)) + + +def function_section(annotation: FunctionalAnnotation | None) -> dict[str, Any]: + """What the protein does, in words, for the report (issue #107). + + `status` keeps "not run" apart from "nothing found": a run without `--annotate` or + `--uniprot-function` knows nothing about function, which is not the same as a protein no + provider could describe. + """ + if annotation is None: + return {"status": "not_run"} + go: dict[str, list[dict[str, str]]] = {} + go_terms: dict[str, Term] = {} + for term in annotation.terms: + if term.kind != "go": + continue + previous = go_terms.get(term.term_id) + # Local providers often supply only an ID before UniProt supplies its name + # and aspect. Deduplicate after choosing the richest display record; the + # per-source annotations retain all original evidence. + if previous is None or _go_detail_rank(term) > _go_detail_rank(previous): + go_terms[term.term_id] = term + for term in go_terms.values(): + prefix, _, name = term.name.partition(":") + aspect = _GO_ASPECTS.get(prefix) if name else None + go.setdefault(aspect or "unclassified", []).append( + {"id": term.term_id, "name": (name if aspect else term.name) or None, "source": term.source} + ) + section: dict[str, Any] = { + "description": annotation.description or None, + "description_source": annotation.description_source or None, + "summary": annotation.summary or None, + "summary_source": annotation.summary_source or None, + "summary_evidence": annotation.summary_evidence or None, + "go": go, + "ec": annotation.terms_of("ec"), + "kegg_ko": annotation.terms_of("ko"), + "cog_category": annotation.terms_of("cog_category"), + } + known = section["description"] or section["summary"] or go or section["ec"] or section["kegg_ko"] + section["status"] = "annotated" if known else "none" + return section + + # Which term identifies the hit, most specific first. A COG or KO names the ortholog group the # annotation came from; a COG *category* is a single letter and identifies nothing. _HIT_PREFERENCE = ("cog", "ko", "interpro", "pfam", "ec", "signature", "gene_name", "go") @@ -212,6 +264,7 @@ def protein_enrichment( "related_uniprot": list(xrefs.related_uniprot) if xrefs else [], }, "annotations": annotations, + "function": function_section(functional), "flags": { "virulence": bool(score.components.virulence_amr), "amr": bool(score.components.virulence_amr), diff --git a/tests/test_full_report.py b/tests/test_full_report.py index 62fd2e0..cd66152 100644 --- a/tests/test_full_report.py +++ b/tests/test_full_report.py @@ -142,3 +142,32 @@ def test_cli_dry_run_needs_no_run_directory(tmp_path: Path) -> None: def test_cli_refuses_a_run_directory_with_no_report(tmp_path: Path) -> None: assert main(["--run", str(tmp_path)]) == 2 + + +def _one_selected(function: dict | None) -> dict: + protein = {"feature_id": "fig|1.1.peg.1", "product": "hypothetical protein", + "triage": {"rank": 1, "score": 0.5, "selected": True, "reason": "", "components": {}}} + if function is not None: + protein["function"] = function + return {"run": {"run_id": "fn"}, "proteins": [protein]} + + +def test_selected_targets_say_what_the_protein_does() -> None: + """Issue #107: a target carries a function line, not only structural evidence.""" + html = build_page(_one_selected({ + "status": "annotated", "description": "Outer membrane porin", "description_source": "uniprot", + "summary": "Forms pores that allow passive diffusion.", "summary_source": "uniprot", + "go": {"function": [{"id": "GO:0015288", "name": "porin activity", "source": "uniprot"}]}, + "ec": [], "kegg_ko": ["K09475"], + }), {}) + + assert "Function | " in html + assert "Outer membrane porin" in html + assert "passive diffusion" in html + assert "porin activity" in html + assert "K09475" in html + + +def test_function_not_run_is_not_shown_as_nothing_found() -> None: + assert "not annotated in this run" in build_page(_one_selected(None), {}) + assert "no functional annotation found" in build_page(_one_selected({"status": "none"}), {}) diff --git a/tests/test_m2_function.py b/tests/test_m2_function.py index 38f9bf6..20af29f 100644 --- a/tests/test_m2_function.py +++ b/tests/test_m2_function.py @@ -351,6 +351,11 @@ def uniprot_payload(*, experimental: bool) -> dict: } }, "comments": [ + { + "commentType": "FUNCTION", + "texts": [{"value": "Binds a test substrate in the periplasm.", + "evidences": [{"evidenceCode": code}]}], + }, { "commentType": "SUBCELLULAR LOCATION", "subcellularLocations": [ @@ -890,6 +895,66 @@ def test_uniprot_function_without_map_ids_is_skipped_not_guessed(tmp_path): assert any("--map-ids" in note for note in notes) +# --- function description for the report (issue #107) --------------------------------------- + + +def test_uniprot_function_comment_becomes_the_summary(): + from s2f.m2_triage.function import merge_annotation + + result = parse_uniprot_entry("f1", "P00000", uniprot_payload(experimental=True)) + assert result.summary.value == "Binds a test substrate in the periplasm." + assert result.summary.source == SOURCE_UNIPROT_EXP + + merged = merge_annotation("f1", [result]) + assert merged.description == "Test periplasmic binding protein" + assert merged.summary == "Binds a test substrate in the periplasm." + + +def test_function_section_groups_go_by_aspect_and_keeps_unknown_apart(): + from s2f.m2_triage.function import merge_annotation + from s2f.m2_triage.report_adapter import function_section + + eggnog = ProviderResult(source=SOURCE_EGGNOG, terms=[Term("go", "GO:0005215", source=SOURCE_EGGNOG)]) + uniprot = parse_uniprot_entry("f1", "P00000", uniprot_payload(experimental=False)) + section = function_section(merge_annotation("f1", [uniprot, eggnog])) + + assert section["status"] == "annotated" + assert section["go"]["component"] == [ + {"id": "GO:0042597", "name": "periplasmic space", "source": SOURCE_UNIPROT} + ] + assert section["go"]["unclassified"][0]["id"] == "GO:0005215" + assert section["ec"] == ["1.2.3.4"] + + assert function_section(None) == {"status": "not_run"} + assert function_section(merge_annotation("f2", []))["status"] == "none" + + +@pytest.mark.parametrize("bare_source", [SOURCE_EGGNOG, SOURCE_INTERPROSCAN]) +@pytest.mark.parametrize("bare_first", [True, False]) +def test_function_section_keeps_named_go_term_regardless_of_provider_order(bare_source, bare_first): + from s2f.m2_triage.report_adapter import function_section + + bare = ProviderResult( + source=bare_source, + terms=[Term("go", "GO:0042597", source=bare_source)], + ) + uniprot = parse_uniprot_entry("f1", "P00000", uniprot_payload(experimental=False)) + providers = [bare, uniprot] if bare_first else [uniprot, bare] + merged = merge_annotation("f1", providers) + section = function_section(merged) + + assert section["go"] == { + "component": [ + {"id": "GO:0042597", "name": "periplasmic space", "source": SOURCE_UNIPROT} + ] + } + # The display chooses one term, but the original providers' evidence survives. + rows = functional_annotations(merged, "2026-10-14T00:00:00Z") + assert {row["source"] for row in rows if "GO:0042597" in row.get("terms", {}).get("go", [])} == { + bare_source, SOURCE_UNIPROT + } + + # --- #72: confidence per flag, and a source for lipoprotein ----------------------------------- def _deeptmhmm_plus_heuristic(lipo: bool | None):
|---|