annotuneagent 0.1.0__py3-none-any.whl

annotuneagent/granularity/cl_dag.py

@@ -0,0 +1,179 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Cell Ontology DAG: is_a edges, cycle check, shortest upward distance, LCA."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import deque
+from pathlib import Path
+
+
+class OntologyCycleError(RuntimeError):
+    def __init__(self, cycle: list[str]):
+        self.cycle = cycle
+        shown = " -> ".join(cycle)
+        super().__init__(f"ontology has a cycle: {shown}")
+
+
+class CellOntology:
+    def __init__(self, parents: dict[str, set[str]], labels: dict[str, str], source: dict):
+        self.labels = dict(labels)
+        self.parents = {node: set(items) for node, items in parents.items()}
+        self.source = dict(source)
+        nodes = set(self.parents)
+        for items in self.parents.values():
+            nodes.update(items)
+        self.nodes = nodes
+        self._ancestors: dict[str, set[str]] = {}
+        self._depth: dict[str, int | None] = {}
+        _reject_cycles(self.parents, nodes)
+
+    @property
+    def sha256(self) -> str:
+        return str(self.source.get("sha256") or "")
+
+    def parents_of(self, node: str) -> set[str]:
+        return self.parents.get(node, set())
+
+    def ancestors(self, node: str) -> set[str]:
+        cached = self._ancestors.get(node)
+        if cached is not None:
+            return cached
+        seen: set[str] = set()
+        stack = list(self.parents_of(node))
+        while stack:
+            parent = stack.pop()
+            if parent in seen:
+                continue
+            seen.add(parent)
+            stack.extend(self.parents_of(parent))
+        self._ancestors[node] = seen
+        return seen
+
+    def depth(self, node: str) -> int | None:
+        if node in self._depth:
+            return self._depth[node]
+        seen = {node}
+        queue: deque[tuple[str, int]] = deque([(node, 0)])
+        found: int | None = None
+        while queue:
+            current, dist = queue.popleft()
+            if current == "CL:0000000":
+                found = dist
+                break
+            for parent in self.parents_of(current):
+                if parent not in seen:
+                    seen.add(parent)
+                    queue.append((parent, dist + 1))
+        self._depth[node] = found
+        return found
+
+    def up_dist(self, src: str, dst: str) -> tuple[int, list[str]] | None:
+        """Shortest directed distance from src up is_a edges to dst, and one path."""
+        queue: deque[tuple[str, list[str]]] = deque([(src, [src])])
+        seen = {src}
+        while queue:
+            current, path = queue.popleft()
+            if current == dst:
+                return len(path) - 1, path
+            for parent in sorted(self.parents_of(current)):
+                if parent not in seen:
+                    seen.add(parent)
+                    queue.append((parent, path + [parent]))
+        return None
+
+    def lca(self, left: str, right: str) -> str | None:
+        common = (self.ancestors(left) | {left}) & (self.ancestors(right) | {right})
+        if not common:
+            return None
+
+        def key(node: str) -> tuple[int, str]:
+            dist = self.depth(node)
+            return (-1 if dist is None else -dist, node)
+
+        return min(common, key=key)
+
+
+def load_ontology(path: Path) -> CellOntology:
+    file = Path(path)
+    blob = file.read_bytes()
+    data = json.loads(blob)
+    if "parents" in data and "labels" in data:
+        source = dict(data.get("source") or {})
+        source.setdefault("sha256", hashlib.sha256(blob).hexdigest())
+        parents = {node: set(items) for node, items in data["parents"].items()}
+        return CellOntology(parents, data["labels"], source)
+    if "edges" in data and "id_2_lbl" in data:
+        parents, labels = _from_popv_snapshot(data)
+        source = {
+            "name": file.name,
+            "sha256": hashlib.sha256(blob).hexdigest(),
+            "edges": sum(len(items) for items in parents.values()),
+        }
+        return CellOntology(parents, labels, source)
+    raise ValueError(f"{file} is not a Cell Ontology snapshot")
+
+
+def _from_popv_snapshot(data: dict) -> tuple[dict[str, set[str]], dict[str, str]]:
+    labels = {_norm_id(uri): label for uri, label in data["id_2_lbl"].items()}
+    parents: dict[str, set[str]] = {}
+    for edge in data["edges"]:
+        if edge.get("pred") != "is_a":
+            continue
+        child = _norm_id(edge["sub"])
+        parent = _norm_id(edge["obj"])
+        parents.setdefault(child, set()).add(parent)
+    used = set(parents)
+    for items in parents.values():
+        used.update(items)
+    return parents, {node: labels[node] for node in used if node in labels}
+
+
+def _norm_id(uri: str) -> str:
+    token = uri.rstrip("/").rsplit("/", 1)[-1]
+    if token.startswith("CL_"):
+        return "CL:" + token[3:]
+    return token
+
+
+def _reject_cycles(parents: dict[str, set[str]], nodes: set[str]) -> None:
+    indegree = {node: 0 for node in nodes}
+    for child, items in parents.items():
+        indegree.setdefault(child, 0)
+        for parent in items:
+            indegree[parent] = indegree.get(parent, 0) + 1
+    queue = deque(sorted(node for node, degree in indegree.items() if degree == 0))
+    seen = 0
+    while queue:
+        node = queue.popleft()
+        seen += 1
+        for parent in parents.get(node, ()):
+            indegree[parent] -= 1
+            if indegree[parent] == 0:
+                queue.append(parent)
+    if seen == len(indegree):
+        return
+    remaining = {node for node, degree in indegree.items() if degree > 0}
+    raise OntologyCycleError(_one_cycle(parents, remaining))
+
+
+def _one_cycle(parents: dict[str, set[str]], remaining: set[str]) -> list[str]:
+    for start in sorted(remaining):
+        path: list[str] = []
+        index: dict[str, int] = {}
+        node = start
+        while node in remaining:
+            if node in index:
+                return path[index[node] :] + [node]
+            index[node] = len(path)
+            path.append(node)
+            parent = next(
+                (item for item in sorted(parents.get(node, ())) if item in remaining), None
+            )
+            if parent is None:
+                break
+            node = parent
+    return [sorted(remaining)[0]]

