deeprank-gnn-esm
Graph Network for protein-protein interface including language model features.
For details refer to our publication at https://academic.oup.com/bioinformaticsadvances/article/4/1/vbad191/7511844
For detailed protocol to use our deeprank-gnn-esm software, refer to our publication
at https://arxiv.org/abs/2407.16375
Installation
We recommend installing deeprank-gnn-esm in a Python virtual environment, to
keep its dependencies separate from other projects:
python3 -m venv .venv
source .venv/bin/activate # csh/tcsh: source .venv/bin/activate.csh; Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install deeprank-gnn-esm
Activate the environment (source .venv/bin/activate) in every new shell
before using deeprank-gnn-esm; the commands below assume it is active.
Requirements
Your Python interpreter must be compiled with sqlite3 support (needed by pdb2sql
for structure interface calculations). Most system Python installs already include
this; check with::
python -c "import sqlite3"
If this raises ModuleNotFoundError: No module named '_sqlite3', rebuild or
reinstall Python with sqlite3 support.
CPU only
To avoid downloading the heavy CUDA libraries (~3GB), install the CPU-only torch first:
pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
pip install deeprank-gnn-esm
GPU support
GPU support is included automatically — the default PyPI torch wheel bundles CUDA.
If your system requires a specific CUDA version, install torch first:
# example for CUDA 12.1
pip install torch --extra-index-url https://download.pytorch.org/whl/cu121
pip install deeprank-gnn-esm
Check pytorch.org for the right CUDA version for your system.
Usage
As a scoring function
We provide a command-line interface for deeprank-gnn-esm that can easily be
used to score protein-protein complexes. It accepts one or more PDB files
(each optionally a multi-model ensemble) in a single invocation. Every pair
of chains in each input structure is scored as a separate interface - a
3-chain complex produces 3 pairwise predictions (A-B, A-C, B-C), an ensemble
of N models produces predictions for every model. A pair of chains without
interface cannot be scored: its predicted fnat is reported as NA. Only amino
acids are used: waters, ions and ligands are removed from the input, as well as
chains that contain no amino acids. Modified amino acids are kept, but are not
officially supported (they are unknown residues, X, for ESM-2). The
command-line interface can be used as follows:
$ deeprank-gnn-esm-predict -h
usage: deeprank-gnn-esm-predict [-h] [--num_cores NUM_CORES] [--output-dir OUTPUT_DIR]
pdb_files [pdb_files ...]
positional arguments:
pdb_files Path(s) to the PDB file(s).
optional arguments:
-h, --help show this help message and exit
--num_cores NUM_CORES
Number of cores to use (default: 1)
--output-dir OUTPUT_DIR
Directory to save intermediate files in (default: a
temporary directory that is discarded after the run).
Example, score the 1B6C complex
# download it
$ wget https://files.rcsb.org/view/1B6C.pdb -q
$ deeprank-gnn-esm-predict 1B6C.pdb
2026-07-22 06:08:21,889 predict:41 INFO - Setting up workspace - /tmp/tmpabcd1234
2026-07-22 06:08:21,945 input:49 INFO - Renumbering structure 1B6C.
2026-07-22 06:08:22,294 input:99 INFO - Reading sequence of structure 1B6C
2026-07-22 06:08:22,423 sequence:57 INFO - Generating embeddings for 2 unique sequence(s).
2026-07-22 06:08:32,459 input:212 INFO - Wrote 1 chain-pair PDB(s) of structure 1B6C to /tmp/tmpabcd1234/structures
2026-07-22 06:08:36,470 predict:48 INFO - Generating graph, using 1 processors
2026-07-22 06:09:03,345 predict:63 INFO - Graph file generated: /tmp/tmpabcd1234/graph.hdf5
2026-07-22 06:09:03,345 predict:69 INFO - Predicting fnat of protein complex.
2026-07-22 06:09:03,345 predict:77 INFO - Using device: cuda:0
# ...
2026-07-22 06:09:07,794 predict:130 INFO - Predicted fnat for 1B6C between chain A and chain B: 0.359
2026-07-22 06:09:07,803 predict:141 INFO - Output written to /tmp/tmpabcd1234/GNN_esm_prediction.csv
2026-07-22 06:09:07,805 main:71 INFO - Result saved to /home/deeprank-gnn-esm/GNN_esm_prediction.csv
From the output above you can see that the predicted fnat for the 1B6C
complex is 0.359, this information is also written to the
GNN_esm_prediction.csv file in the directory you ran the command from:
pdb_id,chain_i,chain_j,predicted_fnat
1B6C,A,B,0.359
The GNN_esm_prediction_summary.csv file, written next to it, gives for every
model the number of scored chain pairs and the mean, standard deviation and
minimum of their predicted fnat (NA if none of its pairs could be scored):
pdb_id,scored_pairs,mean_fnat,std_fnat,min_fnat
1B6C,1,0.359,0.000,0.359
By default all intermediate files (renumbered PDB, per-chain embeddings,
per-pair PDBs, graph/prediction hdf5) live in a temporary directory that's
removed once the run finishes. Pass --output-dir to keep them around for
inspection instead:
$ deeprank-gnn-esm-predict 1B6C.pdb --output-dir 1B6C-gnn_esm_pred
1B6C-gnn_esm_pred
├── 1B6C.pdb #renumbered copy of the input pdb file
├── 1B6C.A.pt #esm-2 embedding for chain A in protein 1B6C
├── 1B6C.B.pt #esm-2 embedding for chain B in protein 1B6C
├── structures/
│ └── 1B6C_A-B.pdb #2-chain pdb materialized for the A-B interface
├── graph.hdf5 #input protein graph in hdf5 format
├── GNN_esm_prediction.hdf5 #prediction output in hdf5 format
├── GNN_esm_prediction.csv #prediction output in csv format
└── GNN_esm_prediction_summary.csv #fnat statistics per model in csv format
Multiple PDB files (including multi-model ensembles) can be scored in one call - each input must have a unique filename stem:
$ deeprank-gnn-esm-predict 1B6C.pdb ensemble.pdb --num_cores 4
As a framework
Note about input pdb files
To ensure the mapping between interface residue and esm-2 embeddings is correct, make sure that for all the chains, residue numbering in the PDB file is continuous and starts with residue '1'.
We provide a script (scripts/pdb_renumber.py) to do the numbering.
Generate esm-2 embeddings for your protein
-
To generate fasta sequences from PDBs, use script
get_fasta.pyusage: get_fasta.py [-h] pdb_file_path chain_id1 chain_id2 positional arguments: pdb_file_path Path to the directory containing PDB files chain_id1 Chain ID for the first sequence chain_id2 Chain ID for the second sequence options: -h, --help show this help message and exit python scripts/get_fasta.py tests/data/pdb/1ATN/ A B
-
Generate embeddings in bulk from combined fasta files, use the script provided inside esm-2 package,
$ python esm_2_installation_location/scripts/extract.py \ esm2_t33_650M_UR50D \ all.fasta \ tests/data/embedding/1ATN/ \ --repr_layers 0 32 33 \ --include mean per_tok
Replace 'esm_2_installation_location' with your installation location, 'all.fasta' with fasta sequence generated above, 'tests/data/embedding/1ATN/' with the output folder name for esm embeddings
Generate graph
-
Example code to generate residue graphs in hdf5 format:
from deeprank_gnn.GraphGenMP import GraphHDF5 pdb_path = "tests/data/pdb/1ATN/" pssm_path = "tests/data/pssm/1ATN/" embedding_path = "tests/data/embedding/1ATN/" nproc = 20 outfile = "1ATN_residue.hdf5" GraphHDF5( pdb_path = pdb_path, pssm_path = pssm_path, embedding_path = embedding_path, graph_type = "residue", outfile = outfile, nproc = nproc, #number of cores to use tmpdir="./tmpdir")
-
Example code to add continuous or binary targets to the hdf5 file
import h5py import random hdf5_file = h5py.File('1ATN_residue.hdf5', "r+") for mol in hdf5_file.keys(): fnat = random.random() bin_class = [1 if fnat > 0.3 else 0] hdf5_file.create_dataset(f"/{mol}/score/binclass", data=bin_class) hdf5_file.create_dataset(f"/{mol}/score/fnat", data=fnat) hdf5_file.close()
Use pre-trained models to predict
-
Example code to use pre-trained deeprank-gnn-esm model
from deeprank_gnn.ginet import GINet from deeprank_gnn.NeuralNet import NeuralNet database_test = "1ATN_residue.hdf5" gnn = GINet target = "fnat" edge_attr = ["dist"] threshold = 0.3 pretrained_model = 'deeprank-GNN-esm/paper_pretrained_models/scoring_of_docking_models/gnn_esm/treg_yfnat_b64_e20_lr0.001_foldall_esm.pth.tar' node_feature = ["type", "polarity", "bsa", "charge", "embedding"] device_name = "cuda:0" num_workers = 10 model = NeuralNet( database_test, gnn, device_name = device_name, edge_feature = edge_attr, node_feature = node_feature, target = target, num_workers = num_workers, pretrained_model = pretrained_model, threshold = threshold) model.test(hdf5 = "tmpdir/GNN_esm_prediction.hdf5")
AI Declaration
Large language models (LLM) were used in this repository since v2.0.0: part of the unit tests were AI-generated and checked manually, and later changes are made with the help of Claude Code. The changes are always reviewed by a human before being merged. See aidecl.yaml for machine-readable details of the LLM usage.
Metadata
Release files for deeprank-gnn-esm 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| deeprank_gnn_esm-2.0.1.tar.gz | 645.7 kB | With provenance | Details for deeprank_gnn_esm-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| deeprank_gnn_esm-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for deeprank_gnn_esm-2.0.1-py3-none-any.whl |
Total release size: 1.3 MB
Release files / deeprank_gnn_esm-2.0.1.tar.gz
| Download URL | deeprank_gnn_esm-2.0.1.tar.gz |
|---|---|
| Size | 645.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
191a52608b3320e161f1da648ace9e551f12a41c57a8df17b36faeeca2f8528d
|
|
BLAKE2b-256 checksum How to use checksums |
2ab2bfa26c050d8ddecf2d05e64bb329d164aa2ee690a04a0b17f98c10a5610d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logRelease files / deeprank_gnn_esm-2.0.1-py3-none-any.whl
| Download URL | deeprank_gnn_esm-2.0.1-py3-none-any.whl |
|---|---|
| Size | 637.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c082f6d7428ef0fc88db05e4bc298e45adde7d959e1ea1f83780e12632f677c4
|
|
BLAKE2b-256 checksum How to use checksums |
367495b732c3d32478c3dbdc942027c252b1fd77a19dc19fcffaf435ad8e9304
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logSecurity for deeprank-gnn-esm 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for deeprank_gnn_esm-2.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.