# brunetch123/k2-annotator architecture

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

- Interactive diagram: https://gitdiagram.com/brunetch123/k2-annotator
- Repository: https://github.com/brunetch123/k2-annotator

## Overview

K2 Annotator processes GC-MS data into Level 2 compound annotations, with optional hazard assessment and surrogate recovery reporting. Users can start in the GUI or CLI; the full GUI workflow can convert raw files and run MZmine before matching, while preprocessed feature tables enter at matching. The graph preserves parsing, calibration, normalization, scoring, reporting, provenance and documented external services. Some subsystem links are documented by the README; unsampled implementation details are not inferred.

Main entry points: [`scripts/cli.py`](https://github.com/brunetch123/k2-annotator/blob/main/scripts/cli.py) (Command Line), [`scripts/src/matching_engine.py`](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/matching_engine.py) (Matching Engine), [`scripts/gcms_pipeline.py`](https://github.com/brunetch123/k2-annotator/blob/main/scripts/gcms_pipeline.py) (GC-MS Pipeline), [`scripts/src/structure_helper.py`](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/structure_helper.py) (Structure & Hazard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_gui["Workflow GUI<br/>[k2_gui.py]"]
  node_screens["GUI Screens<br/>[k2_screens.py]"]
  node_cli["Command Line<br/>[cli.py]"]
end

subgraph group_preprocess["Data Preparation"]
  node_pipeline["GC-MS Pipeline<br/>[gcms_pipeline.py]"]
  node_msconvert["MSConvert"]
  node_mzmine["MZmine"]
end

subgraph group_identify["Identification"]
  node_features["Feature Parser"]
  node_ri["RI Calibration<br/>[ri_calibration.py]"]
  node_msp["MSP Reader<br/>[msp_reader.py]"]
  node_library["Library Parser<br/>[library_parser.py]"]
  node_normalizer["IS Normalizer<br/>[is_normalizer.py]"]
  node_matcher["Matching Engine<br/>[matching_engine.py]"]
  node_spectral["Spectral Scoring<br/>[spectral_math.py]"]
  node_rhrmf["RHR Mass Filter<br/>[rhrmf.py]"]
end

subgraph group_assess["Assessment"]
  node_surrogate["Recovery Analysis"]
  node_hazard["Structure &amp; Hazard"]
  node_ctx["EPA CompTox Client<br/>[ctx_client.py]"]
  node_http["HTTP Session<br/>[http_session.py]"]
end

subgraph group_outputs["Results"]
  node_reporter["Report Generator<br/>[reporter.py]"]
  node_summary["Summary Tables<br/>[summary_tables.py]"]
  node_surrogate_report["Recovery Reports"]
  node_manifest["Run Provenance<br/>[run_manifest.py]"]
end

node_user(("Analyst"))
node_epa["EPA CompTox"]
node_pubchem["PubChem"]

node_user -->|"starts workflow"| node_gui
node_user -->|"runs matching"| node_cli
node_gui -->|"presents screens"| node_screens
node_screens -->|"starts pipeline"| node_pipeline
node_pipeline -->|"converts raw files"| node_msconvert
node_pipeline -->|"runs feature detection"| node_mzmine
node_pipeline -->|"invokes matching"| node_cli
node_cli -->|"runs matching"| node_matcher
node_matcher -->|"parses features"| node_features
node_matcher -->|"loads library"| node_library
node_features -->|"calibrates RI"| node_ri
node_library -->|"reads MSP"| node_msp
node_matcher -->|"normalizes abundances"| node_normalizer
node_matcher -->|"scores spectra"| node_spectral
node_matcher -->|"filters matches"| node_rhrmf
node_rhrmf -->|"uses mass math"| node_spectral
node_cli -->|"analyzes recovery"| node_surrogate
node_surrogate -->|"loads standards"| node_library
node_cli -.->|"requests hazard data"| node_hazard
node_hazard -->|"queries toxicity"| node_ctx
node_hazard -->|"sends HTTP requests"| node_http
node_ctx -->|"looks up hazards"| node_epa
node_http -->|"fetches structures"| node_pubchem
node_cli -->|"generates reports"| node_reporter
node_reporter -->|"builds summaries"| node_summary
node_reporter -->|"adds recovery reports"| node_surrogate_report
node_cli -->|"records provenance"| node_manifest
node_surrogate_report -->|"formats results"| node_surrogate

click node_gui "https://github.com/brunetch123/k2-annotator/blob/main/scripts/k2_gui.py"
click node_screens "https://github.com/brunetch123/k2-annotator/blob/main/scripts/k2_screens.py"
click node_cli "https://github.com/brunetch123/k2-annotator/blob/main/scripts/cli.py"
click node_pipeline "https://github.com/brunetch123/k2-annotator/blob/main/scripts/gcms_pipeline.py"
click node_features "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/universal_parser.py"
click node_ri "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/ri_calibration.py"
click node_msp "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/msp_reader.py"
click node_library "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/library_parser.py"
click node_normalizer "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/is_normalizer.py"
click node_matcher "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/matching_engine.py"
click node_spectral "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/spectral_math.py"
click node_rhrmf "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/rhrmf.py"
click node_surrogate "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/surrogate_analyzer.py"
click node_hazard "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/structure_helper.py"
click node_ctx "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/ctx_client.py"
click node_http "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/http_session.py"
click node_reporter "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/reporter.py"
click node_summary "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/summary_tables.py"
click node_surrogate_report "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/surrogate_reporter.py"
click node_manifest "https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/run_manifest.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_gui,node_screens,node_cli toneBlue
class node_pipeline,node_msconvert,node_mzmine toneAmber
class node_features,node_ri,node_msp,node_library,node_normalizer,node_matcher,node_spectral,node_rhrmf toneMint
class node_surrogate,node_hazard,node_ctx,node_http toneRose
class node_reporter,node_summary,node_surrogate_report,node_manifest,node_user,node_epa,node_pubchem toneIndigo
```

## Components

### User Entry

- [Workflow GUI](https://github.com/brunetch123/k2-annotator/blob/main/scripts/k2_gui.py): `scripts/k2_gui.py`
- [GUI Screens](https://github.com/brunetch123/k2-annotator/blob/main/scripts/k2_screens.py): `scripts/k2_screens.py`
- [Command Line](https://github.com/brunetch123/k2-annotator/blob/main/scripts/cli.py): `scripts/cli.py`

### Data Preparation

- [GC-MS Pipeline](https://github.com/brunetch123/k2-annotator/blob/main/scripts/gcms_pipeline.py): `scripts/gcms_pipeline.py`
- **MSConvert**
- **MZmine**

### Identification

- [Feature Parser](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/universal_parser.py): `scripts/src/universal_parser.py`
- [RI Calibration](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/ri_calibration.py): `scripts/src/ri_calibration.py`
- [MSP Reader](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/msp_reader.py): `scripts/src/msp_reader.py`
- [Library Parser](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/library_parser.py): `scripts/src/library_parser.py`
- [IS Normalizer](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/is_normalizer.py): `scripts/src/is_normalizer.py`
- [Matching Engine](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/matching_engine.py): `scripts/src/matching_engine.py`
- [Spectral Scoring](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/spectral_math.py): `scripts/src/spectral_math.py`
- [RHR Mass Filter](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/rhrmf.py): `scripts/src/rhrmf.py`

### Assessment

- [Recovery Analysis](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/surrogate_analyzer.py): `scripts/src/surrogate_analyzer.py`
- [Structure & Hazard](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/structure_helper.py): `scripts/src/structure_helper.py`
- [EPA CompTox Client](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/ctx_client.py): `scripts/src/ctx_client.py`
- [HTTP Session](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/http_session.py): `scripts/src/http_session.py`

### Results

- [Report Generator](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/reporter.py): `scripts/src/reporter.py`
- [Summary Tables](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/summary_tables.py): `scripts/src/summary_tables.py`
- [Recovery Reports](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/surrogate_reporter.py): `scripts/src/surrogate_reporter.py`
- [Run Provenance](https://github.com/brunetch123/k2-annotator/blob/main/scripts/src/run_manifest.py): `scripts/src/run_manifest.py`

### Other components

- **Analyst**
- **EPA CompTox**
- **PubChem**

## Connections

- Analyst → Workflow GUI: starts workflow (evidence: `README.md`)
- Analyst → Command Line: runs matching (evidence: `README.md`)
- Workflow GUI → GUI Screens: presents screens (evidence: `scripts/k2_gui.py`)
- GUI Screens → GC-MS Pipeline: starts pipeline (evidence: `scripts/k2_screens.py`)
- GC-MS Pipeline → MSConvert: converts raw files (evidence: `README.md`)
- GC-MS Pipeline → MZmine: runs feature detection (evidence: `README.md`)
- GC-MS Pipeline → Command Line: invokes matching (evidence: `scripts/gcms_pipeline.py`)
- Command Line → Matching Engine: runs matching (evidence: `scripts/cli.py`)
- Matching Engine → Feature Parser: parses features (evidence: `scripts/src/matching_engine.py`)
- Matching Engine → Library Parser: loads library (evidence: `scripts/src/matching_engine.py`)
- Feature Parser → RI Calibration: calibrates RI (evidence: `scripts/src/universal_parser.py`)
- Library Parser → MSP Reader: reads MSP (evidence: `scripts/src/library_parser.py`)
- Matching Engine → IS Normalizer: normalizes abundances (evidence: `scripts/src/matching_engine.py`)
- Matching Engine → Spectral Scoring: scores spectra (evidence: `scripts/src/matching_engine.py`)
- Matching Engine → RHR Mass Filter: filters matches (evidence: `scripts/src/matching_engine.py`)
- RHR Mass Filter → Spectral Scoring: uses mass math (evidence: `scripts/src/rhrmf.py`)
- Command Line → Recovery Analysis: analyzes recovery (evidence: `scripts/cli.py`)
- Recovery Analysis → Library Parser: loads standards (evidence: `scripts/src/surrogate_analyzer.py`)
- Command Line → Structure & Hazard: requests hazard data
- Structure & Hazard → EPA CompTox Client: queries toxicity (evidence: `scripts/src/structure_helper.py`)
- Structure & Hazard → HTTP Session: sends HTTP requests (evidence: `scripts/src/structure_helper.py`)
- EPA CompTox Client → EPA CompTox: looks up hazards (evidence: `README.md`)
- HTTP Session → PubChem: fetches structures
- Command Line → Report Generator: generates reports (evidence: `scripts/cli.py`)
- Report Generator → Summary Tables: builds summaries (evidence: `scripts/src/reporter.py`)
- Report Generator → Recovery Reports: adds recovery reports (evidence: `scripts/src/reporter.py`)
- Command Line → Run Provenance: records provenance (evidence: `scripts/cli.py`)
- Recovery Reports → Recovery Analysis: formats results (evidence: `scripts/src/surrogate_reporter.py`)