Upload folder using huggingface_hub

README.md

@@ -13,15 +13,15 @@ language:
 - en
 ---
 
-# PhageContraMLM: Contrastive Learning for Phage Protein Representations
+# ContraMLM: Contrastive Learning for Phage Protein Representations
 
-PhageContraMLM is a fine-tuned version of the `Rostlab/prot_t5_xl_uniref50` protein language model, trained with Low-Rank Adaptation (LoRA) using a hybrid objective that combines standard Masked Language Modeling (MLM) with a contrastive loss.
+ContraMLM is a fine-tuned version of the `Rostlab/prot_t5_xl_uniref50` protein language model, trained with Low-Rank Adaptation (LoRA) using a hybrid objective that combines standard Masked Language Modeling (MLM) with a contrastive loss.
 
 The model is built to improve the embedding space for bacteriophage proteins, clustering them by functional group and PHROG family in a zero-shot setting.
 
 ## Intended Use
 
-PhageContraMLM is intended for researchers in computational biology and virology who need function-aware embeddings for phage protein sequences.
+ContraMLM is intended for researchers in computational biology and virology who need function-aware embeddings for phage protein sequences.
 
 **Primary use cases:**
 - **Zero-shot functional retrieval:** querying unknown phage proteins against a database of known PHROG families using cosine similarity or L2 distance.
@@ -29,7 +29,7 @@ PhageContraMLM is intended for researchers in computational biology and virology
 
 ## How to Use
 
-The model relies on the Hugging Face `transformers` and `peft` libraries.
+The model relies on the Hugging Face `transformers` and `peft` libraries. The LoRA adapters live inside this repo under `runs/protrans_XL_Full_lora_envhog_ContraMLM_v1_1/lora_adapters`, so make sure to pass `subfolder` when loading.
 
 ```python
 import torch
@@ -38,14 +38,15 @@ from peft import PeftModel
 
 device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 base_model_name = "Rostlab/prot_t5_xl_uniref50"
-adapter_dir = "Amin-Saeidi/PhageContraMLM"  # update to your exact repo ID
+adapter_repo = "Amin-Saeidi/PhageContraMLM"
+adapter_subfolder = "runs/protrans_XL_Full_lora_envhog_ContraMLM_v1_1/lora_adapters"
 
 # 1. Load tokenizer and base model
 tokenizer = T5Tokenizer.from_pretrained(base_model_name, do_lower_case=False)
 model = T5ForConditionalGeneration.from_pretrained(base_model_name, torch_dtype=torch.float16)
 
 # 2. Attach LoRA adapters and merge
-model = PeftModel.from_pretrained(model, adapter_dir)
+model = PeftModel.from_pretrained(model, adapter_repo, subfolder=adapter_subfolder)
 model = model.merge_and_unload().to(device).eval()
 
 # 3. Prepare sequence (space-separated, rare amino acids replaced)
@@ -62,6 +63,39 @@ with torch.no_grad():
 print(pooled_embedding.shape)
 ```
 
+## From Source
+
+If you want to retrain or modify the model locally, clone the full repo (adapters, data, and scripts included).
+
+First, create a virtual environment in Python 3.11.5:
+
+```
+conda create -n contramlm_env python=3.11.5
+conda activate contramlm_env
+```
+
+Clone the repo. You will need git-lfs: for WSL or Linux use `sudo apt-get install git-lfs`, for Windows either use [git bash](https://git-scm.com/downloads) or get git-lfs from [here](https://github.com/git-lfs/git-lfs/releases). Then:
+
+```
+git lfs install
+git clone https://huggingface.co/Amin-Saeidi/PhageContraMLM
+```
+
+Install dependencies:
+
+```
+cd PhageContraMLM
+pip install -r requirements.txt
+```
+
+Usage (training):
+
+```
+python src/train.py
+```
+
+Check `src/train.py` for the available config flags (data paths, LoRA rank/alpha, loss weighting) before launching a run.
+
 ## Training Data and Process
 
 - **Data:** `envhog_phrog2` dataset.
@@ -83,7 +117,7 @@ High-throughput script for generating mean-pooled encoder embeddings. Loads the
 **`src/eval_EmbeddingSpace.py`**
 Generates publication-quality plots analyzing the embedding space:
 - t-SNE grids colored by PhrogCat category
-- Pairwise L2 and cosine scatter plots comparing the base model against the fine-tuned PhageContraMLM model
+- Pairwise L2 and cosine scatter plots comparing the base model against the fine-tuned ContraMLM model
 
 **`src/eval_PhrogRetrieval.py`**
 Zero-shot functional retrieval benchmarking using `hnswlib` (Hierarchical Navigable Small World graphs):