fcampelo/epitopetransfer

This repository contains data and code for the paper "Phylogeny-informed Transfer Learning Induces Performance Gains in Epitope Prediction Models", by Lindeberg Pessoa Leite, Teófilo E. de Campos, Francisco Pereira Lobo and Felipe Campelo.

IMPORTANT: The code in this repository uses a slightly different naming convention to that used in the paper. Please consider the following equivalencies:

• EpitopeTransfer <--> PITL-based models
• NPTransfer <--> PATL-based models
• ESM baseline <--> NTL-based models

• Dependencies
• Running models for published metrics
• Running the complete pipeline
• Running the analyses
• Contact

This project requires Python 3.10, although other versions are likely compatible. Follow the instructions below to set up your environment.

1. Install Python 3.10

Ensure that Python 3.10 is installed on your system. If not, you can install it using your system's package manager. For Ubuntu-based distributions, you can use:

    sudo apt update
    sudo apt install software-properties-common -y
    sudo add-apt-repository ppa:deadsnakes/ppa -y
    sudo apt update
    sudo apt install python3.10 python3.10-venv python3.10-distutils -y

2. Activate epitopetransfer environment

  source esm2/bin/activate
  # or
  source esm1b_v1/bin/activate
  # or
  source esm1b_v2/bin/activate

To exit any environment, run: deactivate

To run the models for specific taxa or for all taxa included in the study, use the following command format in the terminal:

  python3.10 main.py [base_model] [taxa]

Replace [base_model] to esm1b or esm2, and [taxa] to the desired taxa or all (for esm2 only). Example:

  source esm2/bin/activate
  (esm2) python3.10 main.py esm2 all # (the 'all' option is available for esm2 base model only)

To exit the esm2 environment, use this command: deactivate

  source esm1b_v1/bin/activate
  (esm1b_v1) python3.10 main.py esm1b bpertussis

  source esm1b_v2/bin/activate
  (esm1b_v2) python3.10 main.py esm1b mononegavirales

Available Taxa

Note: For the esm1b base model, activate the esm1b_v1 environment (source esm1b_v1/bin/activate) for taxa in the first column, or the esm1b_v2 environment (source esm1b_v2/bin/activate) for taxa in the second column. For the esm2 base model, activate the esm2 environment (source esm2/bin/activate) for all taxa.

All steps of the pipeline for the B. pertussis taxon are available in the pipeline folder. The same procedure applies to the other taxa as well.

Make sure to download the ESM-2 model or just point to this online repository, and adjust the file paths accordingly before execution.

To run the complete process, execute the following notebooks in sequence:

1. dataset_generation_taxa.ipynb
2. finetune_higher_level.ipynb
3. feature_calculation_reduction.ipynb

The analysis of the results was done using R version 4.4.1 (reproducible using the script under folder ./R). The main packages used in the analysis were:

• dplyr_1.1.4
• tidyr_1.3.1
• yardstick_1.3.1
• pROC_1.18.5
• multcomp_1.4-26
• ggplot2_3.5.1
• ggrepel_0.9.5
• see_0.9.0
• stringr_1.5.1
• wrappedtools_0.9.5

The full details of the R session used in the analysis are available in /R/SessionInfo.txt

Felipe Campelo - Principal investigator
Lindeberg Leite - First author