How cbg-ethz/viloca works
• User Input & CLI Interface:
– Represent the command‐line interface, which is defined in the “viloca” directory (modules like cli.py, __main__.py, and specialized modules such as b2w.py, pooled_post.py, pooled_pre.py, shorah_snv.py, shotgun.py, and tiling.py).
– This layer is responsible for parsing user arguments (BAM/CRAM alignments, FASTA reference, optional primer insert file, window sizes) and dispatching commands.
• Core Analytical Modules:
• Error Parameter Learning Pipeline: Corresponds to functionality in the submodules under “viloca/local_haplotype_inference/learn_error_params” (modules like cavi.py, elbo_eqs.py, initialization.py, etc.).
• Quality Scores Pipeline: Found under “viloca/local_haplotype_inference/use_quality_scores” carrying similar processing stages but incorporating quality scores.
– Also include “shorah_snv.py” for integration with the external ShoRAH tool, as mentioned in the README.
• C++ Core Library:
– Represent the core backend computation implemented in C/C++ (found under lib/include and lib/src). Components here (like b2w.cpp, dpm_sampler.cpp, fil.cpp) provide heavy-lifting functionality.
– Highlight the “bindings.cpp” file in lib/src that suggests a bridge layer connecting the C++ routines with Python.
• Data I/O and External Artifacts:
– Show the input files (alignment file, reference FASTA, and optional insert/primer bed file) entering the system.
• Build & Deployment Tools:
– Include the CMake system (CMakeLists.txt and cmake/ scripts) and Docker infrastructure (Dockerfile, GitHub workflows) that enable building, testing, and containerized deployment.
• Testing and CI:
– Represent the tests directory (with the multiple test files and data sets under tests/) that verifies each module and integration aspect.
– Note that GitHub Actions (e.g., .github/workflows/tests.yaml) and Docker setups support continuous integration.
Relationships & Data Flow
• Start from the user’s command, where the CLI (viloca/__main__.py and cli.py) handles input parsing.
• Based on detected mode (passed via --mode option), the CLI directs the process into one of the two pipelines (learn_error_params or use_quality_scores), or possibly calls the ShoRAH module.
• Each pipeline then interacts with the backend:
– They call computational routines in the C++ library either directly (or via Python bindings provided through lib/src/bindings.cpp) to perform tasks like error correction, haplotype reconstruction, and mutation analysis.
• After processing, output data are generated and saved in the expected directories.
– Data flowing from user inputs to CLI.
– Mode dispatching from the CLI to the corresponding analysis pipeline.
– Interactions between Python modules and the C++ library.
– Data flow from processing to output files.
– Dependency flows from build configurations (CMake, Docker) to the final runtime environment.
Architectural Patterns & Technologies
• Modular Separation:
– Clearly show the decoupling between the user interface (Python scripts), computational back-end (C++ library), and mode-specific pipelines.
• Integration via Bindings:
– Illustrate how the Python modules “call into” the C++ library (possibly via shared bindings) to enhance performance.
• Use of CI/CD & Containerization:
– Optionally display how Docker, CMake, and GitHub workflows integrate into the overall development pipeline.
• External Dependencies and Tools:
– Display conda environments and pip installations as part of the deployment preparation.
– Note the integration with ShoRAH (via Python module “shorah_snv.py”) and how that fits into the pipeline.