# csb5/lofreq architecture

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

- Interactive diagram: https://gitdiagram.com/csb5/lofreq
- Repository: https://github.com/csb5/lofreq

## Overview

##### Project Type and Purpose
- LoFreq is a specialized bioinformatics tool designed to perform ultra-sensitive variant calling by taking into account sequence quality.
- It is implemented in C (with some Python support for auxiliary scripts and pipelines) and is built using autotools. It relies on system dependencies like HTSlib, zlib, and third-party libraries (e.g., cdflib90 and uthash).

##### File Structure
- Top-level files such as Makefile.am, configure.ac, bootstrap, and various autotools files signal that the project uses the autotools build system.
- The “src/cdflib90” subdirectory contains code for statistical calculations, indicating that precision statistics are crucial for variant calling.
- "src/uthash" provides data structures used by the system (likely for in-memory hash tables).
- There is also a “src/scripts” directory (and additional Python tool directories under “src/tools” and “snakemake”) that complement the core C engine by providing pipelining, pre-/post-processing scripts, and auxiliary command-line tools (e.g., quality filtering, parallel variant calling, somatic analysis).
- The “snakemake” directory shows that a pipeline-oriented approach is supported, which ties together the components for reproducible NGS data analyses.
- The “tests” directory is rich with scripts for validation and performance checking, further clarifying how components need to be tested and verified.

##### Main Components
a. Build & Configuration:
- A block representing the autotools build system (bootstrap, configure, make, make install) with dependencies on the C compiler, Python 3 interpreter, zlib, and HTSlib.
- External libraries used (HTSlib, cdflib90, uthash).

b. Core Variant Calling Engine:
- Modules within “src/lofreq”:
- Input processing (BAM file handling, reference checking: e.g., bam_index, bam_md_ext, bedidx).
- Statistical modules for computing probabilities (binom, fet, multtest, etc.).
- Core variant calling routines (lofreq_call, lofreq_filter, lofreq_index, etc.).
- Supporting utilities (e.g., log, utils, viterbi) for quality scoring and data validation.

c. Auxiliary and Pipeline Components:
- Python scripts and tools in “src/scripts” and “src/tools” (including lofreq_star) that act as wrappers or specialized variant calling workflows (such as local and somatic call pipelines).
- The “snakemake” pipeline that orchestrates these components and integrates data pre-/post-processing.
- You may represent these as separate modules connected to the core engine, illustrating how they call the core executable as part of a workflow.

d. Testing & Validation:
- The “tests” directory should be represented to indicate integration and unit test components. This shows quality assurance practices integrated into the architecture.

##### Architectural Patterns and Relationships
- A modular design: the core engine is built as independent modules (each function implemented across different C source files) that interact with each other through well-defined function calls.
- Layered dependencies: at the lowest level are external libraries (HTSlib, cdflib90, uthash), above which sits the variant calling logic, and at the top are the pipeline and user interface scripts.

- A central “Variant Calling Engine” split into:
- Input/Parsing Modules (BAM processing, reference checks),
- Statistical Modules (binom, fet, multiple testing),
- Core Calling Algorithms (lofreq_call, lofreq_filter, viterbi),
- Utility Modules (logging, quality scoring).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Environment
    subgraph "Build Environment"
        BuildConfig["Build & Configuration"]:::build
    end

    %% Core Processing
    subgraph "Core Processing"
        VariantEngine["Variant Calling Engine"]:::core
        subgraph "Variant Engine Modules"
            InputProc["Input/Parsing Modules"]:::core
            StatModules["Statistical Modules"]:::core
            CoreCall["Core Calling Algorithms"]:::core
            Utility["Utility Modules"]:::core
        end
        Output["Variant Calls (VCF)"]:::core
    end

    %% Workflow & Auxiliary Tools
    subgraph "Workflow & Auxiliary Tools"
        PythonScripts["Python Scripts & Tools"]:::pipeline
        LofreqStar["lofreq_star Tool"]:::pipeline
        PipelineOrch["Snakemake Pipeline"]:::pipeline
    end

    %% External Libraries
    subgraph "External Libraries"
        HTSlib["HTSlib"]:::external
        Zlib["zlib"]:::external
        Uthash["Data Structures (uthash)"]:::external
        StatLib["Statistical Library (cdflib90)"]:::external
    end

    %% Testing & Validation
    subgraph "Testing & Validation"
        Testing["Testing & Validation"]:::testing
    end

    %% Connections
    BuildConfig -->|"build"| VariantEngine

    InputProc -->|"processes"| CoreCall
    StatModules -->|"supports"| CoreCall
    Utility -->|"aids"| CoreCall
    CoreCall -->|"produces"| Output

    StatLib -->|"feeds"| StatModules

    HTSlib -->|"supports"| VariantEngine
    Zlib -->|"supports"| VariantEngine
    Uthash -->|"supports"| VariantEngine

    PythonScripts -->|"orchestrates"| VariantEngine
    LofreqStar -->|"integrates"| PythonScripts
    PipelineOrch -->|"orchestrates"| VariantEngine

    VariantEngine -->|"validated by"| Testing

    %% Click Events
    click BuildConfig "https://github.com/csb5/lofreq/tree/master/bootstrap"
    click VariantEngine "https://github.com/csb5/lofreq/tree/master/src/lofreq"
    click StatModules "https://github.com/csb5/lofreq/tree/master/src/lofreq"
    click Uthash "https://github.com/csb5/lofreq/tree/master/src/uthash"
    click PythonScripts "https://github.com/csb5/lofreq/tree/master/src/scripts"
    click LofreqStar "https://github.com/csb5/lofreq/tree/master/src/tools/lofreq_star"
    click PipelineOrch "https://github.com/csb5/lofreq/tree/master/snakemake"
    click Testing "https://github.com/csb5/lofreq/tree/master/tests"

    %% Styles
    classDef build fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#FFECB3,stroke:#FBC02D,stroke-width:2px;
    classDef pipeline fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef testing fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
```
