e_emb2bind: protein binding prediction tool

e_emb2bind is a protein binding prediction tool that returns residue-level binding predictions. It takes as input a FASTA file and a directory containing precomputed ESM-2 residue-level embeddings, and applies a set of pre-trained emb2bind models combined by simple voting.

Model overview

The model was trained to predict protein binding residues using binding annotations from DisProt, release 25_12. Residues annotated as binding were used as positive examples, while all other residues were treated as negative examples.

The input representation is composed of two components:

• ESM-2 residue-level embeddings, extracted with the esm2_t6_8M_UR50D model (Lin et al., 2023). These embeddings are provided by the user as precomputed .npy files and must have shape (320, L), where L is the length of the protein sequence.
• AIUPred energy-based features, which provide residue-level energy information (Erdős and Dosztányi, 2024). These features are computed internally during prediction.

The ESM-2 embeddings and the AIUPred energy-based features are concatenated internally and used as input to the binding prediction model.

Local environment setup

1. Clone the repository:

git clone https://github.com/sinc-lab/e_emb2bind_caid4.git
cd e_emb2bind_caid4

2. Create and activate a virtual environment:

conda create -n e_emb2bind_caid4 python=3.11
conda activate e_emb2bind_caid4

3. Install required packages:

pip install -r requirements.txt

Usage

The main prediction script is predict.py.

To run the predictor, you need:

1. A FASTA file containing the protein sequences.
2. A directory containing the precomputed embeddings for the same sequences.

Each embedding file must correspond to one FASTA record and should be named {protein_id}.npy, where {protein_id} is the identifier of the protein in the FASTA file. The embeddings should have shape (320, L), where L is the length of the protein sequence.

Generate embeddings

If embeddings are not already available, they can be computed locally using compute_embeddings.py:

python compute_embeddings.py \
  --fasta <path_to_fasta> \
  --output-dir <output_directory> \
  [--device <device>] \
  [--skip-existing]

For example, using the provided sample files:

python compute_embeddings.py \
  --fasta data/samples.fasta \
  --output-dir data/embeddings/ \
  --device cuda

This writes one {protein_id}.npy file per FASTA record (shape (320, L)).

Run prediction

After computing the embeddings, run the prediction script with the following command:

python predict.py \
  --fasta <path_to_fasta> \
  --embedding-dir <embedding-directory> \
  [--output-dir <output_directory>] \
  [--device <device>]

For example, using the provided sample files:

python predict.py \
  --fasta data/samples.fasta \
  --embedding-dir data/embeddings/

This script will:

• Read all sequences from the input FASTA file.
• Load the corresponding precomputed embeddings.
• Predict residue-level binding scores using a sliding-window approach.
• Save the output files in the selected output directory (./results/ by default).

In addition to individual {protein_id}.caid files, the predictor also writes all_predictions.caid, which contains the predictions for all proteins in the input FASTA file.

Command-line arguments

Argument	Short	Description
--fasta	-f	Path to the input FASTA file. Required.
--embedding-dir	-e	Directory containing one precomputed .npy embedding file per FASTA record. Required.
--output-dir	-o	Directory where predictions and additional outputs are saved. Default: ./results/.
--device	-d	Device used for prediction: cpu, cuda, cuda:0, etc. Default: cpu.
--threads		Number of CPU threads to use. Default: 8.
--verbose	-v	Enable detailed progress messages. Default: disabled.

Container usage for CAID challenge

For the CAID challenge container, embeddings must be precomputed outside the container and mounted at runtime. The container includes the trained classifier and the minimal dependencies needed for CPU inference. The container is designed to run without internet access during prediction.

1. Precompute embeddings

First, generate the embeddings as described above. This step must be done before running the container.

2. Pull the Docker image

The image is available on Docker Hub:

docker pull sofiaaduarte/e_emb2bind:caid4

3. Run the container offline

docker run --rm --network none \
  -v </absolute/path/to/samples.fasta>:/data/input.fasta:ro \
  -v </absolute/path/to/embeddings>:/data/embeddings:ro \
  -v </absolute/path/to/output>:/output \
  sofiaaduarte/e_emb2bind:caid4 \
  --threads 8

The paths on the left side of each : correspond to paths on the host machine and can be changed by the user. The paths on the right side are fixed inside the container.

The required mounts are:

Host path	Container path	Description
/absolute/path/to/samples.fasta	/data/input.fasta	Input FASTA file. Mounted as read-only.
/absolute/path/to/embeddings	/data/embeddings	Directory containing one {protein_id}.npy file per FASTA record. Mounted as read-only.
/absolute/path/to/output	/output	Directory where predictions are written.

For example, using the current working directory and the provided sample FASTA and embeddings:

docker run --rm --network none \
  -v "$(pwd)/data/samples.fasta:/data/input.fasta:ro" \
  -v "$(pwd)/data/embeddings:/data/embeddings:ro" \
  -v "$(pwd)/results:/output" \
  sofiaaduarte/e_emb2bind:caid4 \
  --threads 8

The container will write one {protein_id}.caid file per protein in the output directory, along with a timings.csv file containing per-sequence execution times in milliseconds. Also, an all_predictions.caid file will be written, containing the predictions for all proteins in the input FASTA file.

4. (Optional) Build and publish the Docker image

The Docker image is already available on Docker Hub. To build it locally from this repository:

docker build --network=host -t e_emb2bind:caid4 .

In order to publish to Docker Hub, log in:

docker login

Tag the local image:

docker tag e_emb2bind:caid4 <dockerhub-user>/e_emb2bind:caid4

And then push it:

docker push <dockerhub-user>/e_emb2bind:caid4