How boyle-lab/blacklist works
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.