# kad-ecoli/blastknn_benchmark architecture

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

- Interactive diagram: https://gitdiagram.com/kad-ecoli/blastknn_benchmark
- Repository: https://github.com/kad-ecoli/blastknn_benchmark

## Overview

##### Project type and purpose
- This is an open-source benchmarking pipeline (“blastKNN_benchmark”) for large-scale assessment of various sequence database search tools (BLAST, Diamond, MMseqs2, HHSuite, JACKHMMER, PSIBLAST, PHMMER) aimed at homology-based protein function prediction.
- There is no frontend/backend web layer; it’s a command-line, data-processing and evaluation framework built from bash wrappers, Python scripts, and C++ code, orchestrating external bioinformatics engines.

##### File structure
- Top-level areas:
- curated/ – preprocessed ground-truth data (ontologies, sequences, labels)
- raw/ontology – original GO OBO file
- script/ – all orchestration code, wrappers, parsers, tuners, plotters, and third-party tool subrepos (hhsuite2, mmseqs)
- Patterns:
- Download & prep scripts under script/ (download_*.sh, curate_GAF, cdhit_src)
- Runner scripts (run_blastp.sh … run_phmmer.sh) invoking each tool and saving outputs
- Tuning scripts (tune_*.sh, tune_*.py)
- Plotting scripts (plot_*.py)
- Third-party code trees in script/hhsuite2 and script/mmseqs

