# lxiao06/asap architecture

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

- Interactive diagram: https://gitdiagram.com/lxiao06/asap
- Repository: https://github.com/lxiao06/asap

## Overview

##### Project type and purpose
- ASAP is an R package (open-source tool) for longitudinal analysis of birdsong recordings.
- Its core is a “SAP” object that holds raw data, intermediate results, and final analysis.
- It exposes a pipeline of modular processing steps (bout detection, segmentation, spectral analysis, clustering, etc.)

##### File structure
- R/: contains R functions, organized by functionality (bout.R, segment.R, spectral.R, motif.R, clustering.R, umap.R, pca.R, plot.R, etc.)
- src/: C++ source files (ModularityOptimizer.cpp/h, snn.cpp) wrapped by Rcpp for compute-intensive algorithms
- inst/extdata/: example WAV files
- man/: documentation for each function
- DESCRIPTION/NAMESPACE: package metadata and export settings
- .github/workflows: CI for R-CMD-check and pkgdown site deployment

##### README
- Describes pipeline stages:
– create_sap_object → create_audio_clip → create_template → detect_template → find_motif → analyze_spectral → find_clusters → run_umap/run_pca → plot_*
- Mentions dependency on SAP2011-style directory conventions (file ingestion) and flexibility to add other backends

A. Data Ingestion
– WAV files on disk (inst/extdata or user’s recordings)
– create_sap_object reads directory tree → instantiates SAP S4 object in R memory

B. Core SAP Object
– Central in-memory data structure
– Fields: file paths, audio clips, templates, motif matches, features, embeddings, cluster labels

C. Processing Modules (R functions)
1. Bout Detection (find_bout)
2. Syllable Segmentation (segment)
3. Envelope & RMS Computation (bout.R, envelope.R, amplitude features)
4. Spectral Analysis (spectral.R, spectrogramming.R, entropy.R)
5. Template Matching & Motif Extraction (template.R, motif.R)
6. Feature Extraction (pca.R, umap.R, clustering.R, trajectory.R)

D. Native Extensions (C++ via Rcpp in src/)
– ModularityOptimizer (community detection)
– SNN graph construction
– Exposed to R through RcppExports and Rcpp attributes

E. Analytics & Dimensionality Reduction
– run_pca (R wrapper around fast_pca or prcomp)
– run_umap (calls uwot or reticulate-backed UMAP)

F. Visualization
– plot_heatmap, plot_umap, plot_traces, etc.
– Depends on ggplot2 and base R graphics

G. Documentation & CI/CD
– man/: Rd files auto-generated from R comments
– pkgdown site config (_pkgdown.yml)
– GitHub Actions: R-CMD check, pkgdown deploy

##### Relationships & Data Flows
- From SAP Object → each processing module → updated SAP Object (method chaining via pipes)
- Processing modules → native C++ modules for heavy compute
- SAP Object → analytics modules → embedding & cluster results
- SAP Object → visualization modules → plots delivered to user
- GitHub Actions → triggers on push → runs tests → builds pkgdown

