# phenological/python-nmr-parser architecture

> Architecture diagram of the GitHub repository phenological/python-nmr-parser, 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/phenological/python-nmr-parser
- Repository: https://github.com/phenological/python-nmr-parser

## Overview

nmr-parser reads Bruker IVDr experiment folders into structured parameters, spectra, and assay results; its higher-level parse_nmr workflow scans and consolidates runs for tabular export and optional DuckDB querying. The graph preserves the distinct spectrum, XML assay, QC, and lipoprotein-processing capabilities documented in the README. Wiring is based on the supplied excerpts and README; unsampled parser and export internals are represented only where their documented role is clear.

Main entry points: [`src/nmr_parser/core/experiment.py`](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/experiment.py) (Experiment reader), [`src/nmr_parser/reference/tables.py`](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/reference/tables.py) (Reference tables), [`src/nmr_parser/core/parse_nmr.py`](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/parse_nmr.py) (Batch parser), [`src/nmr_parser/xml_parsers/quality_control.py`](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/quality_control.py) (QC parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment_io["Experiment reading"]
  node_experiment_reader["Experiment reader<br/>[experiment.py]"]
  node_folder_scanner["Folder scanner<br/>[folders.py]"]
  node_parameters["Parameter reader<br/>[parameters.py]"]
  node_spectrum["Spectrum reader<br/>[spectrum.py]"]
end

subgraph group_assay_parsing["Assay parsing"]
  node_xml_quant["Quantification parser<br/>[quantification.py]"]
  node_xml_lipo["Lipoprotein parser<br/>[lipoproteins.py]"]
  node_xml_qc["QC parser<br/>[quality_control.py]"]
  node_xml_pacs["PACS parser<br/>[pacs.py]"]
  node_xml_eretic["ERETIC parser<br/>[eretic.py]"]
  node_xml_title["Title parser<br/>[title.py]"]
end

subgraph group_processing["Processing and references"]
  node_lipo_extension["Lipoprotein extension"]
  node_name_cleanup["Name cleanup<br/>[utils.py]"]
  node_reference_tables["Reference tables<br/>[tables.py]"]
end

subgraph group_batch_export["Batch export"]
  node_batch_parser["Batch parser<br/>[parse_nmr.py]"]
end

node_bruker_files(("Bruker experiment files"))
node_parquet_files["Parquet outputs"]
node_duckdb[("DuckDB database")]

node_bruker_files -->|"provides files"| node_experiment_reader
node_experiment_reader -->|"reads parameters"| node_parameters
node_experiment_reader -->|"reads spectra"| node_spectrum
node_experiment_reader -->|"reads reports"| node_xml_quant
node_experiment_reader -->|"reads reports"| node_xml_lipo
node_experiment_reader -->|"reads reports"| node_xml_qc
node_experiment_reader -->|"reads reports"| node_xml_pacs
node_experiment_reader -->|"reads calibration"| node_xml_eretic
node_experiment_reader -->|"reads titles"| node_xml_title
node_spectrum -->|"reads settings"| node_parameters
node_xml_qc -->|"cleans names"| node_name_cleanup
node_reference_tables -->|"parses references"| node_xml_qc
node_reference_tables -->|"parses references"| node_xml_pacs
node_reference_tables -->|"parses references"| node_xml_quant
node_batch_parser -->|"scans folders"| node_folder_scanner
node_batch_parser -->|"writes data"| node_parquet_files
node_batch_parser -.->|"creates database"| node_duckdb

click node_experiment_reader "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/experiment.py"
click node_folder_scanner "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/folders.py"
click node_parameters "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/parameters.py"
click node_spectrum "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/spectrum.py"
click node_xml_quant "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/quantification.py"
click node_xml_lipo "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/lipoproteins.py"
click node_xml_qc "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/quality_control.py"
click node_xml_pacs "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/pacs.py"
click node_xml_eretic "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/eretic.py"
click node_xml_title "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/title.py"
click node_lipo_extension "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/processing/lipoprotein_calc.py"
click node_name_cleanup "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/processing/utils.py"
click node_reference_tables "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/reference/tables.py"
click node_batch_parser "https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/parse_nmr.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_experiment_reader,node_folder_scanner,node_parameters,node_spectrum toneBlue
class node_xml_quant,node_xml_lipo,node_xml_qc,node_xml_pacs,node_xml_eretic,node_xml_title,node_duckdb toneAmber
class node_lipo_extension,node_name_cleanup,node_reference_tables toneMint
class node_batch_parser toneRose
class node_bruker_files,node_parquet_files toneIndigo
```

## Components

### Experiment reading

- [Experiment reader](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/experiment.py): `src/nmr_parser/core/experiment.py`
- [Folder scanner](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/folders.py): `src/nmr_parser/core/folders.py`
- [Parameter reader](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/parameters.py): `src/nmr_parser/core/parameters.py`
- [Spectrum reader](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/spectrum.py): `src/nmr_parser/core/spectrum.py`

### Assay parsing

- [Quantification parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/quantification.py): `src/nmr_parser/xml_parsers/quantification.py`
- [Lipoprotein parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/lipoproteins.py): `src/nmr_parser/xml_parsers/lipoproteins.py`
- [QC parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/quality_control.py): `src/nmr_parser/xml_parsers/quality_control.py`
- [PACS parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/pacs.py): `src/nmr_parser/xml_parsers/pacs.py`
- [ERETIC parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/eretic.py): `src/nmr_parser/xml_parsers/eretic.py`
- [Title parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/xml_parsers/title.py): `src/nmr_parser/xml_parsers/title.py`

### Processing and references

- [Lipoprotein extension](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/processing/lipoprotein_calc.py): `src/nmr_parser/processing/lipoprotein_calc.py`
- [Name cleanup](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/processing/utils.py): `src/nmr_parser/processing/utils.py`
- [Reference tables](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/reference/tables.py): `src/nmr_parser/reference/tables.py`

### Batch export

- [Batch parser](https://github.com/phenological/python-nmr-parser/blob/main/src/nmr_parser/core/parse_nmr.py): `src/nmr_parser/core/parse_nmr.py`

### Other components

- **Bruker experiment files**
- **Parquet outputs**
- **DuckDB database**

## Connections

- Bruker experiment files → Experiment reader: provides files
- Experiment reader → Parameter reader: reads parameters
- Experiment reader → Spectrum reader: reads spectra
- Experiment reader → Quantification parser: reads reports
- Experiment reader → Lipoprotein parser: reads reports
- Experiment reader → QC parser: reads reports
- Experiment reader → PACS parser: reads reports
- Experiment reader → ERETIC parser: reads calibration
- Experiment reader → Title parser: reads titles
- Spectrum reader → Parameter reader: reads settings
- QC parser → Name cleanup: cleans names
- Reference tables → QC parser: parses references
- Reference tables → PACS parser: parses references
- Reference tables → Quantification parser: parses references
- Batch parser → Folder scanner: scans folders
- Batch parser → Parquet outputs: writes data
- Batch parser → DuckDB database: creates database