# vdhooftcompmet/ms2lda architecture

> Architecture diagram of the GitHub repository vdhooftcompmet/ms2lda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vdhooftcompmet/ms2lda
- Repository: https://github.com/vdhooftcompmet/ms2lda

## Overview

MS2LDA discovers recurring substructures in mass-spectrometry spectra through preprocessing and topic modeling, then supports motif annotation and exploration. The repository includes both a command-line analysis route and the MS2LDAViz web application, plus a MassQL query engine for motif-oriented spectral searches. The README documents these capabilities, while the sampled source is partial; links among unsampled subsystems are therefore shown only where the tree and documented workflow support them.

Main entry points: [`App/app.py`](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/app.py) (MS2LDAViz app), [`MS2LDA/Mass2Motif.py`](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Mass2Motif.py) (Motif representation), [`MS2LDA/run.py`](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/run.py) (Analysis runner), [`App/callbacks`](https://github.com/vdhooftcompmet/ms2lda/tree/main/App/callbacks) (UI callbacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis"]
  node_cli["CLI runner<br/>[ms2lda_runfull.py]"]
  node_run["Analysis runner<br/>[run.py]"]
  node_clean["Load and clean<br/>[load_and_clean.py]"]
  node_corpus["Corpus generation<br/>[generate_corpus.py]"]
  node_model["Topic modeling<br/>[modeling.py]"]
  node_motif["Motif representation<br/>[Mass2Motif.py]"]
  node_document["Motif documents"]
end

subgraph group_annotation["Motif Annotation"]
  node_screening["Motif screening<br/>[Screening.py]"]
  node_spec2vec["Spec2Vec annotation"]
  node_fingerprints["Fingerprint annotation"]
  node_massqlmotif["Motif MassQL<br/>[MassQL4MotifDB.py]"]
end

subgraph group_explore["Exploration"]
  node_web["MS2LDAViz app<br/>[app.py]"]
  node_callbacks["UI callbacks"]
  node_runlayout["Run analysis tab<br/>[run_analysis.py]"]
  node_loadlayout["Load results tab<br/>[load_results.py]"]
  node_rankings["Motif rankings<br/>[motif_rankings.py]"]
  node_details["Motif details<br/>[motif_details.py]"]
  node_network["Network view<br/>[network_view.py]"]
  node_visuals["Visualizations<br/>[visualisation.py]"]
end

subgraph group_query["Spectral Queries"]
  node_searchlayout["Spectra search tab<br/>[spectra_search.py]"]
  node_parser["MassQL parser<br/>[msql_parser.py]"]
  node_engine["Query engine<br/>[msql_engine.py]"]
  node_filters["Query filters"]
  node_loader["Spectra loader"]
end

node_researcher(("Researcher"))
node_spectra["Spectra data"]

node_researcher -->|"runs analysis"| node_cli
node_researcher -->|"explores results"| node_web
node_spectra -->|"input spectra"| node_run
node_cli -->|"invokes"| node_run
node_run -->|"preprocesses"| node_clean
node_clean -->|"builds corpus"| node_corpus
node_run -->|"runs model"| node_model
node_model -->|"produces motifs"| node_motif
node_web -->|"presents"| node_runlayout
node_web -->|"presents"| node_loadlayout
node_web -->|"presents"| node_rankings
node_web -->|"presents"| node_details
node_web -->|"presents"| node_network
node_web -->|"presents"| node_searchlayout
node_web -->|"registers callbacks"| node_callbacks
node_callbacks -->|"screens motifs"| node_screening
node_callbacks -->|"requests plots"| node_visuals
node_motif -.->|"annotated by"| node_spec2vec
node_motif -.->|"annotated by"| node_fingerprints
node_motif -.->|"searched by"| node_massqlmotif
node_searchlayout -->|"submits query"| node_parser
node_parser -->|"parses to"| node_engine
node_engine -->|"applies filters"| node_filters
node_engine -->|"loads spectra"| node_loader

click node_cli "https://github.com/vdhooftcompmet/ms2lda/blob/main/scripts/ms2lda_runfull.py"
click node_run "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/run.py"
click node_clean "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Preprocessing/load_and_clean.py"
click node_corpus "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Preprocessing/generate_corpus.py"
click node_model "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/modeling.py"
click node_motif "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Mass2Motif.py"
click node_document "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Mass2MotifDocument.py"
click node_web "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/app.py"
click node_callbacks "https://github.com/vdhooftcompmet/ms2lda/tree/main/App/callbacks"
click node_runlayout "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/run_analysis.py"
click node_loadlayout "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/load_results.py"
click node_rankings "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/motif_rankings.py"
click node_details "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/motif_details.py"
click node_network "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/network_view.py"
click node_visuals "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Visualisation/visualisation.py"
click node_screening "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Add_On/NTS/Screening.py"
click node_spec2vec "https://github.com/vdhooftcompmet/ms2lda/tree/main/MS2LDA/Add_On/Spec2Vec"
click node_fingerprints "https://github.com/vdhooftcompmet/ms2lda/tree/main/MS2LDA/Add_On/Fingerprints"
click node_massqlmotif "https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Add_On/MassQL/MassQL4MotifDB.py"
click node_searchlayout "https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/spectra_search.py"
click node_parser "https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_parser.py"
click node_engine "https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_engine.py"
click node_filters "https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_engine_filters.py"
click node_loader "https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_fileloading.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_run,node_clean,node_corpus,node_model,node_motif,node_document toneBlue
class node_screening,node_spec2vec,node_fingerprints,node_massqlmotif toneAmber
class node_web,node_callbacks,node_runlayout,node_loadlayout,node_rankings,node_details,node_network,node_visuals toneMint
class node_searchlayout,node_parser,node_engine,node_filters,node_loader toneRose
class node_researcher,node_spectra toneIndigo
```

## Components

### Analysis

- [CLI runner](https://github.com/vdhooftcompmet/ms2lda/blob/main/scripts/ms2lda_runfull.py): `scripts/ms2lda_runfull.py`
- [Analysis runner](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/run.py): `MS2LDA/run.py`
- [Load and clean](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Preprocessing/load_and_clean.py): `MS2LDA/Preprocessing/load_and_clean.py`
- [Corpus generation](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Preprocessing/generate_corpus.py): `MS2LDA/Preprocessing/generate_corpus.py`
- [Topic modeling](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/modeling.py): `MS2LDA/modeling.py`
- [Motif representation](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Mass2Motif.py): `MS2LDA/Mass2Motif.py`
- [Motif documents](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Mass2MotifDocument.py): `MS2LDA/Mass2MotifDocument.py`

### Motif Annotation

- [Motif screening](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Add_On/NTS/Screening.py): `MS2LDA/Add_On/NTS/Screening.py`
- [Spec2Vec annotation](https://github.com/vdhooftcompmet/ms2lda/tree/main/MS2LDA/Add_On/Spec2Vec): `MS2LDA/Add_On/Spec2Vec`
- [Fingerprint annotation](https://github.com/vdhooftcompmet/ms2lda/tree/main/MS2LDA/Add_On/Fingerprints): `MS2LDA/Add_On/Fingerprints`
- [Motif MassQL](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Add_On/MassQL/MassQL4MotifDB.py): `MS2LDA/Add_On/MassQL/MassQL4MotifDB.py`

### Exploration

- [MS2LDAViz app](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/app.py): `App/app.py`
- [UI callbacks](https://github.com/vdhooftcompmet/ms2lda/tree/main/App/callbacks): `App/callbacks`
- [Run analysis tab](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/run_analysis.py): `App/layout/run_analysis.py`
- [Load results tab](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/load_results.py): `App/layout/load_results.py`
- [Motif rankings](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/motif_rankings.py): `App/layout/motif_rankings.py`
- [Motif details](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/motif_details.py): `App/layout/motif_details.py`
- [Network view](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/network_view.py): `App/layout/network_view.py`
- [Visualizations](https://github.com/vdhooftcompmet/ms2lda/blob/main/MS2LDA/Visualisation/visualisation.py): `MS2LDA/Visualisation/visualisation.py`

### Spectral Queries

- [Spectra search tab](https://github.com/vdhooftcompmet/ms2lda/blob/main/App/layout/spectra_search.py): `App/layout/spectra_search.py`
- [MassQL parser](https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_parser.py): `massql4motifs/msql_parser.py`
- [Query engine](https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_engine.py): `massql4motifs/msql_engine.py`
- [Query filters](https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_engine_filters.py): `massql4motifs/msql_engine_filters.py`
- [Spectra loader](https://github.com/vdhooftcompmet/ms2lda/blob/main/massql4motifs/msql_fileloading.py): `massql4motifs/msql_fileloading.py`

### Other components

- **Researcher**
- **Spectra data**

## Connections

- Researcher → CLI runner: runs analysis
- Researcher → MS2LDAViz app: explores results
- Spectra data → Analysis runner: input spectra
- CLI runner → Analysis runner: invokes
- Analysis runner → Load and clean: preprocesses
- Load and clean → Corpus generation: builds corpus
- Analysis runner → Topic modeling: runs model
- Topic modeling → Motif representation: produces motifs
- MS2LDAViz app → Run analysis tab: presents
- MS2LDAViz app → Load results tab: presents
- MS2LDAViz app → Motif rankings: presents
- MS2LDAViz app → Motif details: presents
- MS2LDAViz app → Network view: presents
- MS2LDAViz app → Spectra search tab: presents
- MS2LDAViz app → UI callbacks: registers callbacks
- UI callbacks → Motif screening: screens motifs
- UI callbacks → Visualizations: requests plots
- Motif representation → Spec2Vec annotation: annotated by
- Motif representation → Fingerprint annotation: annotated by
- Motif representation → Motif MassQL: searched by
- Spectra search tab → MassQL parser: submits query
- MassQL parser → Query engine: parses to
- Query engine → Query filters: applies filters
- Query engine → Spectra loader: loads spectra