##### Key README insights
- Three stages:
a. Download data
b. Run function prediction (invoke each tool & tune parameters)
c. Plot results (compare performance)
- Ground-truth labels in curated/sequence/*.is_a

a. Main components
1. Data Layer
- Raw GO ontology (raw/ontology/go-basic.obo)
- Raw sequences & validation sets (download via scripts)
- Curated sequences & ground truth labels (curated/sequence, curated/ontology)
2. Preprocessing & Curation
- Scripts that parse OBO, build GO term tables (obo2csv), cluster sequences (cdhit_src), validate formats
3. Execution Orchestrator
- Bash wrappers (run_*.sh) driving each search engine
- Parameter-tuner scripts (tune_*.sh / tune_*.py)
4. External Search Engines
- BLAST+ (blastp, psiblast), Diamond, MMseqs2, HHSuite2, JACKHMMER, PHMMER
- Each as a separate submodule or binary invoked by scripts
5. Results Processing
- Parsers (blast2tsv, diamond2tsv, ghostx2tsv, hhsuite2tsv)
- Combine & reformat scripts (combineFPC.py, fasta2tsv.cpp)
6. Evaluation & Visualization
- assess_result.py compares predicted .is_a with ground truth
- plot_*.py generates performance curves
b. Data flows and interactions
- Orchestrator → External Engines (bidirectional: commands & results files)
- Engines → Results Processing → Evaluation
- Evaluation → Visualization → Output plots
c. Architectural patterns & principles
- Pipeline pattern: linear data flow through discrete stages
- Modular tool‐wrapper architecture: each search engine is encapsulated
- Extensibility point: add new tool by dropping in a run_<tool>.sh + parser
d. Technologies & frameworks
- Bash scripting for orchestration
- Python for data parsing, tuning, plotting
- C++ modules for performance-critical tasks & third-party tools
- CSV/TSV, FASTA formats, OBO ontology parsing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawOntology["Raw Ontology\n(go-basic.obo)"]:::data
        CuratedOntology["Curated Ontology\n(is_a.csv, ...)"]:::data
        CuratedSeq["Curated Sequences\n(uniprot_sprot_exp.fasta, *.is_a)"]:::data
    end

    %% Preprocessing & Curation
    subgraph "Preprocessing & Curation"
        direction TB
        OBO2CSV["OBO to CSV Converter\n(obo2csv)"]:::processing
        GAF["GAF Curation\n(curate_GAF)"]:::processing
        CDHIT["Sequence Clustering\n(cdhit_src)"]:::processing
        IC["Information Content\nCalculator"]:::processing
        Subset["Subset Tools\n(subset_GOA, subset_tsv)"]:::processing
        FASTAut["FASTA Utilities\n(fasta2len, fasta2miss)"]:::processing
    end

    %% Execution Orchestrator
    subgraph "Execution Orchestrator"
        direction TB
        subgraph "Runner Scripts"
            direction TB
            RunBLAST["run_blastp.sh"]:::processing
            RunPSI["run_psiblast.sh"]:::processing
            RunDiamond["run_diamond.sh"]:::processing
            RunMMseqs["run_mmseqs.sh"]:::processing
            RunHH["run_hhblits.sh"]:::processing
            RunJack["run_jackhmmer.sh"]:::processing
            RunPHM["run_phmmer.sh"]:::processing
        end
        subgraph "Parameter Tuning"
            direction TB
            TuneUnified["tune.py"]:::processing
            TuneBLAST["tune_blastp.sh / .py"]:::processing
            TuneDiamond["tune_diamond.sh / .py"]:::processing
            TuneMMseqs["tune_mmseqs.sh / .py"]:::processing
        end
    end

    %% External Search Engines
    subgraph "External Search Engine Plugins"
        direction TB
        BLASTPlugin[(BLAST+)]:::engine
        DiamondPlugin[(Diamond)]:::engine
        MMseqs2Plugin[(MMseqs2)]:::engine
        HHSuitePlugin[(HHSuite2)]:::engine
        GhostXPlugin[(GhostX)]:::engine
        JackPlugin[(JackHMMER)]:::engine
        PHMMERPlugin[(PHMMER)]:::engine
    end

    %% Results Processing
    subgraph "Results Processing"
        direction TB
        ParseBlast["parse_blast.py"]:::results
        CombineFPC["combineFPC.py"]:::results
        GhostX2TSV["ghostx2tsv.py"]:::results
        HH2TSV["hhblits2tsv.py"]:::results
        Fasta2TSV["fasta2tsv"]:::results
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        direction TB
        Assess["assess_result.py"]:::viz
        PlotBest["plot_best.py"]:::viz
        PlotDef["plot_default.py"]:::viz
        PlotDiamond["plot_diamond.py"]:::viz
    end

    %% Data flows
    RawOntology --> OBO2CSV
    CuratedOntology --> IC
    CuratedSeq --> FASTAut
    OBO2CSV --> RunBLAST
    GAF --> RunBLAST
    CDHIT --> RunBLAST
    IC --> RunBLAST
    Subset --> RunBLAST

    RunBLAST --> BLASTPlugin
    RunPSI --> BLASTPlugin
    RunDiamond --> DiamondPlugin
    RunMMseqs --> MMseqs2Plugin
    RunHH --> HHSuitePlugin
    RunJack --> JackPlugin
    RunPHM --> PHMMERPlugin

    BLASTPlugin --> ParseBlast
    DiamondPlugin --> CombineFPC
    GhostXPlugin --> GhostX2TSV
    HHSuitePlugin --> HH2TSV
    MMseqs2Plugin --> CombineFPC
    JackPlugin --> CombineFPC
    PHMMERPlugin --> CombineFPC

    ParseBlast --> Assess
    CombineFPC --> Assess
    GhostX2TSV --> Assess
    HH2TSV --> Assess
    Fasta2TSV --> Assess

    Assess --> PlotBest
    Assess --> PlotDef
    Assess --> PlotDiamond

    %% Click Events
    click RawOntology "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/raw/ontology/go-basic.obo"
    click CuratedOntology "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/curated/ontology/is_a.csv"
    click CuratedSeq "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/curated/sequence/uniprot_sprot_exp.fasta"
    click OBO2CSV "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/obo2csv"
    click GAF "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/curate_GAF"
    click CDHIT "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/cdhit_src/"
    click IC "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/calculate_ic"
    click Subset "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/subset_GOA.cpp"
    click FASTAut "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/fasta2len"
    click RunBLAST "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_blastp.sh"
    click RunPSI "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_psiblast.sh"
    click RunDiamond "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_diamond.sh"
    click RunMMseqs "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_mmseqs.sh"
    click RunHH "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_hhblits.sh"
    click RunJack "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_jackhmmer.sh"
    click RunPHM "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/run_phmmer.sh"
    click TuneUnified "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/tune.py"
    click TuneBLAST "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/tune_blastp.sh"
    click TuneDiamond "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/tune_diamond.sh"
    click TuneMMseqs "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/tune_mmseqs.sh"
    click BLASTPlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/blastp/"
    click DiamondPlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/diamond/"
    click MMseqs2Plugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/mmseqs/"
    click HHSuitePlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/hhsuite2/"
    click GhostXPlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/ghostx/"
    click JackPlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/jackhmmer/"
    click PHMMERPlugin "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/phmmer/"
    click ParseBlast "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/parse_blast.py"
    click CombineFPC "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/combineFPC.py"
    click GhostX2TSV "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/ghostx2tsv.py"
    click HH2TSV "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/hhblits2tsv.py"
    click Fasta2TSV "https://github.com/kad-ecoli/blastknn_benchmark/tree/master/script/fasta2tsv"
    click Assess "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/assess_result.py"
    click PlotBest "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/plot_best.py"
    click PlotDef "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/plot_default.py"
    click PlotDiamond "https://github.com/kad-ecoli/blastknn_benchmark/blob/master/script/plot_diamond.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef processing fill:#d4edda,stroke:#333,stroke-width:1px
    classDef engine fill:#fff3cd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef results fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef viz fill:#f8d7da,stroke:#333,stroke-width:1px
```
