bindsight 0.3.5__py3-none-any.whl

bindsight/io/cbioportal.py

@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""cBioPortal molecular-subtype fetcher.
+
+Pulls canonical PAM50 intrinsic-subtype calls for a TCGA study from the public
+cBioPortal REST API (https://www.cbioportal.org/api). Subtype labels are keyed
+by patient barcode (``TCGA-XX-XXXX``), which is identical to the GDC
+``cases.submitter_id`` — so the labels map straight onto the STAR-Counts files
+fetched by :mod:`bindsight.io.gdc`.
+
+This is what lets the rediscovery validation run *subtype-stratified* cohorts
+(e.g. HER2-enriched breast tumors vs. adjacent normal), which is the scientific
+prerequisite for recovering a subtype-specific antigen like ERBB2 — bulk
+tumor-vs-normal over the whole BRCA cohort averages the HER2 signal away.
+
+Source: cBioPortal (https://www.cbioportal.org/), Cerami et al. 2012
+(doi:10.1158/2159-8290.CD-12-0095), Gao et al. 2013 (doi:10.1126/scisignal.2004088).
+PAM50 subtypes: Parker et al. 2009 (doi:10.1200/JCO.2008.18.1370).
+"""
+
+from __future__ import annotations
+
+import collections
+import datetime as _dt
+import hashlib
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import requests
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+LOG = logging.getLogger(__name__)
+
+CBIOPORTAL_API = "https://www.cbioportal.org/api"
+DEFAULT_STUDY = "brca_tcga_pan_can_atlas_2018"
+
+
+@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=2, min=2, max=16))
+def _get_subtype_clinical_data(study_id: str) -> list[dict[str, Any]]:
+    """GET the per-patient SUBTYPE clinical attribute for a study (retried)."""
+    resp = requests.get(
+        f"{CBIOPORTAL_API}/studies/{study_id}/clinical-data",
+        params={
+            "clinicalDataType": "PATIENT",
+            "attributeId": "SUBTYPE",
+            "projection": "SUMMARY",
+        },
+        headers={"Accept": "application/json"},
+        timeout=60,
+    )
+    resp.raise_for_status()
+    data: list[dict[str, Any]] = resp.json()
+    return data
+
+
+def fetch_pam50_subtypes(
+    study_id: str = DEFAULT_STUDY,
+    *,
+    cache_dir: Path | None = None,
+) -> dict[str, str]:
+    """Return ``{patient_barcode: subtype_label}`` for a cBioPortal study.
+
+    For ``brca_tcga_pan_can_atlas_2018`` the labels are the PAM50 calls
+    ``BRCA_Basal``, ``BRCA_Her2``, ``BRCA_LumA``, ``BRCA_LumB``, ``BRCA_Normal``.
+
+    Args:
+        study_id: cBioPortal study id.
+        cache_dir: if given, write the raw labels + provenance JSON here and
+            reuse them on subsequent calls (offline after the first run).
+
+    Returns:
+        Mapping from TCGA patient barcode to subtype label.
+    """
+    cache_path = None
+    if cache_dir is not None:
+        cache_dir = Path(cache_dir)
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_path = cache_dir / f"{study_id}_SUBTYPE.json"
+        if cache_path.exists():
+            cached = json.loads(cache_path.read_text(encoding="utf-8"))
+            LOG.info("cBioPortal: using cached subtypes (%d patients)", len(cached["labels"]))
+            return dict(cached["labels"])
+
+    LOG.info("cBioPortal: fetching SUBTYPE for %s", study_id)
+    rows = _get_subtype_clinical_data(study_id)
+    labels = {r["patientId"]: r["value"] for r in rows if r.get("value")}
+    if not labels:
+        raise RuntimeError(f"cBioPortal returned no SUBTYPE labels for {study_id}")
+
+    counts = collections.Counter(labels.values())
+    LOG.info("cBioPortal: %d patients with SUBTYPE (%s)", len(labels), dict(counts))
+
+    if cache_path is not None:
+        payload = {
+            "schema": "bindsight-cbioportal-subtypes/1",
+            "source": "cBioPortal (https://www.cbioportal.org/)",
+            "study_id": study_id,
+            "attribute": "SUBTYPE",
+            "retrieved_utc": _dt.datetime.now(_dt.UTC).isoformat(timespec="seconds"),
+            "n_patients": len(labels),
+            "counts": dict(sorted(counts.items())),
+            "labels": labels,
+        }
+        text = json.dumps(payload, indent=2, sort_keys=True) + "\n"
+        cache_path.write_text(text, encoding="utf-8", newline="\n")
+        payload_sha = hashlib.sha256(text.encode()).hexdigest()
+        (cache_path.parent / f"{study_id}_SUBTYPE.sha256").write_text(
+            payload_sha + "\n", encoding="utf-8", newline="\n"
+        )
+
+    return labels
+
+
+def patients_with_subtype(labels: dict[str, str], subtype: str) -> list[str]:
+    """Return the sorted patient barcodes whose label equals ``subtype``."""
+    return sorted(bc for bc, st in labels.items() if st == subtype)

bindsight/io/gdc.py

@@ -0,0 +1,343 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""NIH/GDC RNA-seq cohort fetcher.
+
+Downloads **real** TCGA gene-expression (STAR - Counts) for a project such as
+``TCGA-BRCA``, assembles a gene × sample integer-count matrix plus a sample
+design table, and writes full provenance (GDC file UUIDs, case barcodes,
+sample types, workflow, retrieval timestamp, SHA-256 of the outputs).
+
+This is what makes ``bindsight demo`` / a ``bindsight discover`` config run on
+authentic patient data rather than illustrative numbers. The GDC open-access
+gene-level expression API needs no token. Outputs are written where the run
+config's ``inputs.counts`` / ``inputs.design`` point (typically a cache dir),
+so the first run downloads and subsequent runs are offline.
+
+Source: GDC Data Portal, https://portal.gdc.cancer.gov/ (NIH/NCI, open access).
+TCGA data usage: https://www.cancer.gov/ccg/research/genome-sequencing/tcga/using-tcga-data/citing
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import gzip
+import hashlib
+import json
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import requests
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+LOG = logging.getLogger(__name__)
+
+GDC_FILES_ENDPOINT = "https://api.gdc.cancer.gov/files"
+GDC_DATA_ENDPOINT = "https://api.gdc.cancer.gov/data/{file_id}"
+
+# STAR-Counts column layout (GENCODE v36); column 3 (0-based) is the raw count.
+_UNSTRANDED_COL = 3
+_SKIP_ROW_PREFIXES = ("N_unmapped", "N_multimapping", "N_noFeature", "N_ambiguous")
+
+_SAMPLE_TYPES = {"tumor": "Primary Tumor", "normal": "Solid Tissue Normal"}
+
+
+@dataclass(frozen=True)
+class CohortSample:
+    """One downloaded sample's provenance."""
+
+    sample: str  # short bindsight sample id, e.g. "T01"
+    condition: str  # "tumor" | "normal"
+    sample_type: str  # GDC sample_type, e.g. "Primary Tumor"
+    case_barcode: str  # TCGA case submitter id
+    sample_barcode: str  # TCGA sample submitter id
+    gdc_file_id: str
+
+
+@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=2, min=2, max=16))
+def _post_files_query(
+    filters: dict[str, Any], fields: list[str], size: int
+) -> list[dict[str, Any]]:
+    """Query the GDC files endpoint; return the hits list (retried on failure)."""
+    resp = requests.post(
+        GDC_FILES_ENDPOINT,
+        json={
+            "filters": filters,
+            "fields": ",".join(fields),
+            "format": "JSON",
+            "size": str(size),
+            "sort": "file_id:asc",  # deterministic selection
+        },
+        timeout=60,
+    )
+    resp.raise_for_status()
+    hits: list[dict[str, Any]] = resp.json()["data"]["hits"]
+    return hits
+
+
+_FILE_FIELDS = [
+    "file_id",
+    "cases.submitter_id",
+    "cases.samples.submitter_id",
+    "cases.samples.sample_type",
+]
+
+
+def _list_cohort_files(
+    project: str, condition: str, n: int, *, cases: list[str] | None = None
+) -> list[dict[str, Any]]:
+    """List STAR-Counts files for a project + tumor/normal class.
+
+    With ``cases=None`` this returns the first ``n`` files (deterministic by
+    ``file_id``). With ``cases`` (a list of TCGA case submitter ids, e.g. the
+    HER2-enriched patients from cBioPortal) it restricts to those cases and
+    de-duplicates to at most one file per case before capping at ``n`` — so a
+    subtype-stratified cohort fetches exactly the patients you asked for.
+
+    An empty list raises. It means the restriction was applied and matched
+    nobody, which is not the same request as ``None`` and must not be answered
+    with an unrestricted cohort.
+    """
+    if cases is not None and not cases:
+        # `None` means "no restriction"; `[]` means "restrict to these, and
+        # there are none". Every guard below was `if cases:`, which merged them,
+        # so a subtype that matched nobody dropped the `cases.submitter_id`
+        # clause and fetched the first `n` files of any subtype instead. The
+        # cohort then carried the label of a stratified one while being an
+        # unstratified sample, with nothing raised, nothing warned, and
+        # `selection: "first_n"` recorded in its own provenance.
+        raise ValueError(
+            f"an empty case list was supplied for {project} {condition}: the "
+            "restriction matched no patients. Passing None asks for an "
+            "unrestricted cohort; passing [] asks for a cohort of nobody, which "
+            "cannot be silently widened to everybody."
+        )
+
+    content = [
+        {"op": "in", "content": {"field": "cases.project.project_id", "value": [project]}},
+        {
+            "op": "in",
+            "content": {"field": "data_type", "value": ["Gene Expression Quantification"]},
+        },
+        {"op": "in", "content": {"field": "analysis.workflow_type", "value": ["STAR - Counts"]}},
+        {
+            "op": "in",
+            "content": {"field": "cases.samples.sample_type", "value": [_SAMPLE_TYPES[condition]]},
+        },
+    ]
+    if cases:
+        content.append({"op": "in", "content": {"field": "cases.submitter_id", "value": cases}})
+
+    # When selecting by case, ask for all matching files (a case can have >1
+    # sample) then dedupe to one-per-case; otherwise just ask for n.
+    size = max(n, len(cases) * 2) if cases else n
+    hits = _post_files_query({"op": "and", "content": content}, _FILE_FIELDS, size=size)
+
+    if cases:
+        seen: set[str] = set()
+        deduped: list[dict[str, Any]] = []
+        for hit in hits:
+            barcode = (hit.get("cases", [{}])[0]).get("submitter_id", "")
+            if barcode and barcode not in seen:
+                seen.add(barcode)
+                deduped.append(hit)
+        hits = deduped
+
+    if len(hits) < n:
+        LOG.warning(
+            "%s %s: requested %d files but only %d available", project, condition, n, len(hits)
+        )
+    return hits[:n]
+
+
+def matched_pair_cases(project: str, *, limit: int = 500) -> list[str]:
+    """Case barcodes with BOTH a primary tumour and a solid-tissue normal.
+
+    A paired differential-expression design removes between-patient variance,
+    which is the largest free power gain available to this study: in most TCGA
+    projects nearly every normal has a tumour from the same patient, so pairing
+    costs no data at all. It only works if both arms are drawn from the same
+    patients, which is what this selects.
+
+    The normal arm is the scarce one — a project with 113 normals and a thousand
+    tumours is limited by the normals — so normals are listed first and tumours
+    are then restricted to those patients.
+
+    Args:
+        project: GDC project id, for example ``"TCGA-BRCA"``.
+        limit: upper bound on files requested per arm.
+
+    Returns:
+        Sorted case submitter ids present in both arms. Sorted so a cohort is
+        reproducible rather than dependent on GDC's response ordering.
+    """
+
+    def _barcodes(condition: str, cases: list[str] | None = None) -> set[str]:
+        hits = _list_cohort_files(project, condition, limit, cases=cases)
+        return {
+            barcode
+            for hit in hits
+            if (barcode := (hit.get("cases", [{}])[0]).get("submitter_id", ""))
+        }
+
+    normals = _barcodes("normal")
+    if not normals:
+        LOG.warning("%s: no solid-tissue-normal files; no paired contrast is possible", project)
+        return []
+    tumours = _barcodes("tumor", cases=sorted(normals))
+    matched = sorted(normals & tumours)
+    LOG.info(
+        "%s: %d normal case(s), %d of which also have a primary tumour",
+        project,
+        len(normals),
+        len(matched),
+    )
+    return matched
+
+
+@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=2, min=2, max=16))
+def _download_counts(file_id: str, gene_types: tuple[str, ...]) -> dict[str, int]:
+    """Download one STAR-Counts file; return {ensembl_gene_id: unstranded_count}.
+
+    Strips the Ensembl version suffix, skips the STAR summary rows and the
+    pseudoautosomal ``_PAR_Y`` duplicates, and optionally restricts to the
+    given gene biotypes.
+    """
+    resp = requests.get(GDC_DATA_ENDPOINT.format(file_id=file_id), timeout=120)
+    resp.raise_for_status()
+    counts: dict[str, int] = {}
+    for line in resp.text.splitlines():
+        if not line or line.startswith("#") or line.startswith("gene_id\t"):
+            continue
+        if line.startswith(_SKIP_ROW_PREFIXES):
+            continue
+        parts = line.split("\t")
+        if len(parts) <= _UNSTRANDED_COL:
+            continue
+        gene_id = parts[0]
+        if "_PAR_Y" in gene_id:
+            continue
+        gene_type = parts[2]
+        if gene_types and gene_type not in gene_types:
+            continue
+        base = gene_id.split(".")[0]
+        try:
+            counts[base] = int(parts[_UNSTRANDED_COL])
+        except ValueError:
+            continue
+    return counts
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def fetch_cohort(
+    *,
+    project: str,
+    n_tumor: int,
+    n_normal: int,
+    counts_out: Path,
+    design_out: Path,
+    gene_types: tuple[str, ...] = ("protein_coding",),
+    tumor_cases: list[str] | None = None,
+    normal_cases: list[str] | None = None,
+) -> dict[str, object]:
+    """Download a real TCGA cohort and write counts + design + provenance.
+
+    Args:
+        project: GDC project id, e.g. ``"TCGA-BRCA"``.
+        n_tumor: number of Primary Tumor samples to download.
+        n_normal: number of Solid Tissue Normal samples to download.
+        counts_out: where to write the gzipped gene × sample counts TSV.
+        design_out: where to write the sample design TSV.
+        gene_types: biotypes to keep (``()`` keeps all). Defaults to
+            protein-coding, which covers the surface-antigen targets and keeps
+            DESeq2 tractable.
+        tumor_cases: optional list of TCGA case submitter ids to restrict the
+            Primary Tumor samples to (e.g. a PAM50 subtype cohort). When given,
+            ``n_tumor`` caps how many of those cases are used.
+        normal_cases: optional list of case submitter ids for the Solid Tissue
+            Normal samples (usually left ``None`` to take adjacent normals).
+
+    Returns:
+        The provenance dict (also written next to ``counts_out`` as
+        ``provenance.json``).
+    """
+    counts_out = Path(counts_out)
+    design_out = Path(design_out)
+    counts_out.parent.mkdir(parents=True, exist_ok=True)
+    design_out.parent.mkdir(parents=True, exist_ok=True)
+
+    LOG.info("GDC: listing %s files (%d tumor + %d normal)…", project, n_tumor, n_normal)
+    tumor_hits = _list_cohort_files(project, "tumor", n_tumor, cases=tumor_cases)
+    normal_hits = _list_cohort_files(project, "normal", n_normal, cases=normal_cases)
+
+    samples: list[CohortSample] = []
+    per_sample_counts: dict[str, dict[str, int]] = {}
+    for condition, hits in (("tumor", tumor_hits), ("normal", normal_hits)):
+        prefix = "T" if condition == "tumor" else "N"
+        for i, hit in enumerate(hits, start=1):
+            sample_id = f"{prefix}{i:02d}"
+            case = hit.get("cases", [{}])[0]
+            sample0 = (case.get("samples") or [{}])[0]
+            LOG.info("GDC: downloading %s (%s) %s…", sample_id, condition, hit["file_id"][:8])
+            per_sample_counts[sample_id] = _download_counts(hit["file_id"], gene_types)
+            samples.append(
+                CohortSample(
+                    sample=sample_id,
+                    condition=condition,
+                    sample_type=sample0.get("sample_type", _SAMPLE_TYPES[condition]),
+                    case_barcode=case.get("submitter_id", ""),
+                    sample_barcode=sample0.get("submitter_id", ""),
+                    gdc_file_id=hit["file_id"],
+                )
+            )
+
+    if not per_sample_counts:
+        raise RuntimeError(f"GDC returned no files for {project}")
+
+    # Assemble the gene × sample matrix on the intersection of genes (all STAR
+    # files share the GENCODE v36 gene set, so this is the full set in practice).
+    counts_df = pd.DataFrame(per_sample_counts).dropna().astype(int)
+    counts_df.index.name = "gene_id"
+    counts_df = counts_df.sort_index()
+
+    with gzip.open(counts_out, "wt", newline="", encoding="utf-8") as fh:
+        counts_df.to_csv(fh, sep="\t")
+
+    design_df = pd.DataFrame([asdict(s) for s in samples]).set_index("sample")
+    design_df.to_csv(design_out, sep="\t", lineterminator="\n")
+
+    provenance: dict[str, object] = {
+        "schema": "bindsight-gdc-cohort/1",
+        "source": "NIH/GDC (https://portal.gdc.cancer.gov/)",
+        "project": project,
+        "workflow": "STAR - Counts (GENCODE v36)",
+        "data_column": "unstranded",
+        "gene_types": list(gene_types),
+        "retrieved_utc": _dt.datetime.now(_dt.UTC).isoformat(timespec="seconds"),
+        "selection": "by_case" if (tumor_cases or normal_cases) else "first_n",
+        "requested_tumor_cases": sorted(tumor_cases) if tumor_cases else None,
+        "requested_normal_cases": sorted(normal_cases) if normal_cases else None,
+        "n_tumor": sum(1 for s in samples if s.condition == "tumor"),
+        "n_normal": sum(1 for s in samples if s.condition == "normal"),
+        "n_genes": int(counts_df.shape[0]),
+        "samples": [asdict(s) for s in samples],
+        "outputs": {
+            counts_out.name: {"sha256": _sha256(counts_out), "bytes": counts_out.stat().st_size},
+            design_out.name: {"sha256": _sha256(design_out), "bytes": design_out.stat().st_size},
+        },
+    }
+    prov_path = counts_out.parent / "provenance.json"
+    prov_path.write_text(json.dumps(provenance, indent=2) + "\n", encoding="utf-8", newline="\n")
+    LOG.info(
+        "GDC: wrote %s (%d genes × %d samples) + %s",
+        counts_out,
+        counts_df.shape[0],
+        counts_df.shape[1],
+        design_out.name,
+    )
+    return provenance

