# gaius-augustus/galba architecture

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

- Interactive diagram: https://gitdiagram.com/gaius-augustus/galba
- Repository: https://github.com/gaius-augustus/galba

## Overview

Based on our analysis of the file tree and the detailed README, the GALBA project is a bioinformatics pipeline designed for automated gene structure annotation. It builds on well‐established tools (like AUGUSTUS, Miniprot, DIAMOND, TSEBRA, and others) and is written primarily in Perl (with some Python scripts) to run a complex workflow that takes protein sequences and a target genome as input, creates training data, and then predicts gene structures. The project is distributed with a Dockerfile and Singularity image for containerized deployment, along with a comprehensive set of documentation and example test runs.

##### Main Components
- Main Pipeline Controller: The central entry point is the “galba.pl” script. This component orchestrates the whole workflow.
- Protein-to-Genome Alignment Module: This module can use one of two aligners – either Miniprot (default) or GenomeThreader (gth option). Supporting scripts (e.g., startAlign.pl, aln2hints.pl) fall into this category.
- Training & Prediction Module: Once evidence is produced (e.g., hints files), AUGUSTUS is trained and then used for gene prediction. This module involves multiple iterative training steps (with additional scripts like galba_cleanup.py and optimize_augustus.pl – even though the latter might be part of AUGUSTUS itself).
- Filtering and Post-processing: DIAMOND filtering, TSEBRA for selecting transcripts, and scripts for checking and cleaning predictions (scripts such as filterIntronsFindStrand.pl, gtf_sanity_check.py, etc.) form another group.
- Optional Hub Generation: MakeHub and UCSC track hub creation pipeline (using MakeHub in the container) are also part of the architecture.
- Testing & Validation: The “t” and “example” directories house test cases and example results—important for ensuring proper execution on sample data.
- Environment and Configuration Components: Dockerfile, Singularity instructions, and configuration scripts (as seen by the existence of “cpanfile”, “scripts/cfg” etc.) indicate environment setup and dependency management.

##### Relationships and Data Flow
- Inputs: Genome file (FASTA) and protein sequences serve as the input.
- The main pipeline script (galba.pl) first calls protein alignment module (using the chosen aligner). Results are converted into “hints” (GFF or similar), then these hints feed into the training module (where training genes are selected and used to parameterize AUGUSTUS).
- AUGUSTUS is then run (both in prediction-with-hints mode and optionally in ab initio mode). Output files (GTF, GFF3, FASTA coding sequences, protein sequences) are produced.
- Optional post-processing modules (DIAMOND filtering, TSEBRA, and hub creation with MakeHub) operate on these outputs.
- Multiple external dependencies (Miniprot, DIAMOND, AUGUSTUS, TSEBRA, Pygustus, etc.) are called as separate programs via command-line from within one or more scripts.
- The Docker/Singularity containerization ensures that many of these components are preconfigured and that the environment (e.g., paths to executables, writable configuration directories) is maintained.

