bindsight 0.3.5__py3-none-any.whl

bindsight-0.3.5.dist-info/METADATA

@@ -0,0 +1,495 @@
+Metadata-Version: 2.5
+Name: bindsight
+Version: 0.3.5
+Summary: A reproducible bridge from RNA-seq to de novo protein binder design, with end-to-end provenance.
+Project-URL: Homepage, https://mikhaeelatefrizk.github.io/bindsight/
+Project-URL: Documentation, https://mikhaeelatefrizk.github.io/bindsight/
+Project-URL: Repository, https://github.com/mikhaeelatefrizk/bindsight
+Project-URL: Issues, https://github.com/mikhaeelatefrizk/bindsight/issues
+Project-URL: Changelog, https://github.com/mikhaeelatefrizk/bindsight/blob/main/CHANGELOG.md
+Author-email: Mikhaeel Atef Rizk Wahba <mikhaeelatefrizk@proton.me>
+License-Expression: AGPL-3.0-or-later
+License-File: COPYRIGHT
+License-File: LICENSE
+Keywords: AlphaFold,BindCraft,Boltz,PROV-O,ProteinMPNN,RFdiffusion,RNA-seq,RO-Crate,bioinformatics,de-novo-binder-design,protein-design,reproducibility,target-discovery
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markupsafe>=2.1
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.32
+Requires-Dist: rich>=13.7
+Requires-Dist: tenacity>=8.4
+Provides-Extra: all
+Requires-Dist: biopython<2,>=1.83; extra == 'all'
+Requires-Dist: fastapi<1,>=0.110; extra == 'all'
+Requires-Dist: kaggle>=1.6; extra == 'all'
+Requires-Dist: matplotlib<4,>=3.8; extra == 'all'
+Requires-Dist: modal>=0.64; extra == 'all'
+Requires-Dist: numpy<3,>=1.26; extra == 'all'
+Requires-Dist: openpyxl>=3.1; extra == 'all'
+Requires-Dist: pandas<3,>=2.2; extra == 'all'
+Requires-Dist: pyarrow<25,>=16; extra == 'all'
+Requires-Dist: pydeseq2<0.6,>=0.5; extra == 'all'
+Requires-Dist: scipy<2,>=1.11; extra == 'all'
+Requires-Dist: snakemake>=8.0; extra == 'all'
+Requires-Dist: uvicorn<1,>=0.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx2<3,>=2.0; extra == 'dev'
+Requires-Dist: mypy<3,>=2.1; extra == 'dev'
+Requires-Dist: packaging>=22; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: discover
+Requires-Dist: biopython<2,>=1.83; extra == 'discover'
+Requires-Dist: numpy<3,>=1.26; extra == 'discover'
+Requires-Dist: openpyxl>=3.1; extra == 'discover'
+Requires-Dist: pandas<3,>=2.2; extra == 'discover'
+Requires-Dist: pyarrow<25,>=16; extra == 'discover'
+Requires-Dist: pydeseq2<0.6,>=0.5; extra == 'discover'
+Requires-Dist: scipy<2,>=1.11; extra == 'discover'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: pillow>=10; extra == 'docs'
+Provides-Extra: embed
+Requires-Dist: torch<3,>=2.0; extra == 'embed'
+Requires-Dist: transformers<6,>=4.40; extra == 'embed'
+Provides-Extra: report
+Requires-Dist: fastapi<1,>=0.110; extra == 'report'
+Requires-Dist: matplotlib<4,>=3.8; extra == 'report'
+Requires-Dist: uvicorn<1,>=0.27; extra == 'report'
+Provides-Extra: runners
+Requires-Dist: kaggle>=1.6; extra == 'runners'
+Requires-Dist: modal>=0.64; extra == 'runners'
+Provides-Extra: workflow
+Requires-Dist: snakemake>=8.0; extra == 'workflow'
+Description-Content-Type: text/markdown
+
+# bindsight
+
+> **Expression → Binder.** An open-source pipeline that joins cohort RNA-seq target
+> discovery to de novo protein binder design in one reproducible workflow, with
+> machine-readable provenance from every ranked binder back to the patient samples
+> it came from.
+
+[![CI](https://github.com/mikhaeelatefrizk/bindsight/actions/workflows/ci.yml/badge.svg)](https://github.com/mikhaeelatefrizk/bindsight/actions/workflows/ci.yml)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
+[![Python: 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Workflow: Snakemake](https://img.shields.io/badge/workflow-Snakemake-brightgreen.svg)](https://snakemake.github.io/)
+
+Genomics tooling stops at *"here are the interesting genes."* Protein-design
+tooling starts at *"given a target…"*. The bridge between them is built ad-hoc,
+per project, and rarely reproducibly. bindsight ships that bridge as one tool,
+and carries a PROV-O / RO-Crate audit trail across the join.
+
+---
+
+## Start here
+
+Everything below is in this repository. Nothing on this page requires a website,
+an account, or a GPU to read.
+
+| If you want to… | Go to |
+|---|---|
+| **Run it in five minutes** | [Install](#install), then `bindsight demo` |
+| **See what it has and has not shown** | [What the evidence says](#what-the-evidence-says) |
+| **Reproduce a published number** | [Reproducing the results](#reproducing-the-results) |
+| **Understand how it works** | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| **Read the study** | [`benchmarks/study/`](benchmarks/study/) · [write-up](paper/validation/manuscript.md) |
+| **Read the control that withdrew a headline** | [`benchmarks/calibration/`](benchmarks/calibration/) |
+| **See the provenance chain, run end to end** | [`benchmarks/provenance_join/`](benchmarks/provenance_join/) |
+| **Find your way around the code** | [Repository map](#repository-map) |
+| **Use your own data** | [Scope — what it accepts](#scope--what-it-accepts) |
+| **Design binders on a free GPU** | [`RUN_FREE_GPU.md`](benchmarks/designer_benchmark/RUN_FREE_GPU.md) |
+| **Look up a term** (PROV-O, RO-Crate, ipTM, PAE-int…) | [Glossary](docs/glossary.md) |
+| **Contribute** | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| **Cite it** | [Citation](#citation) |
+
+---
+
+## Install
+
+One command, one way. Python 3.11+, Windows / macOS / Linux, CPU only.
+
+```bash
+git clone https://github.com/mikhaeelatefrizk/bindsight.git
+cd bindsight
+pip install -e ".[discover,report]"
+```
+
+Add `dev` if you intend to run the tests (`pip install -e ".[dev,discover,report]"`),
+and `runners` if you intend to send work to a GPU backend. Conda users can build the
+same dependency set first with `mamba env create -f envs/discover.yaml`.
+
+Check the install, then run the demo:
+
+```bash
+bindsight --version
+bindsight doctor
+bindsight demo
+```
+
+`bindsight demo` runs the full discovery half on a **real TCGA-BRCA
+tumour-versus-adjacent-normal cohort**, auto-downloaded from NIH/GDC, and writes an
+HTML report you can open in a browser. It needs internet on first run (the cohort
+and the enrichment lookups are cached afterwards) and takes a few minutes of real
+DESeq2. No GPU.
+
+For a local interface over the same thing — the evidence behind every claim
+below, the demo, your own cohort, and the predicted binder–target complexes
+rendered in 3-D. Served from your machine; nothing is fetched from a network
+once installed.
+
+```bash
+bindsight ui      # opens http://localhost:8501
+```
+
+---
+
+## What the evidence says
+
+Stated plainly, including the parts that did not work. Each claim links to the
+artifacts it comes from.
+
+### The discovery half
+
+Run on **fifteen whole, unstratified TCGA projects** as patient-paired contrasts,
+scored against a panel of 22 antigen-cohort pairs fixed in git before any cohort was
+run. Nothing in a cohort's definition refers to the antigen being sought.
+
+Two null models, and they point in different directions — both are reported, because
+reporting only one would make the other the finding:
+
+- **Against abundance- and dispersion-matched decoys — negative.** 3 of 22 pairs are
+  nominally significant; **none survives Benjamini-Hochberg** across the panel. The
+  smallest adjusted value this panel could have produced is 0.022, so a pair could
+  genuinely have survived — the negative is a measurement, but not a sensitive one.
+- **Against a permuted assignment of indications — positive.** Mean standing
+  **0.858** against every reassignment of cohorts to antigens, **exact permutation
+  p = 3.97e-04 over all 5,040 orderings**. 5,040 is 7!, because the test is
+  restricted to the **7 antigens with a single indication** in the panel — an
+  antigen used in two cancers has no one cohort to permute. That p is the floor
+  this design can express, so it says the result is as extreme as an exhaustive
+  enumeration of this panel can show, not that it is vanishingly unlikely.
+
+  *Calibration, on its own denominator.* KICH and THCA carry no panel antigen and
+  were run to show what no signal looks like on this scale. Antigens sit at mean
+  standing **0.765** in the cancer they are actually used in against **0.417**
+  there: a **within-antigen difference of 0.348 (95% CI 0.188–0.513),
+  cluster-bootstrapped over 13 antigens**, each antigen its own control, interval
+  excluding zero. It carries an interval and no p-value — the permutation p above
+  belongs to the 7-antigen test and is not the significance of this difference,
+  which no test reports.
+
+The indication-specificity null is the strongest claim this project supports, and
+it is a claim about the **ordering**, not about any individual hit. Absolute recall is low and
+stated as such: at rank 20 it is 1 of 17 on approved-agent antigens (95% CI
+0.01–0.27). Most clinically validated antigens are simply not significantly
+over-expressed in an unstratified bulk contrast.
+
+→ [`benchmarks/study/RESULTS.md`](benchmarks/study/RESULTS.md) · [write-up](paper/validation/manuscript.md)
+
+### The design half
+
+The pipeline runs RFdiffusion → ProteinMPNN → Boltz-2 end to end on a free Kaggle
+T4 and produces real predicted complexes. What it does **not** establish is that
+those designs bind.
+
+A paired control folds every design beside a shuffle of its own sequence — same
+length, same composition, order destroyed. Under a seeded validator averaging five
+diffusion draws, **the shuffles cleared the customary ipTM 0.65 bar more often than
+the designs did** (50% against 30%; paired difference −0.043, 95% CI −0.142 to
++0.054; 9 of 20 designs beat their own shuffle, where 10 is chance).
+
+`success@0.65` is therefore **withdrawn as a measure of design quality**, and this
+page does not quote it as one. The ipTM values are real Boltz-2 outputs; what does
+not follow is that the rate measures the designs. The control's predictions were
+written down before its data arrived.
+
+→ [`benchmarks/calibration/`](benchmarks/calibration/) · [`benchmarks/designer_benchmark/`](benchmarks/designer_benchmark/)
+
+### The join
+
+The claim the project rests on — a reviewer can start at a ranked binder and reach
+the patient samples it came from — was exhibited once, end to end, on a target the
+discovery half chose for itself: CA9 at rank 1 and CD70 at rank 2 out of TCGA-KIRC,
+carried through to 40 designs and a walkable PROV-O graph. The committed manifest
+lets you verify the first three steps of that walk from this clone; the rest needs
+the crate rebuilt, and that directory says so precisely.
+
+→ [`benchmarks/provenance_join/`](benchmarks/provenance_join/)
+
+### What has not been done
+
+- The three-way designer comparison (RFdiffusion+ProteinMPNN vs BindCraft vs
+  BoltzGen) is **not run**. Both alternatives need 24–32 GB against anything larger
+  than a small domain, so those arms require paid backends; on free hardware no
+  shipped backend can run them.
+- The calibration's own power analysis puts **142 paired designs** at 80% power to
+  detect a 0.05 ipTM difference. The committed control has 20.
+
+---
+
+## Scope — what it accepts
+
+The pipeline takes a **counts matrix** and a **sample design table** naming a
+two-level factor, and contrasts those two levels. Nothing on that path knows about
+cancer. `tumor` and `normal` are values you supply, not values the code expects:
+[`tests/test_non_cancer_cohort.py`](tests/test_non_cancer_cohort.py) drives the whole
+documented path on a drug-versus-vehicle experiment paired within donor, with no
+oncology vocabulary anywhere, and asserts that none leaks into the provenance
+manifest.
+
+Three parts *are* domain-specific, and they are separable:
+
+- **The optional `inputs.download` block** fetches a cohort from NIH/GDC, so it knows
+  TCGA's sample type names. Point `inputs.counts` and `inputs.design` at your own
+  files and it never runs.
+- **The rediscovery benchmark** scores recovery of known tumour antigens. It is an
+  evaluation harness for the ranker, not part of a run.
+- **The safety gate** compares candidates against GTEx normal-tissue baselines. That
+  is a human resource, and so are the SURFY surfaceome, the UniProt membrane
+  extension and SURFACE-Bind's site inventory.
+
+So the honest scope is **any human bulk RNA-seq contrast between two conditions** —
+disease versus healthy, treated versus untreated, responder versus non-responder,
+one tissue versus another. Non-human cohorts would need substitutes for four
+reference resources, none of which is wired in.
+
+---
+
+## What it does
+
+```
+  bulk RNA-seq counts                               Designed protein binders
+              │                                              ▲
+              │                                              │
+              ▼                                              │
+   Differential expression  ──►  Surface-exposed  ──►  De novo backbone
+   (pydeseq2)                   (SURFY)              (RFdiffusion / BindCraft / BoltzGen)
+                                     │                       │
+                                     ▼                       ▼
+                              Targetable sites          Sequence design
+                              (SURFACE-Bind)            (ProteinMPNN)
+                                     │                       │
+                                     ▼                       ▼
+                              AlphaFoldDB structure     Affinity + structure
+                                                        validation
+                                                        (Boltz-2 / Chai-1r)
+                                                              │
+                                                              ▼
+                                                  Multi-objective ranking
+                                                              │
+                                                              ▼
+                                       HTML report + RO-Crate (FAIR)
+                                       with full PROV-O provenance
+```
+
+### Commands
+
+| Capability | Status | How to try |
+|---|---|---|
+| **`bindsight demo`** — full discovery on a real cohort + report | ✅ ready | `bindsight demo` |
+| **`bindsight discover`** — your own RNA-seq cohort → ranked targets | ✅ ready | `bindsight discover my.yaml --out runs/x` |
+| **`bindsight ui`** — local interface: the evidence, a demo, your own data, past runs, and the 20 predicted complexes in 3-D | ✅ ready | `bindsight ui` |
+| **`bindsight report`** — paper-style HTML, embedded volcano + provenance | ✅ ready | `bindsight report runs/x` |
+| **`bindsight run`** — full orchestrator (discover → design → validate → rank → report → export) | ✅ ready | `bindsight run my.yaml --out runs/x` |
+| **`bindsight design`** — RFdiffusion + ProteinMPNN + Boltz-2 on a free Kaggle T4 | ✅ runs end to end | `bindsight design runs/x --backend kaggle` |
+| **`bindsight design <run_dir> --dry-run`** — GPU cost estimate before spending | ✅ ready | `bindsight design runs/x --backend modal --dry-run` |
+| **`bindsight validate`** — materialise the design job's metrics | ✅ ready | `bindsight validate runs/x` |
+| **`bindsight rank`** — multi-objective composite scoring | ✅ ready | `bindsight rank runs/x` |
+| **`bindsight export`** — RO-Crate zip for deposit | ✅ ready | `bindsight export runs/x --out runs/x.crate.zip` |
+| **`bindsight benchmark`** — score rediscovery of held-out known antigens | ✅ ready | `bindsight benchmark runs/x --known-antigens benchmarks/known.tsv` |
+| **`bindsight doctor`** — diagnose deps, caches, vendored data | ✅ ready | `bindsight doctor` |
+| **`bindsight verify-licenses`** — per-component license inventory | ✅ ready | `bindsight verify-licenses` |
+| **Snakemake front-end** — the same stage functions as a DAG | ✅ ready, stops before the crate | `snakemake --configfile my.yaml --cores 4` (needs `.[workflow]`) |
+| **BindCraft / BoltzGen / Chai-1r / AF2-IG** | ⚠️ wired, but no shipped backend can run them | The executor dispatches to all four, and no backend builds an environment in which that dispatch succeeds. The CLI refuses the combination locally rather than spending GPU quota discovering it — see below |
+
+### Runner and plugin status
+
+Not every backend carries the same weight of evidence, and presenting them as peers
+would be misleading.
+
+| | Status | Why |
+|---|---|---|
+| **Kaggle** | The verified free path | Headless via the Kaggle API, so a reader can re-run the exact job on their own free quota. Pinned to a T4: Kaggle's own docs warn its default P100 cannot run current PyTorch. |
+| **local_docker** | For your own GPU | Native and containerised modes; the native mode is what CPU tests exercise. |
+| **Modal** | Prepared, not executed | The paid escape hatch for what free hardware cannot reach. Its image carries the whole design stack, but running it costs money and it has not been run end to end. |
+| **Colab** | Interactive on-ramp only | Google's API does not permit launching a free-tier notebook from a CLI, so this path needs a human with a browser tab open. That is a demo, not a reproducibility path. |
+| **RFdiffusion, ProteinMPNN, Boltz-2** | Verified on free hardware | The committed benchmark ran the whole stack on a free Kaggle T4, from a wheel built out of this tree. All 20 designs carry a target chain byte-identical to the native domain IV, so "the target was held fixed" is a check rather than a claim. |
+| **AF2 initial-guess** | Buildable free | PyRosetta is credential-free for non-commercial use since 2024, and is the restriction on this path; the AlphaFold2 parameters are CC BY 4.0. |
+| **BindCraft, BoltzGen** | Reduced-target only on free hardware | Both fit a 16 GB card against a small domain, not a full receptor. BoltzGen's integration was rewritten after its command was found not to exist upstream. |
+| **Chai-1r** | Needs Ampere or newer | It requires bfloat16, which no free-tier GPU has. Verifying it means renting roughly an hour of a modern card. |
+
+> **Note on GPU stages.** The design and validation models require CUDA, so they run
+> on the backend you choose, not on the CPU host.
+
+---
+
+## Reproducing the results
+
+Three tiers, because they cost very different things.
+
+**1. Regenerate the published pages from committed artifacts — offline, seconds.**
+
+```bash
+python scripts/build_docs_results.py   # rewrites docs/results.md; it should not change
+python -m pytest -q                    # 2000+ tests, no network
+```
+
+**2. Re-run the rediscovery study — needs network, a few CPU-hours.**
+
+Cohorts are downloaded from NIH/GDC on first use and cached under `data/gdc_cache/`,
+which is not committed; the download is the slow part.
+
+```bash
+python benchmarks/run_study.py --all --cpus 2   # fetches + runs DESeq2
+python benchmarks/run_study.py --score-only     # re-scores what is already on disk
+```
+
+**3. Re-run the binder design — needs a GPU.**
+
+`score_run.py` is a scorer, not a runner: it consumes the archive a GPU run
+produces. The full chain is in
+[`RUN_FREE_GPU.md`](benchmarks/designer_benchmark/RUN_FREE_GPU.md), which runs on a
+free Kaggle T4.
+
+```bash
+python benchmarks/designer_benchmark/prepare_erbb2_target.py
+python benchmarks/run_designer_benchmark.py --backend kaggle \
+    --designers rfdiff_mpnn --trajectories 10 \
+    --structures-dir data/target_structures \
+    --out benchmarks/designer_benchmark/run
+python benchmarks/designer_benchmark/score_run.py <out_dir>/<id>.tar.gz \
+    --n-trajectories 10 --out benchmarks/designer_benchmark
+```
+
+---
+
+## Repository map
+
+Each top-level area carries its own `README.md` explaining what is in it and
+why — [`bindsight/`](bindsight/), [`tests/`](tests/), [`scripts/`](scripts/),
+[`benchmarks/`](benchmarks/) and each benchmark under it, [`docs/`](docs/),
+[`examples/`](examples/), [`envs/`](envs/) and [`paper/`](paper/). Package
+subdirectories are documented in the table below rather than individually.
+
+| Path | What it holds |
+|---|---|
+| [`bindsight/`](bindsight/) | The Python package — [`io`](bindsight/io/), [`deg`](bindsight/deg/), [`targets`](bindsight/targets/), [`surfaceome`](bindsight/surfaceome/), [`structures`](bindsight/structures/), [`epitopes`](bindsight/epitopes/), [`design`](bindsight/design/), [`runners`](bindsight/runners/), [`validate`](bindsight/validate/), [`rank`](bindsight/rank/), [`benchmark`](bindsight/benchmark/), [`pipelines`](bindsight/pipelines/), [`provenance`](bindsight/provenance/), [`export`](bindsight/export/), [`report`](bindsight/report/) |
+| [`benchmarks/`](benchmarks/) | All the evidence — the [study](benchmarks/study/), the [calibration control](benchmarks/calibration/), the [designer benchmark](benchmarks/designer_benchmark/), the [provenance join](benchmarks/provenance_join/), and the held-out antigen set |
+| [`tests/`](tests/) | 2,000+ tests. Many are guards on published claims, not on code |
+| [`paper/`](paper/) | JOSS and bioRxiv manuscripts, and the validation write-up |
+| [`docs/`](docs/) | Long-form documentation (mkdocs-material source) |
+| [`examples/`](examples/) | Runnable pipeline configs |
+| [`envs/`](envs/) | Conda environment for the discovery half, with pinned constraints |
+| [`scripts/`](scripts/) | Generators for vendored data and published pages |
+| [`.github/workflows/`](.github/workflows/) | CI, docs, docker, release artifacts, and the two paper PDFs |
+
+| File | What it is |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | The architectural source of truth |
+| [CHANGELOG.md](CHANGELOG.md) | Per-version changes |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, testing, commit conventions |
+| [LICENSING.md](LICENSING.md) | Per-dependency licence inventory and commercial-use guidance |
+| [SECURITY.md](SECURITY.md) | How to report a vulnerability |
+| [CITATION.cff](CITATION.cff) | Citation metadata |
+| [Snakefile](Snakefile) | The Snakemake DAG front-end |
+
+---
+
+## Who it's for
+
+- **Translational researchers** who want a free, reproducible "data → designed
+  binder" pipeline.
+- **Clinical biologists** who need an audit trail back from a binder to the cohort.
+- **Method developers** who want a held-out evaluation harness to benchmark new
+  designers and validators.
+- **Anyone with a two-condition human RNA-seq experiment** — the cancer framing
+  throughout this document reflects where it has been validated, not what it accepts.
+
+## What's distinctive
+
+| | Existing protein-design tools | bindsight |
+|---|---|---|
+| Input | Target structure | RNA-seq counts |
+| Provenance | PDB + maybe a log | PROV-O JSON-LD + RO-Crate, audit trail to the cohort |
+| Hardware | HPC assumed | CPU laptop + offload to a free Kaggle T4 |
+| Cost-awareness | None | `--dry-run` estimates GPU spend before running |
+| Negative results | Discarded | Catalogued (`failure_taxonomy.parquet`), and published |
+| Citability | Code dump | Tagged releases with SHA-256 checksums, JSON-Schema-validated outputs |
+
+For the full landscape comparison, see
+[ARCHITECTURE.md § 8](ARCHITECTURE.md#8-comparison-vs-existing-tools).
+
+---
+
+## Acknowledgments
+
+bindsight is an opinionated wrapper. Real intellectual credit belongs to the upstream
+tool authors. See [LICENSING.md](LICENSING.md) for the full inventory; the work this
+builds on most directly:
+
+- [SURFACE-Bind](https://github.com/hamedkhakzad/SURFACE-Bind) (Balbi et al., PNAS 2026) — the targetable-sites catalog that makes the bridge tractable
+- [pydeseq2](https://github.com/scverse/PyDESeq2) (Muzellec et al., Bioinformatics 2023) — Python DESeq2 implementation
+- [RFdiffusion](https://github.com/RosettaCommons/RFdiffusion) (Watson et al., Nature 2023) — backbone generation
+- [ProteinMPNN](https://github.com/dauparas/ProteinMPNN) (Dauparas et al., Science 2022) — sequence design
+- [Boltz-2](https://github.com/jwohlwend/boltz) (Wohlwend et al., 2025) — structure + affinity prediction
+- [BindCraft](https://github.com/martinpacesa/BindCraft) (Pacesa et al., Nature 2025) — one-shot binder design
+- [Snakemake](https://github.com/snakemake/snakemake) (Mölder et al., F1000Research 2021) — workflow orchestration
+
+## Citation
+
+This release is not archived under a DOI. Cite the repository, the tag you ran
+and the checksums attached to the release, plus the author:
+
+> Wahba, M. A. R. (2026). *bindsight: a reproducible bridge from RNA-seq to de
+> novo protein binder design* (version X.Y.Z).
+> <https://github.com/mikhaeelatefrizk/bindsight>
+
+Citation metadata also lives in [CITATION.cff](CITATION.cff); GitHub's "Cite this
+repository" button generates BibTeX and APA from it. Every release attaches a
+wheel, an sdist and a `SHA256SUMS` file, and every image is digest-pinned, so
+the artifacts behind a version are checkable even though the version has no
+DOI. From 0.3.5 a release also carries the bioRxiv manuscript and the JOSS
+paper as PDFs, typeset by CI. Please also cite the upstream tools you used — each run emits a
+`software.bib` to make that straightforward.
+
+## About the author
+
+bindsight is built and maintained by **Mikhaeel Atef Rizk Wahba**, an
+independent researcher in Cairo, Egypt.
+
+- ORCID: [0009-0006-1069-9558](https://orcid.org/0009-0006-1069-9558)
+- GitHub: [@mikhaeelatefrizk](https://github.com/mikhaeelatefrizk)
+- Email: `mikhaeelatefrizk@proton.me`
+
+## License
+
+- **Code:** [GNU AGPL-3.0-or-later](LICENSE) — copyright notice in [COPYRIGHT](COPYRIGHT). You may use, study, modify, and
+  redistribute bindsight freely; if you distribute a modified version **or run it as
+  a network service**, you must make your source available under the same licence,
+  with attribution preserved. See [LICENSING.md](LICENSING.md) for component-level
+  details — bindsight orchestrates external tools that keep their own licences, and
+  some carry non-commercial terms.

bindsight-0.3.5.dist-info/RECORD

@@ -0,0 +1,106 @@
+bindsight/README.md,sha256=IHj9CqEe6OaXTrYM7t5kv8t7yriQ2X_UZwek_0pCGpQ,2752
+bindsight/__init__.py,sha256=CxfVze-SJzWgIa-0tsTshfkLRsZq2HGUtHNWI2AvG9A,458
+bindsight/cli.py,sha256=eoJVLUR_nCMu3Ob53ZkcXY19ernXuU-hqoboSDQ3x2g,97928
+bindsight/config.py,sha256=NvJ5yVEq58lNshq5GWO3CVSHT5qb8cA6nnKdvncf_rM,20271
+bindsight/cost.py,sha256=FtJKTYLIaoF8RSiofqONhA9fIDSObwOFmKKNp0ijAFM,8672
+bindsight/plugins.py,sha256=ppD8SfKc_2HlntdeXE5OFo5Mnpwh31Tx8m1yzX5UlyM,13775
+bindsight/benchmark/__init__.py,sha256=9ZGQY990f7Mc6yPfegbku2fqIS0Pigc_Vv7QA4nuOH4,2853
+bindsight/benchmark/core.py,sha256=EXbabufH4mqdwbXQ0gTi680aRe5wNwr3VyZ_MCjWxlQ,20602
+bindsight/benchmark/defaults.py,sha256=8FOmNa9tjc5nafSmwLH9386FuCWh95m6uEkEaJ8bAdI,1247
+bindsight/benchmark/designer_bench.py,sha256=Tr87LlokYrNH0-ecaDd_mnVSL5GBkSiyW035SnSYJvU,39876
+bindsight/benchmark/outcomes.py,sha256=idxPR4JBqbfU3dVblMSxlUwmnl0lfpdJt19SEhu74CQ,21629
+bindsight/benchmark/panel.py,sha256=xqMIbM2YddW1CU1aQi1AQswIXQsE2Jiigxlkf3rpYhQ,26474
+bindsight/benchmark/rediscovery.py,sha256=Pn7GkyEckBkfgk7EpZr92n3H22gE2AbRgqrVKc8tlH4,48741
+bindsight/benchmark/statistics.py,sha256=MF9HRn57tFaWMom4S5GLVEuOJE2nBU72M7UCtml2d9o,24480
+bindsight/benchmark/study.py,sha256=j1h6XoRD-ocQwmD8nGHh_N-1UhleQNIoKXUAJmYIyt0,50797
+bindsight/benchmark/study_figures.py,sha256=TWY8FFG7fwJMsOBcVGQ8gSt1Acri4J8CqhxoX0mNs08,6479
+bindsight/benchmark/study_report.py,sha256=au2DrDKlEe-6csct5B1TvkPgFZRoKT2wOtGW5qRE6vQ,26378
+bindsight/deg/__init__.py,sha256=MbTbI05Mwb7w8jxIIamnZgf753_yHiVoEyKAomAcFks,240
+bindsight/deg/pydeseq2_runner.py,sha256=YAVttucqnot9y4kX49GT5qi520Rp-r9dpvVQi7LW_TI,11852
+bindsight/design/__init__.py,sha256=-alFskc8Hn749axvFkr_qOqYpeFq9OYHOQBbOhFobEg,988
+bindsight/design/_common.py,sha256=Tu144LbcfV5udAvRZ5z6R48DtiJBuF_fgCRWrLOiPv0,22815
+bindsight/design/bindcraft.py,sha256=oIaSNkqcg9EJMlC2nRnLq-Tx3M70-CvcwCsqAFtzpig,2936
+bindsight/design/boltzgen.py,sha256=g02eea8zoUQey71LT2hMKBuItSY1ULKB8Kejt7itZuM,2929
+bindsight/design/developability.py,sha256=o859No05U95ks5UzbJHvGuJl_NAwWPBtJiZW36OG23Q,5878
+bindsight/design/embeddings.py,sha256=TUHlht1eRiAFvIfGOqTqSw-HPdlMfsPFMvPxyI2TBN4,6536
+bindsight/design/prescreen.py,sha256=nwUSkfmgFDmPjVMfofPoe6vu1en_dZyXer29Bqzr7fM,6471
+bindsight/design/protocol.py,sha256=NR0dvcBrJ41p4Obc2kwvs628xszTVfbjzqMBW2gjUrs,4379
+bindsight/design/rfdiff_mpnn.py,sha256=T2VHf_3fHs7Bkx8SqOf9gAU72c_KTNdsMIsMADOi3sI,3625
+bindsight/epitopes/__init__.py,sha256=3RN6-PDH9qor4HqSwEFIoNTOaS0BSjxVEvF8AbUprEA,323
+bindsight/epitopes/surface_bind.py,sha256=rMyN8GHk6Vprk1AwG5nHb0Pf0a2dgh5uVnmIsvsYImc,5954
+bindsight/export/__init__.py,sha256=9W9aiIprA6NcWoiA0nN57t55xKt-zVjiXktkotO-lCY,253
+bindsight/export/ro_crate.py,sha256=ws7VqF5L2Yp6h0xuNd3fpY5nHjBMpGsLm4edtfKwKUY,23919
+bindsight/io/__init__.py,sha256=vaccHAFXPg4WFRW4fifgBGBQEcilLOczE-aS5LGsAIc,400
+bindsight/io/cbioportal.py,sha256=jiSGQ3QXp11BSWahu1Rz-BoRTrO-6QLuEMkST7rNJW8,4596
+bindsight/io/gdc.py,sha256=Zggcb1PwUztwvgumgFpEHUo6i5umjwQ8EdQdBqIpNSY,14000
+bindsight/io/paths.py,sha256=6Fa2UQQkzO0EvWZpaVuZvz8hcJnU2RnEsJrUAZ-Gu6k,4229
+bindsight/pipelines/__init__.py,sha256=giDVlYyMU4fNNVJ39O3I61BiE-jXhMEZhI7HhkaT_AA,415
+bindsight/pipelines/caveats.py,sha256=gzvRJVLy-3MDs8YZbKZrYyu22QrAzilCR75_k2hcoQE,3219
+bindsight/pipelines/discover.py,sha256=Vcmf21G-ASP_j0EBnG6ejyIUtn9LG_OucGQZjznT0tE,63610
+bindsight/pipelines/full_run.py,sha256=BuScLDTgNR3GR91gl8Ye8Gwsd3Eor_vuExYU9-FzAHs,16081
+bindsight/provenance/__init__.py,sha256=-vPdU3mFhPTe-3v2hAuYWJT-T8pmlUZCQMXkV_yxBbM,899
+bindsight/provenance/append.py,sha256=5drH_e9Z-fnXy6v5ZUosQ93V_MBN4xov20xdwd5v7ug,7238
+bindsight/provenance/fragments.py,sha256=svQNuYvX5MAu9t-D_8gXI30fpvheqlx7GCk5q-VeqzM,7445
+bindsight/provenance/manifest.py,sha256=t4r6SxoGh0plvW3KFJ3fr5Y6EJgDo-GXYvvrtmAv4rM,20351
+bindsight/rank/__init__.py,sha256=oHzRIupAKAIvPK5ltuV-JJC1BMuy42_XkHhem69pnMc,256
+bindsight/rank/scoring.py,sha256=-vFynGZD4fo4ljP1sosJtWpTS00F3x74t3cZf9udFDQ,16078
+bindsight/report/__init__.py,sha256=qe9onfweRn37SW4E7ykXZakShonNrkJ7F4rZ81lDFT4,1568
+bindsight/report/format.py,sha256=J59pfTi4_jsolwe_hSmCnMI0SkUG9-xfyAc08nZj07c,3614
+bindsight/report/html.py,sha256=svlx-qTb9FiEB37gI-qoC7eVBGJyroE_Ttjbhxzcem4,26285
+bindsight/report/showcase.py,sha256=B9sWzAtPMKXGEuHx27uF5IbmSvFCTUh7Wf9_eGHYHgI,25863
+bindsight/report/theme.py,sha256=MDncvPCQpzIeYVk62o3hze19IcarxKgmB0mkdUtdKeI,10296
+bindsight/report/web/__init__.py,sha256=CDP6ewvAT4Vs2cTCtHTXNqfSTuCH8DcA0hw3DhqyIPE,1521
+bindsight/report/web/app.py,sha256=v3LONLEU-mzaxrZLZtHlDuWOPylDFqN1JP1O1jNHzq4,23653
+bindsight/report/web/static/binder_viewer.js,sha256=7pm21kydNJa4ZGGxV4a7UwudcdDJx8AJqXvGrIHmLqc,10753
+bindsight/report/web/static/bindsight.css,sha256=Uy8-bbMAI_c7ch5OELQ-IAKYE-MF3KK176IMH18_vs4,16735
+bindsight/report/web/static/charts.js,sha256=xLKGcyaCnVrWdDGELOX7aoVSKjIc2nP-8E2uRlpSSvU,16344
+bindsight/report/web/static/your_data_check.js,sha256=DioBgZ05QRkwLf6BQ1U3qEfClqdEfLRJ-a20lmWc9tY,13892
+bindsight/report/web/static/vendor/3Dmol-min.js,sha256=98x4khrnLnYj6JzdERQ09Ywu_d0v_aHNISZEtAb7gBY,537792
+bindsight/report/web/static/vendor/3Dmol.LICENSE,sha256=TG6q7YVvPyijsamOdPSopxYY3n1R6kFVwp9veTvO-GE,4283
+bindsight/report/web/templates/base.html.j2,sha256=NG8Cb8-FfCeTIm_Qyy65zt75xkWSaAc3hXiPk_ODOYQ,1620
+bindsight/report/web/templates/evidence.html.j2,sha256=yWtO59iY64GAj-rIhgfk9Fpf59wvSt0Au7070PdLKnk,14870
+bindsight/report/web/templates/overview.html.j2,sha256=UjcgM7LW0XpugrId_PKxBoYX3hiSA-EIN8WWTTf4sdo,5617
+bindsight/report/web/templates/runs.html.j2,sha256=Y6m7arCv6J6ygkhUWPPGH6LwZzuFPJjb1OAL5Jr8HPY,5025
+bindsight/report/web/templates/try.html.j2,sha256=-UA7-5X36eJXs6itz5wQyJqLpq7U1FIpdULQPUR8o9k,5710
+bindsight/report/web/templates/your_data.html.j2,sha256=qKZlV4C271W9L4qFWMBml-N27niPxLulmHtrRtlel8g,1823
+bindsight/runners/__init__.py,sha256=BTNeNMySM2ebrVDsWbL1nAFVxw7PQKpOXpPNNuflnNs,331
+bindsight/runners/colab.py,sha256=9vaJFHLpr18NqSdig6ic_hx7yfr0HusPTh6UOOJBYi4,5983
+bindsight/runners/job_exec.py,sha256=qviBYVomjEgvxUdSEm4jSIG0IBht38_lQH39z1yvj6g,47633
+bindsight/runners/kaggle.py,sha256=TEvqmEQEA33awuIyvO7D2XOGQ6OPN3qogeHHSQjUM8E,17988
+bindsight/runners/kaggle_kernel.py,sha256=NSCd-aHn0hdcfeCil1OT9PVuRnCEOslbNqQdNje49W8,23884
+bindsight/runners/local_docker.py,sha256=1m0C5lfY_xPFN-i8WHalDp0-Zc_FFhTqA9_kqu4nZwY,5602
+bindsight/runners/mock.py,sha256=L6a5Xz8mKmFQG-ofpbzapv9CZKGRGP6cUVBhq2UY44A,6784
+bindsight/runners/modal_runner.py,sha256=XMKNHFu1VT7yj7UT5SJH0GPsPxnynUyv1u1eKALjGZI,7875
+bindsight/runners/notebook.py,sha256=vWwJ7XQ_dcRWRQ3NCvz8SSpyRFK2-DIcgTZHU5-5bHk,3624
+bindsight/runners/notebook_content.py,sha256=2svTCfauBqYoSjm4FocDi8cgllVuO2O1hKVmTizyw0Q,8671
+bindsight/runners/protocol.py,sha256=vfbPd31ANhREZDQHhbSXDW5y7bBExjer-vLKk7Ox8cM,2438
+bindsight/runners/source_wheel.py,sha256=SAl5Bi36yq1ra7sGp1yEh3dUyWDzbKO2kjJM5zn6Nh0,3945
+bindsight/runners/tools.py,sha256=TYE3XTjG_GQRHZ11rbD5dBwn-cc3OFJyalYIUgxIEjA,41235
+bindsight/structures/__init__.py,sha256=MlEy-xJttJV76aiw2EHf0zWZzQmv0IDCc8UORg2pkGs,281
+bindsight/structures/alphafolddb.py,sha256=J25b1SWUXsTpwhBdkvuFt9hsQ2PKfPDIiNQcxUxMaqQ,2979
+bindsight/structures/plddt.py,sha256=kavRKPGryg_fBESwM0xvYDkEpIX8wY1YGF8G9D0NRGU,3199
+bindsight/structures/topology.py,sha256=lXg1kZIZPQ1R8PcJAhgCbdheCbMbuaZZyvDXYmA-Zjs,9448
+bindsight/surfaceome/__init__.py,sha256=6YBffo_Xid0MnaVe_jBKfKtuufxmi2t45PQACnZWmYE,1384
+bindsight/surfaceome/surfy.py,sha256=4KwtAkwidtApopjc-gtoIImHXn7l6Dr-f9KMwrUpHFc,16958
+bindsight/targets/__init__.py,sha256=C9hqs6FuosDW9hQuaRxQNc-117WuH5A433JGGHBeSnw,314
+bindsight/targets/ensembl_uniprot.py,sha256=EjZm4Ul3103kwIVggOzZpQUOmz5du5AJ8c4J81IIskU,2286
+bindsight/targets/gtex.py,sha256=I8ykBZ9qq2ofQCbh6HL8KXJU33mQpSW3jNB5hsk7mdE,10094
+bindsight/targets/open_targets.py,sha256=xKZXMHAKlLjSE0ZRmB3fMJhpodqkACtAc3_60yiKmYM,8487
+bindsight/validate/__init__.py,sha256=7YB73cV8xeCdRUSlOupm6basTekQ0ASK7YE5oUQ76aI,276
+bindsight/validate/af2_ig.py,sha256=ZNdepi0FZK32tzMC1-qhyQqaE-xkesDbzPDUJ797LpA,1952
+bindsight/validate/boltz2.py,sha256=9Vs52qDcF3tYa32HaG2OrbY8NV8GYJ6vsGBipRnolJA,9837
+bindsight/validate/chai1r.py,sha256=8WYkytpEgTIgOeobEen8P2jAmX2pdW-MLpRtk9PFm5Q,1490
+bindsight/validate/protocol.py,sha256=2vw3o-Vxpk4UCeLXl4SWRG7X5TjR9dHeleVghBxeuHA,6818
+bindsight/report/templates/report.css,sha256=sVVU18a0PDx30ed4MkR2uOgZwbRd-1suDB9xLwlU6DY,2355
+bindsight/report/templates/report.html.j2,sha256=9d_mun3rYTTT6mztgInB1HYjnlKpQTh0LUcKhiU5JZ8,17540
+bindsight/surfaceome/data/surfaceome_extended.tsv,sha256=2bC_zliu-4IJ8vKwHXuOnVPoa1bEmD0CVHhZpgtXau4,191247
+bindsight/surfaceome/data/surfy_offline.txt,sha256=JvbfIMAU8UKEgd1jYvnPrAr4EDNIa9dVesNzzlQCS9g,490
+bindsight/surfaceome/data/surfy_v1.ensembl.tsv,sha256=QZk_omgb1ExX0yEj6TiBIr8f6kPGsBdBTuitJb33VzI,77920
+bindsight/surfaceome/data/surfy_v1.uniprot.txt,sha256=TiokuYr7KKif52yd6ctAqIjfN2PkJ6n_Bpx4REF5ZxU,21033
+bindsight-0.3.5.data/data/bindsight_demo/config.yaml,sha256=bqbGZlS1xL8PEDOF5b2aysRPI4U5tTnjXv6Vp6Y0YQ8,2276
+bindsight-0.3.5.dist-info/METADATA,sha256=Ze4kRvwqvwBGPut35NZ6gfGj3Z4u6QVqgXpCM3K5UdE,26898
+bindsight-0.3.5.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+bindsight-0.3.5.dist-info/entry_points.txt,sha256=zAgJtW_ZofdLTRiP60-lwH6QqnFagl70lVV_IFHyr7o,740
+bindsight-0.3.5.dist-info/licenses/COPYRIGHT,sha256=vOgzY1O_lBhftGC1Xyh3Ke-bh2LY66sxTR0k8hodU5g,1296
+bindsight-0.3.5.dist-info/licenses/LICENSE,sha256=tsz9sSYFXXPRYM2B0YodlBIj_wpPTD983fe-QxxuYx0,35564
+bindsight-0.3.5.dist-info/RECORD,,

bindsight-0.3.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

bindsight-0.3.5.dist-info/entry_points.txt

@@ -0,0 +1,20 @@
+[console_scripts]
+bindsight = bindsight.cli:main
+bindsight-design = bindsight.runners.job_exec:main
+
+[bindsight.designers]
+bindcraft = bindsight.design.bindcraft:BindCraftDesigner
+boltzgen = bindsight.design.boltzgen:BoltzGenDesigner
+rfdiff_mpnn = bindsight.design.rfdiff_mpnn:RFdiffMPNNDesigner
+
+[bindsight.runners]
+colab = bindsight.runners.colab:ColabRunner
+kaggle = bindsight.runners.kaggle:KaggleRunner
+local_docker = bindsight.runners.local_docker:LocalDockerRunner
+mock = bindsight.runners.mock:MockRunner
+modal = bindsight.runners.modal_runner:ModalRunner
+
+[bindsight.validators]
+af2_ig = bindsight.validate.af2_ig:AF2IGValidator
+boltz2 = bindsight.validate.boltz2:Boltz2Validator
+chai1r = bindsight.validate.chai1r:Chai1rValidator

bindsight-0.3.5.dist-info/licenses/COPYRIGHT

@@ -0,0 +1,24 @@
+bindsight — a reproducible bridge from RNA-seq to de novo protein binder design
+
+Copyright (C) 2026 Mikhaeel Atef Rizk Wahba <mikhaeelatefrizk@proton.me>
+ORCID: https://orcid.org/0009-0006-1069-9558
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along
+with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The full licence text is in LICENSE, which holds the verbatim AGPL-3.0 and
+nothing else so that automated licence detection resolves it correctly.
+
+Per-file copyright and licence are also declared as SPDX headers throughout the
+source tree. Component-level terms — bindsight orchestrates external tools that
+keep their own licences, some with non-commercial restrictions — are inventoried
+in LICENSING.md, which is the source of truth for commercial use.