bindsight/io/paths.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Cache and run directory helpers.
+
+Cache layout (resolved via :mod:`platformdirs`):
+
+    <user_cache>/bindsight/
+        surface_bind/<commit_sha>/...
+        alphafolddb/<uniprot_id>.cif.gz
+        opentargets/<query_sha>.json
+
+Run layout (per-run, user-chosen via ``--out``):
+
+    <run_dir>/
+        config.yaml
+        run_manifest.jsonld
+        deg/results.parquet
+        targets/candidates.parquet
+        epitopes/epitopes.parquet
+        structures/<uniprot_id>.cif
+        design/<uniprot_id>/...
+        validate/<uniprot_id>/...
+        rank/ranking.parquet
+        report.html
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from platformdirs import user_cache_path
+
+#: Overrides the cache root. The only cross-platform seam for redirecting the
+#: cache: ``XDG_CACHE_HOME`` is ignored by platformdirs on macOS, and a
+#: ``monkeypatch`` cannot reach a subprocess — which is what the Snakemake
+#: front-end and its test are. Same convention as ``BINDSIGHT_SURFACE_BIND_DATA``.
+ENV_CACHE_DIR = "BINDSIGHT_CACHE_DIR"
+
+#: Subdirectory of a run holding structures copied in from the cache.
+STRUCTURES_SUBDIR = "structures"
+
+
+def cache_root() -> Path:
+    """Return the bindsight cache root, honouring ``BINDSIGHT_CACHE_DIR``."""
+    override = os.environ.get(ENV_CACHE_DIR)
+    if override:
+        base = Path(override).expanduser()
+        base.mkdir(parents=True, exist_ok=True)
+        return base
+    return user_cache_path("bindsight", appauthor=False, ensure_exists=True)
+
+
+def cache_dir(subdir: str | None = None) -> Path:
+    """Return ``<cache_root>/[subdir]``, creating it if missing."""
+    base = cache_root()
+    if subdir is None:
+        return base
+    p = base / subdir
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def run_dir(out: Path | str) -> Path:
+    """Initialize a run directory, creating the standard subdirectories."""
+    root = Path(out)
+    for sub in ("deg", "targets", "epitopes", STRUCTURES_SUBDIR, "design", "validate", "rank"):
+        (root / sub).mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def adopt_structure(run_root: Path | str, source: Path | str) -> str:
+    """Copy a structure into the run's ``structures/`` directory.
+
+    ``structures/`` has always been created by :func:`run_dir` and never written
+    to, while the structure itself stayed in the machine-local cache. Runs were
+    therefore not portable: a candidate table, and any RO-Crate built from it,
+    pointed at absolute paths that exist on exactly one machine.
+
+    Copying is deliberate — the cache is shared across runs and may be pruned,
+    so a hard link or symlink would let an unrelated cleanup silently gut a
+    finished, exported run.
+
+    Args:
+        run_root: The run directory.
+        source: Path to the cached structure file.
+
+    Returns:
+        The path relative to ``run_root``, in POSIX form, suitable for storing
+        in a Parquet column and reading back on another machine.
+    """
+    root = Path(run_root)
+    src = Path(source)
+    dest_dir = root / STRUCTURES_SUBDIR
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / src.name
+    if not dest.exists() or dest.stat().st_size != src.stat().st_size:
+        shutil.copy2(src, dest)
+    return dest.relative_to(root).as_posix()
+
+
+def resolve_run_path(run_root: Path | str, stored: str | Path | None) -> Path | None:
+    """Resolve a path stored in a run artifact back to a real file.
+
+    Accepts both forms deliberately. New runs store run-relative paths so they
+    stay portable; runs produced before that change stored absolute cache
+    paths, and must keep working.
+
+    Args:
+        run_root: The run directory the artifact belongs to.
+        stored: The stored path, possibly empty or ``None``.
+
+    Returns:
+        An existing absolute path, or ``None`` if the reference is empty or
+        cannot be resolved.
+    """
+    if not stored:
+        return None
+    p = Path(stored)
+    if p.is_absolute():
+        return p if p.exists() else None
+    candidate = Path(run_root) / p
+    return candidate if candidate.exists() else None

