ntranoslab/esm-variants

ESM Variants

This repository contains resources, tools, and command-line tools developed for the paper, "Genome-wide prediction of disease variant effects with a deep protein language model" by Nadav Brandes, Grant Goldman, Charlotte H. Wang, Chun Jimmie Ye, and Vasilis Ntranos. A complete catalog of missense variant effect predictions is accessible here.

Repository Contents

Notebooks/Scripts

• esm_variants_utils.ipynb
• esm_variants_utils.py

Command-Line Tools

• esm_score_missense_mutations.py
• esm_score_multi_residue_mutations.py

Benchmarks

• ClinVar_gnomAD_benchmark_with_predictions.csv
• ClinVar_indel_benchmark_with_predictions.csv
• ClinVar_stop_gains_benchmark_with_predictions.csv.gz
• dms_assays.zip

Results

• Table_of_results.xlsx These files contain all benchmark data, VEP predictions used for performance evaluation, and results, except HGMD variants (see below).

Data Availability

Most data used in this work is already within the public domain. Exceptions and other data sources are detailed in the paper and below:

• The HGMD dataset is a private resource owned by the Institute of Medical Genetics in Cardiff University. Request access here.
• ClinVar labels of missense variants in all protein isoforms and of indels and stop-gains are available here.
• Full details on how the datasets and benchmarks were processed are available in the Supplementary Methods.
• Predicted effect scores for most VEP methods were downloaded from dbNSFP.

Related Resources

• ESM1b: This study leverages and expands the use of ESM1b, a protein language model developed by MetaAI. The code and pre-trained parameters for ESM1b were taken from the model’s official GitHub repository.
• Web portal: We created a web portal allowing researchers to query, visualize, and download missense variant effect predictions for all protein isoforms in the human genome.

Installation

The following dependencies are required:

pip3 install tqdm numpy pandas biopython torch fair-esm

Clone the repository:

git clone https://github.com/ntranoslab/esm-variants.git
cd esm-variants

Usage

Scoring Missense Mutations

python3 esm_score_missense_mutations.py --input-fasta-file /path/to/input.fasta --output-csv-file /path/to/output.csv

Scoring Multi-Residue Mutations

python3 esm_score_multi_residue_mutations.py --input-csv-file /path/to/input.csv --output-csv-file /path/to/output.csv

The input CSV file for multi-residue mutations should have three fields:

• wt_seq: the wild type (original) protein sequence
• mut_seq: the mutated protein sequence
• start_pos: the starting position (1-indexed) of the mutation relative to the wild type sequence

Examples

Example for Scoring Missense Mutations

Assuming an example FASTA file named example.fasta:

>seq1
FISHWISHFQRCHIPSTHATARECRISP
>seq2
RAGEAGAINSTTHEMACHINE

You can calculate ESM scores for all possible missense mutations in these sequences:

python3 esm_score_missense_mutations.py --input-fasta-file example.fasta --output-csv-file esm_scores.csv

This will create a CSV file (esm_scores.csv) that starts like this:

seq_id,mut_name,esm_score
seq1,F1K,-3.2310808
seq1,F1R,-2.872289
seq1,F1H,-3.4361703
...

Each row represents a possible missense mutation and its ESM score.

Example for Scoring Multi-Residue Mutations

Assuming the following example.csv:

wt_seq,mut_seq,start_pos
FISHWISHFQRCHIPSTHATARECRISP,FISHWISHFQRCHEESETHATARECRISP,14
MARGTYNMGKHFDA,MGTYNMGKHFDA,2

You can calculate ESM (PLLR) scores for the specified multi-residue mutations:

python3 esm_score_multi_residue_mutations.py --input-csv-file example.csv --output-csv-file esm_multi_residue_scores.csv

This will create a CSV file (esm_multi_residue_scores.csv) that starts like this:

wt_seq,mut_seq,start_pos,esm_score
FISHWISHFQRCHIPSTHATARECRISP,FISHWISHFQRCHEESETHATARECRISP,14,-1.0078125
MARGTYNMGKHFDA,MGTYNMGKHFDA,2,1.0056415

Each row represents a multi-residue mutation and its ESM (PLLR) score.