# brentp/bwa-meth architecture

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

- Interactive diagram: https://gitdiagram.com/brentp/bwa-meth
- Repository: https://github.com/brentp/bwa-meth

## Overview

This project is a command-line tool designed specifically for aligning bisulfite sequencing (BS-Seq) reads. Its purpose is to wrap and streamline the operation of existing aligners (BWA-MEM or BWA-MEM2) by converting reads in silico (changing C→T) and then “piping” them to the underlying aligner. The provided directory structure and README indicate that, in addition to the core alignment functionality (bwameth.py), the repository contains additional directories for benchmarking (compare), usage examples (example), visualization and documentation (paper), and auxiliary scripts (scripts).

##### Main Components
- Core Alignment Module: Represented by the bwameth.py script which serves as the primary entry point for running the alignment.
- In-Silico Conversion Process: The module/process where C’s are converted to T’s in both reference and reads before alignment.
- External Alignment Engines: BWA-MEM and BWA-MEM2 are the engines that perform the actual sequence alignment.
- Data Input/Output: FASTQ files for sequencing reads as input, reference FASTA for the genome, and SAM/BAM output files.
- Dependency and Environment: External tools such as samtools (for SAM/BAM conversion), python dependencies (toolshed), and shell scripts.
- Supporting Scripts & Benchmarks: The compare directory contains benchmarking scripts and data to compare performance with other aligners. The example directory provides sample datasets and minimal usage examples.
- Documentation & Publication: The paper directory contains LaTeX files and figures for academic publication, indicating broader documentation and evaluation.

##### Relationships and Interactions
- A Documentation component (paper directory) which, while not directly part of the runtime, plays an important role in communicating the design and results.

##### Important Architectural Patterns or Design Principles
- Streaming Data Pipeline: Emphasize that the conversion output is piped directly to the external aligner without intermediate file writes.
- Modularity: The project is segregated into clearly defined directories (core tool, example usage, benchmarking, publication) to maintain separation of concerns.
- Extensibility: The use of shell scripts in the compare folder and additional scripts (in scripts/) for post-alignment processing (like methylation tabulation) shows an extensible and modular design.

##### Emphasizing Detail
- Examples or callouts from subdirectories (e.g., use a note that “compare” contains benchmarking scripts that test different alignment parameters).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input Subgraph
    subgraph "Data Input"
        A1("Reference FASTA"):::dataInput
        A2("FASTQ Read R1"):::dataInput
        A3("FASTQ Read R2"):::dataInput
    end

    %% Core Pipeline
    A1 --> B
    A2 --> B
    A3 --> B
    B("Alignment Controller (bwameth.py)\n(In-silico Conversion & PIPE to External Aligner)"):::core
    B --> C
    C("External Aligner (BWA-MEM/BWA-MEM2)"):::external
    C --> D
    D("Output: SAM"):::output
    D --> E
    E("SAM->BAM Conversion (samtools)"):::output

    %% Environment & Dependencies Subgraph
    subgraph "Environment & Dependencies"
        F1("requirements.txt"):::dependency
        F2("ez_setup.py"):::dependency
        F3("setup.py"):::dependency
    end
    F1 --> B
    F2 --> B
    F3 --> B

    %% Benchmarking & Auxiliary Subgraph
    subgraph "Benchmarking & Auxiliary"
        G1("compare directory"):::support
        G2("compare/run-bis1.sh"):::support
        G3("compare/run-bwa.sh"):::support
        S1("scripts/tabulate-methylation.py"):::support
        S2("scripts/bsseq-caller.R"):::support
        P1("Documentation (paper)"):::support
    end
    %% Dotted arrows representing interaction or support relationship
    B -.-> S1
    B -.-> S2
    G1 -.-> E
    G2 -.-> E
    G3 -.-> E

    %% Styles
    classDef core fill:#f9d57a,stroke:#b37a00,stroke-width:2px;
    classDef dataInput fill:#a8d0e6,stroke:#368bc1,stroke-width:2px;
    classDef external fill:#c1e1c1,stroke:#2d6a2d,stroke-width:2px;
    classDef output fill:#e3d4ff,stroke:#7a5caa,stroke-width:2px;
    classDef dependency fill:#f4cccc,stroke:#d04437,stroke-width:2px;
    classDef support fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;

    %% Click Events
    click B "https://github.com/brentp/bwa-meth/blob/master/bwameth.py"
    click A1 "https://github.com/brentp/bwa-meth/blob/master/example/ref.fa"
    click A2 "https://github.com/brentp/bwa-meth/blob/master/example/t_R1.fastq.gz"
    click A3 "https://github.com/brentp/bwa-meth/blob/master/example/t_R2.fastq.gz"
    click F1 "https://github.com/brentp/bwa-meth/blob/master/requirements.txt"
    click F2 "https://github.com/brentp/bwa-meth/blob/master/ez_setup.py"
    click F3 "https://github.com/brentp/bwa-meth/blob/master/setup.py"
    click G1 "https://github.com/brentp/bwa-meth/tree/master/compare"
    click G2 "https://github.com/brentp/bwa-meth/blob/master/compare/run-bis1.sh"
    click G3 "https://github.com/brentp/bwa-meth/blob/master/compare/run-bwa.sh"
    click S1 "https://github.com/brentp/bwa-meth/blob/master/scripts/tabulate-methylation.py"
    click S2 "https://github.com/brentp/bwa-meth/blob/master/scripts/bsseq-caller.R"
    click P1 "https://github.com/brentp/bwa-meth/tree/master/paper"
```
