# boyle-lab/blacklist architecture

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

- Interactive diagram: https://gitdiagram.com/boyle-lab/blacklist
- Repository: https://github.com/boyle-lab/blacklist

## Overview

##### Main Components
- Blacklist Engine: The core executable (compiled from sources like blacklist.cpp) that processes input data. This is the principal processing component.
- Input Data Modules:
– The “input” directory contains sorted and indexed BAM files (and corresponding .bai index files) representing the experimental data tracks.
– The “mappability” folder holds gapless Umap files (uint8 files) necessary to assess alignment uniqueness.
- External Dependency – Bamtools Library: Incorporated via the submodule and compiled within the bamtools folder. This library is used for interacting with BAM files.
- Data Resources: The “lists” folder holds pre-existing blacklists and metadata for various genomes (e.g., hg19, hg38, mm10, etc.), which might act as either reference data or for historical context.
- Demo/Testing Environment: The demo folder with sample files (e.g., a demo input BAM file for an unmapped chromosome) is used both for quick testing and illustrating expected functionality.

##### Relationships and Interactions
- The Blacklist Engine is run with a specific chromosome/contig argument (e.g., “chr1” or the demo “chrUn_GL456392”). It expects:
- Input: It reads BAM data from the “input” directory.
- Mappability: It uses corresponding Umap files from the “mappability” directory to calibrate or contextualize the analysis.
- Bamtools provides the necessary functionality for parsing and processing the BAM files.
- After processing, the engine outputs a BED-style file that annotates problematic, high-signal regions.
- The prebuilt blacklists in the “lists” folder serve as a reference or historical context for what regions are problematic across different genome builds.

##### Architectural Patterns and Design Principles
- Modular Structure: The system employs a modular approach where input, processing, and output are clearly separated via distinct directories.
- Command-Line Interface: The flow is centered around a single executable that takes command-line arguments (chromosome/contig names) and produces output.
- Dependency Injection: The reliance on an external bamtools API suggests that I/O and parsing are abstracted through a dedicated library.
- Directory-based Configuration: The application depends on a specific directory layout (with “input” and “mappability” folders positioned relative to the executable) to function correctly.

##### Relevant Technologies and Frameworks
- C++ as the primary language.
- Bamtools API for interacting with BAM files.
- Standard command-line compilation (Makefile-driven build process).
- External genomic file formats such as BAM, BAI, BED, and compressed BED formats.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources & Resources"
        A1["Input Data Module (BAM Files)"]:::data
        A2["Mappability Files"]:::data
        A3["Precompiled Blacklists & Metadata"]:::data
    end

    subgraph "Processing Core"
        B1["Blacklist Engine (Executable)"]:::process
        B2["External Dependency - Bamtools Library"]:::external
    end

    subgraph "Demo/Testing Environment"
        C1["Demo Executable - Blacklist"]:::demo
    end

    A1 -->|"readsBAM"| B1
    A2 -->|"readsUmap"| B1
    B2 -->|"parsesBAM"| B1
    B1 -->|"outputsBED"| A3
    B1 -->|"demoRun"| C1

    click B1 "https://github.com/boyle-lab/blacklist/blob/master/blacklist.cpp"
    click A1 "https://github.com/boyle-lab/blacklist/tree/master/demo/input"
    click A2 "https://github.com/boyle-lab/blacklist/tree/master/demo/mappability"
    click B2 "https://github.com/boyle-lab/blacklist/tree/master/bamtools"
    click A3 "https://github.com/boyle-lab/blacklist/tree/master/lists"
    click C1 "https://github.com/boyle-lab/blacklist/tree/master/demo/Blacklist"

    classDef data fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef process fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef demo fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
