# cbg-ethz/covvfit architecture

> Architecture diagram of the GitHub repository cbg-ethz/covvfit, 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/covvfit
- Repository: https://github.com/cbg-ethz/covvfit

## Overview

##### Project and Its Purpose
- covvfit is a scientific tool that processes variant abundance data (for instance, from wastewater sequencing) and computes fitness estimates of SARS‐CoV‐2 variants.
- It is distributed via PyPI and has a strong emphasis on reproducible computation, simulation, and visualization.
- The README includes installation instructions and a reference to a tutorial on using the CLI, which indicates that the primary interface is command-line driven.

##### File Structure
- Top-Level Directories:
– src: Contains the source code for covvfit. The layout shows modules for CLI (_cli), core computations (_deconvolution, _dynamics, _numeric, _quasimultinomial, etc.), simulations (simulation), and plotting (plotting).
– docs: Contains API and developer documentation, examples of usage (including running deconvolution), and static assets like images.
– examples: Demonstrates sample scripts that show different analysis or visualization scenarios.
– tests: Holds unit tests for core modules and simulation components.
– workflows: Houses Snakemake workflows to run complete pipelines for various processes (e.g., simulation bootstrap, evaluation, comparative clinical workflows).
– configuration files (.github workflows, environment.yml, etc.) ensure continuous integration and reproducibility.

##### Main Components of the System
a. Command-Line Interface (CLI):
– Located within src/covvfit/_cli and the main CLI entry-point (src/covvfit/cli.py).
– Responsible for handling user inputs, command parsing, and directing the flow to the appropriate processing modules.

b. Core Computational Modules:
– Deconvolution Module (_deconvolution): Processes raw variant abundance data to infer fitness estimates.
– Dynamics and Numeric Modules (_dynamics and _numeric): Handle the mathematical/statistical computations and underlying time-series / dynamic modeling.
– Supporting Modules for Data Preparations: _preprocess_abundances, _splines, _padding, _quasimultinomial, and _random — which assist in data preprocessing and performing specialized numerical tasks.

c. Simulation Module:
– Located in src/covvfit/simulation with submodules for _logistic and _sde.
– Simulates variant dynamics, likely to validate models or forecast evolutionary trends.

d. Plotting/Visualization Module:
– Found in src/covvfit/plotting with distinct submodules (_grid, _simplex, _timeseries) focusing on visual representations of data and simulation output.

e. External and Integration Components:
– Workflows (in workflows/ and .github/workflows): Automated pipelines for running large-scale simulations, evaluation of predictions, and CI integration.
– Data and Examples: Real data samples and example analyses that facilitate understanding how the components interact.

