feefipho 0.0.2

Functionally-informed, embedding-based phage host identification pipeline.

FEE FI PHO PHAGE
I smell the host of this bacteriophage

A Framework Employing protein Embeddings for the Functionally-Informed Prediction of the HOsts of PHAGEs

Image generated using ChatGPT.

Table of Contents

1. About the Project
2. Citation
3. Getting Started
   • Prerequisites
   • Installation
4. Usage details
5. Output format
6. Training new models

About the project

This repo contains the code to train and launch models for the functionally-informed prediction of the bacterial host of phages based on their protein embeddings. The classifiers are trained using the functional predictions obtained from Empathi and SUBLYME and use as input the protein embeddings generated using ProtT5. Independent binary models (SVMs) are trained - using only one protein type (function) at a time - to predict if a protein is associated to a host of interest or not (i.e., host1 vs all). The predictions from each function-specific model are then combined to make a final prediction per host of interest.

Citation

Preprint forthcoming. In the meantime please cite:

Boulay, A., Rousseau, E., Galiez, C. Feefipho. https://huggingface.co/AlexandreBoulay/feefipho.

Getting started

Feefipho can be installed via PyPI, Apptainer or directly from the HuggingFace repository.

A script is provided to download required models.

Prerequisites

A GPU is recommended to compute embeddings for large datasets.

The full list of dependencies can be found in requirements.txt.

Dependencies are taken care of by pip or Apptainer.

python==3.11.5
joblib==1.2.0
numpy==1.26.4
pandas==2.2.1
torch==2.3.0
scipy==1.13.1
scikit-learn==1.3.0
transformers==4.43.1
sentencepiece==0.2.0

Installation

From PyPI:

First, create a virtual environment in python 3.11.5. For example:

conda create -n feefipho_env python=3.11.5
conda activate feefipho_env

Download Feefipho and its dependencies:

pip install feefipho

Download required models:

feefipho download --feefipho --empathi

If you plan on running the tool offline, you will also require ProtT5 models to be downloaded locally (add --protT5 to command above). Note that the "Rostlab" folder must be placed in the same directory from which you will run the "feefipho predict" command.

If you are only interested in one bacterial host in particular (or in using only one type of protein), you may specify which in the download command:

feefipho download --feefipho Staphylococcus Mycobacterium #or
feefipho download --feefipho lysin

All models associated to only these bacteria or functions will be downloaded. Specifying a combination of hosts and functions will further restrict the download to this combination.

From Apptainer:

Download Apptainer or singularity. On windows, this will require a virtual machine. WSL works well.

Fetch the container from GHCR:

apptainer pull oras://ghcr.io/alexandreboulay/feefipho:latest #make sure to include 'oras://' if using apptainer

Download required models:

apptainer run feefipho.sif download --feefipho --empathi  #if running offline, --protT5

Usage:

apptainer run feefipho.sif predict input.faa [options]

From source:

winget install git-xet
git clone https://huggingface.co/AlexandreBoulay/feefipho
cd feefipho
pip install -r requirements.txt

ex.

python src/feefipho/download.py --empathi_models
python src/feefipho/feefipho.py test/test.faa -o test/outputs --empathi\_models empathi\_models/ -m host\_models

Usage details

Quick launch:

feefipho predict input.faa -m host\_models --empathi\_models empathi\_models

Only make predictions for a given host or function:

feefipho predict input.faa -m host\_models --empathi\_models empathi\_models -b Staphylococcus
feefipho predict input.faa -m host\_models --empathi\_models empathi\_models -f lysin

Resume a previous run from a given checkpoint (calc_embeddings, pred_functions, pred_host_step1, pred_host_step2):

feefipho predict output/input.csv -m host\_models --empathi\_models empathi\_models -c pred\_host\_step1 #if embeddings and functional prediction is already completed. Note that the input file now corresponds to the embeddings calculated previously.

A fasta file of protein sequences or a csv file of protein embeddings can be used as input. All proteins from a same phage should be separated in a similar way as phageID_proteinID (see --separator option).

Specifying the option --only_embeddings will only compute embeddings. This step is much faster with a GPU. The embeddings file can then be reinputted using the same command (without --only_embeddings) and specifying the new embedding file as input file.

Options:

