# cemos-mannheim/molecular architecture

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

- Interactive diagram: https://gitdiagram.com/cemos-mannheim/molecular
- Repository: https://github.com/cemos-mannheim/molecular

## Overview

##### Project Type and Purpose
- This is an R package ("moleculaR") that provides a computational framework for spatial probabilistic mapping of metabolites in mass-spectrometry imaging (MSI).
- It includes both (a) a library of core R functions (under R/) for data import, processing, statistical mapping, and visualization, and (b) two Shiny-based web-apps (under inst/shiny/) for interactive GUI deployment (example-app and package-app).
- It comes with built-in example data, uses the SwissLipids database, ingests METASPACE annotations, and supports deployment via Shiny Server.

##### File-Structure Analysis
- Top-level “R/” directory: contains ~40 .R files (core algorithmic modules: data import, normalization, spatial window creation, probability mapping, plotting, Shiny launcher).
- “inst/shiny/”: two Shiny apps (example-app.R and package-app.R) plus static “www” assets.
- “data/”: preprocessed example RData.
- “vignettes/”: R Markdown walk-throughs illustrating package usage.
- “renv/” + renv.lock: reproducible environment for dependencies.
- Standard R package metadata: DESCRIPTION, NAMESPACE, man/ Rd docs.

##### README Insights
- Core tech: R, Shiny, renv.
- Data sources: SwissLipids DB (bundled), METASPACE (via REST / file import).
- Features: FDR-verified probabilistic maps (MPMs), collective projection maps (CPPMs), spatial and statistical ops, interactive GUI.
- Deployment: local Shiny Server, standalone web-apps.