##### Architectural Patterns and Design Principles
- Modular Structure: The separation into distinct scripting components (each handling a specific task) suggests a modular, “pipeline-style” architecture.
- Dependency Injection & Configuration: The project relies extensively on environment variables (e.g., AUGUSTUS_CONFIG_PATH, MINIPROT_PATH, DIAMOND_PATH) and command-line options to dynamically assign paths and parameters.
- Containerization: Dockerfile and Singularity instructions encapsulate the runtime environment.
- Logging/Testing: The “t” directory and example test scripts ensure the robust testing and validation of each module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Data
    subgraph "Input Data"
        INPUT_G["Genome FASTA"]:::input
        INPUT_P["Protein FASTA"]:::input
    end

    %% Core Pipeline
    subgraph "GALBA Pipeline"
        GALBA["GALBA Main Controller (galba.pl)"]:::custom
        ALIGN["Protein Alignment Module"]:::custom
        ALIGN1["startAlign.pl"]:::custom
        ALIGN2["aln2hints.pl"]:::custom
        TRAIN["Training & Prediction Module (AUGUSTUS)"]:::custom
        TRAIN_SCRIPT["galba_cleanup.py"]:::python
        FILTER["Filtering & Post-Processing Module"]:::custom
        FILTER1["filterIntronsFindStrand.pl"]:::custom
        FILTER2["filterIntronsFindStrand.py"]:::python
        FILTER3["filter_gtf_by_diamond_against_ref.py"]:::python
        FILTER4["filter_single_exon_predictions_by_evidence.py"]:::python
        FILTER5["gtf_sanity_check.py"]:::python
    end

    %% Testing & Validation
    subgraph "Testing & Validation"
        TEST_EX["example"]:::data
        TEST_T["t"]:::data
    end

    %% Environment & Configuration
    subgraph "Environment & Configuration"
        DOCKER["Dockerfile"]:::config
        CPAN["cpanfile"]:::config
        CFG["galba.cfg"]:::config
    end

    %% Data Flow Connections
    INPUT_G --> GALBA
    INPUT_P --> GALBA

    GALBA --> ALIGN
    ALIGN --> ALIGN1
    ALIGN --> ALIGN2

    GALBA --> TRAIN
    TRAIN --> TRAIN_SCRIPT

    TRAIN --> FILTER
    FILTER --> FILTER1
    FILTER --> FILTER2
    FILTER --> FILTER3
    FILTER --> FILTER4
    FILTER --> FILTER5

    GALBA --> TEST_EX
    GALBA --> TEST_T

    DOCKER --- GALBA
    CPAN --- GALBA
    CFG --- GALBA

    DOCKER --- ALIGN
    CPAN --- ALIGN
    CFG --- ALIGN

    DOCKER --- TRAIN
    CPAN --- TRAIN
    CFG --- TRAIN

    DOCKER --- FILTER
    CPAN --- FILTER
    CFG --- FILTER

    %% Click Events
    click GALBA "https://github.com/gaius-augustus/galba/blob/main/scripts/galba.pl"
    click ALIGN1 "https://github.com/gaius-augustus/galba/blob/main/scripts/startAlign.pl"
    click ALIGN2 "https://github.com/gaius-augustus/galba/blob/main/scripts/aln2hints.pl"
    click TRAIN_SCRIPT "https://github.com/gaius-augustus/galba/blob/main/scripts/galba_cleanup.py"
    click FILTER1 "https://github.com/gaius-augustus/galba/blob/main/scripts/filterIntronsFindStrand.pl"
    click FILTER2 "https://github.com/gaius-augustus/galba/blob/main/scripts/filterIntronsFindStrand.py"
    click FILTER3 "https://github.com/gaius-augustus/galba/blob/main/scripts/filter_gtf_by_diamond_against_ref.py"
    click FILTER4 "https://github.com/gaius-augustus/galba/blob/main/scripts/filter_single_exon_predictions_by_evidence.py"
    click FILTER5 "https://github.com/gaius-augustus/galba/blob/main/scripts/gtf_sanity_check.py"
    click TEST_EX "https://github.com/gaius-augustus/galba/tree/main/example"
    click TEST_T "https://github.com/gaius-augustus/galba/tree/main/t"
    click DOCKER "https://github.com/gaius-augustus/galba/tree/main/Dockerfile"
    click CPAN "https://github.com/gaius-augustus/galba/tree/main/cpanfile"
    click CFG "https://github.com/gaius-augustus/galba/blob/main/scripts/cfg/galba.cfg"

    %% Styles
    classDef custom fill:#ffe6e6,stroke:#b30000,stroke-width:2px;
    classDef python fill:#e6f2ff,stroke:#0059b3,stroke-width:2px;
    classDef config fill:#e6ffe6,stroke:#008000,stroke-width:2px;
    classDef input fill:#fff0f5,stroke:#d147a3,stroke-width:2px;
    classDef data fill:#f0fff0,stroke:#008080,stroke-width:2px;
```
