annotuneagent 0.1.0__py3-none-any.whl

annotuneagent/marker_plot.py

@@ -0,0 +1,172 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Literature backed marker panels checked against the current expression matrix."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import numpy as np
+import scanpy as sc
+from anndata import AnnData
+from scipy import sparse
+
+from .evidence import measure_gene
+from .markers import load_entries
+
+MIN_PCT_IN = 0.25
+MIN_LOGFC = 0.5
+MAX_PVALUE = 0.05
+MAX_MARKERS_PER_TYPE = 4
+
+
+def select_marker_panels(
+    adata: AnnData, label_key: str, species: str | None, tissue: str | None
+) -> tuple[dict[str, list[str]], dict[str, list[dict[str, object]]], dict[str, str]]:
+    """Keep cited positive and support markers that are expressed and enriched.
+
+    A type with no passing marker is still drawn with its best-measured cited
+    genes; its status stays ``no_marker_passed_expression_check``.
+
+    The specificity contrast uses the strongest *other labeled type* so panels
+    form diagonal blocks in a dotplot. The p-value tests the type against all
+    other cells, including cells without a written label.
+    """
+    labels = adata.obs[label_key]
+    names = list(dict.fromkeys(labels.dropna().astype(str)))
+    panels: dict[str, list[str]] = {}
+    checks: dict[str, list[dict[str, object]]] = {}
+    status: dict[str, str] = {}
+    entries = {
+        entry.cell_type: entry
+        for entry in load_entries()
+        if species == entry.species
+        and (entry.scope == "any" or entry.scope == tissue)
+        and "lit=PMID:" in entry.evidence
+    }
+    observed = set(map(str, adata.var_names))
+    # StringDtype NA stays NA through astype(str); a later equality is not a mask.
+    label_text = labels.astype("string").fillna("").to_numpy()
+    position = {name: i for i, name in enumerate(names)}
+    type_codes = np.array([position.get(x, -1) for x in label_text])
+    type_sizes = np.bincount(type_codes[type_codes >= 0], minlength=len(names))
+    for name in names:
+        entry = entries.get(name)
+        if entry is None:
+            checks[name] = []
+            status[name] = "no_literature_backed_dictionary_row"
+            continue
+        mask = label_text == name
+        if mask.all():
+            checks[name] = []
+            status[name] = "no_other_cells_for_expression_test"
+            continue
+        rows: list[dict[str, object]] = []
+        pmids = re.findall(r"PMID:\d+", entry.evidence)
+        cited = (*entry.positive, *entry.support)
+        n_tests = sum(gene in observed for gene in cited)
+        for gene in cited:
+            if gene not in observed:
+                rows.append(
+                    {
+                        "gene": gene,
+                        "literature": entry.evidence,
+                        "pmids": pmids,
+                        "selected": False,
+                        "reason": "not_measured",
+                    }
+                )
+                continue
+            evidence = measure_gene(adata, mask, gene, direction="positive")
+            column = adata[:, gene].X
+            values = (
+                column.toarray().ravel() if sparse.issparse(column) else np.asarray(column).ravel()
+            )
+            linear = np.expm1(values)
+            kept = type_codes >= 0
+            sums = np.bincount(type_codes[kept], weights=linear[kept], minlength=len(names))
+            means = sums / np.maximum(type_sizes, 1)
+            competitor_means = [float(m) for i, m in enumerate(means) if names[i] != name]
+            strongest_other = max(competitor_means, default=evidence.mean_out)
+            specificity_logfc = float(np.log2((evidence.mean_in + 1) / (strongest_other + 1)))
+            adjusted_pvalue = (
+                min(1.0, evidence.pvalue * n_tests) if evidence.pvalue is not None else None
+            )
+            reasons = []
+            if evidence.pct_in < MIN_PCT_IN:
+                reasons.append("low_detection")
+            if evidence.logfc < MIN_LOGFC:
+                reasons.append("not_enriched_vs_all_cells")
+            if specificity_logfc < MIN_LOGFC:
+                reasons.append("not_specific_vs_other_labels")
+            if adjusted_pvalue is None or adjusted_pvalue > MAX_PVALUE:
+                reasons.append("not_significant")
+            rows.append(
+                {
+                    "gene": gene,
+                    "literature": entry.evidence,
+                    "pmids": pmids,
+                    "pct_in": evidence.pct_in,
+                    "mean_in": evidence.mean_in,
+                    "mean_out": evidence.mean_out,
+                    "logfc": evidence.logfc,
+                    "strongest_other_mean": strongest_other,
+                    "specificity_logfc": specificity_logfc,
+                    "pvalue": evidence.pvalue,
+                    "adjusted_pvalue": adjusted_pvalue,
+                    "selected": False,
+                    "reason": "+".join(reasons) if reasons else None,
+                }
+            )
+        eligible = [row for row in rows if row["reason"] is None]
+        eligible.sort(key=lambda row: (-row["specificity_logfc"], -row["pct_in"], row["gene"]))
+        chosen = eligible[:MAX_MARKERS_PER_TYPE]
+        for row in chosen:
+            row["selected"] = True
+        if chosen:
+            panels[name] = [str(row["gene"]) for row in chosen]
+            status[name] = "selected"
+        else:
+            status[name] = "no_marker_passed_expression_check"
+            # The type is still drawn, with its best cited genes, so the figure
+            # shows what was checked. These rows stay selected=False.
+            measured = [row for row in rows if "specificity_logfc" in row]
+            measured.sort(key=lambda row: (-row["specificity_logfc"], -row["pct_in"], row["gene"]))
+            if measured:
+                panels[name] = [str(row["gene"]) for row in measured[:MAX_MARKERS_PER_TYPE]]
+        checks[name] = rows
+    return panels, checks, status
+
+
+def plot_marker_panels(
+    adata: AnnData,
+    label_key: str,
+    panels: dict[str, list[str]],
+    order: list[str],
+    path: Path | str | None = None,
+) -> str | None:
+    """Plot cited, data checked markers with matching type and marker order."""
+    if not panels:
+        return None
+    part = adata[adata.obs[label_key].notna()].copy()
+    ordered_panels = {name: panels[name] for name in order if name in panels}
+    plot = sc.pl.dotplot(
+        part,
+        ordered_panels,
+        groupby=label_key,
+        categories_order=order,
+        dendrogram=False,
+        use_raw=False,
+        standard_scale="var",
+        show=False,
+        return_fig=True,
+    )
+    if path is None:
+        plot.show()
+        return None
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    plot.savefig(str(target))
+    return str(target)

