bindsight 0.3.5__py3-none-any.whl

bindsight/surfaceome/surfy.py

@@ -0,0 +1,441 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""SURFY surfaceome filter.
+
+SURFY is a curated list of ~2,886 human surface proteins published by
+Bausch-Fluck et al. (PNAS 2018). It's a high-confidence subset of the
+predicted human surfaceome based on a machine-learned classifier trained on
+mass-spec evidence.
+
+Distribution: the full list (its source states no licence; see LICENSING.md)
+is **vendored** in
+``bindsight/surfaceome/data/surfy_v1.uniprot.txt`` (2,886 accessions) and is
+the authoritative source at query time. Discovery therefore needs no network
+access for the surfaceome at all.
+
+That is a deliberate change from lazy-fetching it on first use. The upstream
+spreadsheet is no longer retrievable: ``wlab.ethz.ch`` serves an HTML landing
+page (so ``pandas.read_excel`` died with ``BadZipFile``), and the relocated
+``wollscheidlab.org`` serves a 132-byte Git-LFS pointer. Every fresh install
+was therefore either hard-failing or silently degrading to a ten-protein list
+and surfacing almost no candidates. Regenerate the vendored list with
+``scripts/build_surfy_list.py``.
+
+Resolution order at query time:
+
+1. ``<user_cache>/bindsight/surfy/surfy_v1.uniprot.txt`` — a user-refreshed
+   cache, if one exists, so a newer release can be adopted without upgrading.
+2. The vendored full list — the normal path.
+3. A ten-protein bundled fallback, used only when the first two are missing
+   *and* the caller explicitly allows degraded results.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import resources
+from pathlib import Path
+
+import requests
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from bindsight.io.paths import cache_dir
+
+LOG = logging.getLogger(__name__)
+
+# Number of proteins in the canonical SURFY list (Bausch-Fluck et al. 2018).
+# Used as a sanity check after parsing.
+SURFY_PROTEIN_COUNT = 2886
+
+# Canonical SURFY surfaceome table, Bausch-Fluck et al. PNAS 2018. The site
+# states no licence; the article is CC BY-NC-ND 4.0 (see LICENSING.md).
+#
+# Retained for `populate_surfy_cache`, which is now an explicit opt-in refresh
+# path rather than something the pipeline depends on. As of 2026-07 neither
+# host serves the spreadsheet: the original returns an HTML landing page and
+# the mirror returns a Git-LFS pointer. `load_surfy` uses the vendored list.
+SURFY_XLSX_URL = "https://wollscheidlab.org/SURFY/table_S3_surfaceome.xlsx"
+
+# The full vendored list, generated by scripts/build_surfy_list.py.
+VENDORED_LIST_FILENAME = "surfy_v1.uniprot.txt"
+
+# Bundled fallback for offline tests — a small set of well-characterized
+# surface antigens. NOT a substitute for the full SURFY list in production.
+_OFFLINE_FALLBACK_UNIPROT = frozenset(
+    {
+        "P04626",  # ERBB2 / HER2
+        "P00533",  # EGFR
+        "P56747",  # CLDN6
+        "Q13421",  # MSLN (mesothelin)
+        "P10747",  # CD28
+        "P16410",  # CTLA-4
+        "Q9NZQ7",  # PD-L1 / CD274
+        "P09038",  # FGF2
+        "P10275",  # AR
+        "P19838",  # NF-kB1
+    }
+)
+
+
+def _parse_accessions(text: str) -> frozenset[str]:
+    """Parse one-accession-per-line text, ignoring comments and blanks."""
+    return frozenset(
+        line.strip() for line in text.splitlines() if line.strip() and not line.startswith("#")
+    )
+
+
+def _read_packaged(filename: str) -> str | None:
+    """Read a data file shipped inside the package, or ``None`` if absent."""
+    try:
+        return (
+            resources.files("bindsight.surfaceome")
+            .joinpath("data", filename)
+            .read_text(encoding="utf-8")
+        )
+    except (FileNotFoundError, ModuleNotFoundError, OSError):
+        return None
+
+
+def _bundled_uniprot_set() -> frozenset[str]:
+    """Return the small offline-test surface-protein set bundled with bindsight."""
+    text = _read_packaged("surfy_offline.txt")
+    if text is None:
+        return _OFFLINE_FALLBACK_UNIPROT
+    return _parse_accessions(text)
+
+
+def load_vendored_surfy() -> frozenset[str] | None:
+    """Return the full vendored SURFY accession set, or ``None`` if unavailable.
+
+    This is the canonical list shipped with the package — not a degraded
+    fallback. It exists because the upstream spreadsheet is no longer
+    retrievable; see the module docstring.
+
+    Returns:
+        The full accession set, or ``None`` when the data file is missing (for
+        example in a trimmed-down install).
+    """
+    text = _read_packaged(VENDORED_LIST_FILENAME)
+    if text is None:
+        return None
+    accessions = _parse_accessions(text)
+    return accessions or None
+
+
+def load_surfaceome_extension() -> dict[str, tuple[str, str]]:
+    """Accession -> (source, semicolon-joined Ensembl gene ids), extended reference.
+
+    The SURFY list is prediction-based and demonstrably incomplete: the
+    rediscovery study measured CA9 at a log2 fold change of 9.58 in clear-cell
+    kidney, the largest effect in the whole panel, and could not surface it at any
+    expression level because the accession is absent. STEAP1 is in the same
+    position. Those are instrument-coverage failures, and the fix is a better
+    instrument.
+
+    The extension adds reviewed human proteins UniProt curates as located at the
+    cell membrane — a curated experimental call rather than a second prediction.
+    It is additive: SURFY membership is preserved in the ``source`` field, so a
+    result can be reported against the original list, the extension, or both, and
+    an earlier result stays reproducible.
+
+    Regenerate with ``scripts/build_surfaceome_extension.py``.
+
+    Returns:
+        The mapping, or an empty dict if the file is not packaged.
+    """
+    text = _read_packaged("surfaceome_extended.tsv")
+    if not text:
+        LOG.warning("surfaceome_extended.tsv is not packaged; falling back to the SURFY list alone")
+        return {}
+    out: dict[str, tuple[str, str]] = {}
+    for line in text.splitlines():
+        line = line.rstrip()
+        if not line or line.startswith("#") or line.startswith("accession\t"):
+            continue
+        parts = line.split("\t")
+        if len(parts) < 4:
+            continue
+        accession, _symbol, genes, source = parts[0], parts[1], parts[2], parts[3]
+        if accession:
+            out[accession] = (source, genes)
+    return out
+
+
+def load_surfaceome(*, extended: bool = True) -> frozenset[str]:
+    """The surfaceome accessions to filter on.
+
+    Args:
+        extended: include the UniProt cell-membrane extension alongside SURFY.
+            ``False`` reproduces a SURFY-only run exactly.
+
+    Returns:
+        The accession set. Falls back to SURFY alone if the extension is absent,
+        with a warning, rather than silently narrowing what the tool can see.
+    """
+    core = load_surfy(allow_offline_fallback=False)
+    if not extended:
+        return core
+    extension = load_surfaceome_extension()
+    if not extension:
+        return core
+    return frozenset(core | set(extension))
+
+
+def load_surfaceome_gene_map(*, extended: bool = True) -> dict[str, str]:
+    """Ensembl gene id -> accession, over the chosen surfaceome.
+
+    Merges the vendored SURFY gene map with the extension's own gene ids, so a
+    gene reachable through either reference can be pre-filtered before the
+    enrichment cut.
+    """
+    mapping = dict(load_surfy_gene_map())
+    if not extended:
+        return mapping
+    for accession, (_source, genes) in load_surfaceome_extension().items():
+        for gene in genes.split(";"):
+            if gene:
+                mapping.setdefault(gene, accession)
+    return mapping
+
+
+def load_surfy_gene_map() -> dict[str, str]:
+    """Ensembl gene id -> UniProt accession, for the surfaceome.
+
+    A differential-expression table is keyed by gene id and the surfaceome
+    reference is a list of accessions, so without this mapping "the eligible
+    surfaceome" can only be approximated by whichever genes a run happened to
+    resolve — its enriched subset. A rank taken within that subset is a rank
+    within the pipeline's own output rather than within the set it should be
+    judged against, which defeats the purpose of a counterfactual rank.
+
+    Vendored, so no run needs the network. Regenerate with
+    ``scripts/build_surfy_gene_map.py``.
+
+    Returns:
+        The mapping, or an empty dict if the file is not packaged.
+    """
+    text = _read_packaged("surfy_v1.ensembl.tsv")
+    if not text:
+        LOG.warning(
+            "surfy_v1.ensembl.tsv is not packaged; the eligible surfaceome cannot be "
+            "resolved and any rank taken within it would be misleading"
+        )
+        return {}
+    mapping: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        gene, _, accession = line.partition("	")
+        if gene and accession:
+            mapping[gene] = accession
+    return mapping
+
+
+def surfaceome_source() -> str:
+    """Which list ``load_surfy`` would resolve, as a recordable label.
+
+    The choice between a user-refreshed cache and the vendored list is made
+    silently inside ``load_surfy``. Two runs on two machines could therefore use
+    different surfaceome lists -- different eligible denominators, different
+    counterfactual ranks -- and nothing in either manifest would say so. This
+    reports the decision so the discover stage can record it.
+    """
+    cache_path = _surfy_cache_path()
+    if cache_path.exists() and _parse_accessions(cache_path.read_text(encoding="utf-8")):
+        return f"user cache ({cache_path})"
+    if load_vendored_surfy() is not None:
+        return "vendored"
+    return "bundled fallback (ten proteins)"
+
+
+def load_surfy(*, allow_offline_fallback: bool = True) -> frozenset[str]:
+    """Return the set of UniProt accessions classified as surface by SURFY.
+
+    Resolution order:
+
+    1. ``<user_cache>/bindsight/surfy/surfy_v1.uniprot.txt`` — a refreshed cache,
+       if the user populated one.
+    2. The full vendored list shipped with the package (the normal path).
+    3. The ten-protein bundled fallback.
+
+    ``allow_offline_fallback`` gates **step 3 only**. Its purpose is to stop a
+    run silently producing near-empty results from a ten-protein list; the
+    vendored list is the real SURFY set and does not degrade anything, so it is
+    always acceptable.
+
+    Args:
+        allow_offline_fallback: Permit the tiny bundled list when no full list
+            is available.
+
+    Returns:
+        The set of surface-protein UniProt accessions.
+
+    Raises:
+        FileNotFoundError: No full list is available and the tiny fallback is
+            not permitted.
+    """
+    cache_path = _surfy_cache_path()
+    if cache_path.exists():
+        cached = _parse_accessions(cache_path.read_text(encoding="utf-8"))
+        if cached:
+            return cached
+        LOG.warning("SURFY cache at %s is empty; falling back to the vendored list", cache_path)
+
+    vendored = load_vendored_surfy()
+    if vendored is not None:
+        LOG.debug("using vendored SURFY list (%d accessions)", len(vendored))
+        return vendored
+
+    if not allow_offline_fallback:
+        raise FileNotFoundError(
+            f"No full SURFY list available (cache: {cache_path}, vendored: "
+            f"{VENDORED_LIST_FILENAME}). Reinstall bindsight, run "
+            "scripts/build_surfy_list.py, or set allow_offline_fallback=True "
+            "to accept the small bundled set."
+        )
+
+    LOG.warning(
+        "Using small bundled offline SURFY fallback (%d proteins) — the full "
+        "vendored list is missing from this install. Real discovery runs will "
+        "surface almost nothing.",
+        len(_bundled_uniprot_set()),
+    )
+    return _bundled_uniprot_set()
+
+
+@retry(
+    retry=retry_if_exception_type(requests.RequestException),
+    wait=wait_exponential(multiplier=1, min=2, max=30),
+    stop=stop_after_attempt(5),
+    reraise=True,
+)
+def _download_xlsx(url: str) -> bytes:
+    """Fetch the SURFY spreadsheet, verifying it really is one.
+
+    Every other network client in the package retries; this one did not, and it
+    also trusted a 200 response blindly. Both hosts now answer 200 with
+    something that is not a spreadsheet — an HTML landing page and a Git-LFS
+    pointer respectively — so the old code handed those bytes to openpyxl and
+    surfaced ``BadZipFile: File is not a zip file``, which tells the user
+    nothing about what actually went wrong.
+
+    Args:
+        url: Spreadsheet URL.
+
+    Returns:
+        The raw ``.xlsx`` bytes.
+
+    Raises:
+        RuntimeError: The response was not a spreadsheet.
+    """
+    resp = requests.get(url, timeout=120)
+    resp.raise_for_status()
+    content = resp.content
+
+    # .xlsx is a zip container; anything else is an error page or a pointer.
+    if not content.startswith(b"PK"):
+        content_type = resp.headers.get("content-type", "unknown")
+        if content.startswith(b"version https://git-lfs"):
+            detail = "a Git-LFS pointer file, not the tracked content"
+        elif b"<html" in content[:512].lower():
+            detail = "an HTML page, not a spreadsheet"
+        else:
+            detail = f"{len(content)} bytes that are not a zip/xlsx container"
+        raise RuntimeError(
+            f"SURFY download from {url} returned {detail} "
+            f"(content-type: {content_type}). Upstream has moved or is serving "
+            "a placeholder. bindsight ships the full list already — "
+            "load_surfy() does not need this download."
+        )
+    return content
+
+
+def populate_surfy_cache(*, url: str = SURFY_XLSX_URL, force: bool = False) -> Path:
+    """Refresh the on-disk SURFY cache from the upstream spreadsheet.
+
+    **This is an opt-in refresh path, not a prerequisite.** :func:`load_surfy`
+    reads the full vendored list and needs no network; call this only to adopt
+    a newer upstream release without upgrading bindsight.
+
+    As of 2026-07 neither known host serves the spreadsheet (one returns an
+    HTML page, the other a Git-LFS pointer), so this will raise a descriptive
+    ``RuntimeError``. Regenerating the vendored list with
+    ``scripts/build_surfy_list.py`` is the supported route.
+
+    Args:
+        url: Spreadsheet URL to fetch.
+        force: Re-download even when a cache already exists.
+
+    Returns:
+        Path to the populated cache file.
+
+    Raises:
+        RuntimeError: The download did not yield a spreadsheet, the ``discover``
+            extra is missing, or the table parsed to zero surface proteins.
+    """
+    cache_path = _surfy_cache_path()
+    if cache_path.exists() and not force:
+        return cache_path
+
+    try:
+        import pandas as pd
+    except ImportError as e:  # pragma: no cover - import guard
+        raise RuntimeError(
+            "populate_surfy_cache needs the 'discover' extra (pandas + openpyxl). "
+            'Install with: pip install -e ".[discover]"'
+        ) from e
+
+    LOG.info("downloading SURFY surfaceome table from %s …", url)
+    content = _download_xlsx(url)
+
+    import io
+
+    try:
+        df = pd.read_excel(
+            io.BytesIO(content),
+            sheet_name="SurfaceomeMasterTable",
+            header=1,
+            engine="openpyxl",
+        )
+    except ImportError as e:  # pragma: no cover - import guard
+        raise RuntimeError(
+            "reading the SURFY .xlsx needs openpyxl (in the 'discover' extra). "
+            'Install with: pip install -e ".[discover]"'
+        ) from e
+
+    label = df["Surfaceome Label"].astype(str).str.strip().str.lower()
+    accessions = df.loc[label == "surface", "UniProt accession"].dropna().astype(str).str.strip()
+    accs = sorted({a for a in accessions if a})
+    if not accs:
+        raise RuntimeError("parsed 0 surface proteins from SURFY table; format changed?")
+    if len(accs) != SURFY_PROTEIN_COUNT:
+        LOG.warning(
+            "SURFY surface count %d != expected %d (upstream table may have been revised)",
+            len(accs),
+            SURFY_PROTEIN_COUNT,
+        )
+
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    cache_path.write_text(
+        "# SURFY surfaceome (Bausch-Fluck et al., PNAS 2018; no licence stated by\n"
+        "# the source, article CC BY-NC-ND 4.0; see LICENSING.md).\n"
+        f"# {len(accs)} UniProt accessions labelled 'surface'. Source: {url}\n"
+        + "\n".join(accs)
+        + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    LOG.info("wrote %d surface accessions to %s", len(accs), cache_path)
+    return cache_path
+
+
+def is_surface_protein(uniprot_id: str, *, surfy: frozenset[str] | None = None) -> bool:
+    """Return True if the UniProt accession is in the loaded SURFY set."""
+    if surfy is None:
+        surfy = load_surfy()
+    return uniprot_id in surfy
+
+
+def _surfy_cache_path() -> Path:
+    return cache_dir("surfy") / "surfy_v1.uniprot.txt"

bindsight/targets/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Target evidence: Open Targets enrichment + a bundled ENSG→UniProt fallback."""
+
+from bindsight.targets.open_targets import OpenTargetsClient, TargetEvidence
+
+__all__ = ["OpenTargetsClient", "TargetEvidence"]

bindsight/targets/ensembl_uniprot.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Bundled Ensembl gene ID → UniProt accession map for offline / demo runs.
+
+Used as a fallback when ``use_open_targets`` is disabled (e.g. the demo) or
+when Open Targets is unreachable. The full pipeline always prefers Open
+Targets' authoritative mapping; this is a small curated set of well-known
+human surface antigens + driver oncoproteins kept in sync with the bundled
+``examples/demo`` and the SURFY offline fallback.
+
+Source: UniProt Swiss-Prot canonical IDs as of 2026-05.
+"""
+
+from __future__ import annotations
+
+# (gene_id, symbol, uniprot_id)
+_BUNDLED: dict[str, tuple[str, str]] = {
+    # ---- Surface antigens (also in the SURFY offline fallback) ----
+    "ENSG00000141736": ("ERBB2", "P04626"),  # HER2
+    "ENSG00000146648": ("EGFR", "P00533"),
+    "ENSG00000184697": (
+        "CLDN6",
+        "P56747",
+    ),  # (was wrongly ENSG00000111799/Q14953 = COL12A1/KIR2DS5)
+    "ENSG00000102854": ("MSLN", "Q13421"),  # (was wrongly ENSG00000133110 = POSTN)
+    "ENSG00000086205": ("FOLH1", "Q04609"),  # PSMA — prostate (TCGA-PRAD) target
+    "ENSG00000105383": ("CD33", "P20138"),  # SIGLEC3 — AML target
+    "ENSG00000185291": ("IL3RA", "P26951"),  # CD123 — AML target
+    "ENSG00000178562": ("CD28", "P10747"),
+    "ENSG00000163599": ("CTLA4", "P16410"),
+    "ENSG00000120217": ("CD274", "Q9NZQ7"),  # PD-L1
+    "ENSG00000091831": ("ESR1", "P03372"),
+    # ---- Driver oncoproteins (not surface; used in demo for the "stable / down" rows) ----
+    "ENSG00000142208": ("AKT1", "P31749"),
+    "ENSG00000118260": ("CREB1", "P16220"),
+    "ENSG00000074706": ("PTEN", "P60484"),
+    "ENSG00000196712": ("NF1", "P21359"),
+    "ENSG00000133703": ("KRAS", "P01116"),
+    "ENSG00000174775": ("HRAS", "P01112"),
+    "ENSG00000129965": ("INS-IGF2", "P01308"),
+}
+
+
+def lookup(gene_id: str) -> tuple[str | None, str | None]:
+    """Return ``(symbol, uniprot_id)`` for a gene_id, or ``(None, None)`` if unknown."""
+    if gene_id in _BUNDLED:
+        return _BUNDLED[gene_id]
+    return (None, None)
+
+
+def is_known(gene_id: str) -> bool:
+    """Return True if the bundled map has an entry for ``gene_id``."""
+    return gene_id in _BUNDLED
+
+
+__all__ = ["is_known", "lookup"]