How westlake-repl/saprot works
Project Type and Purpose
• SaProt is a protein language modeling project that augments amino acid sequences with structure-aware (3Di) information to improve protein-specific predictions. It provides tools for tasks such as mutational effect prediction, protein embedding extraction, and protein inverse folding.
• The README makes it clear that the repository is an official implementation accompanying a scientific paper, and it supports multiple functionalities (e.g., fine-tuning, zero-shot evaluation) using different protein structures (AF2, ESMFold).
Analyzing the File Structure
• Top-level directories indicate separation of concerns:
• "config": YAML configuration files for various tasks (ClinVar, Contact, DeepLoc, EC, GO, HumanPPI, etc.) and pre-training.
• "dataset": Contains different dataset implementations and helpers (lmdb_dataset, mutation_zeroshot_dataset, and specialized saprot datasets) to interface with the protein data.
• "model": Contains abstraction and concrete implementations for the model components. Inside "model/saprot" are different modules addressing various tasks (annotation, classification, contact, foldseek mutation, inverse folding, etc.).
• "scripts": Scripts for training, evaluation (e.g., compute_clinvar_auc, mutation_zeroshot) – these represent entry points for running different tasks.
• "utils": Supporting utilities (esm_loader, foldseek_util, metrics, and other helper functions).
• "bin": Contains support binaries (for example, the foldseek binary to convert protein structures).
• "LMDB": Contains a README and is used for holding preprocessed datasets.
• Other directories/files (e.g., “figures”, “weights”, “README.md”) further support documentation, experiments, and model weights setups.
• This structure indicates a design that separates configuration, data interfaces, model implementations, and scripts for training/inference – a modular, layered design.
a. Main Components (Nodes):
• Data Preparation Module:
• Components: "dataset" and "LMDB"
• Functions: Fetches raw protein data, applies transformations via data interface scripts (e.g., lmdb_dataset.py) and specialized datasets (mutation_zeroshot, saprot datasets).
• Configuration Module:
• Components: "config" folder (ClinVar, DeepLoc, GO, etc.), specifying hyperparameters and settings for different tasks.
• Model Module:
• Components: "model" folder including:
▪ Abstract model interface (abstract_model.py, model_interface.py)
▪ Specific task models (saprot annotation, classification, contact, foldseek mutation, inverse folding, etc.)
• Functions: Defines the neural network architectures and encapsulates inference/training logic.
• Utilities and Helpers:
• Components: "utils" folder (esm_loader, foldseek_util, metrics, module_loader, etc.)
• Functions: Manage model loading, structure-to-sequence conversion (using foldseek), evaluation metrics, and other support tasks.
• Execution Scripts:
• Components: "scripts"
• Functions: Entry points for training, performing zero-shot prediction, computing evaluation metrics.
• External Binaries and Dependencies:
• Components: "bin" and possibly external model repositories (e.g., Hugging Face, esm)
• Functions: Handling protein structure encoding, interaction with external tools like foldseek.
• Output/Results Handling:
• Components: "output" folder – stores evaluation results (e.g., protein benchmarks) and logs.
• Weights/Pretrained Models:
• Components: "weights/PLMs" for storing model checkpoints.
b. Relationships and Data Flow:
• Data flows from the dataset interfaces into the model training pipeline. Configuration files dictate how each script or model instance is instantiated.
• The model layer interacts with utilities (for loading pretrained embeddings, converting structures).
• Inference and evaluation scripts call models (from the "model" folder) after retrieving appropriate inputs from the "dataset" and pre-processing modules.
• External services and libraries (e.g., Hugging Face, esm repository, foldseek binary) are integrated via wrappers within "utils" or directly referenced in the "model" implementations.
c. Architectural Patterns and Design Principles:
• Modular separation is evident (configuration, dataset, model, utilities) which aligns with practices like the separation of concerns and loose coupling.
• The system supports plug-and-play functionality (users can choose between AF2 and ESMFold structures as seen in the README) and supports multiple task-specific pipelines.
• Clear abstraction layers (abstract model interfaces and specialized implementations) facilitate future extension via additional tasks.
d. Relevant Technologies and Frameworks:
• Deep Learning: PyTorch along with the Transformers library (observed in code snippets).
• External tools: foldseek for structural processing, esm for model loading.
• Configuration: YAML files for experiment settings.
• Data: LMDB for dataset handling.