# vortexpixelz/gjb2-mcore-sonification architecture

> Architecture diagram of the GitHub repository vortexpixelz/gjb2-mcore-sonification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vortexpixelz/gjb2-mcore-sonification
- Repository: https://github.com/vortexpixelz/gjb2-mcore-sonification

## Overview

1. **Repository purpose**
   - This repo is a companion to a manuscript about two related but separate workflows:
     - **MCORE-1 ternary encoding / sequence analysis** of the GJB2 (Connexin 26) coding sequence.
     - **Gabor-atom sonification** of the wildtype sequence and two pathogenic deletion alleles.
   - The code supports both the **paper artifacts** and the **audio artifacts**.

2. **Primary subsystems**
   - **Analysis subsystem**: `code/analysis.py`
     - Produces the figures and table fragments used by the LaTeX paper.
   - **Sonification subsystem**: `code/gjb2_sonification.py`
     - Generates the WAV audio files for the sequences.
   - **Manuscript subsystem**: `paper/main.tex` plus supporting figure/table files and bibliography.
   - **Published artifacts**: committed reference WAVs under `audio/`.

3. **Data source and ingestion boundary**
   - The scripts do **not** rely on a checked-in FASTA file.
   - The reference transcript **NM_004004.6** is fetched live from **NCBI via E-utilities** when the scripts run.
   - That makes NCBI an external dependency and the repository’s main data-ingestion boundary.

4. **Analysis flow**
   - `code/analysis.py` is the reproducibility entry point for the manuscript’s quantitative outputs.
   - It generates LaTeX-ready fragments in `paper/figures/`, specifically:
     - `analysis_stats.tex`
     - `summary_table.tex`
   - These are then included by `paper/main.tex` during paper compilation.

5. **Sonification flow**
   - `code/gjb2_sonification.py` is the synthesis entry point.
   - It converts the sequence/allele representations into audio and writes rendered WAV files.
   - The README notes the output location is controlled by `OUTPUT_DIR` in that script, with a default path outside the repo (`/mnt/user-data/outputs`).
   - Committed copies of the generated WAVs are stored under `audio/` as reference outputs.

6. **What the audio artifacts represent**
   - The repository includes three rendered WAVs corresponding to:
     - `gjb2_wildtype.wav`
     - `gjb2_delta_c35delG.wav`
     - `gjb2_delta_c235delC.wav`
   - These appear both at the repo root and under `audio/`, suggesting the root copies are convenience artifacts while `audio/` is the curated committed location referenced by the README.

7. **Paper assembly boundary**
   - The LaTeX manuscript in `paper/main.tex` is built separately from the Python scripts.
   - The build chain is standard TeX tooling:
     - `pdflatex`
     - `bibtex`
     - repeated `pdflatex` runs
   - `paper/references.bib` is the bibliography source.
   - The Python analysis outputs are consumed by the paper as generated inputs, not manually authored content.

8. **Technology stack**
   - Core implementation language: **Python 3.10+**
   - Python dependencies are installed from `code/requirements.txt`.
   - Document production: **LaTeX/BibTeX**
   - Output media format: **WAV audio**

9. **Important artifact boundaries**
   - Source code lives in `code/`.
   - Generated manuscript fragments live in `paper/figures/`.
   - Final audio artifacts live in `audio/`.
   - The repo is therefore organized around **reproducible generation** rather than a runtime application or service.

10. **End-to-end architecture**
   - External biological sequence data is fetched from NCBI.
   - Python analysis transforms the sequence into publication tables/figures.
   - Python sonification transforms sequence/allele representations into audio waveforms.
   - LaTeX consumes the generated analysis fragments to produce the manuscript.
   - The checked-in WAVs and figure fragments serve as reproducible reference outputs for the paper.