##### Architectural patterns & design principles
- Pipeline pattern: data flows through ordered, composable steps
- Modular design: each R file implements one concern (separation of concerns)
- S4 object for state encapsulation (SAP)
- Native extension for performance-critical code (Rcpp)
- CI/CD for quality assurance and documentation deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Storage
    subgraph "Data & Storage"
        direction TB
        WAV(("Disk (WAV files)")):::dataStorage
        extdata["inst/extdata (example WAVs)"]:::dataStorage
        createSAP["create_sap_object()"]:::coreR
        SAPObj(("SAP Object (S4)")):::dataStorage
    end

    %% Core R Modules - Processing
    subgraph "Processing Modules (R)" 
        direction TB
        Bout["Bout Detection"]:::coreR
        Seg["Syllable Segmentation"]:::coreR
        Env["Envelope & RMS Computation"]:::coreR
        Spectral["Spectral Analysis"]:::coreR
        Template["Template Matching & Motif Extraction"]:::coreR
        Features["Feature Extraction"]:::coreR
    end

    %% Native Extensions
    subgraph "Native Extensions (C++)"
        direction TB
        ModOpt["Modularity Optimizer"]:::native
        SNN["SNN Graph Construction"]:::native
        RcppExports["RcppExports Bindings"]:::native
    end

    %% Analytics & Visualization
    subgraph "Analytics & Visualization"
        direction TB
        PCA["run_pca()"]:::analytics
        UMAP["run_umap()"]:::analytics
        Plot["Visualization (plot_* functions)"]:::analytics
    end

    %% CI/CD & Documentation
    subgraph "CI/CD & Documentation"
        direction TB
        Docs["man/ & pkgdown site"]:::ci
        CICheck["R-CMD-check CI"]:::ci
        CIPkg["pkgdown deploy CI"]:::ci
    end

    %% External Dependencies
    RcppExt["Rcpp"]:::external
    ggplot2["ggplot2"]:::external
    uwot["uwot/reticulate"]:::external
    GHAct["GitHub Actions"]:::external

    %% Data Flow
    WAV -->|"reads files"| createSAP
    extdata -->|"example WAVs"| createSAP
    createSAP -->|"instantiates"| SAPObj

    SAPObj -->|"pipe to"| Bout -->|"updates"| SAPObj
    SAPObj -->|"pipe to"| Seg -->|"updates"| SAPObj
    SAPObj -->|"pipe to"| Env -->|"updates"| SAPObj
    SAPObj -->|"pipe to"| Spectral -->|"updates"| SAPObj
    SAPObj -->|"pipe to"| Template -->|"updates"| SAPObj
    SAPObj -->|"pipe to"| Features -->|"updates"| SAPObj

    %% Native calls
    Spectral -->|"heavy compute"| ModOpt
    Features -->|"graph build"| SNN
    ModOpt --> RcppExt
    SNN --> RcppExt
    RcppExports --> RcppExt

    %% Analytics & Viz
    SAPObj -->|"analytics"| PCA -->|"embeddings"| SAPObj
    SAPObj -->|"analytics"| UMAP -->|"embeddings"| SAPObj
    SAPObj -->|"visualize"| Plot

    Plot --> ggplot2
    UMAP --> uwot

    %% CI/CD & Docs flow
    GHAct --> CICheck
    GHAct --> CIPkg
    Docs --> CIPkg

    %% Click Events
    click createSAP "https://github.com/lxiao06/asap/blob/main/R/objects.R"
    click extdata "https://github.com/lxiao06/asap/tree/main/inst/extdata"
    click WAV "https://github.com/lxiao06/asap/tree/main/inst/extdata"
    click SAPObj "https://github.com/lxiao06/asap/blob/main/R/objects.R"
    click Bout "https://github.com/lxiao06/asap/blob/main/R/bout.R"
    click Seg "https://github.com/lxiao06/asap/blob/main/R/segment.R"
    click Env "https://github.com/lxiao06/asap/blob/main/R/envelope.R"
    click Env "https://github.com/lxiao06/asap/blob/main/R/duration.R"
    click Spectral "https://github.com/lxiao06/asap/blob/main/R/spectral.R"
    click Spectral "https://github.com/lxiao06/asap/blob/main/R/spectrogramming.R"
    click Spectral "https://github.com/lxiao06/asap/blob/main/R/entropy.R"
    click Template "https://github.com/lxiao06/asap/blob/main/R/template.R"
    click Template "https://github.com/lxiao06/asap/blob/main/R/motif.R"
    click Features "https://github.com/lxiao06/asap/blob/main/R/clustering.R"
    click Features "https://github.com/lxiao06/asap/blob/main/R/pca.R"
    click Features "https://github.com/lxiao06/asap/blob/main/R/umap.R"
    click Features "https://github.com/lxiao06/asap/blob/main/R/trajectory.R"
    click ModOpt "https://github.com/lxiao06/asap/blob/main/src/ModularityOptimizer.cpp"
    click ModOpt "https://github.com/lxiao06/asap/blob/main/src/ModularityOptimizer.h"
    click SNN "https://github.com/lxiao06/asap/blob/main/src/snn.cpp"
    click RcppExports "https://github.com/lxiao06/asap/blob/main/src/RcppExports.cpp"
    click RcppExports "https://github.com/lxiao06/asap/blob/main/R/RcppExports.R"
    click PCA "https://github.com/lxiao06/asap/blob/main/R/pca.R"
    click UMAP "https://github.com/lxiao06/asap/blob/main/R/umap.R"
    click Plot "https://github.com/lxiao06/asap/blob/main/R/plot.R"
    click Docs "https://github.com/lxiao06/asap/tree/main/man/"
    click Docs "https://github.com/lxiao06/asap/blob/main/_pkgdown.yml"
    click CICheck "https://github.com/lxiao06/asap/blob/main/.github/workflows/R-CMD-check.yaml"
    click CIPkg "https://github.com/lxiao06/asap/blob/main/.github/workflows/pkgdown.yaml"

    %% Styles
    classDef dataStorage fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef coreR fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef native fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef analytics fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
```
