# ngsfc/scgraphverse architecture

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

- Interactive diagram: https://gitdiagram.com/ngsfc/scgraphverse
- Repository: https://github.com/ngsfc/scgraphverse

## Overview

##### Project Type and Purpose
- Project type: R package for single-cell gene regulatory network (GRN) inference, consensus, evaluation, and visualization.
- Purpose: Provide a suite of interchangeable GRN algorithms (GENIE3, GRNBoost2, ZILGM, PCzinb, JRF), thresholding/consensus tools, performance metrics, and plotting utilities on single-cell RNA-seq data.

##### File Structure
Top-level directories:
- R/ – Core R functions, each file encapsulates one algorithm or utility (e.g., community_path.R, infer_networks.R, plotg.R).
- man/ – Auto-generated Rd documentation.
- tests/ – testthat unit tests for networks, comparisons, simulations.
- vignettes/ – User-facing how-to guides and case studies (RMarkdown).
- docs/, pkgdown.yml – Static site (pkgdown) for HTML docs, articles, reference.
- DESCRIPTION, NAMESPACE – R package metadata and exports.
- _pkgdown.yml – Controls site layout.
- NEWS.md, LICENSE – Release notes and license.

##### README for Additional Insights
- High-level workflow: data ingestion → GRN inference (multiple engines) → thresholding → consensus → evaluation → visualization.
- External dependencies: Python’s arboreto (for GRNBoost2), GitHub packages (ZILGM, learn2count, INet-Tool), CRAN/Bioconductor – these must be installed outside R.

##### Main Components and Interactions
a. Core R Functions (R/ folder) – each boxed as a module:
– GRN inference modules (GENIE3, GRNBoost2 wrapper, ZILGM, PCzinb, JRF)
– null-model thresholding (cutoff_adjacency)
– consensus (create_consensus, compare_consensus)
– evaluation (plotROC, pscores, network topology metrics)
– visualization (plotg, community_similarity, community_path)
– utility/support (generate_adjacency, symmetrize, init_py, utils)
b. External Services & Packages:
– Python Arboreto for GRNBoost2
– GitHub/Bioc packages for ZILGM, PCzinb, INet-Tool
– CRAN packages: igraph, ggraph, etc.
c. Data Flow & Dependencies:
1. User input: single-cell expression matrix (R object or file).
2. init_py() → sets up Python env (reticulate) for GRNBoost2.
3. infer_networks() dispatches to chosen inference module(s).
4. generate_adjacency() composes adjacency matrices.
5. cutoff_adjacency() filters edges via null distributions.
6. create_consensus() or compare_consensus() merges or compares networks.
7. pscores() and plotROC() compute and plot performance metrics.
d. Documentation & Testing:
– vignettes/ illustrate end-to-end workflows (case_study, simulation_study).
– man/ and docs/ generated via roxygen2 + pkgdown.
– tests/ verify algorithm outputs, consistency, edge cases.

##### Architectural Patterns & Design Principles
- Modular design: one‐function‐per‐file, easy to extend with new inference methods.
- Functional pipeline: pure functions for each step, chaining via lists of adjacency objects.
- Adapter pattern: wrapper functions (e.g., GRNBoost2, ZILGM) normalize external engine interfaces.
- Plugin-style extensibility: new methods simply drop in an R file and register in NAMESPACE.

