# foundation-lab-ai/lc_ns_women_chem_graph architecture

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

- Interactive diagram: https://gitdiagram.com/foundation-lab-ai/lc_ns_women_chem_graph
- Repository: https://github.com/foundation-lab-ai/lc_ns_women_chem_graph

## Overview

This research toolkit builds mass-difference graphs from untargeted plasma mass-spectrometry data, then evaluates chemical structure and disease-association patterns. The principal workflow is input parsing and feature QC, graph construction, and downstream discovery: testing modules, finding homologous series, proposing identities for unknowns, and diffusing association statistics. Additional scripts evaluate published modules and estimate chance edges. The README documents the study and capabilities; some downstream wiring is inferred only from command-line inputs and is shown only where those inputs are explicit.

Main entry points: [`scripts/discover.py`](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/discover.py) (Association discovery), [`scripts/annotate_to_graph.py`](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/annotate_to_graph.py) (Feature graph builder), [`scripts/edge_fdr.py`](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/edge_fdr.py) (Edge FDR), [`scripts/parse_mwtab.py`](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/parse_mwtab.py) (MWTab parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_parse["MWTab parser<br/>[parse_mwtab.py]"]
  node_prep["Feature QC<br/>[prep_results.py]"]
  node_pairing["Pair reconstruction"]
end

subgraph group_graph["Chemical graph"]
  node_annotation["Feature graph builder"]
  node_graphdata["Graph data"]
end

subgraph group_analysis["Graph analysis"]
  node_common["Analysis utilities<br/>[common.py]"]
  node_discover["Association discovery<br/>[discover.py]"]
  node_edgefdr["Edge FDR<br/>[edge_fdr.py]"]
  node_series["Series detection<br/>[find_series.py]"]
  node_unknowns["Unknown proposals"]
  node_propagate["Graph propagation<br/>[propagate.py]"]
end

subgraph group_validation["Study validation"]
  node_connectivity["Connectivity test"]
  node_match["ME16 matching<br/>[match_module.py]"]
  node_me8["ME8 evaluation<br/>[run_me8.py]"]
end

node_researcher(("Researcher"))
node_mwtab["MWTab study data"]
node_results["Results tables"]
node_pubmodule["Published modules"]
node_compounddb[("Compound database")]

node_researcher -->|"supplies data"| node_parse
node_mwtab -->|"parses"| node_parse
node_results -->|"filters features"| node_prep
node_parse -.->|"provides metadata"| node_prep
node_prep -->|"provides features"| node_annotation
node_compounddb -.->|"optional annotation"| node_annotation
node_annotation -->|"writes graph"| node_graphdata
node_researcher -->|"configures build"| node_annotation
node_researcher -->|"requests pairing"| node_pairing
node_pairing -.->|"reads metadata"| node_parse
node_researcher -->|"requests analysis"| node_discover
node_discover -->|"reads graph"| node_graphdata
node_common -->|"provides statistics"| node_discover
node_graphdata -->|"counts edges"| node_edgefdr
node_annotation -->|"provides transformations"| node_edgefdr
node_graphdata -->|"enumerates relations"| node_series
node_edgefdr -.->|"optional edge filter"| node_series
node_graphdata -->|"finds neighbors"| node_unknowns
node_discover -->|"supplies feature ranks"| node_unknowns
node_graphdata -->|"diffuses statistics"| node_propagate
node_common -->|"provides statistics"| node_propagate
node_edgefdr -.->|"optional edge filter"| node_propagate
node_graphdata -->|"tests subgraph"| node_connectivity
node_pubmodule -->|"provides ME16"| node_match
node_discover -->|"provides feature results"| node_match
node_pubmodule -->|"provides ME8"| node_me8
node_discover -->|"provides analysis results"| node_me8

click node_parse "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/parse_mwtab.py"
click node_prep "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/prep_results.py"
click node_pairing "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/reconstruct_pairs.py"
click node_annotation "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/annotate_to_graph.py"
click node_common "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/common.py"
click node_discover "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/discover.py"
click node_edgefdr "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/edge_fdr.py"
click node_series "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/find_series.py"
click node_unknowns "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/explore_unknowns.py"
click node_propagate "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/propagate.py"
click node_connectivity "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/module_connectivity.py"
click node_match "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/match_module.py"
click node_me8 "https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/run_me8.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_parse,node_prep,node_pairing toneBlue
class node_annotation,node_graphdata,node_compounddb toneAmber
class node_common,node_discover,node_edgefdr,node_series,node_unknowns,node_propagate toneMint
class node_connectivity,node_match,node_me8 toneRose
class node_researcher,node_mwtab,node_results,node_pubmodule toneIndigo
```

## Components

### Data preparation

- [MWTab parser](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/parse_mwtab.py): `scripts/parse_mwtab.py`
- [Feature QC](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/prep_results.py): `scripts/prep_results.py`
- [Pair reconstruction](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/reconstruct_pairs.py): `scripts/reconstruct_pairs.py`

### Chemical graph

- [Feature graph builder](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/annotate_to_graph.py): `scripts/annotate_to_graph.py`
- **Graph data**

### Graph analysis

- [Analysis utilities](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/common.py): `scripts/common.py`
- [Association discovery](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/discover.py): `scripts/discover.py`
- [Edge FDR](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/edge_fdr.py): `scripts/edge_fdr.py`
- [Series detection](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/find_series.py): `scripts/find_series.py`
- [Unknown proposals](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/explore_unknowns.py): `scripts/explore_unknowns.py`
- [Graph propagation](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/propagate.py): `scripts/propagate.py`

### Study validation

- [Connectivity test](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/module_connectivity.py): `scripts/module_connectivity.py`
- [ME16 matching](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/match_module.py): `scripts/match_module.py`
- [ME8 evaluation](https://github.com/foundation-lab-ai/lc_ns_women_chem_graph/blob/main/scripts/run_me8.py): `scripts/run_me8.py`

### Other components

- **Researcher**
- **MWTab study data**
- **Results tables**
- **Published modules**
- **Compound database**

## Connections

- Researcher → MWTab parser: supplies data
- MWTab study data → MWTab parser: parses
- Results tables → Feature QC: filters features
- MWTab parser → Feature QC: provides metadata
- Feature QC → Feature graph builder: provides features
- Compound database → Feature graph builder: optional annotation
- Feature graph builder → Graph data: writes graph
- Researcher → Feature graph builder: configures build
- Researcher → Pair reconstruction: requests pairing
- Pair reconstruction → MWTab parser: reads metadata
- Researcher → Association discovery: requests analysis
- Association discovery → Graph data: reads graph
- Analysis utilities → Association discovery: provides statistics
- Graph data → Edge FDR: counts edges
- Feature graph builder → Edge FDR: provides transformations
- Graph data → Series detection: enumerates relations
- Edge FDR → Series detection: optional edge filter
- Graph data → Unknown proposals: finds neighbors
- Association discovery → Unknown proposals: supplies feature ranks
- Graph data → Graph propagation: diffuses statistics
- Analysis utilities → Graph propagation: provides statistics
- Edge FDR → Graph propagation: optional edge filter
- Graph data → Connectivity test: tests subgraph
- Published modules → ME16 matching: provides ME16
- Association discovery → ME16 matching: provides feature results
- Published modules → ME8 evaluation: provides ME8
- Association discovery → ME8 evaluation: provides analysis results