How vortexpixelz/gjb2-mcore-sonification works
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: gjb2_sonification.py GJB2 synth · analysis.py Analysis · main.tex Main tex · audio Audio dir
Components 14
Python code
Analysis and sonification scripts that generate manuscript and audio artifacts.
- Analysis · Reproducibility entry point for manuscript figures and tables.
code/analysis.py - GJB2 synth · Entry point for rendering GJB2 sequence and allele audio.
code/gjb2_sonification.py - MCORE synth · Related sonification logic for the MCORE workflow.
code/mcore_q_sonification.py - Requirements · 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 · Primary LaTeX source for the paper.
paper/main.tex - Bibliography · Citation database for the manuscript.
paper/references.bib - Stats fragment · LaTeX-ready analysis statistics included by the manuscript.
paper/figures/analysis_stats.tex - Summary table · 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 · Committed reference WAV outputs.
audio - Wildtype WAV · Rendered wildtype GJB2 sequence audio.
audio/gjb2_wildtype.wav - Δc35delG WAV · Rendered pathogenic deletion allele audio.
audio/gjb2_delta_c35delG.wav - Δc235delC WAV · Rendered pathogenic deletion allele audio.
audio/gjb2_delta_c235delC.wav
External data
Live biological sequence source fetched at runtime.
- NCBI E-utilities · Live source for NM_004004.6 fetched at runtime.
Other components
- README · Project overview and usage notes.
README.md
Connections 19
- 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.