From 73fa5c80976ef941a193f0f7fe50c8b08bbe4118 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 10 Jun 2026 23:00:21 +0000 Subject: [PATCH] spec: add audiogram-clinical specification Created from issue #8655 --- plots/audiogram-clinical/specification.md | 31 +++++++++++++++++++++ plots/audiogram-clinical/specification.yaml | 28 +++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 plots/audiogram-clinical/specification.md create mode 100644 plots/audiogram-clinical/specification.yaml diff --git a/plots/audiogram-clinical/specification.md b/plots/audiogram-clinical/specification.md new file mode 100644 index 0000000000..141ba0b651 --- /dev/null +++ b/plots/audiogram-clinical/specification.md @@ -0,0 +1,31 @@ +# audiogram-clinical: Clinical Audiogram + +## Description + +A standardized clinical audiogram that displays hearing test results, plotting hearing threshold (dB HL) against test frequency for each ear. The y-axis is inverted so that 0 dB HL (best hearing) sits at the top and increasing hearing loss extends downward, while the x-axis is logarithmic spanning the standard audiometric frequencies (125 Hz to 8 kHz). Thresholds are marked with the conventional symbols — a circle (O) for the right ear in red and a cross (X) for the left ear in blue — and connected per ear, with shaded horizontal bands indicating severity of hearing loss (normal, mild, moderate, severe, profound). + +## Applications + +- Audiology clinics recording and interpreting pure-tone audiometry results to diagnose and grade hearing loss +- ENT (otolaryngology) practices distinguishing conductive, sensorineural, and mixed hearing loss patterns across ears +- Occupational health programs screening for noise-induced hearing loss in workers exposed to loud environments +- Pediatric and educational audiology documenting hearing thresholds for hearing-aid fitting and follow-up + +## Data + +- `frequency` (int) - Test frequency in Hz on a logarithmic x-axis; standard values 125, 250, 500, 1000, 2000, 4000, 8000 (often also 750, 1500, 3000, 6000) +- `threshold_right` (int) - Right-ear hearing threshold in dB HL, plotted with red circle (O) markers +- `threshold_left` (int) - Left-ear hearing threshold in dB HL, plotted with blue cross (X) markers +- Size: 7-11 frequency points per ear +- Example: Pure-tone audiometry showing a typical high-frequency sensorineural notch (sloping loss toward 4-8 kHz) + +## Notes + +- Y-axis: hearing threshold in dB HL, **inverted** so 0 dB HL is at the top and values increase downward (typical range -10 to 120 dB HL, gridlines every 10 dB) +- X-axis: **logarithmic** frequency from 125 Hz to 8 kHz; label octave frequencies as ticks (125, 250, 500, 1k, 2k, 4k, 8k) using kHz shorthand where conventional +- Right ear: red, circle (O) marker, solid connecting line. Left ear: blue, cross (X) marker, solid connecting line (dashed line is an acceptable convention to distinguish ears) +- Connect thresholds within each ear in ascending frequency order; do not connect across ears +- Shade horizontal severity bands across the full width with labels: normal (-10–25 dB), mild (26–40), moderate (41–55) / moderately severe (56–70), severe (71–90), profound (>90). Use light, distinguishable fills that do not obscure the markers +- Include a legend mapping the O/red and X/blue symbols to right and left ear +- Keep the plot square-ish with a clear grid; the standardized appearance (inverted axis, log frequency, O/X symbols) is the defining feature and must be preserved +- Axis titles: x = "Frequency (Hz)", y = "Hearing Level (dB HL)" diff --git a/plots/audiogram-clinical/specification.yaml b/plots/audiogram-clinical/specification.yaml new file mode 100644 index 0000000000..16e188ef52 --- /dev/null +++ b/plots/audiogram-clinical/specification.yaml @@ -0,0 +1,28 @@ +# Specification-level metadata for audiogram-clinical +# Auto-synced to PostgreSQL on push to main + +spec_id: audiogram-clinical +title: Clinical Audiogram + +# Specification tracking +created: "2026-06-10T22:59:50Z" +updated: null +issue: 8655 +suggested: MarkusNeusinger + +# Classification tags (applies to all library implementations) +# See docs/reference/tagging-system.md for detailed guidelines +tags: + plot_type: + - line + - scatter + data_type: + - numeric + - paired + domain: + - healthcare + - science + features: + - annotated + - comparison + - threshold