# poisonalien/maftools architecture

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

- Interactive diagram: https://gitdiagram.com/poisonalien/maftools
- Repository: https://github.com/poisonalien/maftools

## Overview

##### Project Type and Purpose
- maftools is an R library for summarizing, analyzing, and visualizing MAF (Mutation Annotation Format) files from cancer genomics studies.
- It wraps high-level R functions around core C routines for performance, ingests various input formats (MAF, BAM, GISTIC), and outputs plots, tables, and reports.

##### File Structure
- R/: Main R functions (data ingestion, statistical analyses, plotting).
- src/: Native C code (ntcounts.c, snpcounts.c, somaticfreq.c) for heavy computations.
- inst/extdata/: Bundled example datasets (MAF files, cytobands, signature references).
- man/: Documentation stubs for each R function (used by R help system).
- vignettes/: Tutorials and case-studies (R Markdown).
- scripts/: Utility scripts for pre-processing outside the package.
- DESCRIPTION, NAMESPACE: R package metadata and exports.
- .github/, workflows: CI checks and issue templates.

##### README for Additional Insights
- Core workflows: import MAF → create MAF object → pass to analysis/plot functions.
- Supported inputs: MAF, BAM, GISTIC, mosdepth.
- External dependencies: data.table, NMF, ggplot2, BiocManager, downstream tools (annovar2maf, vcf2maf).
- External services: TCGA, ICGC, cBioPortal.

##### Main Components & Their Relationships
a. User Interface Layer (R API)
– Entry-points for end users: functions such as `read_maf()`, `oncoPlot()`, `inferTumHetero()`, `plotSignatures()`, etc.
b. Core Engine
– R code orchestrates workflows: data validation, reshaping, statistical testing (fisherCorrect, estimateSignatures).
– Native C modules for performance-critical tasks (e.g., `ntcounts`, `snpcounts`, `somaticfreq`).
c. Data Layer
– Example/reference data in inst/extdata (cytobands, signature matrices).
– External input files: MAF, BAM, GISTIC.
– Clinical metadata (user-supplied or loaded via `tcgaLoad()`).
d. Visualization Layer
– ggplot2 wrappers for oncoplots, lollipop plots, rainfall plots, signature plots.
– Report generation via R Markdown vignettes.
e. Extensibility Points
– scripts/ folder for pre-processing pipelines.
– vignettes/ to guide custom workflows.
– S3/S4 class system (MAF-class, GISTIC-class) for method dispatch.
f. Integration with External Services
– BiocManager for installation.
– TCGA/ICGC REST or flat-file downloads.
– Third-party annotation tools (Annovar, vcf2maf).

##### Architectural Patterns & Design Principles
- Modular layering: clear separation between API, core logic, native code, data, and visualization.
- S3/S4 class dispatch: encapsulate MAF and GISTIC objects.
- “Plug-and-play” external data: inst/extdata and user-provided files.
- CI/CD with GitHub Actions (.github/workflows).
- Reproducibility via vignettes and scripts.

