# hao-zou-lab/decepticonx architecture

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

- Interactive diagram: https://gitdiagram.com/hao-zou-lab/decepticonx
- Repository: https://github.com/hao-zou-lab/decepticonx

## Overview

##### Project Type and Purpose
- DECEPTICONx is an R/Bioconductor‐style open‐source tool (an R package) for pan‐cancer microenvironment deconvolution.
- It exposes a single top‐level API (`run_DECEPTICONx`) that integrates multiple deconvolution engines (BayesPrism, MuSiC, MuSiC2, monocle3, CIBERSORT/BSeqSC) and manages signature matrices.

##### File Structure
- Top‐level files:
- DESCRIPTION, NAMESPACE, LICENSE – standard R package metadata.
- README.md – usage instructions.
- CIBERSORT.R, DOCKER_codes.R, bseqsc_proportions.R, music_basis.R, music_prop.R – engine‐specific wrappers.
- R/ directory: core R functions (e.g. DECEPTICONx.R, run_DECEPTICONx.R).
- signature_matrix/: pre‐computed gene expression templates for six cell types and three engines.
- man/: documentation stubs for each public function.

##### Extract Architectural Insights from the README
- Inputs: bulk expression matrix + single‐cell data + subtype labels + optional custom template flag.
- Outputs: deconvolution results per cell type.
- Dependencies: external R packages (BayesPrism, MuSiC, monocle3, etc.) and optional Docker workflows.

##### Main Components & Interactions
a. User Interface Layer
- R console or script that calls `run_DECEPTICONx`.
b. Input Management
- File readers for bulk and single‐cell matrices.
- Subtype parsing (n×2 lookup).
c. Signature‐Matrix Module
- Loads built‐in templates from signature_matrix/.
- Optionally generates custom templates via `DOCKER_codes.R`.
d. Deconvolution Engines (modular subcomponents)
- BayesPrism wrapper (`bayes_base.R`).
- MuSiC & MuSiC2 wrappers (`MuSiC2_base.R`, `music_basis.R`, `music_prop.R`).
- monocle3 wrapper (`monocle3_base.R`).
- CIBERSORT/BSeqSC wrapper (`CIBERSORT.R`, `bseqsc_proportions.R`).
e. Orchestration Core
- `run_DECEPTICONx` coordinates input → template selection → engine execution → results collation.
f. Output & Reporting
- Result tables and summary statistics saved under RUNpath.

##### External Dependencies & Services
- Bioconductor repositories (for SingleCellExperiment, TOAST, etc.)
- GitHub (devtools::install_github)
- Docker (optional containerized code in DOCKER_codes.R)

##### Architectural Patterns & Design Principles
- Modular wrappers isolate each engine’s API and parameter handling.
- Plug‐in pattern for adding new deconvolution methods.
- Separation of concerns: I/O, template management, computation, and reporting.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Metadata
    subgraph "Project Metadata & Installation"
        META_DESC["DESCRIPTION"]:::external
        META_NS["NAMESPACE"]:::external
        META_LIC["LICENSE"]:::external
        META_README["README.md"]:::external
    end

    %% External Dependencies
    ExtDeps["External Dependencies\n(BiocManager, GitHub, Docker)"]:::externalGray

    %% User Interface
    UI["User (R console/script)"]:::external

    %% Core Modules
    InputM["Input Management\n(file readers, subtype parsing)"]:::dataOrange
    Orchestrator["Orchestration Core\n(run_DECEPTICONx)"]:::coreBlue
    InitHelpers["Package Init & Helpers\n(R/DECEPTICONx.R)"]:::coreBlue
    Signature["Signature-Matrix Module\n(signature_matrix/)"]:::dataOrange

    %% Engines
    subgraph "Deconvolution Engines"
        BP["BayesPrism Wrapper\n(bayes_base.R)"]:::engineGreen
        MS["MuSiC & MuSiC2 Wrapper\n(music_basis.R / music_prop.R)"]:::engineGreen
        MC3["monocle3 Wrapper\n(DOCKER_codes.R)"]:::engineGreen
        CS["CIBERSORT/BSeqSC Wrapper\n(CIBERSORT.R / bseqsc_proportions.R)"]:::engineGreen
    end

    %% Output
    Output["Output & Reporting\n(results tables, summary)"]:::external

    %% Connections
    UI -->|calls| Orchestrator
    META_DESC -->|installation info| Orchestrator
    META_NS -->|installation info| Orchestrator
    META_LIC -->|license checks| Orchestrator
    META_README -->|usage guide| Orchestrator

    UI -->|provides inputs| InputM
    InputM -->|passes data| Orchestrator
    Orchestrator -->|loads templates| Signature
    Orchestrator -->|orchestrates| BP
    Orchestrator -->|orchestrates| MS
    Orchestrator -->|orchestrates| MC3
    Orchestrator -->|orchestrates| CS
    BP -->|sends results| Output
    MS -->|sends results| Output
    MC3 -->|sends results| Output
    CS -->|sends results| Output

    ExtDeps -.-> Orchestrator
    ExtDeps -.-> BP
    ExtDeps -.-> MS
    ExtDeps -.-> MC3
    ExtDeps -.-> CS

    %% Click Events
    click META_DESC "https://github.com/hao-zou-lab/decepticonx/tree/main/DESCRIPTION"
    click META_NS "https://github.com/hao-zou-lab/decepticonx/tree/main/NAMESPACE"
    click META_LIC "https://github.com/hao-zou-lab/decepticonx/tree/main/LICENSE"
    click META_README "https://github.com/hao-zou-lab/decepticonx/blob/main/README.md"
    click Orchestrator "https://github.com/hao-zou-lab/decepticonx/blob/main/R/run_DECEPTICONx.R"
    click InitHelpers "https://github.com/hao-zou-lab/decepticonx/blob/main/R/DECEPTICONx.R"
    click Signature "https://github.com/hao-zou-lab/decepticonx/tree/main/signature_matrix/"
    click BP "https://github.com/hao-zou-lab/decepticonx/blob/main/man/bayes_base.Rd"
    click MS "https://github.com/hao-zou-lab/decepticonx/blob/main/man/MuSiC2_base.Rd"
    click MC3 "https://github.com/hao-zou-lab/decepticonx/blob/main/man/monocle3_base.Rd"

    %% Styles
    classDef coreBlue fill:#a6cee3,stroke:#1f78b4,color:#000;
    classDef engineGreen fill:#b2df8a,stroke:#33a02c,color:#000;
    classDef dataOrange fill:#fdbf6f,stroke:#ff7f00,color:#000;
    classDef external fill:#dddddd,stroke:#999999,color:#000;
    classDef externalGray fill:#cccccc,stroke:#666666,color:#000;
```