Parameter	Description
input_file	Path to input file containing protein sequences (.fa*) or protein embeddings (.csv) that you wish to annotate.
--threads (-t)	Number of threads (default 1).
--output_folder (-o)	Path to the output folder. Default folder is ./host_predictions/.
--only_embeddings	Whether to only calculate embeddings (no lysin prediction).
--bacterial_host (-b)	Bacterial host of interest. Default behaviour is to make predictions for all hosts. Either "all", "gram-pos", "gram-neg", "host_type" or genus of bacterial host of interest with first letter capitalized (ex. Staphylococcus).
--function (-f)	Function of interest. By default all functions are used. Ex. "all", "lysin", etc.
--models_folder (-m)	Path to folder containing pretrained host models. Default is ./models
--empathi_models	Path to folder containing Empathi models.
--checkpoint (-c)	Last checkpoint completed. Only applies if this is a continuation of a previous run that failed or was stopped. Specify one of {calc_embeddings, pred_functions, pred_host_step1, pred_host_step2}. If unsure see checkpoints.log.
--separator (-s)	Seperator between phageID and proteinID (ex. if phageID_proteinID then s="_").
--separator_position	Describes relationship between phageID and proteinID. If "right", the split will be made on last occurrence of "separator" (ex. NIC06_P2_01), if "left", the split will be made on first occurrence of "separator" (ex. IMGVR_UViG_2529292985_000008

Output format

When evaluating predictions, it is important to consider not only the host_proba (mean prediction over all proteins), but also the support (number of proteins that agree with this host prediction). The more proteins agree with a prediction, the more that phage ressembles known phages that infect that host, even if it also possesses many other proteins so far not known to be associated with that host.

Along with the host prediction, all functional predictions and embeddings will be outputted by the pipeline.

final_predictions.csv contains the final host prediction per phage. It is formatted as follows:

accession	host	host_proba	coverage	support
AB009866	Staphylococcus	0.812	0.878	43
AB609718	Enterococcus	0.838	0.890	130

where "host_proba" corresponds to the mean of all protein-level prediction probabilities, "support" corresponds to the number of proteins that agree with the final prediction and "coverage" corresponds to the proportion of all proteins that support the final prediction (without considering proteins that do not contribute to the prediction, i.e., proteins with no predicted function).

functional_predictions.csv contains the probabilities associated to the functional predictions of all proteins (Empathi and SUBLYME). A prediction >0.5 corresponds to a positive prediction.

protein_host_predictions.csv contains the probabilities of predictions made by protein-level models. For each protein, a prediction was made for each function-host-specific model (given that the protein was predicted to have that function). This file can be used to identify proteins (or types of proteins) that contributed positively to the final prediction.

phage_g{pos|neg}_host_predictions.csv contains the probabilities of all host predictions agglomerated per phage, that can be used to create a ranking of the most probable hosts per phage.

protein_gram_predictions.csv and phage_gram_predictions.csv contains the same information but for gram-pos/gram-neg classification instead of for host genus prediction.

Training new models

This section provides information relating to the training of models.

A binary model is trained per protein-type and per bacterial host using protein embeddings as input.

Requirements

Data files (found in the Zenodo archive)

• embeddings.csv - protein embeddings of all proteins.
• metadata.csv - bacterial host, protein cluster, viral cluster, etc.
• functional_predictions.csv - Empathi and SUBLYME predictions.

Scripts

• split_dataset.py - create train-test splits
• train.py - train models

If you want to add your own data, follow the format present in the data files. Embeddings must be generated with the ProtT5 version linked above, unless you recalculate all embeddings, or if you use only your own data.

Step 1. Generate splits.

Five splits are generated (20% of data in each). Four splits are used for training and the last is saved for testing. As a check of robustness, all 5 splits can be used to train/test models.

The splits are saved for the sake of reproducibility.

Protein clusters at 30% seq ID and 80% cov are used to split dataset. Proteins in the training and testing set are as distinct as possible and overfitting is limited as much as possible in each protein-level model. Taken individually, these models allow us to evaluate the predictive power of each protein-type for each host (i.e. which protein function is a better predictor for a given host).

To generate the splits:

python scripts/split\_train\_test\_clusters.py data/metadata.py random\_pc Escherichia -o new\_splits -f lysin --function\_file data/functional\_prediction.py

Step 2. Train models

Binary SVMs using protein embeddings as input are trained for each host independently.

ex. python scripts/train.py data/ random_pc lysin Staphylococcus --ratio_classes 5 -s combined -o new_models/ --data_augmentation 2

Step 3. Make predictions

You can use the main tool to make predictions. Make sure to use the newly trained models with the --models_folder (-m) option.