# westlake-repl/saprot architecture

> Architecture diagram of the GitHub repository westlake-repl/saprot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/westlake-repl/saprot
- Repository: https://github.com/westlake-repl/saprot

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        Input["Protein Data (Sequences & Structures)"]
        BinNode["External Binaries"]
    end

    %% Configuration Module
    subgraph "Configuration Module"
        ConfigClinVar["ClinVar Config"]
        ConfigDeepLoc["DeepLoc Config"]
    end

    %% Data Preparation Module
    subgraph "Data Preparation Module"
        DS["Dataset Module"]
        LMDB["LMDB Repository"]
    end

    %% Model Module
    subgraph "Model Module"
        ModelAbstract["Abstract Model"]
        ModelSaprotAnnotation["Saprot Annotation Model"]
        ModelSaprotClassification["Saprot Classification Model"]
        ModelESMMutation["ESM Mutation Model"]
    end

    %% Utility Functions
    subgraph "Utility Functions"
        UtilsESMLoader["esm_loader"]
        UtilsFoldseek["foldseek_util"]
        UtilsMetrics["metrics"]
        UtilsModuleLoader["module_loader"]
    end

    %% Execution Scripts
    subgraph "Execution Scripts"
        ScriptTraining["training.py"]
        ScriptClinvarAUC["compute_clinvar_auc.py"]
        ScriptMutationZeroshot["mutation_zeroshot.py"]
    end

    %% Output and Storage
    subgraph "Output and Storage"
        Output["Output/Results"]
        Weights["Weights/Pretrained Models"]
    end

    %% Connections
    Input -->|"raw_data"| DS
    Input -->|"raw_data"| LMDB

    ConfigClinVar -->|"config"| ModelAbstract
    ConfigDeepLoc -->|"config"| ModelAbstract
    ConfigClinVar -->|"config"| ScriptClinvarAUC
    ConfigDeepLoc -->|"config"| ScriptTraining

    DS -->|"processed_data"| ModelAbstract
    LMDB -->|"support_training"| ModelAbstract

    UtilsESMLoader -->|"utils_support"| ModelAbstract
    UtilsFoldseek -->|"structure_conversion"| ModelAbstract
    UtilsModuleLoader -->|"module_loading"| ModelAbstract
    UtilsMetrics -->|"evaluation"| ScriptClinvarAUC

    ModelAbstract -->|"inference"| ModelSaprotAnnotation
    ModelAbstract -->|"inference"| ModelSaprotClassification
    ModelAbstract -->|"inference"| ModelESMMutation

    ModelSaprotAnnotation -->|"processing"| ScriptTraining
    ModelSaprotClassification -->|"processing"| ScriptTraining
    ModelESMMutation -->|"processing"| ScriptMutationZeroshot

    ScriptTraining -->|"training_results"| Output
    ScriptClinvarAUC -->|"evaluation_results"| Output
    ScriptMutationZeroshot -->|"inference_output"| Output

    ModelAbstract -->|"checkpoints"| Weights

    BinNode -->|"dependency"| UtilsFoldseek

    %% Click Events
    click DS "https://github.com/westlake-repl/saprot/blob/main/dataset/lmdb_dataset.py"
    click LMDB "https://github.com/westlake-repl/saprot/blob/main/LMDB/README.md"
    click ConfigClinVar "https://github.com/westlake-repl/saprot/tree/main/config/ClinVar/"
    click ConfigDeepLoc "https://github.com/westlake-repl/saprot/tree/main/config/DeepLoc/"
    click ModelAbstract "https://github.com/westlake-repl/saprot/blob/main/model/abstract_model.py"
    click ModelSaprotAnnotation "https://github.com/westlake-repl/saprot/blob/main/model/saprot/saprot_annotation_model.py"
    click ModelSaprotClassification "https://github.com/westlake-repl/saprot/blob/main/model/saprot/saprot_classification_model.py"
    click ModelESMMutation "https://github.com/westlake-repl/saprot/blob/main/model/saprot/esm_mutation_model.py"
    click UtilsESMLoader "https://github.com/westlake-repl/saprot/blob/main/utils/esm_loader.py"
    click UtilsFoldseek "https://github.com/westlake-repl/saprot/blob/main/utils/foldseek_util.py"
    click UtilsMetrics "https://github.com/westlake-repl/saprot/blob/main/utils/metrics.py"
    click UtilsModuleLoader "https://github.com/westlake-repl/saprot/blob/main/utils/module_loader.py"
    click ScriptTraining "https://github.com/westlake-repl/saprot/blob/main/scripts/training.py"
    click ScriptClinvarAUC "https://github.com/westlake-repl/saprot/blob/main/scripts/compute_clinvar_auc.py"
    click ScriptMutationZeroshot "https://github.com/westlake-repl/saprot/blob/main/scripts/mutation_zeroshot.py"
    click BinNode "https://github.com/westlake-repl/saprot/blob/main/bin/README.md"
    click Output "https://github.com/westlake-repl/saprot/tree/main/output/ClinVar"
    click Weights "https://github.com/westlake-repl/saprot/blob/main/weights/PLMs/README.md"

    %% Styles
    classDef config fill:#CCE5FF,stroke:#007BFF,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
    classDef model fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef utils fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef scripts fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef bin fill:#E8DAEF,stroke:#9B59B6,stroke-width:2px;
    classDef output fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef weights fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    class ConfigClinVar,ConfigDeepLoc config;
    class DS,LMDB data;
    class ModelAbstract,ModelSaprotAnnotation,ModelSaprotClassification,ModelESMMutation model;
    class UtilsESMLoader,UtilsFoldseek,UtilsMetrics,UtilsModuleLoader utils;
    class ScriptTraining,ScriptClinvarAUC,ScriptMutationZeroshot scripts;
    class BinNode bin;
    class Output output;
    class Weights weights;
```
