VCDesign

Finite-Budget Intervention Design for Virtual Cells

Rank the experiments worth running, not just the intervention identity.

English · 简体中文

🌐 Project website · 🚀 Quick start · 🧭 How it works · 🤗 Data · 🧪 Reproduce · 📄 Paper

VCDesign formulates cellular intervention design as finite-budget ranking over a variable candidate set. A solver ranks feasible interventions for a source-to-target transition; evaluation scores the executable top-$B$ prefix using independently measured held-out outcomes. In this CRISPRi benchmark, utility measures the direction of the transcriptomic response. VCDesign-CED combines direct candidate scoring with effects inferred from historical perturbation measurements and biological knowledge when a candidate's own response is absent from the CED effect atlas.

_{VCDesign framework and VCDesign-CED reference realization · Figure 1 · Read the paper ↗}

✨ From prediction to design

🎯 Rank a candidate set Score a variable set of feasible interventions for a requested source-to-target transition and select the top-B prefix.

🧪 Evaluate decisions by outcomes Exclude the query identity and grade selected candidates using independently measured held-out outcomes.

🧬 Transfer to unmeasured candidates Distill historical responses into an effect predictor using STRING and MAP-KG candidate knowledge.

Choose the information regime

Candidate information at decision time	Recommended route
Measured candidate responses are available	Direct response-profile retrieval
Candidate responses are unavailable	VCDesign-CED predicted-effect scoring

Both routes use the same downstream decision interface: a candidate pool, an experimental budget, and outcome-based evaluation.

What the manuscript establishes

• In three held-out cellular contexts, masking candidate responses from the CED atlas gives a pooled paired BU@20 gain of +0.0492 over the same base scorer and, among 20 selections, 1.11 more top-5% candidates on average.
• When candidate responses have been measured in other contexts, direct profile retrieval scores higher than VCDesign-CED (pooled BU@20 0.675 versus 0.508).
• Response masking applies to the CED atlas, not to all prior supervision: the fixed base scorer was trained on 68% of masked candidate identities. The manuscript also reports a base-scorer-unseen subset and a locked K562 identity test.

These are retrospective results for transcriptomic directional prioritization, not prospective evidence of improved biological endpoints. The unit-direction held-context configuration was selected on the same evaluation pools and fixed before external baselines were run; the K562 configuration was fixed before its locked split was scored.

🚀 Quick start

Python 3.11 is required. The bundled demo is synthetic and does not download biological data.

git clone https://github.com/Boom5426/VCDesign-CED.git
cd VCDesign-CED
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[model,data,dev]"
python examples/ced_demo.py
python -m pytest -q

Note

The demo checks response-basis construction, ridge effect prediction, missing-knowledge handling, and score fusion. Its scores are a software smoke test, not a biological result.

Install the exact tested CPU environment

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-cpu.txt
python -m pip install -e . --no-deps

For GPU training, install the PyTorch 2.4 build appropriate for the local CUDA system, then install the remaining dependencies from requirements.txt.

🧠 Candidate Effect Distillation

CED learns a deliberately simple transfer map:

historical perturbation responses ──► response basis
                                      ▲
STRING + MAP-KG candidate features ──► ridge effect predictor
                                      │
unmeasured candidate knowledge ──────► predicted effect ──► target alignment

The deployment candidate's measured response is never an input. Candidates missing all supported knowledge modalities receive the frozen all-missing score defined by the protocol.

🌍 Evaluation contexts

Context	Perturbation setting	Role
K562	CRISPRi Perturb-seq	Primary genome-scale setting
RPE1	CRISPRi Perturb-seq	Cross-context evaluation
HepG2	CRISPRi Perturb-seq	External cellular context
Jurkat	CRISPRi Perturb-seq	External cellular context

Exact source versions, variants, and citations are listed in DATA_SOURCES.md.

🤗 Data & frozen artifacts

The processed feature matrices, four-context packs, comparator scores, selected checkpoint, run records, and SHA-256 manifest are hosted in the companion dataset:

Released artifact	Contents
inputs/	Frozen response, STRING, MAP-KG, candidate-knowledge, and comparator arrays
checkpoints/	Selected epoch-8 reference checkpoint
records/	Training, selection, evaluation, external-baseline, and verification records
DATA_MANIFEST.json	Byte sizes and SHA-256 digests for release verification

🔁 Reproduce

Download the frozen processed inputs, checkpoints, and run records into the repository root, then verify every released byte:

python -m pip install "huggingface_hub>=0.35"
hf download Boom5426/VCDesign --repo-type dataset --local-dir . \
  --include 'inputs/**' 'checkpoints/**' 'records/**' 'DATA_MANIFEST.json'
python tools/verify_processed_data.py --root .

Train the primary base scorer with an explicit, new output directory:

python -m gene_open_inverse.final_clean_model_v1.train \
  --config configs/paper_run_v1.json \
  --output outputs/final_clean_train \
  --device cuda

The training command refuses to overwrite an existing output directory. The frozen reference checkpoint is checkpoints/final_clean_epoch_008.pt; its SHA-256 is recorded in both the run configuration and processed-data manifest.

Goal	Entry point
Try CED without external data	examples/ced_demo.py
Verify the processed release	tools/verify_processed_data.py
Inspect the frozen run contract	configs/paper_run_v1.json
Run the complete command sequence	REPRODUCE.md
Understand the source tree	PROJECT_STRUCTURE.md

🗂️ Repository map

src/gene_open_inverse/
├── candidate_effect_distillation_v1/  CED basis, predictor, fusion, evaluation
├── final_clean_model_v1/              base scorer, selection, locked evaluation
├── four_context_v1/                   K562/RPE1/HepG2/Jurkat data contracts
├── external_baselines_v1/             comparator adapters and reporting
├── open_vocab_generalization_v1/      masking and open-vocabulary analyses
└── model/                             knowledge features and model components

configs/                               portable paper-run configuration
examples/                              synthetic end-to-end demonstration
tools/                                 integrity and release utilities
paper/                                 manuscript PDF

Important

GitHub contains the source, configuration, synthetic demo, and manuscript. Large processed inputs and frozen artifacts live in the companion Hugging Face release; raw H5AD matrices remain with their original public repositories.

---

From predicting responses to prioritizing experiments.
_{Back to top ↑}