# itsvenu/alps architecture

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

- Interactive diagram: https://gitdiagram.com/itsvenu/alps
- Repository: https://github.com/itsvenu/alps

## Overview

##### Project type and purpose
- This is an R/Bioconductor package (“ALPS”) for genome-wide epigenomics data analysis.
- It exposes a suite of R functions that ingest bigWig and BED files, compute summaries and correlations, annotate regions, and produce publication-ready plots.

##### File structure
- Top‐level “R/” directory: core function implementations grouped by functionality (e.g., retrieving genomic annotations, computing summaries, plotting).
- “inst/extdata/”: example data sets (bigWig, BED, motif files, overlap tables).
- “inst/script/”: end-to-end example pipeline.
- “man/” & “vignettes/”: documentation and usage tutorials.
- “tests/”: automated unit tests.
- Package metadata: DESCRIPTION, NAMESPACE, Rbuildignore, etc.

##### README and existing overview
- The README describes an “ALPS workflow” and even embeds an overview figure (inst/figures/README-ALPS-overview.png).
- Dependencies: BiocManager, various Bioconductor classes (GenomicRanges, rtracklayer, etc.).

- External Data Sources
– bigWig & BED files (inst/extdata/bw)
– Motif libraries (inst/extdata/motifs)
- ALPS Core Modules (R/)
– Data Ingestion & Preprocessing (get_genomic_annotations.R, multiBigwig_summary.R)
– Region Discovery (get_variable_regions.R)
– Enrichment & Correlation Analysis (plot_enrichments.R, plot_correlation.R)
– Visualization (plot_browser_tracks.R, plot_genomic_annotations.R, plot_motif_logo.R)
– Utility & Pipeline Glue (utils-pipe.R, global_vars.R)
- Example Pipelines (inst/script/DATASET.R)
- Documentation & User Guides (vignettes/ALPS-vignette.Rmd, man/*.Rd)
- Testing Suite (tests/testthat/*.R)
- External Dependencies (Bioconductor packages: GenomicRanges, rtracklayer, BiocManager, ggplot2, etc.)

1. External Data → Data Ingestion modules
2. Ingestion → Region Discovery & Summary modules
3. Summary modules → Enrichment & Correlation modules
4. All analysis modules → Visualization modules
5. Visualization modules → Output figures (inst/figures/)
6. inst/script → orchestrates calls to core modules in sequence
7. Vignette & man pages ← reference core module APIs
8. tests → exercise each core module

C. Highlight architectural patterns & design principles
- Modular functional decomposition: each R script implements a cohesive analysis step.
- Pipeable workflow: functions designed to be chained via the pipe (`%>%`) in utils-pipe.R.
- Test-driven quality: thorough unit tests for each function.
- Extensibility: external motif formats processed via “process_*” Rd documented functions.

D. Annotate technologies & frameworks
- R / Bioconductor ecosystem
- Key classes: GRanges, BigWigFile, DataFrame
- Plotting: ggplot2, Gviz (if used), gridExtra
- Testing: testthat

##### Diagramming conventions
- Blue = Data Input
- Green = Core Analysis Functions
- Orange = Visualization
- Gray = Documentation & Tests
- Purple = External Dependencies

##### Detail
- `inst/extdata` as read-only example data.
- How NAMESPACE and DESCRIPTION glue everything into an installable package.
- Role of `utils-pipe.R` in enabling `%>%` chaining.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Input"
        E1["bigWig & BED files"]:::dataInput
        E2["Motif libraries"]:::dataInput
    end

    subgraph "Data Ingestion & Preprocessing"
        A1["get_genomic_annotations.R"]:::coreAnalysis
        A2["multiBigwig_summary.R"]:::coreAnalysis
    end

    B1["get_variable_regions.R"]:::coreAnalysis

    subgraph "Enrichment & Correlation Analysis"
        C1["plot_enrichments.R"]:::coreAnalysis
        C2["plot_correlation.R"]:::coreAnalysis
    end

    subgraph "Visualization"
        D1["plot_browser_tracks.R"]:::visualization
        D2["plot_genomic_annotations.R"]:::visualization
        D3["plot_motif_logo.R"]:::visualization
    end

    S["Example pipeline (inst/script/DATASET.R)"]:::coreAnalysis

    subgraph "Documentation & User Guides"
        DOC1["ALPS-vignette.Rmd"]:::docs
        DOC2["man/*.Rd"]:::docs
    end

    T["tests/testthat/"]:::docs

    M1["DESCRIPTION"]:::deps
    M2["NAMESPACE"]:::deps

    XD["External Dependencies"]:::deps

    E1 --> A1
    E1 --> A2
    E2 --> D3

    A1 --> B1
    A2 --> B1

    B1 --> C1
    B1 --> C2

    C1 --> D1
    C1 --> D2
    C1 --> D3
    C2 --> D1
    C2 --> D2

    S --> A1
    S --> A2
    S --> B1
    S --> C1
    S --> C2
    S --> D1
    S --> D2
    S --> D3

    DOC1 -.-> A1
    DOC1 -.-> B1
    DOC1 -.-> C1
    DOC1 -.-> D1

    DOC2 -.-> A1
    DOC2 -.-> C1

    T -.-> A1
    T -.-> A2
    T -.-> B1
    T -.-> C1
    T -.-> C2
    T -.-> D1
    T -.-> D2
    T -.-> D3

    M1 --> A1
    M1 --> A2
    M1 --> B1
    M2 --> C1
    M2 --> D1

    XD --> A1
    XD --> C1
    XD --> D1

    classDef dataInput fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef coreAnalysis fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef visualization fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef deps fill:#DDA0DD,stroke:#333,stroke-width:1px;

    click E1 "https://github.com/itsvenu/alps/tree/master/inst/extdata/bw/"
    click E2 "https://github.com/itsvenu/alps/tree/master/inst/extdata/motifs/"
    click A1 "https://github.com/itsvenu/alps/blob/master/R/get_genomic_annotations.R"
    click A2 "https://github.com/itsvenu/alps/blob/master/R/multiBigwig_summary.R"
    click B1 "https://github.com/itsvenu/alps/blob/master/R/get_variable_regions.R"
    click C1 "https://github.com/itsvenu/alps/blob/master/R/plot_enrichments.R"
    click C2 "https://github.com/itsvenu/alps/blob/master/R/plot_correlation.R"
    click D1 "https://github.com/itsvenu/alps/blob/master/R/plot_browser_tracks.R"
    click D2 "https://github.com/itsvenu/alps/blob/master/R/plot_genomic_annotations.R"
    click D3 "https://github.com/itsvenu/alps/blob/master/R/plot_motif_logo.R"
    click S "https://github.com/itsvenu/alps/blob/master/inst/script/DATASET.R"
    click DOC1 "https://github.com/itsvenu/alps/blob/master/vignettes/ALPS-vignette.Rmd"
    click DOC2 "https://github.com/itsvenu/alps/tree/master/man/"
    click T "https://github.com/itsvenu/alps/tree/master/tests/testthat/"
    click M1 "https://github.com/itsvenu/alps/tree/master/DESCRIPTION"
    click M2 "https://github.com/itsvenu/alps/tree/master/NAMESPACE"
```
