# rockwillck/cbn2path architecture

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

- Interactive diagram: https://gitdiagram.com/rockwillck/cbn2path
- Repository: https://github.com/rockwillck/cbn2path

## Overview

##### Project Type and Purpose
- CBN2Path is an R/Bioconductor package (open-source tool) that unifies multiple Conjunctive Bayesian Network (CBN) models—CT-CBN, H-CBN, B-CBN, R-CBN—into a single interface.
- It provides functions for data import (cross-sectional genomic patterns), model fitting (R/C code), pathway analysis, and visualization of cancer progression.

##### File Structure Analysis
Top level:
- DESCRIPTION, NAMESPACE, LICENSE*, CITATION.cff – standard R package metadata
- R/ – R functions and wrappers (user interface, model orchestration)
- src/ – core C implementations (bcbn.c, ctcbn.c, queue.c, etc.), headers, Makevars
- inst/extdata/ – example data files (patterns, posets, time data)
- inst/scripts/ – helper scripts (R and Python) for data provenance and raw data parsing/enumeration
- man/ – Rd documentation for each function
- tests/ – testthat suite verifying R-C interface and algorithm correctness
- vignettes/ – usage tutorials and example workflows
- configure / configure.ac – autoconf scripts for locating GSL library

Patterns & architectural choices:
- R/C hybrid: R functions call compiled C code (via .Call or .C)
- Data layer: inst/extdata holds static inputs; inst/scripts transforms raw sources into standardized formats
- Modularity: each CBN variant has its own C module and an R wrapper function

##### README Insights
- External dependency on GNU Scientific Library (GSL)
- Instructions for building vignettes, platform support notes
- “robust quantification, analysis, and visualization”

##### Main Components & Interactions
a. Components
1. User Interface Layer (R functions in R/):
– Model fitters (bcbn(), ctcbn(), hcbn(), rcbn())
– Helper utilities (readPattern(), readPoset(), visualizeCBNModel(), etc.)
2. Computation Engine (C code in src/):
– Core algorithms for each CBN variant
– Supporting modules: random number generation, queues, poset enumeration
3. Data Layer (inst/extdata, inst/scripts/raw_data):
– Raw data parsers (Python, R scripts) → processed R-readable files
4. External Libraries & Build Tools:
– GSL (via autoconf/configure, Makevars)
– R CMD build/install
5. Visualization & Reporting:
– ggplot2, ggraph, sysfonts (implicit via DESCRIPTION)
– Vignettes (vignettes/CBN2Path.Rmd)
6. Quality Assurance:
– tests/testthat/ (unit tests)

b. Relationships / Data Flow
1. User → R API calls
2. R wrappers (.C/.Call) → C modules
3. C modules → GSL routines for numerical computation
4. Results → R for post-processing → Visualization functions
5. Static example data read from inst/extdata or generated via inst/scripts
6. Tests invoke R API and verify C-level results

