# labstructbioinf/plm-blast architecture

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

- Interactive diagram: https://gitdiagram.com/labstructbioinf/plm-blast
- Repository: https://github.com/labstructbioinf/plm-blast

## Overview

##### Project type and purpose
- pLM-BLAST is a Python-based command-line tool and library for sensitive remote homology detection.
- It exposes a core API (the `alntools` and `embedders` packages) as well as several CLI scripts (`embeddings.py`, `plmblast.py`, plus helper scripts in `scripts/`) and example workflows under `examples/`.
- Key workflows:
- Generate protein embeddings from FASTA/CSV → store to disk (via `embeddings.py`, using `embedders/*`)
- Search a database → pre-screen via cosine similarity → perform alignment → post-process → output CSV (`plmblast.py`)

##### File structure
- Top-level: configuration (`pyproject.toml`, `requirements.txt`), CI workflow, packaging metadata.
- Core library:
- alntools/
– `alignment.py`, `density/`, `parser.py`, `prepare/`, `postprocess/`, `filehandle.py`, `settings.py`
- embedders/
– Base class + specific implementations (`pt`, `esm`, `hfautomodel`, etc.), `dataset.py`, `checkpoint.py`, `schema.py`
- CLI entrypoints:
- `embeddings.py` (create or resume embedding generation)
- `plmblast.py` (searching & alignment)
- Helper scripts in `scripts/` (plotting, CSV formatting, merging, etc.)
- Tests under `tests/` and examples under `examples/`

##### README for additional insights
- Detailed usage for database creation, checkpointing, prescreening, search, and visualization
- Dependencies: Python ≥3.9, Transformers models, optional GPU/multiprocessing
- Emphasis on modular embedders and adaptive batching

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface (CLI)
    subgraph "1. User Interface (CLI)"
        direction TB
        embeddings["embeddings.py"]:::cli
        plmblast["plmblast.py"]:::cli
        csv2nice["csv2nice.py"]:::cli
        dbtofile["dbtofile.py"]:::cli
        merge["merge.py"]:::cli
        scripts_plmblast["plmblast.py (helper)"]:::cli
        plot_script["plot.py"]:::cli
    end

    %% Data Preparation & I/O
    subgraph "2. Data Preparation & I/O"
        direction TB
        filehandle["filehandle.py"]:::core
        parser["parser.py"]:::core
        iterate_prep["iterate.py"]:::core
        reduce_dup["reduce_duplicates.py"]:::core
        screening_prep["screening.py"]:::core
        settings["settings.py"]:::core
    end

    %% Embedding Engine
    subgraph "3. Embedding Engine"
        direction TB
        base["base.py"]:::core
        ankh["ankh.py"]:::core
        esm["esm.py"]:::core
        hfauto["hfautomodel.py"]:::core
        prottrans["prottrans.py"]:::core
        checkpoint["checkpoint.py"]:::core
        dataset["dataset.py"]:::core
        schema["schema.py"]:::core
    end

    %% Disk Storage
    disk["Disk Storage\n(.pt embeddings)"]:::store

    %% Pre-screening Module
    subgraph "4. Pre-screening Module"
        direction TB
        density_parallel["parallel.py"]:::core
        density_iterate["iterate.py"]:::core
        density_local["local.py"]:::core
    end

    %% Alignment Module
    subgraph "5. Alignment Module"
        direction TB
        alignment["alignment.py"]:::core
        numeric["numeric.py"]:::core
        local_density["local.py"]:::core
    end

    %% Post-processing & Formatting
    subgraph "6. Post-processing & Formatting"
        direction TB
        compare["compare.py"]:::core
        filter["filter.py"]:::core
        format["format.py"]:::core
    end

    %% Visualization
    subgraph "7. Visualization"
        direction TB
        plot["plot.py"]:::core
    end

    %% External Dependencies
    subgraph "8. External Dependencies"
        direction TB
        hf["HuggingFace AutoModel"]:::ext
        gpu["GPU/CPU"]:::ext
        dbs["Precomputed DBs"]:::ext
    end

    %% Data Flow
    embeddings -->|"load sequences"| parser
    plmblast -->|".fas/.csv"| parser
    parser --> iterate_prep
    iterate_prep --> filehandle
    filehandle --> base
    base --> ankh
    base --> esm
    base --> hfauto
    base --> prottrans
    ankh --> checkpoint
    esm --> checkpoint
    hfauto --> checkpoint
    prottrans --> checkpoint
    checkpoint --> disk
    disk --> dataset
    dataset --> schema
    base -->|"generate embeddings"| disk
    plmblast --> density_parallel
    density_parallel --> density_iterate
    density_iterate --> density_local
    density_local --> alignment
    alignment --> numeric
    numeric --> local_density
    local_density --> compare
    compare --> filter
    filter --> format
    format --> plot
    plot -->|"results.png"| dbs

    %% External Links
    base --> hf
    alignment --> gpu

    %% Click Events
    click embeddings "https://github.com/labstructbioinf/plm-blast/blob/main//embeddings.py"
    click plmblast "https://github.com/labstructbioinf/plm-blast/blob/main//plmblast.py"
    click csv2nice "https://github.com/labstructbioinf/plm-blast/blob/main//scripts/csv2nice.py"
    click dbtofile "https://github.com/labstructbioinf/plm-blast/blob/main//scripts/dbtofile.py"
    click merge "https://github.com/labstructbioinf/plm-blast/blob/main//scripts/merge.py"
    click scripts_plmblast "https://github.com/labstructbioinf/plm-blast/blob/main//scripts/plmblast.py"
    click plot_script "https://github.com/labstructbioinf/plm-blast/blob/main//scripts/plot.py"
    click filehandle "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/filehandle.py"
    click parser "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/parser.py"
    click iterate_prep "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/prepare/iterate.py"
    click reduce_dup "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/prepare/reduce_duplicates.py"
    click screening_prep "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/prepare/screening.py"
    click settings "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/settings.py"
    click base "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/base.py"
    click ankh "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/ankh.py"
    click esm "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/esm.py"
    click hfauto "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/hfautomodel.py"
    click prottrans "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/prottrans.py"
    click checkpoint "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/checkpoint.py"
    click dataset "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/dataset.py"
    click schema "https://github.com/labstructbioinf/plm-blast/blob/main//embedders/schema.py"
    click density_parallel "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/density/parallel.py"
    click density_iterate "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/density/iterate.py"
    click density_local "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/density/local.py"
    click alignment "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/alignment.py"
    click numeric "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/numeric.py"
    click local_density "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/density/local.py"
    click compare "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/postprocess/compare.py"
    click filter "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/postprocess/filter.py"
    click format "https://github.com/labstructbioinf/plm-blast/blob/main//alntools/postprocess/format.py"

    %% Styles
    classDef cli fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6bf,stroke:#333,stroke-width:1px
    classDef store fill:#fb3,stroke:#333,stroke-width:1px
    classDef ext fill:#ccc,stroke:#333,stroke-width:1px
```
