# cbg-ethz/viloca architecture

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

- Interactive diagram: https://gitdiagram.com/cbg-ethz/viloca
- Repository: https://github.com/cbg-ethz/viloca

## Overview

- 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.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Input & CLI"
        Input["Raw Input Files (BAM/CRAM, FASTA, Primer BED)"]:::data
        CLI["CLI Entry Point (viloca/cli.py, __main__.py)"]:::cli
    end

    subgraph "Processing Pipelines"
        ErrorLPipeline["Error Parameter Pipeline (viloca/local_haplotype_inference/learn_error_params)"]:::pipeline
        QSPipeline["Quality Scores Pipeline (viloca/local_haplotype_inference/use_quality_scores)"]:::pipeline
        ShoRAH["ShoRAH Integration (viloca/shorah_snv.py)"]:::pipeline
    end

    subgraph "Backend Computation"
        CPPLib["C++ Core Library (lib, bindings: lib/src/bindings.cpp)"]:::cpplib
    end

    subgraph "Output Generation"
        Output["Output Artifacts (haplotypes, coverage.txt, cooccurring_mutations.csv)"]:::data
    end

    subgraph "Development & Deployment"
        BuildTools["Build & Deployment Tools (CMakeLists.txt, cmake/, Dockerfile)"]:::build
        TestCI["Testing & CI (tests/, .github/workflows/tests.yaml)"]:::test
    end

    %% Data flow connections
    Input --> CLI
    CLI -->|"mode_selection"| ErrorLPipeline
    CLI -->|"mode_selection"| QSPipeline
    CLI -->|"calls"| ShoRAH

    ErrorLPipeline --> CPPLib
    QSPipeline --> CPPLib
    ShoRAH --> CPPLib

    CPPLib --> Output

    %% Supporting development tools connections
    CLI --- BuildTools
    CLI --- TestCI

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef pipeline fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef cpplib fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef data fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef build fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef test fill:#F0E68C,stroke:#000,stroke-width:2px;

click CLI "https://github.com/cbg-ethz/viloca/blob/master/viloca/cli.py"
click ErrorLPipeline "https://github.com/cbg-ethz/viloca/tree/master/viloca/local_haplotype_inference/learn_error_params"
click QSPipeline "https://github.com/cbg-ethz/viloca/tree/master/viloca/local_haplotype_inference/use_quality_scores"
click ShoRAH "https://github.com/cbg-ethz/viloca/blob/master/viloca/shorah_snv.py"
click CPPLib "https://github.com/cbg-ethz/viloca/tree/master/lib"
click BuildTools "https://github.com/cbg-ethz/viloca/blob/master/CMakeLists.txt"
click TestCI "https://github.com/cbg-ethz/viloca/tree/master/tests/"
```