annotuneagent/granularity/ontology_map.py

@@ -0,0 +1,108 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Versioned raw-label map. The ontology file itself is not edited."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+MATCHES = {"exact", "close", "broader", "narrower", "unmapped"}
+STATUSES = {"proposed", "reviewed", "needs_review"}
+
+
+@dataclass(frozen=True)
+class MapEntry:
+    map_version: str
+    raw_label: str
+    species: str
+    cl_id: str | None
+    cl_label: str | None
+    match: str
+    status: str
+    reviewer: str | None
+    evidence: str
+    ontology_sha256: str
+
+
+class OntologyMap:
+    def __init__(self, entries: list[MapEntry]):
+        if not entries:
+            raise ValueError("ontology map is empty")
+        versions = {entry.map_version for entry in entries}
+        hashes = {entry.ontology_sha256 for entry in entries}
+        if len(versions) != 1:
+            raise ValueError(f"ontology map has more than one version: {sorted(versions)}")
+        if len(hashes) != 1:
+            raise ValueError("ontology map rows do not share one snapshot hash")
+        self.version = entries[0].map_version
+        self.ontology_sha256 = entries[0].ontology_sha256
+        self.entries = list(entries)
+        self._rows: dict[tuple[str, str, str], MapEntry] = {}
+        for entry in entries:
+            key = (entry.map_version, entry.raw_label, entry.species)
+            if key in self._rows:
+                raise ValueError(f"duplicate map key {key}")
+            self._rows[key] = entry
+
+    def lookup(
+        self, raw_label: str, species: str | None, *, formal: bool = False
+    ) -> MapEntry | None:
+        for candidate in _species_order(species):
+            entry = self._rows.get((self.version, raw_label, candidate))
+            if entry is None:
+                continue
+            if formal and entry.status != "reviewed":
+                continue
+            return entry
+        return None
+
+    @property
+    def reviewed_only(self) -> bool:
+        return all(entry.status == "reviewed" for entry in self.entries)
+
+
+def load_map(path: Path) -> OntologyMap:
+    entries: list[MapEntry] = []
+    for lineno, line in enumerate(Path(path).read_text().splitlines(), start=1):
+        if not line.strip():
+            continue
+        row = json.loads(line)
+        match = row.get("match")
+        status = row.get("status")
+        if match not in MATCHES:
+            raise ValueError(f"{path}:{lineno}: bad match {match!r}")
+        if status not in STATUSES:
+            raise ValueError(f"{path}:{lineno}: bad status {status!r}")
+        cl_id = row.get("cl_id")
+        if match == "unmapped":
+            if cl_id:
+                raise ValueError(f"{path}:{lineno}: unmapped row has a CL id")
+        elif not cl_id:
+            raise ValueError(f"{path}:{lineno}: mapped row has no CL id")
+        ontology = row.get("ontology") or {}
+        entries.append(
+            MapEntry(
+                map_version=row["map_version"],
+                raw_label=row["raw_label"],
+                species=row["species"],
+                cl_id=cl_id,
+                cl_label=row.get("cl_label"),
+                match=match,
+                status=status,
+                reviewer=row.get("reviewer"),
+                evidence=row.get("evidence") or "",
+                ontology_sha256=ontology.get("sha256") or "",
+            )
+        )
+    return OntologyMap(entries)
+
+
+def _species_order(species: str | None) -> list[str]:
+    order: list[str] = []
+    if species and species != "*":
+        order.append(species)
+    order.append("*")
+    return order

