# pawelqs/cevomod architecture

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

- Interactive diagram: https://gitdiagram.com/pawelqs/cevomod
- Repository: https://github.com/pawelqs/cevomod

## Overview

##### Project Type and Purpose
- Project type: An R package (library) for modeling cancer evolution from NGS data.
- Purpose: Implement and expose statistical methods (power-law + binomial mixtures) for Variant Allele Frequency (VAF) analysis, provide helper data-wrangling, plotting, and two Shiny applications for interactive exploration.

##### File Structure
- Top-level:
– R/ : All core R functions (model fitting, data transformations, plotting, wrappers).
– man/ : Rd documentation for every exported function.
– data-raw/ → data/ : Raw sources (Excel, R scripts) that generate internal datasets (sysdata.rda, driver_genes.rda, etc.).
– inst/ : Shiny applications (cevoapp/app.R and cevobrowser/app.R) and a container definition (CliP.def).
– tests/ : Automated test suite (testthat) including snapshots of plots.
– vignettes/ : R Markdown tutorials (“Get started,” “Fitting models,” “Visualizations”).
– pkgdown/ + _pkgdown.yml : Website generation assets.
– .github/workflows : CI pipelines (R-CMD-check, pkgdown deploy, test coverage).
– DESCRIPTION, NAMESPACE, Makefile : Standard R package metadata and build scripts.

##### Extract Key Insights from README
- Core modeling workflow:
a. Input VAF or CCF data (possibly via readthis integration).
b. Fit power-law component(s) (fixed or optimized exponent).
c. Fit binomial mixture subclones (methods: mclust, BMix, CliP via Apptainer).
d. Provide plotting and summary functions.
- External dependencies/services:
– mclust R package (Gaussian mixtures)
– BMix R package (binomial mixtures)
– Apptainer container runtime for CliP
– pkgdown and GitHub Actions for site build & CI.

##### Main Components & Their Relationships
A. Core Modeling Engine (R/)
- Data input & validation → statistical fit functions → result objects (“cevomod” S3 classes).
B. Internal Data Pipeline
- data-raw/ scripts + Excel sources → sysdata.rda → data/ (packaged data).
C. Extension Points
- readthis integration (bulk data import)
- build_clip_container() → builds Apptainer image for CliP
D. Presentation Layers
- Plotting functions (R/plot_*.R) → static plots in R console & vignettes.
- Shiny apps (inst/cevoapp & inst/cevobrowser) → interactive exploration GUIs.
- pkgdown site (vignettes + function reference).
E. Quality & Deployment
- tests/ → unit & snapshot tests (testthat) → ensure correctness of core & plots.
- .github/workflows → on-push CI, coverage reports, pkgdown deploy.
- Makefile → local build/test/dev commands.

