Protea

Protea is a Graph Neural Network (GNN) pipeline designed for predicting protein-protein interactions (PPI) using graph topologies and ESM-2 language model embeddings.

Tip

The trained Protea model weights are available for download at doi.org/10.6084/m9.figshare.33213876. Place the downloaded weights file under the model/ directory (e.g. ./model/protea_weights.pth).

Repository Layout

• Data_Processing.py: Reusable utilities for file loading, ESM token processing, replicate merging, and prediction generation.
• PPI_Graph_Functions.py: GNN class definitions (Protea, NetworkEmbedder, Conv_Block) and graph processing datasets.
• run_pipeline.py: A unified end-to-end command line script to run the entire pipeline.
• requirements.txt: Python package dependencies list.
• Merge_Pred_Dicts.py, Build_PPIGraph.py, InterHomo_TwoHead_Predict.py: Legacy modular scripts.

---

Installation & Setup

We support two ways to set up the dependencies environment.

Option 1: Conda / Mamba (Recommended for clusters)

Using a Conda/Mamba environment is highly recommended when running on HPC clusters (like Slurm environments), as it packages Python natively inside the environment rather than using host-system symlinks.

# 1. Create the environment (installs python and requirements.txt dependencies via pip)
conda env create -f environment.yml

# 2. Activate the environment
conda activate protea_environment

Option 2: Python Virtual Environment (venv)

An alternative option for local development or machines with system-wide Python 3.12:

# 1. Create a virtual environment using the system's Python 3.12 (or module load python)
python3 -m venv protea_env

# 2. Activate the virtual environment
source protea_env/bin/activate

# 3. Upgrade basic package tools
pip install --upgrade pip setuptools

# 4. Install all dependencies from requirements.txt (including PyG extensions)
pip install -r requirements.txt

Note

If you need to match a different CUDA version on your system, update the cu124 suffix in the index/find-links URLs at the top of requirements.txt.

---

Running the Pipeline

You can run the entire pipeline end-to-end using a single command:

python run_pipeline.py \
  --raw_networks_dir ./data/raw_networks/ \
  --esm2_embeddings_dir ./data/esm2_embeddings/ \
  --model_address ./model/protea_weights.pth

Pipeline Arguments

• --raw_networks_dir: Path to raw input network data (.dat files).
• --esm2_embeddings_dir: Path to folder containing serialized ESM-2 embeddings (.pkl).
• --model_address: Path to the trained GNN weights (.pth file).
• --merged_networks_dir: Directory where merged replicates are output.
• --ppigraphs_dir: Directory where converted PyG graph datasets are stored.
• --predictions_dir: Directory where GNN prediction tables (.csv) are saved.
• --batch_size: Batch size used during evaluation.

---

Downstream Regulation Analysis

After generating predictions, you can run downstream regulation analyses using the following scripts:

1. Cross-Infection Regulation Analysis

Compare interactome regulation dynamics across different infection systems:

python Cross_Infection_Interactome_Regulation.py \
  --homo_folder ./data/protea_predictions/ \
  --output_folder ./data/cross_interactome_regulation/

Arguments

• --homo_folder: Folder containing GNN predictions (.csv).
• --exp_list: Comma-separated list of experiment names to analyze.
• --output_folder: Folder to save outputs.

---

2. Intra-Infection Regulation Analysis

Analyze interactome changes across timepoints within the same infection system relative to control/mock conditions:

python Intra_Infection_Interactome_Regulation.py \
  --homo_folder ./data/protea_predictions/ \
  --relv_cond_list 0 \
  --output_folder ./data/intra_interactome_regulation/

Arguments

• --homo_folder: Folder containing GNN predictions (.csv).
• --exp_list: Comma-separated list of experiment names to analyze.
• --relv_cond_list: Comma-separated list of control/mock conditions (typically 0).
• --output_folder: Folder to save outputs.