# vdhooftcompmet/mosaic-ms architecture

> Architecture diagram of the GitHub repository vdhooftcompmet/mosaic-ms, 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/mosaic-ms
- Repository: https://github.com/vdhooftcompmet/mosaic-ms

## Overview

Mosaic-MS turns input mass spectra into molecular networks, discovers MS2LDA motifs, maps structural candidates with SNAP-MS, and integrates those annotations into Cytoscape CX graphs. The CLI dispatches each stage and offers an end-to-end workflow. The graph follows the documented stages and sampled call sites; implementation details for some subsystems are unsampled, so their internal wiring is shown only where README documentation supports it.

Main entry points: [`src/utils/cx.py`](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/utils/cx.py) (CX I/O), [`src/cli.py`](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/cli.py) (CLI and workflow), [`src/snapms/main.py`](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/main.py) (SNAP-MS workflow), [`src/add_ms2lda/main.py`](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/add_ms2lda/main.py) (Motif integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Pipeline entry"]
  node_cli["CLI and workflow<br/>[cli.py]"]
end

subgraph group_network["Molecular networking"]
  node_mn_main["Network workflow<br/>[main.py]"]
  node_mn_bootstrap["Similarity bootstrap<br/>[bootstrap.py]"]
  node_mn_network["Graph construction<br/>[network.py]"]
  node_cx["CX I/O<br/>[cx.py]"]
end

subgraph group_motifs["Motif discovery"]
  node_ms_main["MS2LDA workflow<br/>[main.py]"]
  node_preprocess["Spectrum preprocessing<br/>[preprocessing.py]"]
  node_lda["Motif model<br/>[lda.py]"]
  node_storage["Model and motif storage<br/>[storage.py]"]
end

subgraph group_annotation["Structural annotation"]
  node_snap_main["SNAP-MS workflow<br/>[main.py]"]
  node_mass_matches["Mass matching<br/>[masses.py]"]
  node_snap_network["Candidate families<br/>[network.py]"]
  node_add_motifs["Motif integration<br/>[main.py]"]
  node_add_snap["SNAP-MS integration<br/>[main.py]"]
end

node_user(("Researcher"))
node_mgf["MGF spectra"]
node_network_graph["Molecular network"]
node_model_artifacts["Model and motifs"]
node_reference_db[("Reference structures")]
node_snap_graphs["SNAP-MS graphs"]
node_integrated_graph["Enriched CX graph"]
node_cytoscape(("Cytoscape user"))

node_user -->|"runs command"| node_cli
node_mgf -->|"provides spectra"| node_mn_main
node_mgf -->|"provides spectra"| node_ms_main
node_cli -->|"dispatches"| node_mn_main
node_cli -->|"dispatches"| node_ms_main
node_cli -->|"dispatches"| node_snap_main
node_cli -->|"dispatches"| node_add_motifs
node_cli -->|"dispatches"| node_add_snap
node_mn_main -->|"calculates similarities"| node_mn_bootstrap
node_mn_main -->|"builds graph"| node_mn_network
node_mn_main -->|"writes CX"| node_cx
node_cx -->|"writes network"| node_network_graph
node_ms_main -->|"prepares spectra"| node_preprocess
node_ms_main -->|"trains and extracts"| node_lda
node_ms_main -->|"stores outputs"| node_storage
node_storage -->|"writes model and motifs"| node_model_artifacts
node_snap_main -->|"reads network"| node_cx
node_snap_main -->|"matches candidates"| node_mass_matches
node_snap_main -->|"loads structures"| node_reference_db
node_snap_main -->|"builds candidate families"| node_snap_network
node_snap_main -->|"writes CX"| node_cx
node_cx -->|"writes annotations"| node_snap_graphs
node_add_motifs -->|"reads and writes CX"| node_cx
node_add_motifs -->|"loads model"| node_model_artifacts
node_add_motifs -->|"converts spectra"| node_preprocess
node_add_motifs -->|"adds motif metadata"| node_integrated_graph
node_add_snap -->|"reads and writes CX"| node_cx
node_add_snap -->|"reads annotations"| node_snap_graphs
node_add_snap -->|"adds annotations"| node_integrated_graph
node_integrated_graph -->|"opens in"| node_cytoscape

click node_cli "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/cli.py"
click node_mn_main "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/main.py"
click node_mn_bootstrap "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/bootstrap.py"
click node_mn_network "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/network.py"
click node_cx "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/utils/cx.py"
click node_network_graph "https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results"
click node_ms_main "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/main.py"
click node_preprocess "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/preprocessing.py"
click node_lda "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/lda.py"
click node_storage "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/storage.py"
click node_model_artifacts "https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results"
click node_snap_main "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/main.py"
click node_mass_matches "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/masses.py"
click node_snap_network "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/network.py"
click node_snap_graphs "https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results"
click node_add_motifs "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/add_ms2lda/main.py"
click node_add_snap "https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/add_snapms/main.py"
click node_integrated_graph "https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results"

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_cytoscape toneBlue
class node_mn_main,node_mn_bootstrap,node_mn_network,node_cx,node_reference_db toneAmber
class node_ms_main,node_preprocess,node_lda,node_storage toneMint
class node_snap_main,node_mass_matches,node_snap_network,node_add_motifs,node_add_snap toneRose
class node_user,node_mgf,node_model_artifacts toneIndigo
class node_network_graph,node_snap_graphs,node_integrated_graph toneTeal
```

## Components

### Pipeline entry

- [CLI and workflow](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/cli.py): `src/cli.py`

### Molecular networking

- [Network workflow](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/main.py): `src/mn/main.py`
- [Similarity bootstrap](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/bootstrap.py): `src/mn/bootstrap.py`
- [Graph construction](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/mn/network.py): `src/mn/network.py`
- [CX I/O](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/utils/cx.py): `src/utils/cx.py`

### Motif discovery

- [MS2LDA workflow](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/main.py): `src/ms2lda/main.py`
- [Spectrum preprocessing](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/preprocessing.py): `src/ms2lda/preprocessing.py`
- [Motif model](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/lda.py): `src/ms2lda/lda.py`
- [Model and motif storage](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/ms2lda/storage.py): `src/ms2lda/storage.py`

### Structural annotation

- [SNAP-MS workflow](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/main.py): `src/snapms/main.py`
- [Mass matching](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/masses.py): `src/snapms/masses.py`
- [Candidate families](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/snapms/network.py): `src/snapms/network.py`
- [Motif integration](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/add_ms2lda/main.py): `src/add_ms2lda/main.py`
- [SNAP-MS integration](https://github.com/vdhooftcompmet/mosaic-ms/blob/master/src/add_snapms/main.py): `src/add_snapms/main.py`

### Other components

- **Researcher**
- **MGF spectra**
- [Molecular network](https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results): `results`
- [Model and motifs](https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results): `results`
- **Reference structures**
- [SNAP-MS graphs](https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results): `results`
- [Enriched CX graph](https://github.com/vdhooftcompmet/mosaic-ms/tree/master/results): `results`
- **Cytoscape user**

## Connections

- Researcher → CLI and workflow: runs command
- MGF spectra → Network workflow: provides spectra
- MGF spectra → MS2LDA workflow: provides spectra
- CLI and workflow → Network workflow: dispatches
- CLI and workflow → MS2LDA workflow: dispatches
- CLI and workflow → SNAP-MS workflow: dispatches
- CLI and workflow → Motif integration: dispatches
- CLI and workflow → SNAP-MS integration: dispatches
- Network workflow → Similarity bootstrap: calculates similarities
- Network workflow → Graph construction: builds graph
- Network workflow → CX I/O: writes CX
- CX I/O → Molecular network: writes network
- MS2LDA workflow → Spectrum preprocessing: prepares spectra
- MS2LDA workflow → Motif model: trains and extracts
- MS2LDA workflow → Model and motif storage: stores outputs
- Model and motif storage → Model and motifs: writes model and motifs
- SNAP-MS workflow → CX I/O: reads network
- SNAP-MS workflow → Mass matching: matches candidates
- SNAP-MS workflow → Reference structures: loads structures
- SNAP-MS workflow → Candidate families: builds candidate families
- SNAP-MS workflow → CX I/O: writes CX
- CX I/O → SNAP-MS graphs: writes annotations
- Motif integration → CX I/O: reads and writes CX
- Motif integration → Model and motifs: loads model
- Motif integration → Spectrum preprocessing: converts spectra
- Motif integration → Enriched CX graph: adds motif metadata
- SNAP-MS integration → CX I/O: reads and writes CX
- SNAP-MS integration → SNAP-MS graphs: reads annotations
- SNAP-MS integration → Enriched CX graph: adds annotations
- Enriched CX graph → Cytoscape user: opens in