bindsight/pipelines/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""End-to-end pipeline orchestrators.
+
+Each module here exposes a ``run(config: RunConfig, ...) -> Manifest``
+function that drives a chunk of the pipeline. The Click CLI calls these
+directly (and the Snakefile calls them via ``scripts/``), so behavior stays
+identical regardless of how a user invokes a stage.
+"""

bindsight/pipelines/caveats.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""User-facing scientific caveats for the discovery half.
+
+Single source of truth so the pipeline logs, the run manifest, and the HTML
+report all state the *same* limitations in the same words. Kept dependency-free
+(stdlib only) so the report renderer can import it without pulling in the heavy
+discovery module — the same reason the disposition list is duplicated in
+``bindsight.report.html``.
+
+These are inherent limits of expression-based discovery, not bugs: bindsight
+surfaces them rather than hiding them, consistent with its failure-honest design.
+
+They are also worded for *any* two-condition contrast, because they are stamped
+into every run manifest and every report. One of them used to be written purely
+in tumour vocabulary, so a drug-versus-vehicle experiment came back carrying a
+note about tumour purity — a limitation that is real and general, described in a
+domain the run was not in.
+"""
+
+from __future__ import annotations
+
+# Each entry is (title, body). Rendered as a "Limitations" section in the HTML
+# report, logged at WARNING when discovery runs, and summarised into the run
+# manifest's discover-stage notes.
+DISCOVERY_LIMITATIONS: tuple[tuple[str, str], ...] = (
+    (
+        "mRNA abundance is not cell-surface protein abundance",
+        "Discovery ranks candidates from RNA-seq transcript abundance and a curated "
+        "surfaceome (SURFY). SURFY establishes that a protein *can* reach the cell "
+        "surface; it does not measure how much protein is actually there. Transcript "
+        "level is an imperfect proxy for surface-protein abundance — translation rate, "
+        "membrane trafficking and ectodomain shedding all intervene. Treat surfaced "
+        "candidates as hypotheses to confirm at the protein level (e.g. flow cytometry, "
+        "immunohistochemistry, or the Human Protein Atlas) before committing design effort.",
+    ),
+    (
+        "Bulk expression cannot attribute a transcript to a cell type",
+        "A bulk contrast measures the average over whatever cells each sample "
+        "contained. It cannot tell whether a transcript rose because the cells of "
+        "interest express more of it, or because the two arms hold different "
+        "mixtures of cells. Apparent over-expression can therefore reflect "
+        "composition rather than biology: in a tumour-versus-normal contrast that "
+        "is tumour purity and immune or stromal infiltration; in a treated-versus-"
+        "untreated contrast it is a shift in which cells survived or proliferated; "
+        "between two tissues it is simply that they are made of different cells. "
+        "Single-cell data or deconvolution is what establishes cell-intrinsic "
+        "expression, and neither is implemented (planned for v1.0).",
+    ),
+)
+
+
+def caveat_titles() -> tuple[str, ...]:
+    """Return just the short titles, for logging."""
+    return tuple(title for title, _ in DISCOVERY_LIMITATIONS)
+
+
+def caveat_summary() -> str:
+    """One-line marker for the manifest discover-stage notes."""
+    return "caveats: " + "; ".join(caveat_titles()) + " (see report Limitations)"