How twolinin/longphase works
Main components
• User/CLI Interface – this is where users interact with the tool via different subcommands (phase, haplotag, modcall).
• Command Argument Parser and Main Entry (main.cpp) – routing inputs to the correct module based on user parameters.
• Core Modules:
– Phasing Module: Contains files like Phasing.cpp, PhasingGraph.cpp, and PhasingProcess.cpp. This component handles building the variant graph, applying phasing algorithms, and processing SNPs, indels, and SVs.
– Haplotag Module: Implemented in files such as Haplotag.cpp and HaplotagProcess.cpp. It assigns haplotype tags to reads in BAM files and coordinates with phased VCF outputs.
– ModCall Module: With ModCall.cpp and ModCallProcess.cpp. It extracts allele-specific modifications from the BAM (using MM/ML tags) and outputs modification VCFs.
– Utility Components: Util.cpp provides common utility functions that support all modules.
• External Library Interface:
– htslib integration: The project includes an entire subdirectory of htslib. This library is used for reading/writing BAM, VCF, and FASTA files, and for other I/O operations.
– jemalloc dependency: Included as a subdirectory; used to optimize dynamic memory allocation.
• Build and Configuration Layer:
– Autotools (configure.ac, config.mk.in) and Makefile support.
– Dockerfile for containerization.
Relationships and interactions
• The user issues a command via the CLI → the main executable (from main.cpp) uses a command-line parser to determine which subcommand to run.
• Depending on the subcommand (phase, haplotag, modcall), control flows to the corresponding module.
– In the Phase module, inputs include VCF (SNP/indels/SV/modification), FASTA (reference genome), and one or more BAM files. These are processed by a pipeline that:
– Reads data via htslib routines,
– Constructs a phasing graph (using PhasingGraph.cpp),
– Applies edge weight adjustments based on base quality (parameters set in Phasing.cpp), and finally
– Writes out phased VCFs.
– In the Haplotag module, the phased VCF output (from phase) and BAM files are re-read (again via htslib) to assign haplotype tags to each read.
– The ModCall module receives BAM input with modification tags and uses similar parsing routines to output a VCF representing allele-specific modifications.
• The utility functions (from Util.cpp) are shared across modules to support logging, error handling, and data conversions.
Architectural patterns and design principles
• Modular design: Each functional command (phase, haplotag, modcall) is implemented as a separate module with its own processing pipeline. This separation allows for maintainability and independent improvements.
• Layered architecture: The system separates the data input/IO (handled via htslib), the processing/algorithm layers (phasing graph construction, haplotagging, modification calling), and the output (VCF/BAM file generation).
• Integration of external dependencies: The design clearly encapsulates the htslib library (and also jemalloc) as external components that provide essential low-level functionality.
• Command-line driven and parameterizable: The design is highly configurable via command-line options (as shown in the README) which drives modules’ behavior.
Additional notes
• Given the project’s pipeline nature, illustrate the sequential flow from data ingestion (reading BAM, VCF, FASTA) through algorithmic processing and then output generation.