##### Architectural Patterns & Design Principles
- Modular single-package design (clear separation: data ingestion, computation, plotting, UI).
- S3 classes + generic methods (plot.cevomod, print.cevodata).
- CI/CD pipeline enforcing test coverage and documentation deployment.
- Data-raw → data → inst (container def) → pkg → pkgdown → GitHub Pages (fully automated).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        DS1["driver_genes.xlsx"]:::data
        DS2["variant_classification.xlsx"]:::data
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        DP1["data-raw/ scripts"]:::data
        DP2["data/ (sysdata.rda, etc.)"]:::data
    end

    %% Core Engine
    subgraph "Core Modeling Engine"
        direction TB
        CE["R/"]:::computation
        RI["readthis integration"]:::computation
        CIc["build_clip_container()"]:::computation
    end

    %% Presentation Layer
    subgraph "Presentation"
        direction TB
        P1["Plotting functions (R/plot_*.R)"]:::ui
        V1["get_started.Rmd"]:::ui
        V2["fitting_models.Rmd"]:::ui
        V3["visualizations.Rmd"]:::ui
        PK["pkgdown/ + _pkgdown.yml"]:::ui
    end

    %% Shiny Apps
    subgraph "Shiny Apps"
        direction TB
        SA1["cevoapp"]:::ui
        SA2["cevobrowser"]:::ui
    end

    %% Testing Suite
    subgraph "Automated Testing"
        direction TB
        T1["tests/testthat/"]:::ci
        T2["tests/testthat/_snaps/"]:::ci
    end

    %% CI/CD & External Services
    subgraph "CI/CD & External Services"
        direction TB
        CI1["R-CMD-check.yaml"]:::ci
        CI2["test-coverage.yaml"]:::ci
        CI3["pkgdown.yaml"]:::ci
        MF["Makefile"]:::ci
        EX1["mclust"]:::ext
        EX2["BMix"]:::ext
        EX3["Apptainer (CliP)"]:::ext
    end

    %% Connections
    DS1 -->|"raw data"| DP1
    DS2 -->|"raw data"| DP1
    DP1 -->|"generate sysdata"| DP2
    DP2 -->|"load data"| CE
    CE -->|"call readthis"| RI
    CE -->|"invoke container build"| CIc
    EX1 -->|"Gaussian mixtures"| CE
    EX2 -->|"Binomial mixtures"| CE
    EX3 -->|"CliP support"| CE
    CE -->|"fit & return objects"| P1
    CE -->|"provide vignettes data"| V1
    CE -->|"provide vignettes data"| V2
    CE -->|"provide vignettes data"| V3
    P1 -->|"plots in docs"| PK
    V1 -->|"render site"| PK
    V2 -->|"render site"| PK
    V3 -->|"render site"| PK
    CE -->|"launch app"| SA1
    CE -->|"launch app"| SA2
    CE -->|"unit & snapshot tests"| T1
    CE -->|"unit & snapshot tests"| T2
    T1 -->|"test results"| CI1
    T2 -->|"snapshots"| CI1
    CI1 -->|"coverage report"| CI2
    CI2 -->|"deploy docs"| CI3
    CI3 -->|"update site"| PK
    MF -->|"build/test commands"| CI1

    %% Click Events
    click DS1 "https://github.com/pawelqs/cevomod/blob/master/data-raw/driver_genes.xlsx"
    click DS2 "https://github.com/pawelqs/cevomod/blob/master/data-raw/variant_classification.xlsx"
    click DP1 "https://github.com/pawelqs/cevomod/tree/master/data-raw/"
    click DP2 "https://github.com/pawelqs/cevomod/tree/master/data/"
    click CE "https://github.com/pawelqs/cevomod/tree/master/R/"
    click RI "https://github.com/pawelqs/cevomod/blob/master/R/cevodata-readthis_integration.R"
    click CIc "https://github.com/pawelqs/cevomod/blob/master/man/build_clip_container.Rd"
    click SA1 "https://github.com/pawelqs/cevomod/blob/master/inst/cevoapp/app.R"
    click SA2 "https://github.com/pawelqs/cevomod/blob/master/inst/cevobrowser/app.R"
    click PK "https://github.com/pawelqs/cevomod/tree/master/pkgdown/"
    click V1 "https://github.com/pawelqs/cevomod/blob/master/vignettes/get_started.Rmd"
    click V2 "https://github.com/pawelqs/cevomod/blob/master/vignettes/fitting_models.Rmd"
    click V3 "https://github.com/pawelqs/cevomod/blob/master/vignettes/visualizations.Rmd"
    click T1 "https://github.com/pawelqs/cevomod/tree/master/tests/testthat/"
    click T2 "https://github.com/pawelqs/cevomod/tree/master/tests/testthat/_snaps/"
    click CI1 "https://github.com/pawelqs/cevomod/blob/master/.github/workflows/R-CMD-check.yaml"
    click CI2 "https://github.com/pawelqs/cevomod/blob/master/.github/workflows/test-coverage.yaml"
    click CI3 "https://github.com/pawelqs/cevomod/blob/master/.github/workflows/pkgdown.yaml"
    click MF "https://github.com/pawelqs/cevomod/tree/master/Makefile"
    click EX3 "https://github.com/pawelqs/cevomod/blob/master/inst/CliP.def"

    %% Styles
    classDef data fill:lightblue,stroke:#333,stroke-width:1px
    classDef computation fill:lightgreen,stroke:#333,stroke-width:1px
    classDef ui fill:lightorange,stroke:#333,stroke-width:1px
    classDef ci fill:lightgray,stroke:#333,stroke-width:1px
    classDef ext fill:lightpink,stroke:#333,stroke-width:1px
```