annotuneagent/granularity/relations.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Directed Cell Ontology relation between two labels."""
+
+from __future__ import annotations
+
+from .cl_dag import CellOntology
+from .ontology_map import OntologyMap
+
+
+def popv_onestep(pred: str, gold: str, dag: CellOntology) -> str:
+    """popV `_ontology_accuracy` order: exact, sibling, parent, child, no match.
+
+    `parent` means the prediction is the gold label's direct parent (one step coarser).
+    `child` means the gold label is the prediction's direct parent (one step finer).
+    """
+    if pred == gold:
+        return "exact"
+    pred_parents = dag.parents_of(pred)
+    gold_parents = dag.parents_of(gold)
+    if pred_parents & gold_parents:
+        return "sibling"
+    if pred in gold_parents:
+        return "parent"
+    if gold in pred_parents:
+        return "child"
+    return "no match"
+
+
+def relation(
+    pred_raw: str | None,
+    gold_raw: str | None,
+    species: str | None,
+    dag: CellOntology,
+    label_map: OntologyMap,
+    *,
+    formal: bool = False,
+) -> dict:
+    """Relation of the prediction `pred_raw` to the reference `gold_raw`.
+
+    Ancestor means the prediction is coarser (negative k). Descendant means finer.
+    Distance is directed along is_a. Unmapped labels are not guessed.
+    """
+    if pred_raw is None or gold_raw is None or pred_raw == "" or gold_raw == "":
+        return _blank("abstain")
+    pred_entry = label_map.lookup(pred_raw, species, formal=formal)
+    gold_entry = label_map.lookup(gold_raw, species, formal=formal)
+    pred_id = pred_entry.cl_id if pred_entry is not None else None
+    gold_id = gold_entry.cl_id if gold_entry is not None else None
+    if pred_id is None or gold_id is None:
+        return _blank("unmapped")
+    step = popv_onestep(pred_id, gold_id, dag)
+    if pred_id == gold_id:
+        return {
+            "relation": "exact",
+            "signed_k": 0,
+            "path": [pred_id],
+            "popv_onestep": step,
+            "same_cl_diff_raw": pred_raw != gold_raw,
+        }
+    if pred_id in dag.ancestors(gold_id):
+        found = dag.up_dist(gold_id, pred_id)
+        if found is None:
+            raise RuntimeError(f"missing upward path {gold_id} -> {pred_id}")
+        dist, path = found
+        return _row("ancestor", -dist, path, step)
+    if gold_id in dag.ancestors(pred_id):
+        found = dag.up_dist(pred_id, gold_id)
+        if found is None:
+            raise RuntimeError(f"missing upward path {pred_id} -> {gold_id}")
+        dist, path = found
+        return _row("descendant", dist, path, step)
+    if dag.parents_of(pred_id) & dag.parents_of(gold_id):
+        return _row("sibling", None, None, step)
+    return _row("unrelated", None, None, step)
+
+
+def _blank(kind: str) -> dict:
+    return {
+        "relation": kind,
+        "signed_k": None,
+        "path": None,
+        "popv_onestep": None,
+        "same_cl_diff_raw": False,
+    }
+
+
+def _row(kind: str, signed_k: int | None, path: list[str] | None, step: str) -> dict:
+    return {
+        "relation": kind,
+        "signed_k": signed_k,
+        "path": path,
+        "popv_onestep": step,
+        "same_cl_diff_raw": False,
+    }

annotuneagent/hypotheses.py

@@ -0,0 +1,38 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Caller-supplied cell-type hypotheses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Hypothesis:
+    """One candidate label and the markers that support or oppose it.
+
+    ``positive`` genes should be enriched in the cluster if this label is right.
+    Their mean fold change is the score. A gene detected in fewer than 25% of
+    the cluster's cells is left out of that mean when at least two genes are
+    detected, so an absent gene does not dilute a high one. With fewer than two
+    detected, the whole panel is averaged. ``support`` genes add their fold
+    change when enriched and do not lower the score when absent. ``negative``
+    genes should not be detected. An enriched negative gene lowers the score
+    by its fold change, scaled by the number of positive genes averaged.
+    Absence of a negative gene is not evidence for the label.
+    """
+
+    name: str
+    positive: tuple[str, ...]
+    negative: tuple[str, ...] = ()
+    support: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("hypothesis name is empty")
+        if not self.positive:
+            raise ValueError(f"{self.name}: at least one positive marker is required")
+        object.__setattr__(self, "positive", tuple(self.positive))
+        object.__setattr__(self, "negative", tuple(self.negative))
+        object.__setattr__(self, "support", tuple(self.support))