annotuneagent/markers.py

@@ -0,0 +1,206 @@
+# Copyright 2026 Zhao Li (李钊)
+# Licensed under the Apache License, Version 2.0
+
+"""Built-in marker dictionary.
+
+Rows live in ``markers.tsv``. A row is one species and either ``any`` tissue
+or one tissue. Gene symbols are the ones used in that species' matrix.
+"""
+
+from __future__ import annotations
+
+import csv
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .hypotheses import Hypothesis
+
+SPECIES = ("human", "mouse")
+_TABLE = Path(__file__).with_name("markers.tsv")
+# Author phrases that are not themselves a page name. The caller still chooses.
+_AUTHOR_TISSUE = (
+    ("dorsal root ganglion", "drg"),
+    ("dorsal root ganglia", "drg"),
+    ("corneal", "cornea"),
+    ("retinal", "retina"),
+    ("placental", "placenta"),
+    ("thymic", "thymus"),
+    ("endometrial", "endometrium"),
+    ("ovarian", "ovary"),
+    ("testicular", "testis"),
+    ("breast", "mammary"),
+)
+
+
+@dataclass(frozen=True)
+class MarkerEntry:
+    species: str
+    scope: str
+    cell_type: str
+    parent: str | None
+    positive: tuple[str, ...]
+    negative: tuple[str, ...]
+    support: tuple[str, ...]
+    note: str
+    evidence: str
+
+
+def _split_genes(text: str) -> tuple[str, ...]:
+    return tuple(part.strip() for part in text.split(";") if part.strip())
+
+
+def load_entries() -> list[MarkerEntry]:
+    entries: list[MarkerEntry] = []
+    with _TABLE.open(newline="") as handle:
+        for row in csv.DictReader(handle, delimiter="\t"):
+            species = row["species"].strip()
+            scope = row["scope"].strip()
+            if species not in SPECIES:
+                raise ValueError(f"unknown species {species!r} in {_TABLE.name}")
+            if not scope:
+                raise ValueError("empty scope")
+            parent = row["parent"].strip() or None
+            entries.append(
+                MarkerEntry(
+                    species=species,
+                    scope=scope,
+                    cell_type=row["cell_type"].strip(),
+                    parent=parent,
+                    positive=_split_genes(row["positive"]),
+                    negative=_split_genes(row["negative"]),
+                    support=_split_genes(row.get("support") or ""),
+                    note=row.get("note", "").strip(),
+                    evidence=row.get("evidence", "").strip(),
+                )
+            )
+    seen: set[tuple[str, str]] = set()
+    for entry in entries:
+        key = (entry.species, entry.cell_type)
+        if key in seen:
+            raise ValueError(f"duplicate marker row for {key}")
+        if not entry.positive:
+            raise ValueError(f"{entry.cell_type}: no positive markers")
+        seen.add(key)
+    # A parent is another row of the same species. A removed umbrella type must not linger here.
+    for entry in entries:
+        if entry.parent is not None and (entry.species, entry.parent) not in seen:
+            raise ValueError(
+                f"{entry.cell_type}: parent {entry.parent!r} is not a {entry.species} row"
+            )
+    return entries
+
+
+_ENTRIES = load_entries()
+
+
+def _available(species: str, tissue: str | None) -> list[MarkerEntry]:
+    _check_species(species)
+    if tissue is not None and tissue not in tissue_pages(species):
+        raise ValueError(
+            f"unknown {species} tissue {tissue!r}; choose from tissue_pages({species!r})"
+        )
+    return [
+        entry
+        for entry in _ENTRIES
+        if entry.species == species and (entry.scope == "any" or entry.scope == tissue)
+    ]
+
+
+def _check_species(species: str) -> None:
+    if species not in SPECIES:
+        raise ValueError(f"species must be one of {', '.join(SPECIES)}")
+
+
+def tissue_pages(species: str | None = None) -> list[str]:
+    """Tissue pages that can be added to the core dictionary.
+
+    The caller chooses one page and passes it as ``tissue``. Pages are listed
+    in table order.
+    """
+    if species is not None:
+        _check_species(species)
+    pages: list[str] = []
+    for entry in _ENTRIES:
+        if species is not None and entry.species != species:
+            continue
+        if entry.scope == "any" or entry.scope in pages:
+            continue
+        pages.append(entry.scope)
+    return pages
+
+
+def suggest_tissues(author: str, species: str | None = None) -> list[str]:
+    """Pages consistent with an author tissue phrase.
+
+    The caller chooses one and passes it to ``run``. An unmatched phrase
+    returns every page. Dorsal root ganglion returns the ``drg`` page.
+    """
+    pages = tissue_pages(species)
+    text = " ".join(author.casefold().replace("_", " ").replace("-", " ").split())
+    tokens = set(re.findall(r"[a-z0-9]+", text))
+    hits: list[str] = []
+    for phrase, page in _AUTHOR_TISSUE:
+        if phrase in text and page in pages and page not in hits:
+            hits.append(page)
+    for page in pages:
+        if page in tokens and page not in hits:
+            hits.append(page)
+    if not hits:
+        return pages
+    return [page for page in pages if page in set(hits)]
+
+
+def marker_names(species: str, tissue: str | None = None) -> list[str]:
+    """Types that can be scored for this species and optional tissue."""
+    return [entry.cell_type for entry in _available(species, tissue)]
+
+
+def hypotheses_from_names(
+    names: list[str],
+    species: str,
+    tissue: str | None = None,
+) -> list[Hypothesis]:
+    """Look up hypotheses. Tissue rows are visible only when ``tissue`` matches."""
+    by_name = {entry.cell_type: entry for entry in _available(species, tissue)}
+    missing = [name for name in names if name not in by_name]
+    if missing:
+        where = _explain_missing(missing[0], species, tissue)
+        raise KeyError(where)
+    return [
+        Hypothesis(
+            name,
+            positive=by_name[name].positive,
+            negative=by_name[name].negative,
+            support=by_name[name].support,
+        )
+        for name in names
+    ]
+
+
+def _explain_missing(name: str, species: str, tissue: str | None) -> str:
+    other = [
+        entry
+        for entry in _ENTRIES
+        if entry.cell_type == name and entry.species == species and entry.scope != "any"
+    ]
+    if other and tissue != other[0].scope:
+        return f"{name!r} is a {species} {other[0].scope} type; pass tissue={other[0].scope!r}"
+    known = ", ".join(marker_names(species, tissue))
+    return f"unknown cell type {name!r} for {species}. Known names: {known}"
+
+
+def parents_for(
+    names: list[str] | None = None,
+    *,
+    species: str,
+    tissue: str | None = None,
+) -> dict[str, str]:
+    """Map a type to its parent when the selected rows define one."""
+    chosen = marker_names(species, tissue) if names is None else names
+    by_name = {entry.cell_type: entry for entry in _available(species, tissue)}
+    return {
+        name: by_name[name].parent
+        for name in chosen
+        if name in by_name and by_name[name].parent is not None
+    }