Main entry points: [`code/gjb2_sonification.py`](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/gjb2_sonification.py) (GJB2 synth), [`code/analysis.py`](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/analysis.py) (Analysis), [`paper/main.tex`](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/main.tex) (Main tex), [`audio`](https://github.com/vortexpixelz/gjb2-mcore-sonification/tree/main/audio) (Audio dir)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_code["Python code"]
  node_node_analysis["Analysis<br/>python script<br/>[analysis.py]"]
  node_node_sonification["GJB2 synth<br/>python script"]
  node_node_mcore_sonification["MCORE synth<br/>python module"]
  node_node_requirements["Requirements<br/>python deps<br/>[requirements.txt]"]
end

subgraph group_group_paper["Manuscript"]
  node_node_main_tex["Main tex<br/>latex manuscript<br/>[main.tex]"]
  node_node_refs_bib["Bibliography<br/>bibtex source<br/>[references.bib]"]
  node_node_analysis_stats["Stats fragment<br/>generated tex<br/>[analysis_stats.tex]"]
  node_node_summary_table["Summary table<br/>generated tex<br/>[summary_table.tex]"]
end

subgraph group_group_audio["Audio artifacts"]
  node_node_audio_dir[("Audio dir<br/>artifact set")]
  node_node_wt_audio["Wildtype WAV<br/>audio artifact<br/>[gjb2_wildtype.wav]"]
  node_node_del35_audio["Δc35delG WAV<br/>audio artifact"]
  node_node_del235_audio["Δc235delC WAV<br/>audio artifact"]
end

subgraph group_group_external["External data"]
  node_node_ncbi(("NCBI E-utilities<br/>external sequence API"))
end

node_node_readme["README<br/>repo guide<br/>[README.md]"]

node_node_readme -->|"describes"| node_node_analysis
node_node_readme -->|"describes"| node_node_sonification
node_node_analysis -->|"fetches sequence"| node_node_ncbi
node_node_sonification -->|"fetches sequence"| node_node_ncbi
node_node_analysis -->|"writes"| node_node_analysis_stats
node_node_analysis -->|"writes"| node_node_summary_table
node_node_main_tex -->|"includes"| node_node_analysis_stats
node_node_main_tex -->|"includes"| node_node_summary_table
node_node_main_tex -->|"uses"| node_node_refs_bib
node_node_sonification -->|"renders"| node_node_wt_audio
node_node_sonification -->|"renders"| node_node_del35_audio
node_node_sonification -->|"renders"| node_node_del235_audio
node_node_audio_dir -->|"contains"| node_node_wt_audio
node_node_audio_dir -->|"contains"| node_node_del35_audio
node_node_audio_dir -->|"contains"| node_node_del235_audio
node_node_analysis -.->|"depends on"| node_node_requirements
node_node_sonification -.->|"depends on"| node_node_requirements
node_node_mcore_sonification -.->|"fetches sequence"| node_node_ncbi
node_node_mcore_sonification -.->|"depends on"| node_node_requirements

click node_node_readme "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/README.md"
click node_node_analysis "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/analysis.py"
click node_node_sonification "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/gjb2_sonification.py"
click node_node_mcore_sonification "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/mcore_q_sonification.py"
click node_node_requirements "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/requirements.txt"
click node_node_main_tex "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/main.tex"
click node_node_refs_bib "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/references.bib"
click node_node_analysis_stats "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/figures/analysis_stats.tex"
click node_node_summary_table "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/figures/summary_table.tex"
click node_node_audio_dir "https://github.com/vortexpixelz/gjb2-mcore-sonification/tree/main/audio"
click node_node_wt_audio "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_wildtype.wav"
click node_node_del35_audio "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_delta_c35delG.wav"
click node_node_del235_audio "https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_delta_c235delC.wav"

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_node_analysis,node_node_sonification,node_node_mcore_sonification,node_node_requirements toneBlue
class node_node_main_tex,node_node_refs_bib,node_node_analysis_stats,node_node_summary_table toneAmber
class node_node_audio_dir,node_node_wt_audio,node_node_del35_audio,node_node_del235_audio toneMint
class node_node_ncbi toneRose
class node_node_readme toneNeutral
```

## Components

### Python code

Analysis and sonification scripts that generate manuscript and audio artifacts.

- [Analysis](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/analysis.py): python script · Reproducibility entry point for manuscript figures and tables. · `code/analysis.py`
- [GJB2 synth](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/gjb2_sonification.py): python script · Entry point for rendering GJB2 sequence and allele audio. · `code/gjb2_sonification.py`
- [MCORE synth](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/mcore_q_sonification.py): python module · Related sonification logic for the MCORE workflow. · `code/mcore_q_sonification.py`
- [Requirements](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/code/requirements.txt): python deps · Python dependency list for the code in this repository. · `code/requirements.txt`

### Manuscript

LaTeX source and generated figure/table fragments used to build the paper.

- [Main tex](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/main.tex): latex manuscript · Primary LaTeX source for the paper. · `paper/main.tex`
- [Bibliography](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/references.bib): bibtex source · Citation database for the manuscript. · `paper/references.bib`
- [Stats fragment](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/figures/analysis_stats.tex): generated tex · LaTeX-ready analysis statistics included by the manuscript. · `paper/figures/analysis_stats.tex`
- [Summary table](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/paper/figures/summary_table.tex): generated tex · LaTeX-ready summary table included by the manuscript. · `paper/figures/summary_table.tex`

### Audio artifacts

Committed WAV outputs and reference renderings for the GJB2 sequences.

- [Audio dir](https://github.com/vortexpixelz/gjb2-mcore-sonification/tree/main/audio): artifact set · Committed reference WAV outputs. · `audio`
- [Wildtype WAV](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_wildtype.wav): audio artifact · Rendered wildtype GJB2 sequence audio. · `audio/gjb2_wildtype.wav`
- [Δc35delG WAV](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_delta_c35delG.wav): audio artifact · Rendered pathogenic deletion allele audio. · `audio/gjb2_delta_c35delG.wav`
- [Δc235delC WAV](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/audio/gjb2_delta_c235delC.wav): audio artifact · Rendered pathogenic deletion allele audio. · `audio/gjb2_delta_c235delC.wav`

### External data

Live biological sequence source fetched at runtime.

- **NCBI E-utilities**: external sequence API · Live source for NM_004004.6 fetched at runtime.

### Other components

- [README](https://github.com/vortexpixelz/gjb2-mcore-sonification/blob/main/README.md): repo guide · Project overview and usage notes. · `README.md`

## Connections

- README → Analysis: describes · Documents the analysis workflow.
- README → GJB2 synth: describes · Documents the audio generation workflow.
- Analysis → NCBI E-utilities: fetches sequence · Retrieves NM_004004.6 from NCBI during analysis runs.
- GJB2 synth → NCBI E-utilities: fetches sequence · Retrieves NM_004004.6 from NCBI during audio rendering.
- Analysis → Stats fragment: writes · Generates the manuscript's statistics fragment.
- Analysis → Summary table: writes · Generates the manuscript's summary table fragment.
- Main tex → Stats fragment: includes · Pulls in generated analysis output.
- Main tex → Summary table: includes · Pulls in generated analysis output.
- Main tex → Bibliography: uses · References bibliography entries for the manuscript.
- GJB2 synth → Wildtype WAV: renders · Writes wildtype WAV output.
- GJB2 synth → Δc35delG WAV: renders · Writes deletion allele WAV output.
- GJB2 synth → Δc235delC WAV: renders · Writes deletion allele WAV output.
- Audio dir → Wildtype WAV: contains · Committed reference audio.
- Audio dir → Δc35delG WAV: contains · Committed reference audio.
- Audio dir → Δc235delC WAV: contains · Committed reference audio.
- Analysis → Requirements: depends on · Python dependencies for reproducible runs.
- GJB2 synth → Requirements: depends on · Python dependencies for reproducible runs.
- MCORE synth → NCBI E-utilities: fetches sequence · Shares the same live biological data boundary.
- MCORE synth → Requirements: depends on · Uses the repository's Python environment.