##### Final Checklist
– All major R modules and folders represented.
– External engines/services and how they’re invoked.
– Notes on extensibility (plugin points for new methods).
– Sections for documentation and testing to show project maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input and Preprocessing
    subgraph "User Input / Preprocessing"
        direction TB
        Input["Single-cell Expression Matrix"] 
        InitPy["init_py()"]:::rmodule
    end

    %% Inference Engines
    subgraph "Inference Engines"
        direction TB
        Dispatcher["infer_networks()"]:::rmodule
        GENIE3["GENIE3 Module"]:::rmodule
        GRNBoost2["GRNBoost2 Wrapper"]:::rmodule
        ZILGM["ZILGM Adapter"]:::rmodule
        PCzinb["PCzinb Adapter"]:::rmodule
        JRF["JRF Module"]:::rmodule
    end

    %% Thresholding & Consensus
    subgraph "Thresholding & Consensus"
        direction TB
        Cutoff["cutoff_adjacency()"]:::rmodule
        ConsensusBuild["create_consensus()"]:::rmodule
        ConsensusComp["compare_consensus()"]:::rmodule
    end

    %% Evaluation
    subgraph "Evaluation"
        direction TB
        PScore["pscores()"]:::rmodule
        ROC["plotROC()"]:::rmodule
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        PlotG["plotg()"]:::rmodule
        CommSim["community_similarity()"]:::rmodule
        CommPath["community_path()"]:::rmodule
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Arboreto["Python Arboreto"]:::external
        GitHubMods["GitHub/Bioc Packages"]:::external
        CRAN["CRAN/Bioconductor Packages"]:::external
    end

    %% Documentation & Testing
    subgraph "Documentation & Testing"
        direction TB
        ManPages["man/*.Rd"]:::doc
        Pkgdown["docs/ & docs/reference/"]:::doc
        Vignettes["vignettes/*.Rmd"]:::doc
        Tests["tests/testthat/*.R"]:::test
    end

    %% Data Flow
    Input --> InitPy
    InitPy --> Dispatcher
    Dispatcher --> GENIE3
    Dispatcher --> GRNBoost2
    Dispatcher --> ZILGM
    Dispatcher --> PCzinb
    Dispatcher --> JRF

    GENIE3 --> Cutoff
    GRNBoost2 --> Cutoff
    ZILGM --> Cutoff
    PCzinb --> Cutoff
    JRF --> Cutoff

    Cutoff --> ConsensusBuild
    Cutoff --> ConsensusComp
    ConsensusBuild --> PScore
    ConsensusComp --> PScore
    PScore --> ROC
    ROC --> PlotG
    ROC --> CommSim
    ROC --> CommPath

    %% Dependencies arrows
    GRNBoost2 -.-> Arboreto
    ZILGM -.-> GitHubMods
    PCzinb -.-> GitHubMods
    JRF -.-> GitHubMods
    GENIE3 -.-> CRAN
    Arboreto -.-> CRAN
    GitHubMods -.-> CRAN

    %% Docs & Tests connections
    Dispatcher -.-> ManPages
    Cutoff -.-> ManPages
    PScore -.-> ManPages
    PlotG -.-> ManPages
    ManPages --> Pkgdown
    Vignettes -.-> Dispatcher
    Vignettes -.-> Cutoff
    Vignettes -.-> PlotG
    Tests -.-> Dispatcher
    Tests -.-> Cutoff
    Tests -.-> PScore

    %% Click Events
    click Dispatcher "https://github.com/ngsfc/scgraphverse/blob/main/R/infer_networks.R"
    click InitPy "https://github.com/ngsfc/scgraphverse/blob/main/R/init_py.R"
    click Cutoff "https://github.com/ngsfc/scgraphverse/blob/main/R/cutoff_adjacency.R"
    click ConsensusBuild "https://github.com/ngsfc/scgraphverse/blob/main/R/create_consensus.R"
    click ConsensusComp "https://github.com/ngsfc/scgraphverse/blob/main/R/compare_consensus.R"
    click PScore "https://github.com/ngsfc/scgraphverse/blob/main/R/pscores.R"
    click ROC "https://github.com/ngsfc/scgraphverse/blob/main/R/plotROC.R"
    click PlotG "https://github.com/ngsfc/scgraphverse/blob/main/R/plotg.R"
    click CommSim "https://github.com/ngsfc/scgraphverse/blob/main/R/community_similarity.R"
    click CommPath "https://github.com/ngsfc/scgraphverse/blob/main/R/community_path.R"
    click AdjGen "https://github.com/ngsfc/scgraphverse/blob/main/R/generate_adjacency.R"
    click Symmetrize "https://github.com/ngsfc/scgraphverse/blob/main/R/symmetrize.R"
    click Utils "https://github.com/ngsfc/scgraphverse/blob/main/R/utils.R"
    click ManPages "https://github.com/ngsfc/scgraphverse/blob/main/man/*.Rd"
    click Pkgdown "https://github.com/ngsfc/scgraphverse/tree/main/docs/"
    click Vignettes "https://github.com/ngsfc/scgraphverse/blob/main/vignettes/case_study.Rmd"
    click Vignettes "https://github.com/ngsfc/scgraphverse/blob/main/vignettes/simulation_study.Rmd"
    click Tests "https://github.com/ngsfc/scgraphverse/tree/main/tests/testthat/"

    %% Styles
    classDef rmodule fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#90EE90,stroke:#333,stroke-width:1px
    classDef test fill:#FFA500,stroke:#333,stroke-width:1px
```
