Using Protein Language Models to compute Variant Effect Predictions across population-scale populations.
Jupyter Notebook
1
176 commits
updated Jun 29, 2026
Using protein sequence models to compute Variant Effect Predictions (VEP) across biobank-scale populations.
This project aims to use protein language models (e.g. ESM2, ESM3) to score the effect of genetic variants on protein sequence, and to study how these variant effect predictions (VEPs) vary across population-scale haplotypes (e.g. 1000 Genomes, HGDP). The main goals are:
The codebase provides pipelines to fetch haplotypes, run ESM-based scoring (e.g. masked-marginals, pseudo-ppl), merge and analyze VEP outputs, fit linear models for joint WT–clinical effects, and perform interaction testing. Results are intended to support both method development and applied analyses (e.g. penetrance, case studies).
conda/*.yml for per-model environments (esm2.yml is the main one; additional envs cover ESM3, ESMFold, evolocity, GenVarLoader, RAPIDS, Snakemake)See the Environment setup and Getting started sections below for step-by-step instructions. Typical install time on a workstation with conda already installed:
esm2 conda environmentTimings are approximate and will vary with hardware, network speed, and model-weight cache state.
A small, self-contained demo of the downstream surrogate-modeling step (the joint-effect Ridge model and epistasis testing) runs on a normal desktop CPU in a few seconds on a tiny bundled, simulated dataset:
python demo/run_demo.py
demo/output/interaction_df.csv and metrics.csv,
matching the committed demo/expected_output/ (deterministic, random_state=42).See demo/README.md for details.
The end-to-end VEP pipeline is in notebooks/VEP.ipynb, which loads protein haplotypes, injects a clinical variant, scores with ESM2-650M, and returns per-haplotype VEP scores.
⚠️ Hardware requirement: ESM-based variant effect prediction requires a CUDA-capable NVIDIA GPU (tested on A100/H100 80 GB). This step cannot be meaningfully run on CPU.
Timings are approximate and will vary with hardware, network speed, and model-weight cache state.
Conda environment files live in conda/. Use the environment that matches what you want to run:
| Environment | File | Use case |
|---|---|---|
| esm2 | conda/esm2.yml | Main VEP workflow: ESM2 models, VEP pipeline, haplosaurus, ProteinGym, most analysis notebooks. Start here for the VEP tutorial. |
| esm3 | conda/esm3.yml | ESM3 models and related notebooks. |
| esmfold | conda/esmfold.yml | ESMFold structure prediction (separate Python/toolchain). |
Quick start:
git clone https://github.com/bschilder/VEP_protein.git && cd VEP_protein
conda env create -f conda/esm2.yml
conda activate esm2
Then set DATA_DIR in src/config.py to the path where you want to store data (default: ~/projects/data/). Use the esm2 kernel when opening the VEP tutorial notebook.
Hardware: A GPU is recommended for running ESM model inference; larger models and batch jobs will be slow on CPU only.
Data: External data (ProteinGym clinical sets, haplotype sequences from Haplosaurus/1000 Genomes, etc.) is downloaded on first use or by pipeline scripts into DATA_DIR. Ensure sufficient disk space for model weights and VEP outputs.
| Directory | Description |
|---|---|
src/ | Python package used by notebooks and scripts. Key modules: |
→ vep_pipeline.py | Runs the VEP pipeline (ESM models, scoring strategies, ProteinGym/clinical variants). |
→ vep_analysis.py | Analysis, plotting, and aggregation of VEP results (distributions, interactions, figures). |
→ vep_metrics.py | VEP-related metrics and evaluation. |
→ haplosaurus.py | Haplotype and population sequence handling (e.g. 1000 Genomes, HGDP). |
→ proteingym.py | ProteinGym clinical mutation and benchmark data. |
→ config.py | Global config: DATA_DIR, PARAMS_VEP, PARAMS_HAPLOTYPES, palettes. |
→ analysis/ | Analysis helpers: attributions, distributions, matrices, VEP GMM. |
→ Align/ | Alignment utilities (ClustalOmega, Clustalw). |
→ benchmark/ | ClinVar and related benchmarking. |
→ colabfold/ | ColabFold and categorical Jacobians. |
→ ESM.py, ESM_predict.py, ESM3.py, ESMfold.py | ESM model loading and inference. |
notebooks/ | Step-by-step tutorials and analyses; entry point for reproducing results. |
config/ | ProHap and other pipeline configs (YAML). |
docs/ | Method and metric write-ups (e.g. interactions). |
scripts/ | Shell scripts for batch runs (e.g. vep_pipeline.sh, haplosaurus/HGDP). |
tests/ | Pytest tests for haplotype ref, preprocessed index, ID mapping, mutation index, MSA query. |
results/ | Outputs (e.g. plots, parquet). |
Data (VEP outputs, caches, etc.) is written under DATA_DIR as set in src/config.py; the repo itself stays code-only.
Clone and enter the repo
git clone https://github.com/bschilder/VEP_protein.git && cd VEP_protein
Create and activate the main environment
conda env create -f conda/esm2.yml
conda activate esm2
Set the data directory
Edit DATA_DIR in src/config.py to the on-disk location where you want to store data.
Run the VEP tutorial
Open notebooks/VEP.ipynb, select the esm2 kernel, and run the cells. The notebook imports src (e.g. vep_pipeline, vep_analysis, haplosaurus, proteingym) and walks through loading proteins, clinical variants, and computing VEPs.
Notebooks are the main way to reproduce and explore the analyses.
| Notebook | Description |
|---|---|
| VEP.ipynb | Main tutorial: VEP with protein LMs — candidate proteins, ProteinGym clinical mutations, pipeline usage. |
| VEP_case_studies.ipynb | Case studies using the VEP pipeline. |
| VEP_embeddings.ipynb | Embeddings and VEP. |
| VEP_penetrance.ipynb | Penetrance-related VEP analysis. |
| variant_annotation.ipynb | Variant annotation workflow. |
| variant_attribution.ipynb | Attribution for variants. |
| ProHap.ipynb | ProHap haplotype workflow. |
| haplosaurus.ipynb | Haplosaurus and haplotype handling. |
| 1KG.ipynb, 1KG_wt.ipynb | 1000 Genomes–based analyses. |
| HGDP.ipynb | HGDP population analyses. |
| ProteinGym.ipynb | ProteinGym benchmarks. |
| Zenodo.ipynb | Upload/download manuscript data to Zenodo (personalizedVEP record). |
| ESM3.ipynb | ESM3 model usage. |
| evolocity.ipynb | Evolocity analysis (use conda/evolocity.yml). |
| GVL.ipynb | GVL workflow (use conda/gvl.yml). |
| distributions.ipynb, embeddings.ipynb | Distribution and embedding analyses. |
| colabfold.ipynb, categorical_jacobians.ipynb | ColabFold and Jacobians. |
Other notebooks in notebooks/ (e.g. ensemblVEP, OpenTargets, patient_embeddings) follow the same pattern: they rely on src/ and optional conda envs as noted above.
Run each notebook from the repository root in the relevant conda environment (GPU required for the ESM inference notebooks). The main mappings:
| Manuscript result | Notebook(s) |
|---|---|
| Per-haplotype ESM VEP scores | VEP.ipynb |
| ProteinGym benchmark comparisons | ProteinGym.ipynb |
| Haplotype construction (ProHap / Haplosaurus) | ProHap.ipynb, haplosaurus.ipynb |
| Population analyses (1KG / HGDP) | 1KG.ipynb, HGDP.ipynb |
| VEP score distributions & embeddings | distributions.ipynb, embeddings.ipynb |
| Structure analyses (ColabFold, categorical Jacobians) | colabfold.ipynb, categorical_jacobians.ipynb |
| Variant attribution / epistasis (joint-effect model, F-test) | variant_attribution.ipynb |
The surrogate-modeling / epistasis methodology underlying the attribution
analyses is documented in docs/methods_epistasis.md
and demonstrated on a tiny CPU dataset in demo/.
deviation_from_additive, delta_r2, epistasis_fstat).From the repo root with the appropriate environment activated (e.g. esm2):
pytest tests/ -v
This runs tests in tests/ (haplotype ref, preprocessed index, ID mapping, mutation index, MSA query).
If you use this code in your work, please cite the accompanying manuscript (see Manuscript). BibTeX and DOI can be added here once available.
The manuscript/ directory contains the accompanying manuscript sources, including manuscript/figures.ipynb (figure generation) and manuscript/fig/, manuscript/tbl/ for figures and tables.
This project is licensed under the MIT License (OSI-approved). See LICENSE for the full terms.
Using Protein Language Models to compute Variant Effect Predictions across population-scale populations.
Jupyter Notebook
1
176 commits
updated Jun 29, 2026
Using protein sequence models to compute Variant Effect Predictions (VEP) across biobank-scale populations.
This project aims to use protein language models (e.g. ESM2, ESM3) to score the effect of genetic variants on protein sequence, and to study how these variant effect predictions (VEPs) vary across population-scale haplotypes (e.g. 1000 Genomes, HGDP). The main goals are:
The codebase provides pipelines to fetch haplotypes, run ESM-based scoring (e.g. masked-marginals, pseudo-ppl), merge and analyze VEP outputs, fit linear models for joint WT–clinical effects, and perform interaction testing. Results are intended to support both method development and applied analyses (e.g. penetrance, case studies).
conda/*.yml for per-model environments (esm2.yml is the main one; additional envs cover ESM3, ESMFold, evolocity, GenVarLoader, RAPIDS, Snakemake)See the Environment setup and Getting started sections below for step-by-step instructions. Typical install time on a workstation with conda already installed:
esm2 conda environmentTimings are approximate and will vary with hardware, network speed, and model-weight cache state.
A small, self-contained demo of the downstream surrogate-modeling step (the joint-effect Ridge model and epistasis testing) runs on a normal desktop CPU in a few seconds on a tiny bundled, simulated dataset:
python demo/run_demo.py
demo/output/interaction_df.csv and metrics.csv,
matching the committed demo/expected_output/ (deterministic, random_state=42).See demo/README.md for details.
The end-to-end VEP pipeline is in notebooks/VEP.ipynb, which loads protein haplotypes, injects a clinical variant, scores with ESM2-650M, and returns per-haplotype VEP scores.
⚠️ Hardware requirement: ESM-based variant effect prediction requires a CUDA-capable NVIDIA GPU (tested on A100/H100 80 GB). This step cannot be meaningfully run on CPU.
Timings are approximate and will vary with hardware, network speed, and model-weight cache state.
Conda environment files live in conda/. Use the environment that matches what you want to run:
| Environment | File | Use case |
|---|---|---|
| esm2 | conda/esm2.yml | Main VEP workflow: ESM2 models, VEP pipeline, haplosaurus, ProteinGym, most analysis notebooks. Start here for the VEP tutorial. |
| esm3 | conda/esm3.yml | ESM3 models and related notebooks. |
| esmfold | conda/esmfold.yml | ESMFold structure prediction (separate Python/toolchain). |
Quick start:
git clone https://github.com/bschilder/VEP_protein.git && cd VEP_protein
conda env create -f conda/esm2.yml
conda activate esm2
Then set DATA_DIR in src/config.py to the path where you want to store data (default: ~/projects/data/). Use the esm2 kernel when opening the VEP tutorial notebook.
Hardware: A GPU is recommended for running ESM model inference; larger models and batch jobs will be slow on CPU only.
Data: External data (ProteinGym clinical sets, haplotype sequences from Haplosaurus/1000 Genomes, etc.) is downloaded on first use or by pipeline scripts into DATA_DIR. Ensure sufficient disk space for model weights and VEP outputs.
| Directory | Description |
|---|---|
src/ | Python package used by notebooks and scripts. Key modules: |
→ vep_pipeline.py | Runs the VEP pipeline (ESM models, scoring strategies, ProteinGym/clinical variants). |
→ vep_analysis.py | Analysis, plotting, and aggregation of VEP results (distributions, interactions, figures). |
→ vep_metrics.py | VEP-related metrics and evaluation. |
→ haplosaurus.py | Haplotype and population sequence handling (e.g. 1000 Genomes, HGDP). |
→ proteingym.py | ProteinGym clinical mutation and benchmark data. |
→ config.py | Global config: DATA_DIR, PARAMS_VEP, PARAMS_HAPLOTYPES, palettes. |
→ analysis/ | Analysis helpers: attributions, distributions, matrices, VEP GMM. |
→ Align/ | Alignment utilities (ClustalOmega, Clustalw). |
→ benchmark/ | ClinVar and related benchmarking. |
→ colabfold/ | ColabFold and categorical Jacobians. |
→ ESM.py, ESM_predict.py, ESM3.py, ESMfold.py | ESM model loading and inference. |
notebooks/ | Step-by-step tutorials and analyses; entry point for reproducing results. |
config/ | ProHap and other pipeline configs (YAML). |
docs/ | Method and metric write-ups (e.g. interactions). |
scripts/ | Shell scripts for batch runs (e.g. vep_pipeline.sh, haplosaurus/HGDP). |
tests/ | Pytest tests for haplotype ref, preprocessed index, ID mapping, mutation index, MSA query. |
results/ | Outputs (e.g. plots, parquet). |
Data (VEP outputs, caches, etc.) is written under DATA_DIR as set in src/config.py; the repo itself stays code-only.
Clone and enter the repo
git clone https://github.com/bschilder/VEP_protein.git && cd VEP_protein
Create and activate the main environment
conda env create -f conda/esm2.yml
conda activate esm2
Set the data directory
Edit DATA_DIR in src/config.py to the on-disk location where you want to store data.
Run the VEP tutorial
Open notebooks/VEP.ipynb, select the esm2 kernel, and run the cells. The notebook imports src (e.g. vep_pipeline, vep_analysis, haplosaurus, proteingym) and walks through loading proteins, clinical variants, and computing VEPs.
Notebooks are the main way to reproduce and explore the analyses.
| Notebook | Description |
|---|---|
| VEP.ipynb | Main tutorial: VEP with protein LMs — candidate proteins, ProteinGym clinical mutations, pipeline usage. |
| VEP_case_studies.ipynb | Case studies using the VEP pipeline. |
| VEP_embeddings.ipynb | Embeddings and VEP. |
| VEP_penetrance.ipynb | Penetrance-related VEP analysis. |
| variant_annotation.ipynb | Variant annotation workflow. |
| variant_attribution.ipynb | Attribution for variants. |
| ProHap.ipynb | ProHap haplotype workflow. |
| haplosaurus.ipynb | Haplosaurus and haplotype handling. |
| 1KG.ipynb, 1KG_wt.ipynb | 1000 Genomes–based analyses. |
| HGDP.ipynb | HGDP population analyses. |
| ProteinGym.ipynb | ProteinGym benchmarks. |
| Zenodo.ipynb | Upload/download manuscript data to Zenodo (personalizedVEP record). |
| ESM3.ipynb | ESM3 model usage. |
| evolocity.ipynb | Evolocity analysis (use conda/evolocity.yml). |
| GVL.ipynb | GVL workflow (use conda/gvl.yml). |
| distributions.ipynb, embeddings.ipynb | Distribution and embedding analyses. |
| colabfold.ipynb, categorical_jacobians.ipynb | ColabFold and Jacobians. |
Other notebooks in notebooks/ (e.g. ensemblVEP, OpenTargets, patient_embeddings) follow the same pattern: they rely on src/ and optional conda envs as noted above.
Run each notebook from the repository root in the relevant conda environment (GPU required for the ESM inference notebooks). The main mappings:
| Manuscript result | Notebook(s) |
|---|---|
| Per-haplotype ESM VEP scores | VEP.ipynb |
| ProteinGym benchmark comparisons | ProteinGym.ipynb |
| Haplotype construction (ProHap / Haplosaurus) | ProHap.ipynb, haplosaurus.ipynb |
| Population analyses (1KG / HGDP) | 1KG.ipynb, HGDP.ipynb |
| VEP score distributions & embeddings | distributions.ipynb, embeddings.ipynb |
| Structure analyses (ColabFold, categorical Jacobians) | colabfold.ipynb, categorical_jacobians.ipynb |
| Variant attribution / epistasis (joint-effect model, F-test) | variant_attribution.ipynb |
The surrogate-modeling / epistasis methodology underlying the attribution
analyses is documented in docs/methods_epistasis.md
and demonstrated on a tiny CPU dataset in demo/.
deviation_from_additive, delta_r2, epistasis_fstat).From the repo root with the appropriate environment activated (e.g. esm2):
pytest tests/ -v
This runs tests in tests/ (haplotype ref, preprocessed index, ID mapping, mutation index, MSA query).
If you use this code in your work, please cite the accompanying manuscript (see Manuscript). BibTeX and DOI can be added here once available.
The manuscript/ directory contains the accompanying manuscript sources, including manuscript/figures.ipynb (figure generation) and manuscript/fig/, manuscript/tbl/ for figures and tables.
This project is licensed under the MIT License (OSI-approved). See LICENSE for the full terms.