##### Putting It All Together
- Top layer: R API functions
- Underneath: C Modules
- To the right: Data Store (inst/extdata + user inputs)
- To the left: External Tools & Services
- Bottom: Visualization & Reports (vignettes, plots)
- Class objects (MAF, GISTIC) inside the Core Engine layer.
- CI/CD pipeline off to the side, linked to the GitHub repo.

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User"]:::external

    subgraph "R API (User Interface Layer)"
        direction TB
        ReadMAF["read_maf()"]:::r
        OncoPlot["oncoPlot()"]:::r
        InferTum["inferTumHetero()"]:::r
        PlotSignatures["plotSignatures()"]:::r
    end

    subgraph "Core Engine (R Orchestration)"
        direction TB
        MafMethods["maf_methods()"]:::r
        FisherCorrect["fisherCorrect()"]:::r
        EstimateSign["estimateSignatures()"]:::r
        ExtractSign["extractSignatures()"]:::r
        MAFClass["MAF-class (S4)"]:::r
        GisticClass["GISTIC-class (S4)"]:::r
    end

    subgraph "Native C Modules"
        direction TB
        NTCounts["ntcounts.c"]:::c
        SNPCounts["snpcounts.c"]:::c
        SomaticFreq["somaticfreq.c"]:::c
    end

    subgraph "Data Layer"
        direction TB
        ExampleData["inst/extdata"]:::data
        UserFiles["User MAF/BAM/GISTIC"]:::data
    end

    subgraph "External Services & Tools"
        direction TB
        TCGA["TCGA"]:::external
        ICGC["ICGC"]:::external
        Annovar["Annovar/vcf2maf"]:::external
    end

    subgraph "Visualization & Reports"
        direction TB
        OncoPlotVis["Oncoplot Visualizations"]:::visual
        Lollipop["Lollipop Plots"]:::visual
        Rainfall["Rainfall Plots"]:::visual
        Reports["Vignettes (R Markdown)"]:::visual
    end

    subgraph "CI/CD Pipeline"
        direction TB
        RCMD["R-CMD-check.yaml"]:::external
        StaleBot["stale_bot.yaml"]:::external
    end

    User --> ReadMAF
    User --> OncoPlot
    User --> InferTum
    User --> PlotSignatures

    ReadMAF --> MafMethods
    OncoPlot --> MafMethods
    InferTum --> MafMethods
    PlotSignatures --> MafMethods

    MafMethods --> NTCounts
    MafMethods --> SNPCounts
    MafMethods --> SomaticFreq

    MafMethods -- "reads/writes" --> ExampleData
    MafMethods -- "reads/writes" --> UserFiles

    ReadMAF --> TCGA
    ReadMAF --> ICGC
    ReadMAF --> Annovar

    MafMethods --> OncoPlotVis
    MafMethods --> Lollipop
    MafMethods --> Rainfall

    OncoPlotVis --> Reports
    Lollipop --> Reports
    Rainfall --> Reports

    RCMD -.-> User
    StaleBot -.-> User

    classDef r fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef c fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef visual fill:#FFD700,stroke:#333,stroke-width:1px

    click ReadMAF "https://github.com/poisonalien/maftools/blob/master/R/read_maf_dt.R"
    click OncoPlot "https://github.com/poisonalien/maftools/blob/master/R/oncoplot.R"
    click InferTum "https://github.com/poisonalien/maftools/blob/master/R/inferTumHetero.R"
    click PlotSignatures "https://github.com/poisonalien/maftools/blob/master/R/plotSignatures.R"
    click MafMethods "https://github.com/poisonalien/maftools/blob/master/R/maf_methods.R"
    click FisherCorrect "https://github.com/poisonalien/maftools/blob/master/R/fisherCorrect.R"
    click EstimateSign "https://github.com/poisonalien/maftools/blob/master/R/estimateSignatures.R"
    click ExtractSign "https://github.com/poisonalien/maftools/blob/master/R/extractSignatures.R"
    click NTCounts "https://github.com/poisonalien/maftools/blob/master/src/ntcounts.c"
    click SNPCounts "https://github.com/poisonalien/maftools/blob/master/src/snpcounts.c"
    click SomaticFreq "https://github.com/poisonalien/maftools/blob/master/src/somaticfreq.c"
    click ExampleData "https://github.com/poisonalien/maftools/tree/master/inst/extdata/"
    click MAFClass "https://github.com/poisonalien/maftools/blob/master/man/MAF-class.Rd"
    click GisticClass "https://github.com/poisonalien/maftools/blob/master/man/GISTIC-class.Rd"
    click RCMD "https://github.com/poisonalien/maftools/blob/master/.github/workflows/R-CMD-check.yaml"
    click StaleBot "https://github.com/poisonalien/maftools/blob/master/.github/workflows/stale_bot.yaml"
```