##### Architectural Patterns & Principles
- Layered architecture: clear separation of R interface, C computation, and data
- Modular CBN variants: each model isolated in its own source/h header files
- Data provenance: scripts maintain reproducibility of input generation
- Standard R package conventions: ease of installation, documentation, testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        R_bcbn["R API: bcbn()"]:::frontend
        R_ctcbn["R API: ctcbn()"]:::frontend
        R_hcbn["R API: hcbn()"]:::frontend
        R_pathway["R API: PathwayAnalysis()"]:::frontend
        R_utils["R Utils: readPattern(), readPoset()"]:::frontend
        R_visualize["R Visualize: visualizeCBNModel()"]:::frontend
    end

    %% Computation Engine
    subgraph "Computation Engine"
        C_bcbn["C Engine: bcbn.c & bcbn.h"]:::computation
        C_ctcbn["C Engine: ctcbn.c & ct-cbn.h"]:::computation
        C_init["C Engine: init.c"]:::computation
        C_queue["C Engine: queue.c & queue.h"]:::computation
        C_rand["C Engine: rand.h & bcbn_rand.h"]:::computation
        C_dt["C Engine: dt_cbn.h"]:::computation
        GSL["GNU Scientific Library"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        ExtData["Static Example Data (inst/extdata)"]:::data
        ScriptsDP["Script: data_provenance.R"]:::data
        RawData["Raw Data Parsers (inst/scripts/raw_data)"]:::data
    end

    %% External Libraries & Build Tools
    subgraph "External & Build"
        Configure["configure"]:::external
        ConfigureAC["configure.ac"]:::external
        Makevars["src/Makevars"]:::external
        MakevarsIn["src/Makevars.in"]:::external
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        Vignette["Vignette: CBN2Path.Rmd"]:::viz
        README["README.md"]:::viz
    end

    %% Quality Assurance
    subgraph "Quality Assurance"
        Test1["test-bcbn.R"]:::qa
        Test2["test-ctcbn.R"]:::qa
        Test3["test-hcbn.R"]:::qa
        Test4["tests/testthat.R"]:::qa
    end

    %% Relationships
    R_bcbn -->|calls| C_bcbn
    R_ctcbn -->|calls| C_ctcbn
    R_hcbn -->|calls| C_bcbn
    R_utils -->|calls| C_init
    R_utils -->|calls| C_queue
    R_utils -->|calls| C_rand
    R_utils -->|calls| C_dt
    C_bcbn -->|uses| GSL
    C_ctcbn -->|uses| GSL

    RawData -->|generates| ExtData
    ScriptsDP -->|processes| ExtData
    ExtData -->|loaded by| R_utils

    R_visualize -->|produces| Vignette
    R_visualize -->|produces| README

    Test1 -->|tests| R_bcbn
    Test2 -->|tests| R_ctcbn
    Test3 -->|tests| R_hcbn
    Test4 -->|tests| R_utils

    Configure -->|drives build| Makevars
    ConfigureAC -->|drives build| MakevarsIn
    Makevars -->|compiles| C_bcbn
    MakevarsIn -->|compiles| C_ctcbn

    %% Click Events
    click R_bcbn "https://github.com/rockwillck/cbn2path/blob/main/R/bcbn.R"
    click R_ctcbn "https://github.com/rockwillck/cbn2path/blob/main/R/ctcbn.R"
    click R_hcbn "https://github.com/rockwillck/cbn2path/blob/main/R/hcbn.R"
    click R_pathway "https://github.com/rockwillck/cbn2path/blob/main/R/PathwayAnalysis.R"
    click R_utils "https://github.com/rockwillck/cbn2path/blob/main/R/utils.R"
    click R_visualize "https://github.com/rockwillck/cbn2path/blob/main/R/visualize.R"
    click C_bcbn "https://github.com/rockwillck/cbn2path/blob/main/src/bcbn.c"
    click C_ctcbn "https://github.com/rockwillck/cbn2path/blob/main/src/ctcbn.c"
    click C_init "https://github.com/rockwillck/cbn2path/blob/main/src/init.c"
    click C_queue "https://github.com/rockwillck/cbn2path/blob/main/src/queue.c"
    click ScriptsDP "https://github.com/rockwillck/cbn2path/blob/main/inst/scripts/data_provenance.R"
    click RawData "https://github.com/rockwillck/cbn2path/tree/main/inst/scripts/raw_data/"
    click ExtData "https://github.com/rockwillck/cbn2path/tree/main/inst/extdata/"
    click Configure "https://github.com/rockwillck/cbn2path/tree/main/configure"
    click ConfigureAC "https://github.com/rockwillck/cbn2path/blob/main/configure.ac"
    click Makevars "https://github.com/rockwillck/cbn2path/tree/main/src/Makevars"
    click MakevarsIn "https://github.com/rockwillck/cbn2path/blob/main/src/Makevars.in"
    click Vignette "https://github.com/rockwillck/cbn2path/blob/main/vignettes/CBN2Path.Rmd"
    click README "https://github.com/rockwillck/cbn2path/blob/main/README.md"
    click Test1 "https://github.com/rockwillck/cbn2path/blob/main/tests/testthat/test-bcbn.R"
    click Test2 "https://github.com/rockwillck/cbn2path/blob/main/tests/testthat/test-ctcbn.R"
    click Test3 "https://github.com/rockwillck/cbn2path/blob/main/tests/testthat/test-hcbn.R"
    click Test4 "https://github.com/rockwillck/cbn2path/blob/main/tests/testthat.R"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72;
    classDef computation fill:#D5F5E3,stroke:#145A32;
    classDef data fill:#FCF3CF,stroke:#7D6608;
    classDef external fill:#FAD7A0,stroke:#B9770E;
    classDef viz fill:#EBDEF0,stroke:#6C3483;
    classDef qa fill:#E5E7E9,stroke:#566573;
```