- User Interface
– Web Browser (interacts via HTTP)
– Shiny Web GUI (example-app & package-app)
- Presentation Layer
– Shiny Server (optional) or local R session with runShiny()
- Application Layer (core package functions)
– Data Import Module (readCentrData.R, readSingleSpect.R, manualSpatstatImport.R)
– Database Module (loadSwissDB.R, downloadExData.R, recreateExData.R)
– Processing Engine
· Preprocessing & Filtering (filterPeaks.R, filterDuplicates.R, normalizeIntensity.R, transformIntensity.R)
· Spatial Window & Matrix Generation (createSpatialWindow.R, createSparseMat.R)
· Statistical Mapping (estimateFwhm.R, gaussWeight.R, probMap.R, moleculaR.R)
– Visualization Module (plotting-functions.R, focusPlot.R, plotImg.R, plot.molProbMap.R)
– Batch & Simulation Utilities (batchAnalyteSearch.R, simulation-functions.R)
- Data Layer
– Local Example Data (data/processed-example-Data.RData)
– External METASPACE Annotations (inst/extdata/*.txt, .csv, .tsv)
– SwissLipids DB (inst/extdata/swisslipids-speciesOnly-sep2020.tsv)
- Environment & Deployment
– renv-managed R library (renv/)
– Dependencies: Shiny, terra (GDAL), MALDIquantForeign/XML (Suggests), others from DESCRIPTION

1. User → Browser → (HTTP) → Shiny Web GUI
2. Shiny Web GUI → invokes core functions via runShiny()/Shiny Server
3. Data Import Module ↔ External Data Layer (SwissLipids + METASPACE files)
4. Processing Engine consumes imported data → outputs spatial point patterns & probability scores
5. Visualization Module reads processed objects → renders interactive/ static plots → Shiny UI
6. Batch & Simulation utilities operate on core modules similarly
7. renv ensures reproducible dependency resolution for all modules

c. Architectural Patterns & Principles
- Modular separation of concerns: data import, processing, visualization, deployment
- MVC-style pattern within Shiny: UI (ui.R sections in example-app/package-app), Server (core function calls), Model (R objects representing MSI data)
- Dependency management & reproducibility via renv
- Stateless web layer: Shiny session encapsulates user state

d. Key Technologies & Frameworks
- R (language)
- Shiny (web framework)
- renv (dependency management)
- terra (spatial raster support, GDAL)
- MALDIquantForeign/XML (optional)
- SwissLipids & METASPACE data interfaces

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Web Browser"]:::presentation

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI1["Shiny UI: example-app.R"]:::presentation
        UI2["Shiny UI: package-app.R"]:::presentation
        Launcher["Shiny Launcher (runShiny)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB

        subgraph "Data Import Module"
            direction TB
            Import1["readCentrData"]:::application
            Import2["readSingleSpect"]:::application
            Import3["manualSpatstatImport"]:::application
        end

        subgraph "Database Module"
            direction TB
            DB1["loadSwissDB"]:::application
            DB2["downloadExData"]:::application
            DB3["recreateExData"]:::application
        end

        subgraph "Processing Engine"
            direction TB
            subgraph "Preprocessing & Filtering"
                direction TB
                Pre1["filterPeaks"]:::application
                Pre2["filterDuplicates"]:::application
                Pre3["normalizeIntensity"]:::application
                Pre4["transformIntensity"]:::application
            end
            subgraph "Spatial Window & Matrix"
                direction TB
                SW1["createSpatialWindow"]:::application
                SW2["createSparseMat"]:::application
            end
            subgraph "Statistical Mapping"
                direction TB
                Stat1["estimateFwhm"]:::application
                Stat2["gaussWeight"]:::application
                Stat3["probMap"]:::application
                Stat4["moleculaR"]:::application
            end
        end

        subgraph "Visualization Module"
            direction TB
            Viz1["plotting-functions"]:::application
        end

        subgraph "Batch & Simulation"
            direction TB
            BS1["batchAnalyteSearch"]:::application
            BS2["simulation-functions"]:::application
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Data1["Processed Example Data"]:::data
        Data2["METASPACE Annotations"]:::data
        Data3["SwissLipids DB"]:::data
    end

    %% Environment Layer
    subgraph "Environment & Deployment"
        direction TB
        Env["renv (Dependencies)"]:::env
    end

    %% Connections
    Browser -->|"HTTP"| UI1
    Browser -->|"HTTP"| UI2
    UI1 --> Launcher
    UI2 --> Launcher
    Launcher --> Import1
    Launcher --> Import2
    Launcher --> Import3

    %% Import and DB to Data
    Import1 -->|"reads files"| Data2
    Import2 -->|"reads files"| Data2
    Import3 -->|"imports spatial"| Data2
    DB1 --> Data3
    DB2 --> Data1
    DB3 --> Data1

    %% Processing Pipeline
    Import1 --> Pre1
    Import2 --> Pre1
    Import3 --> Pre1

    Pre1 --> Pre2 --> Pre3 --> Pre4
    Pre4 --> SW1 --> SW2
    SW2 --> Stat1 --> Stat2 --> Stat3 --> Stat4
    Stat4 --> Viz1 --> UI1
    Stat4 --> Viz1 --> UI2

    %% Batch & Simulation paths
    BS1 --> Pre1
    BS2 --> Pre1

    %% Environment encapsulation
    Env --> Import1
    Env --> DB1
    Env --> Pre1
    Env --> SW1
    Env --> Stat1
    Env --> Viz1
    Env --> BS1

    %% Click Events
    click UI1 "https://github.com/cemos-mannheim/molecular/blob/main/inst/shiny/example-app.R"
    click UI2 "https://github.com/cemos-mannheim/molecular/blob/main/inst/shiny/package-app.R"
    click Launcher "https://github.com/cemos-mannheim/molecular/blob/main/R/runShiny.R"
    click Import1 "https://github.com/cemos-mannheim/molecular/blob/main/R/readCentrData.R"
    click Import2 "https://github.com/cemos-mannheim/molecular/blob/main/R/readSingleSpect.R"
    click Import3 "https://github.com/cemos-mannheim/molecular/blob/main/R/manualSpatstatImport.R"
    click DB1 "https://github.com/cemos-mannheim/molecular/blob/main/R/loadSwissDB.R"
    click DB2 "https://github.com/cemos-mannheim/molecular/blob/main/R/downloadExData.R"
    click DB3 "https://github.com/cemos-mannheim/molecular/blob/main/R/recreateExData.R"
    click Data3 "https://github.com/cemos-mannheim/molecular/blob/main/inst/extdata/swisslipids-speciesOnly-sep2020.tsv"
    click Pre1 "https://github.com/cemos-mannheim/molecular/blob/main/R/filterPeaks.R"
    click Pre2 "https://github.com/cemos-mannheim/molecular/blob/main/R/filterDuplicates.R"
    click Pre3 "https://github.com/cemos-mannheim/molecular/blob/main/R/normalizeIntensity.R"
    click Pre4 "https://github.com/cemos-mannheim/molecular/blob/main/R/transformIntensity.R"
    click SW1 "https://github.com/cemos-mannheim/molecular/blob/main/R/createSpatialWindow.R"
    click SW2 "https://github.com/cemos-mannheim/molecular/blob/main/R/createSparseMat.R"
    click Stat1 "https://github.com/cemos-mannheim/molecular/blob/main/R/estimateFwhm.R"
    click Stat2 "https://github.com/cemos-mannheim/molecular/blob/main/R/gaussWeight.R"
    click Stat3 "https://github.com/cemos-mannheim/molecular/blob/main/R/probMap.R"
    click Stat4 "https://github.com/cemos-mannheim/molecular/blob/main/R/moleculaR.R"
    click Viz1 "https://github.com/cemos-mannheim/molecular/blob/main/R/plotting-functions.R"
    click BS1 "https://github.com/cemos-mannheim/molecular/blob/main/R/batchAnalyteSearch.R"
    click BS2 "https://github.com/cemos-mannheim/molecular/blob/main/R/simulation-functions.R"
    click Data1 "https://github.com/cemos-mannheim/molecular/blob/main/data/processed-example-Data.RData"
    click Data2 "https://github.com/cemos-mannheim/molecular/blob/main/inst/extdata/metaspace_annotations.csv"

    %% Styles
    classDef presentation fill:#fdd,stroke:#333,stroke-width:1px;
    classDef application fill:#dfd,stroke:#333,stroke-width:1px;
    classDef data fill:#ddf,stroke:#333,stroke-width:1px;
    classDef env fill:#eee,stroke:#333,stroke-width:1px;
```
