# djw533/hamburger architecture

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

- Interactive diagram: https://gitdiagram.com/djw533/hamburger
- Repository: https://github.com/djw533/hamburger

## Overview

##### Project type and purpose
- This is a command-line bioinformatics pipeline (“hamburger”) written in Python 3 (core logic) and R (T6SS filtering & plotting).
- It takes GFF3/FASTA files plus concatenated HMM profiles, searches genomes for co-localized gene clusters (especially T6SS loci), then filters, subtypes, and outputs results (tables, GFFs, iTOL inputs).

##### Main components
a. CLI Front-End (scripts/hamburger.py)
- Parses arguments, orchestrates workflow.
b. Python Core Package (hamburger/)
- I/O & parsing: fasta_parsing.py, gff_parsing.py
- HMM search: hmmer_functions.py, run_prodigal.py
- Cluster extraction & cleanup: extract.py, clean.py
- Filtering & grouping: filter.py, filter_t6_types.py, istarmap.py
- T6SS-specific utilities: tool_check.py, search.py
c. HMM Model Store (models/)
- Pre-built .hmm files (T6SS core, accessory, individual sub-units)
d. R Subtyping & Visualization (scripts/*.R)
- install_R_packages.R, filter_t6_types.R, post_hamburger_t6SS_search.R
e. Reference Sets (t6ss_reference_set/)
- FASTA alignments, subtype tables, phylogenetic trees
f. External Tools
- HMMER, Prodigal, Muscle, FastTree, R (+ libraries), Python libs (Biopython, pandas)

##### Relationships & data flow
1) User invokes CLI → passes GFF/FASTA + HMM profiles →
2) Python parses inputs → (optional) runs Prodigal →
3) Python calls HMMER via hmmer_functions → uses models/*.hmm →
4) extract.py identifies candidate clusters → clean.py refines results →
5) filter.py / filter_t6_types.py apply generic filters →
6) If ‑t flag: istarmap.py & search.py perform T6SS subtyping →
7) Python writes intermediate outputs (CSV, GFF) →
8) R scripts consume those outputs for plots / iTOL files →
9) Final outputs: annotated GFFs, summary tables, phylogenetic context files.

##### Architectural patterns & principles
- Modular pipeline: clearly separated parsing, search, filtering, subtyping, visualization.
- Data-driven design: HMM models and reference sets externalized in “models/” and “t6ss_reference_set/”.
- Single-responsibility modules: each .py/.R file has a distinct task.
- CLI orchestration layer decoupled from core logic.

##### Essential elements
- On reusable resources (models/, reference sets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Interface"
        CLI["scripts/hamburger.py\n(CLI)"]:::process
    end

    subgraph "Python Engine"
        FP["fasta_parsing.py"]:::process
        GP["gff_parsing.py"]:::process
        RP["run_prodigal.py"]:::process
        HM["hmmer_functions.py"]:::process
        EX["extract.py"]:::process
        CL["clean.py"]:::process
        FL["filter.py"]:::process
        FT["filter_t6_types.py"]:::process
        IS["istarmap.py"]:::process
        TC["tool_check.py"]:::process
        SE["search.py"]:::process
    end

    subgraph "HMM Model Store"
        M1["models/T6SS/*.hmm"]:::data
        M2["models/full/*.hmm"]:::data
        M3["models/individual/*.hmm"]:::data
    end

    subgraph "R Engine"
        IR["install_R_packages.R"]:::process
        CR["check_R_dependencies.R"]:::process
        FR["filter_t6_types.R"]:::process
    end

    subgraph "Reference Data"
        REF["t6ss_reference_set/"]:::data
    end

    subgraph "External Tools"
        E1["HMMER"]:::external
        E2["Prodigal"]:::external
        E3["Muscle"]:::external
        E4["FastTree"]:::external
        E5["R"]:::external
        E6["Python Libs\n(Biopython, pandas)"]:::external
    end

    CLI -->|"GFF3/FASTA → parse"| FP
    CLI -->|"GFF3/FASTA → parse"| GP
    GP -->|"Genes prediction"| RP
    RP -->|"calls Prodigal"| E2
    CLI -->|"call hmmscan"| HM
    HM -->|".hmm models"| M1
    HM -->|".hmm models"| M2
    HM -->|".hmm models"| M3
    HM -->|"HMM hits"| EX
    EX -->|"clusters"| CL
    CL -->|"refined clusters"| FL
    FL -->|"generic filters"| FT
    FT -->|"T6SS branch"| IS
    IS -->|"subtyping"| SE
    SE -->|"T6SS types"| FT
    FT -->|"intermediate outputs"| IR
    FT -->|"intermediate outputs"| FR
    REF -->|"reference alignments"| SE
    IR -->|"plotting & iTOL"| E5
    FR -->|"plotting & iTOL"| E5

    click CLI "https://github.com/djw533/hamburger/blob/master/scripts/hamburger.py"
    click FP "https://github.com/djw533/hamburger/blob/master/hamburger/fasta_parsing.py"
    click GP "https://github.com/djw533/hamburger/blob/master/hamburger/gff_parsing.py"
    click RP "https://github.com/djw533/hamburger/blob/master/hamburger/run_prodigal.py"
    click HM "https://github.com/djw533/hamburger/blob/master/hamburger/hmmer_functions.py"
    click EX "https://github.com/djw533/hamburger/blob/master/hamburger/extract.py"
    click CL "https://github.com/djw533/hamburger/blob/master/hamburger/clean.py"
    click FL "https://github.com/djw533/hamburger/blob/master/hamburger/filter.py"
    click FT "https://github.com/djw533/hamburger/blob/master/hamburger/filter_t6_types.py"
    click IS "https://github.com/djw533/hamburger/blob/master/hamburger/istarmap.py"
    click TC "https://github.com/djw533/hamburger/blob/master/hamburger/tool_check.py"
    click SE "https://github.com/djw533/hamburger/blob/master/hamburger/search.py"
    click M1 "https://github.com/djw533/hamburger/tree/master/models/T6SS/"
    click M2 "https://github.com/djw533/hamburger/tree/master/models/full/"
    click M3 "https://github.com/djw533/hamburger/tree/master/models/individual/"
    click IR "https://github.com/djw533/hamburger/blob/master/scripts/install_R_packages.R"
    click CR "https://github.com/djw533/hamburger/blob/master/scripts/check_R_dependencies.R"
    click FR "https://github.com/djw533/hamburger/blob/master/scripts/filter_t6_types.R"
    click REF "https://github.com/djw533/hamburger/tree/master/t6ss_reference_set/"

    classDef process fill:#D5E8D4,stroke:#82B366,color:#000;
    classDef data fill:#FFF2CC,stroke:#D6B656,color:#000;
    classDef external fill:#F8CECC,stroke:#B85450,color:#000;
```
