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
9 changes: 9 additions & 0 deletions docs/02c-m2-functional-annotation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 19 additions & 0 deletions s2f/common/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -177,6 +195,7 @@
"specialty": {"type": "array"},
"xrefs": _XREFS,
"annotations": {"type": "array", "items": _ANNOTATION},
"function": _FUNCTION,
"flags": _FLAGS,
"triage": _TRIAGE,
},
Expand Down
37 changes: 35 additions & 2 deletions s2f/full_report/render.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<span class='muted'>not annotated in this run</span>"
if status == "none":
return "<span class='muted'>no functional annotation found</span>"
out = []
if function.get("description"):
out.append(f"<b>{esc(function['description'])}</b> "
f"<span class='muted'>({esc(_fmt(function.get('description_source')))})</span>")
if function.get("summary"):
out.append(f"<div>{esc(str(function['summary'])[:400])} "
f"<span class='muted'>({esc(_fmt(function.get('summary_source')))})</span></div>")
go = _mapping(function.get("go"))
for aspect in ("function", "process", "component", "unclassified"):
terms = [term for term in go.get(aspect) or [] if isinstance(term, dict)][:5]
if terms:
label = "GO" if aspect == "unclassified" else f"GO {aspect}"
names = ", ".join(str(term.get("name") or term.get("id")) for term in terms)
out.append(f"<div class='muted'>{esc(label)}: {esc(names)}</div>")
for key, label in (("ec", "EC"), ("kegg_ko", "KO")):
if function.get(key):
out.append(f"<span class='pill'>{label} {esc(', '.join(function[key][:3]))}</span>")
return "".join(out) or "—"


def tab_targets(report: dict[str, Any], m2_run: dict[str, Any]) -> str:
rows = _triage_rows(report)
if not rows:
Expand Down Expand Up @@ -460,8 +492,8 @@ def tab_targets(report: dict[str, Any], m2_run: dict[str, Any]) -> str:
"rank and reason below.</div>")

out.append("<h3>Selected</h3><div class='tablewrap'><table><thead><tr>"
"<th>Rank</th><th>Score</th><th>Product</th><th>Evidence</th>"
"<th>Flags</th><th>Cross-references</th><th>Why</th>"
"<th>Rank</th><th>Score</th><th>Product</th><th>Function</th>"
"<th>Evidence</th><th>Flags</th><th>Cross-references</th><th>Why</th>"
"</tr></thead><tbody>")
best = max((t.get("score") or 0) for _p, t in rows) or 1
for protein, triage in selected:
Expand Down Expand Up @@ -494,6 +526,7 @@ def tab_targets(report: dict[str, Any], m2_run: dict[str, Any]) -> str:
f"{_bar((triage.get('score') or 0) / best)}</td>"
f"<td>{esc(_fmt(protein.get('product')))}<br>"
f"<code>{esc(protein.get('feature_id'))}</code></td>"
f"<td>{_function_cell(protein)}</td>"
f"<td>{parts or '—'}</td><td>{' '.join(pills) or '—'}</td>"
f"<td>{links or '—'}</td>"
f"<td class='muted'>{esc(_fmt(triage.get('reason')))}</td></tr>")
Expand Down
30 changes: 28 additions & 2 deletions s2f/m2_triage/function.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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"
)


Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand Down
55 changes: 54 additions & 1 deletion s2f/m2_triage/report_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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),
Expand Down
29 changes: 29 additions & 0 deletions tests/test_full_report.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<th>Function</th>" 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"}), {})
65 changes: 65 additions & 0 deletions tests/test_m2_function.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -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):
Expand Down
Loading