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.

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.

Install

One command, one way. Python 3.11+, Windows / macOS / Linux, CPU only.

pip install "bindsight[discover,report]"

From a checkout, pip install -e ".[discover,report]" instead. 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:

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.

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 · write-up

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/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/

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 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

Runner and plugin status

Not every backend carries the same weight of evidence, and presenting them as peers would be misleading.

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.

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.

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, which runs on a free Kaggle T4.

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/, tests/, scripts/, benchmarks/ and each benchmark under it, docs/, examples/, envs/ and paper/. Package subdirectories are documented in the table below rather than individually.

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

For the full landscape comparison, see ARCHITECTURE.md § 8.

Acknowledgments

bindsight is an opinionated wrapper. Real intellectual credit belongs to the upstream tool authors. See LICENSING.md for the full inventory; the work this builds on most directly:

• SURFACE-Bind (Balbi et al., PNAS 2026) — the targetable-sites catalog that makes the bridge tractable
• pydeseq2 (Muzellec et al., Bioinformatics 2023) — Python DESeq2 implementation
• RFdiffusion (Watson et al., Nature 2023) — backbone generation
• ProteinMPNN (Dauparas et al., Science 2022) — sequence design
• Boltz-2 (Wohlwend et al., 2025) — structure + affinity prediction
• BindCraft (Pacesa et al., Nature 2025) — one-shot binder design
• 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; 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
• GitHub: @mikhaeelatefrizk
• Email: mikhaeelatefrizk@proton.me

License

• Code: GNU AGPL-3.0-or-later — copyright notice in 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 for component-level details — bindsight orchestrates external tools that keep their own licences, and some carry non-commercial terms.