# yoakiyama/msa_pairformer architecture

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

- Interactive diagram: https://gitdiagram.com/yoakiyama/msa_pairformer
- Repository: https://github.com/yoakiyama/msa_pairformer

## Overview

##### Project type and purpose
- This is an open-source Python library (MSA Pairformer) for embedding multiple‐sequence alignments (MSAs) of protein sequences, predicting residue–residue interactions, and performing zero-shot variant effect prediction.
- It provides training code, data preprocessing, inference utilities, and Google Colab notebooks to reproduce published results and to embed/query MSAs with a parameter-efficient transformer.

##### File structure
- Top-level:
- MSA_Pairformer/          ← core Python package
- data/complexes/          ← sample MSA FASTA files
- MSA_Pairformer_with_MMseqs2.ipynb  ← Colab notebook with end-to-end workflow
- pyproject.toml           ← build and packaging config
- Core package modules:
- data_downloader.py       ← external tool setup (hhfilter)
- dataset.py               ← MSA ingestion, tokenization, mask generation
- positional_encoding.py   ← sequence position embedding
- categorical_jacobian.py, pairwise_operations.py, outer_product.py
← tensor operations for pairwise representations
- chunk_layer.py           ← sparse/chunk attention mechanism
- model.py                 ← MSAPairformer model class and from_pretrained() logic
- training_utils.py, regression.py
← training/inference helpers, variant effect regression head
- plotting.py              ← contact map visualization
- utils.py, custom_typing.py
← misc helpers and type definitions
- External/tooling:
- HHsuite (hhfilter binary) for MSA subsampling
- HuggingFace Hub client for model weights
- PyTorch for training/inference

##### README for additional insights
- Data pipeline: MSA download → hhfilter subsampling → tokenization → masking
- Model usage: from_pretrained( ) → prepare inputs → get_embeddings_and_contacts()
- Output: embeddings, contact logits, sequence weights, visualizations

##### Detail
- Call out the hhfilter setup step under data_downloader
- How from_pretrained abstracts HuggingFace calls

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        RawMSA["Raw MSA Files (data/complexes/*.fas)"]:::data
        DataDownloader["data_downloader.py"]:::data
        Dataset["dataset.py"]:::data
    end

    %% Core Model & Sub-modules
    subgraph "Core Model"
        direction TB
        PosEnc["positional_encoding.py"]:::model
        ChunkLayer["chunk_layer.py"]:::model
        PairOps["pairwise_operations.py"]:::model
        OuterProd["outer_product.py"]:::model
        CatJac["categorical_jacobian.py"]:::model
        Model["model.MSAPairformer"]:::model
    end

    %% Training & Inference Utilities
    subgraph "Training & Inference"
        direction TB
        TrainUtils["training_utils.py"]:::training
        Regression["regression.py"]:::training
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        Plot["plotting.py"]:::viz
    end

    %% Utilities & Types
    subgraph "Utilities"
        direction TB
        Utils["utils.py"]:::utils
        CustomTyping["custom_typing.py"]:::utils
    end

    %% External Services & Tools
    subgraph "External Services & Tools"
        direction TB
        HHFilter["HHsuite Binary"]:::external
        HFHub["HuggingFace Hub"]:::external
        GPU["GPU/Accelerator"]:::external
    end

    %% Configuration & Entry Points
    subgraph "Project Configuration & Entry Points"
        direction TB
        Config["pyproject.toml"]:::config
        Notebook["MSA_Pairformer_with_MMseqs2.ipynb"]:::config
        Readme["README.md"]:::config
        License["LICENSE"]:::config
    end

    %% Data flow connections
    RawMSA --> DataDownloader
    DataDownloader --> Dataset
    Dataset --> Model
    Model --> Plot
    Model --> Regression
    TrainUtils --> Model
    Utils --> DataDownloader
    Utils --> Model
    CustomTyping --> Dataset
    CustomTyping --> Model

    %% External interactions
    HHFilter --> DataDownloader
    HFHub --> Model
    GPU --> Model
    GPU --> TrainUtils

    %% Click events
    click DataDownloader "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/data_downloader.py"
    click Dataset "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/dataset.py"
    click PosEnc "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/positional_encoding.py"
    click ChunkLayer "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/chunk_layer.py"
    click PairOps "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/pairwise_operations.py"
    click OuterProd "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/outer_product.py"
    click CatJac "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/categorical_jacobian.py"
    click Model "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/model.py"
    click TrainUtils "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/training_utils.py"
    click Regression "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/regression.py"
    click Plot "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/plotting.py"
    click Utils "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/utils.py"
    click CustomTyping "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer/custom_typing.py"
    click Notebook "https://github.com/yoakiyama/msa_pairformer/blob/main/MSA_Pairformer_with_MMseqs2.ipynb"
    click Config "https://github.com/yoakiyama/msa_pairformer/blob/main/pyproject.toml"
    click Readme "https://github.com/yoakiyama/msa_pairformer/blob/main/README.md"
    click License "https://github.com/yoakiyama/msa_pairformer/tree/main/LICENSE"

    %% Styles
    classDef data fill:#D0E6FF,stroke:#0366d6
    classDef model fill:#D6F5D6,stroke:#28a745
    classDef training fill:#E8D0F5,stroke:#6f42c1
    classDef viz fill:#FFE0E0,stroke:#e5534b
    classDef utils fill:#FFF3CD,stroke:#d39e00
    classDef external fill:#FFE6CC,stroke:#e36209
    classDef config fill:#E2E3E5,stroke:#6c757d,stroke-dasharray: 5 5
```
