bindsight 0.3.5__py3-none-any.whl

bindsight/cost.py

@@ -0,0 +1,258 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""GPU cost estimator.
+
+Powers ``bindsight design --dry-run`` and ``bindsight run --dry-run``. Returns
+a :class:`bindsight.runners.CostEstimate` for any (backend, designer/validator,
+spec_size) tuple WITHOUT launching anything.
+
+The pricing tables here are conservative point-in-time values (see
+:data:`PRICE_TABLE_VERSION`). They are NOT a quote — actual cloud pricing
+varies with region, spot vs on-demand, and provider promotions. The cost
+shown by ``--dry-run`` is an order-of-magnitude estimate to help users
+decide whether to proceed, not an invoice.
+
+To update prices: bump :data:`PRICE_TABLE_VERSION` and edit
+:data:`GPU_PRICE_USD_PER_HOUR`. Tests pin specific values and will catch
+unintended drift.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from bindsight.runners.protocol import CostEstimate
+
+# Bumped any time the pricing or timing tables change.
+PRICE_TABLE_VERSION = "2026.05"
+
+
+# ---------------------------------------------------------------------------
+# Pricing — USD per GPU-hour, on-demand list price as of PRICE_TABLE_VERSION
+# ---------------------------------------------------------------------------
+# Free-tier providers map to 0.0; users still pay in queue time and quota.
+GPU_PRICE_USD_PER_HOUR: dict[tuple[str, str], float] = {
+    # backend, gpu_type           USD/hr
+    ("modal", "T4"): 0.59,
+    ("modal", "L4"): 0.75,
+    ("modal", "A10G"): 1.10,
+    ("modal", "A100-40GB"): 3.09,
+    ("modal", "A100-80GB"): 3.50,
+    ("modal", "H100"): 4.56,
+    ("colab", "T4"): 0.00,  # Colab free
+    ("colab", "A100-40GB"): 1.40,  # Colab Pro+ compute units, amortized
+    ("kaggle", "T4"): 0.00,  # Kaggle free
+    ("kaggle", "P100"): 0.00,
+    ("local_docker", "T4"): 0.00,
+    ("local_docker", "A100-40GB"): 0.00,
+    ("local_docker", "RTX4090"): 0.00,
+    ("mock", "mock"): 0.00,
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-designer / per-validator GPU-time estimates
+# ---------------------------------------------------------------------------
+# Time PER trajectory or PER design, in seconds, on a reference GPU.
+# These are rough estimates from the upstream papers + community reports.
+# Sources noted inline so we can revise when better data lands.
+
+
+@dataclass(frozen=True)
+class _Timing:
+    seconds_per_unit: float
+    reference_gpu: str
+    notes: str
+
+
+_DESIGNER_TIMING: dict[str, _Timing] = {
+    # RFdiffusion + ProteinMPNN: backbone diffusion ~30s, sequence design ~2s/seq.
+    # We bundle them into one trajectory unit for simplicity.
+    "rfdiff_mpnn": _Timing(
+        seconds_per_unit=45.0,
+        reference_gpu="A100-40GB",
+        notes="RFdiffusion ~30s + ProteinMPNN ~2s/seq, on A100. Free Colab T4 takes ~3-5x longer.",
+    ),
+    # BindCraft: published ~3-5 min/trajectory on A100, requires >=32GB VRAM.
+    "bindcraft": _Timing(
+        seconds_per_unit=240.0,
+        reference_gpu="A100-40GB",
+        notes="BindCraft Nature 2025 paper reports ~3-5 min/trajectory on A100. Needs >=32GB VRAM.",
+    ),
+    # BoltzGen: similar order to RFdiff+MPNN, slightly faster per unit.
+    "boltzgen": _Timing(
+        seconds_per_unit=40.0,
+        reference_gpu="A100-40GB",
+        notes="BoltzGen 2025 release. Approximate; will refine after benchmark in v0.2 paper.",
+    ),
+}
+
+
+_VALIDATOR_TIMING: dict[str, _Timing] = {
+    "boltz2": _Timing(
+        seconds_per_unit=20.0,
+        reference_gpu="A100-40GB",
+        notes="Boltz-2 README claims ~seconds-minutes per complex on A100. 20s/design conservative.",
+    ),
+    "chai1r": _Timing(
+        seconds_per_unit=25.0,
+        reference_gpu="A100-40GB",
+        notes="Chai-1r similar to Boltz-2 in scale.",
+    ),
+    "af2_ig": _Timing(
+        seconds_per_unit=120.0,
+        reference_gpu="A100-40GB",
+        notes="AF2 with initial guess is slower than single-step models.",
+    ),
+}
+
+
+# Approximate scaling factor when running on a slower GPU than the reference.
+# Applied multiplicatively to the per-unit time.
+_GPU_SLOWDOWN: dict[str, float] = {
+    "T4": 4.0,
+    "L4": 2.5,
+    "A10G": 2.0,
+    "P100": 3.0,
+    "A100-40GB": 1.0,
+    "A100-80GB": 1.0,
+    "H100": 0.6,
+    "RTX4090": 1.5,
+    "mock": 0.0,
+}
+
+
+# Default GPU per backend if the user doesn't specify one.
+_DEFAULT_GPU: dict[str, str] = {
+    "modal": "A100-40GB",
+    "colab": "T4",  # free tier
+    "kaggle": "T4",
+    "local_docker": "A100-40GB",  # arbitrary; user knows their hardware
+    "mock": "mock",
+}
+
+
+# Approximate queue waits in minutes (free tiers are queue-prone).
+_QUEUE_WAIT_MIN: dict[str, float] = {
+    "modal": 0.5,  # cold start
+    "colab": 2.0,  # free tier; Pro is faster
+    "kaggle": 3.0,  # free tier
+    "local_docker": 0.0,
+    "mock": 0.0,
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+StageKind = Literal["design", "validate"]
+
+
+def estimate(
+    *,
+    backend: str,
+    stage: StageKind,
+    plugin: str,
+    n_units: int,
+    gpu_type: str | None = None,
+) -> CostEstimate:
+    """Estimate GPU cost for a stage.
+
+    Args:
+        backend: ``"colab"`` | ``"modal"`` | ``"kaggle"`` | ``"local_docker"`` | ``"mock"``.
+        stage: ``"design"`` (cost per design trajectory) or ``"validate"``
+            (cost per design validated).
+        plugin: designer or validator name (e.g. ``"rfdiff_mpnn"``, ``"boltz2"``).
+        n_units: number of trajectories (design) or designs (validate).
+        gpu_type: override the default GPU for the backend.
+
+    Raises:
+        ValueError: if ``backend``/``plugin``/``gpu_type`` is unknown.
+
+    Returns:
+        A :class:`CostEstimate` with the projected GPU-hours and USD.
+    """
+    if backend not in _DEFAULT_GPU:
+        raise ValueError(f"unknown backend: {backend}")
+
+    chosen_gpu = gpu_type or _DEFAULT_GPU[backend]
+    if chosen_gpu not in _GPU_SLOWDOWN:
+        raise ValueError(f"unknown GPU type: {chosen_gpu}. Known: {sorted(_GPU_SLOWDOWN)}")
+
+    timing_table = _DESIGNER_TIMING if stage == "design" else _VALIDATOR_TIMING
+    if plugin not in timing_table:
+        raise ValueError(f"unknown {stage} plugin: {plugin}. Known: {sorted(timing_table)}")
+    timing = timing_table[plugin]
+
+    if chosen_gpu == "mock":
+        seconds = 0.0
+    else:
+        slowdown = _GPU_SLOWDOWN[chosen_gpu]
+        seconds = timing.seconds_per_unit * slowdown * n_units
+
+    gpu_hours = seconds / 3600.0
+    price_per_hour = GPU_PRICE_USD_PER_HOUR.get((backend, chosen_gpu))
+    if price_per_hour is None:
+        raise ValueError(
+            f"no price entry for ({backend}, {chosen_gpu}) in PRICE_TABLE_VERSION={PRICE_TABLE_VERSION}"
+        )
+    usd = round(gpu_hours * price_per_hour, 2)
+    queue = _QUEUE_WAIT_MIN.get(backend, 0.0)
+
+    return CostEstimate(
+        backend=backend,
+        gpu_type=chosen_gpu,
+        gpu_hours=round(gpu_hours, 3),
+        usd_estimate=usd if price_per_hour > 0 else 0.0,
+        queue_minutes_estimate=queue,
+        notes=(
+            f"{plugin}: {timing.seconds_per_unit:.0f}s/unit on {timing.reference_gpu} "
+            f"× slowdown={_GPU_SLOWDOWN[chosen_gpu]:.1f} × n={n_units}. "
+            f"Pricing table {PRICE_TABLE_VERSION}. {timing.notes}"
+        ),
+    )
+
+
+def estimate_full_run(
+    *,
+    backend: str,
+    designer: str,
+    validator: str,
+    n_targets: int,
+    n_trajectories: int,
+    gpu_type: str | None = None,
+) -> tuple[CostEstimate, CostEstimate, CostEstimate]:
+    """Estimate cost for a full design + validate pass.
+
+    Returns ``(design_cost, validate_cost, combined_cost)``.
+    """
+    n_design_units = n_targets * n_trajectories
+    n_validate_units = n_design_units  # validate one structure per design
+
+    d = estimate(
+        backend=backend,
+        stage="design",
+        plugin=designer,
+        n_units=n_design_units,
+        gpu_type=gpu_type,
+    )
+    v = estimate(
+        backend=backend,
+        stage="validate",
+        plugin=validator,
+        n_units=n_validate_units,
+        gpu_type=gpu_type,
+    )
+    combined = CostEstimate(
+        backend=backend,
+        gpu_type=d.gpu_type,
+        gpu_hours=round(d.gpu_hours + v.gpu_hours, 3),
+        usd_estimate=round((d.usd_estimate or 0.0) + (v.usd_estimate or 0.0), 2),
+        queue_minutes_estimate=d.queue_minutes_estimate,
+        notes=(
+            f"combined: design ({n_design_units} units of {designer}) + "
+            f"validate ({n_validate_units} units of {validator})"
+        ),
+    )
+    return d, v, combined

bindsight/deg/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Differential expression analysis (pydeseq2)."""
+
+from bindsight.deg.pydeseq2_runner import PyDESeq2Runner
+
+__all__ = ["PyDESeq2Runner"]

bindsight/deg/pydeseq2_runner.py

@@ -0,0 +1,285 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""pydeseq2 wrapper.
+
+Wraps `pydeseq2 <https://github.com/scverse/PyDESeq2>`_ (MIT) so the rest of
+the pipeline gets a clean, Pydantic-validated DEG result regardless of which
+backend ran.
+
+.. note::
+   pydeseq2 is **not bit-equivalent** to R's DESeq2. Numeric results agree to
+   within machine precision for default settings on the supported test
+   matrices, but any user expecting cross-paper-equivalent statistics should
+   use the optional R-bridge runner. See LICENSING.md for the GPL caveat.
+
+Output schema (Parquet):
+
+==========  =========  ==========================================================
+column      dtype      meaning
+==========  =========  ==========================================================
+gene_id     str        feature ID as it appears in the counts matrix index
+log2fc      float64    log2 fold-change for the configured contrast
+lfc_se      float64    standard error of log2fc
+stat        float64    Wald statistic
+pvalue      float64    raw p-value
+padj        float64    FDR-adjusted p-value (Benjamini-Hochberg)
+baseMean    float64    mean of normalized counts across all samples
+contrast    str        e.g. ``condition__tumor_vs_normal``
+significant bool       padj < params.fdr_threshold AND |log2fc| ≥ log2fc_threshold
+==========  =========  ==========================================================
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from bindsight.config import DEGParams
+
+LOG = logging.getLogger(__name__)
+
+
+class PyDESeq2Runner:
+    """Run pydeseq2 against a counts matrix + sample design."""
+
+    name = "pydeseq2"
+
+    def __init__(self, params: DEGParams) -> None:
+        self.params = params
+
+    # ------------------------------------------------------------------ #
+    # I/O                                                                #
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def load_counts(path: Path) -> pd.DataFrame:
+        """Read a counts TSV (gene × sample, integer counts)."""
+        return pd.read_csv(
+            path,
+            sep="\t",
+            index_col=0,
+            compression="infer",
+        )
+
+    @staticmethod
+    def load_design(path: Path) -> pd.DataFrame:
+        """Read a sample design TSV. The first column must be the sample ID."""
+        return pd.read_csv(path, sep="\t", index_col=0)
+
+    # ------------------------------------------------------------------ #
+    # Validation                                                         #
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _require_integer_counts(counts: pd.DataFrame) -> None:
+        """Reject a counts matrix holding non-integer values.
+
+        DESeq2's negative-binomial model is defined on raw counts. A TPM/FPKM/
+        normalised matrix silently truncates toward zero on the integer cast
+        (0.7 → 0, 3.9 → 3), after which the test still returns confident
+        p-values that mean nothing. Integral floats (``5.0``) are accepted —
+        count matrices routinely round-trip through float dtypes. Non-finite
+        values are left to the cast, which rejects them on its own.
+
+        Args:
+            counts: Gene × sample matrix as read from disk.
+
+        Raises:
+            ValueError: If any value is finite but not integral, naming a few
+                offending gene/sample cells.
+        """
+        values = np.asarray(counts.to_numpy(), dtype=np.float64)
+        non_integer = np.isfinite(values) & (values != np.trunc(values))
+        if not bool(non_integer.any()):
+            return
+        rows, cols = np.nonzero(non_integer)
+        examples = ", ".join(
+            f"{counts.index[i]}/{counts.columns[j]}={values[i, j]:g}"
+            for i, j in zip(rows[:3], cols[:3], strict=True)
+        )
+        raise ValueError(
+            "counts matrix contains non-integer values — DESeq2 requires raw integer "
+            "counts, not TPM/FPKM/normalised expression; "
+            f"{int(non_integer.sum())} of {values.size} values are non-integer "
+            f"(e.g. {examples})"
+        )
+
+    def _require_replicated_contrast_levels(self, design: pd.DataFrame) -> None:
+        """Reject a design whose contrast levels are not both replicated.
+
+        The total-sample check upstream is blind to how the samples split: a
+        5-tumour / 1-normal cohort clears ``2 * min_replicates`` yet leaves
+        DESeq2 estimating a within-group dispersion from a single sample.
+
+        Args:
+            design: Sample design restricted to the samples actually analysed.
+
+        Raises:
+            ValueError: If the contrast factor is absent, or either contrast
+                level has fewer than ``min_replicates`` samples.
+        """
+        factor, numerator, denominator = self.params.contrast
+        if factor not in design.columns:
+            raise ValueError(
+                f"contrast factor {factor!r} is not a column of the design "
+                f"(columns: {sorted(map(str, design.columns))})"
+            )
+        per_level = design[factor].astype(str).value_counts()
+        for level in (numerator, denominator):
+            n_level = int(per_level.get(level, 0))
+            if n_level < self.params.min_replicates:
+                raise ValueError(
+                    f"contrast level {factor}={level!r} has {n_level} sample(s); "
+                    f"need at least min_replicates={self.params.min_replicates} per level "
+                    "for a valid dispersion estimate"
+                )
+
+    # ------------------------------------------------------------------ #
+    # Filtering                                                          #
+    # ------------------------------------------------------------------ #
+    def _low_count_filter(self, counts: pd.DataFrame) -> pd.DataFrame:
+        """Drop genes with fewer than ``min_count`` counts in ``min_replicates`` samples."""
+        keep = (counts >= self.params.min_count).sum(axis=1) >= self.params.min_replicates
+        n_dropped = int((~keep).sum())
+        if n_dropped:
+            LOG.info(
+                "low-count filter: dropping %d / %d genes (min_count=%d, min_replicates=%d)",
+                n_dropped,
+                len(counts),
+                self.params.min_count,
+                self.params.min_replicates,
+            )
+        return counts.loc[keep]
+
+    # ------------------------------------------------------------------ #
+    # Run                                                                #
+    # ------------------------------------------------------------------ #
+    def run(
+        self,
+        counts_path: Path,
+        design_path: Path,
+        out_path: Path,
+    ) -> dict[str, Any]:
+        """Run pydeseq2 and write the DEG table as Parquet to ``out_path``.
+
+        Returns a metrics dict suitable for embedding in the manifest's
+        ``params``/``notes`` field.
+        """
+        counts = self.load_counts(counts_path)
+        design = self.load_design(design_path)
+
+        # Sanity-check sample alignment.
+        common = counts.columns.intersection(design.index)
+        missing_in_design = set(counts.columns) - set(common)
+        missing_in_counts = set(design.index) - set(common)
+        if missing_in_design:
+            LOG.warning("samples in counts but not design: %s", sorted(missing_in_design))
+        if missing_in_counts:
+            LOG.warning("samples in design but not counts: %s", sorted(missing_in_counts))
+        if len(common) < 2 * self.params.min_replicates:
+            raise ValueError(
+                f"only {len(common)} samples in common between counts and design; "
+                f"need at least {2 * self.params.min_replicates}"
+            )
+
+        counts = counts[common]
+        design = design.loc[common]
+
+        self._require_integer_counts(counts)
+        self._require_replicated_contrast_levels(design)
+
+        # Filter low-count genes BEFORE pydeseq2 (faster + more stable estimates).
+        counts = self._low_count_filter(counts)
+
+        results_df = self._run_pydeseq2(counts, design)
+        results_df = self._postprocess(results_df)
+
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        results_df.to_parquet(out_path, index=False)
+
+        n_sig = int(results_df["significant"].sum())
+        LOG.info(
+            "wrote %s: %d genes tested, %d significant (FDR<%g, |log2fc|≥%g)",
+            out_path,
+            len(results_df),
+            n_sig,
+            self.params.fdr_threshold,
+            self.params.log2fc_threshold,
+        )
+        return {
+            "n_samples": len(common),
+            "n_genes_tested": len(results_df),
+            "n_significant": n_sig,
+            "fdr_threshold": self.params.fdr_threshold,
+            "log2fc_threshold": self.params.log2fc_threshold,
+            "n_cpus": self.params.n_cpus,
+        }
+
+    # ------------------------------------------------------------------ #
+    # pydeseq2 invocation (split out so tests can mock it)               #
+    # ------------------------------------------------------------------ #
+    def _run_pydeseq2(self, counts: pd.DataFrame, design: pd.DataFrame) -> pd.DataFrame:
+        """Invoke pydeseq2; returns the raw results_df keyed by gene ID."""
+        # Lazy-import so the module loads cleanly even if pydeseq2 isn't installed.
+        from pydeseq2.dds import DeseqDataSet
+        from pydeseq2.default_inference import DefaultInference
+        from pydeseq2.ds import DeseqStats
+
+        # pydeseq2 wants samples × genes (rows = samples).
+        counts_t = counts.T.astype(int)
+        dds = DeseqDataSet(
+            counts=counts_t,
+            metadata=design,
+            design=self.params.design_formula,
+            refit_cooks=True,
+            # n_cpus=None lets pydeseq2 use every core, which is correct on a
+            # server and hostile on a laptop running a multi-hour cohort sweep.
+            inference=DefaultInference(n_cpus=self.params.n_cpus),
+            quiet=True,
+        )
+        dds.deseq2()
+
+        # alpha drives pydeseq2's independent filtering, so it must be the FDR the
+        # user configured — otherwise the filter is tuned for a threshold nobody asked for.
+        ds = DeseqStats(
+            dds,
+            contrast=self.params.contrast,
+            alpha=self.params.fdr_threshold,
+            quiet=True,
+        )
+        ds.summary()
+        return ds.results_df
+
+    # ------------------------------------------------------------------ #
+    # Postprocess: standardise column names + add ``significant``        #
+    # ------------------------------------------------------------------ #
+    def _postprocess(self, df: pd.DataFrame) -> pd.DataFrame:
+        # pydeseq2's columns: log2FoldChange, lfcSE, stat, pvalue, padj, baseMean
+        out = df.rename(
+            columns={
+                "log2FoldChange": "log2fc",
+                "lfcSE": "lfc_se",
+            }
+        )
+        out = out.reset_index().rename(columns={"index": "gene_id"})
+        contrast_label = (
+            f"{self.params.contrast[0]}__{self.params.contrast[1]}_vs_{self.params.contrast[2]}"
+        )
+        out["contrast"] = contrast_label
+        out["significant"] = (out["padj"].fillna(1.0) < self.params.fdr_threshold) & (
+            out["log2fc"].abs() >= self.params.log2fc_threshold
+        )
+        cols = [
+            "gene_id",
+            "log2fc",
+            "lfc_se",
+            "stat",
+            "pvalue",
+            "padj",
+            "baseMean",
+            "contrast",
+            "significant",
+        ]
+        return out[cols]

bindsight/design/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2026 Mikhaeel Atef Rizk Wahba
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Designer plugin interface.
+
+Designers consume ``(structure, epitope)`` and produce designed binders.
+Implementations are loaded via the ``bindsight.designers`` entry point group
+(see pyproject.toml). Note that the CLI currently validates ``--designer``
+against a fixed ``click.Choice`` of the built-in names, and
+``runners.job_exec`` dispatches on the same fixed set, so a third-party
+designer is not yet usable without also editing those two places. Lifting
+that restriction is a roadmap item.
+
+Built-in designers:
+
+- ``rfdiff_mpnn`` (default) — RFdiffusion backbone + ProteinMPNN sequence,
+  T4-friendly, BSD-3 / MIT.
+- ``bindcraft`` — BindCraft one-shot AF2-based, A100 (≥32 GB), MIT.
+- ``boltzgen`` — BoltzGen universal binder design, MIT.
+"""
+
+from bindsight.design.protocol import Designer, DesignResult, DesignSpec
+
+__all__ = ["DesignResult", "DesignSpec", "Designer"]