##### Relationships and Data Flow
- The user invokes the CLI with specific commands or scripts:
– CLI reads configurations (potentially using config-demo.yaml in the data directory or workflow-specific YAML).
– It orchestrates data pre-processing (via _preprocess_abundances) that feeds into the deconvolution and dynamics modules.
- Simulations (via the simulation module) can run in parallel or as part of a validation workflow, with outputs that might be fed back into the core modules or visualized.
- Automated tests ensure correctness by validating interactions between these components.
- External workflows (Snakemake scripts) bundle these operations into repeatable pipelines for both research and production environments.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each functionality (CLI, processing, simulation, plotting) is encapsulated in its own module, promoting separation of concerns.
- Pipeline/Workflow Integration: The presence of Snakemake workflows and CI scripts underscores a reproducible and scalable pipeline design.
- Extensibility: The clear separation of core numerical methods, simulations, and data visualization makes it easier to add new features or update existing ones.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["Command-Line Interface (CLI)"]
    end

    %% Core Computation Layer
    subgraph "Core Computation"
        DP["Data Preprocessing (_preprocess_abundances)"]
        DEC["Deconvolution Engine (_deconvolution)"]
        DYN["Dynamics (_dynamics)"]
        NUM["Numeric Processing (_numeric)"]
        
        %% Supporting Algorithms within Core Computation
        subgraph "Supporting Algorithms"
            SPL["Splines (_splines)"]
            PAD["Padding (_padding)"]
            QMN["Quasimultinomial (_quasimultinomial)"]
            RAND["Random (_random)"]
        end
    end

    %% Simulation Module
    subgraph "Simulation Module"
        LOG["Logistic Simulation (_logistic)"]
        SDE["SDE Simulation (_sde)"]
    end

    %% Plotting/Visualization Layer
    subgraph "Plotting/Visualization"
        GRID["Grid Plot (_grid)"]
        SIMP["Simplex Plot (_simplex)"]
        TS["Time Series Plot (_timeseries)"]
    end

    %% Integration & Workflows
    subgraph "Integration & Workflows"
        WF["Workflows"]
        TEST["CI/CD & Testing"]
    end

    %% Data Flow Relationships
    CLI -->|"triggers"| DP
    CLI -->|"triggers"| DEC
    CLI -->|"triggers"| DYN
    CLI -->|"triggers"| NUM

    DP -->|"feeds"| DEC
    DP -->|"feeds"| DYN
    DP -->|"feeds"| NUM

    DEC -->|"processes"| DYN
    DEC -->|"processes"| NUM

    SPL -->|"supports"| DEC
    PAD -->|"supports"| DYN
    QMN -->|"supports"| NUM
    RAND -->|"supports"| DEC

    LOG -->|"simulated data"| DYN
    LOG -->|"simulated data"| NUM
    SDE -->|"simulated data"| DYN
    SDE -->|"simulated data"| NUM

    DEC -->|"results"| GRID
    DYN -->|"results"| TS
    NUM -->|"results"| SIMP

    %% Simulation outputs also contribute to visualization
    LOG -->|"visualizes"| GRID
    SDE -->|"visualizes"| TS

    %% Workflows orchestrate the process
    WF -->|"orchestrates"| CLI
    WF -->|"orchestrates"| DEC
    WF -->|"orchestrates"| DYN
    WF -->|"orchestrates"| NUM
    WF -->|"orchestrates"| LOG
    WF -->|"orchestrates"| SDE
    WF -->|"orchestrates"| GRID
    WF -->|"orchestrates"| TS
    TEST -->|"validates"| WF

    %% Click Events for CLI Components
    click CLI "https://github.com/cbg-ethz/covvfit/tree/main/src/covvfit/_cli"
    click CLI "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/cli.py"

    %% Click Events for Core Computation Components
    click DP "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_preprocess_abundances.py"
    click DEC "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_deconvolution.py"
    click DYN "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_dynamics.py"
    click NUM "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_numeric.py"

    %% Click Events for Supporting Numerical Algorithms
    click SPL "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_splines.py"
    click PAD "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_padding.py"
    click QMN "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_quasimultinomial.py"
    click RAND "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/_random.py"

    %% Click Events for Simulation Module
    click LOG "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/simulation/_logistic.py"
    click SDE "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/simulation/_sde.py"

    %% Click Events for Plotting/Visualization Module
    click GRID "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/plotting/_grid.py"
    click SIMP "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/plotting/_simplex.py"
    click TS "https://github.com/cbg-ethz/covvfit/blob/main/src/covvfit/plotting/_timeseries.py"

    %% Click Events for External & Workflow Integration
    click WF "https://github.com/cbg-ethz/covvfit/tree/main/workflows"
    click WF "https://github.com/cbg-ethz/covvfit/blob/main/workflows/animation.smk"
    click WF "https://github.com/cbg-ethz/covvfit/blob/main/workflows/bootstrap_simulation.smk"
    click TEST "https://github.com/cbg-ethz/covvfit/tree/main/.github/workflows"
    click TEST "https://github.com/cbg-ethz/covvfit/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef cli fill:#CFF,stroke:#333,stroke-width:2px;
    classDef core fill:#F9C,stroke:#333,stroke-width:2px;
    classDef support fill:#FF9,stroke:#333,stroke-width:2px;
    classDef sim fill:#C9F,stroke:#333,stroke-width:2px;
    classDef plot fill:#9F9,stroke:#333,stroke-width:2px;
    classDef wf fill:#FCC,stroke:#333,stroke-width:2px;

    class CLI cli;
    class DP,DEC,DYN,NUM core;
    class SPL,PAD,QMN,RAND support;
    class LOG,SDE sim;
    class GRID,SIMP,TS plot;
    class WF,TEST wf;
```
