feat(altair): implement spectrum-nmr

[github-actions]

Implementation: spectrum-nmr - altair

Implements the altair version of spectrum-nmr.

File: plots/spectrum-nmr/implementations/altair.py

Parent Issue: #4676

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays an ethanol ¹H NMR spectrum rendered as a blue line (#306998) on a white background. The x-axis shows "Chemical Shift (ppm)" ranging from 12.0 (left) to -0.5 (right), correctly following NMR convention with higher ppm on the left. The y-axis shows "Intensity (a.u.)" from 0 to 1.25. The title reads "Ethanol ¹H NMR · spectrum-nmr · altair · pyplots.ai" in bold at the top center. Four labeled peaks are visible: TMS reference at 0.00 ppm (small singlet), CH₃ triplet at 1.18 ppm (tallest peak cluster with three resolved sub-peaks), OH singlet at 2.61 ppm (medium peak), and CH₂ quartet at 3.69 ppm (four resolved sub-peaks). The baseline is clean with minimal noise. Grid lines are removed, axis domain lines are subtle gray, and peak labels are in blue matching the spectrum line. The left ~60% of the x-axis (5-12 ppm) is empty baseline, which is scientifically correct but visually sparse.

Score: 87/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	13	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	87	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=28, axis=22, ticks=18, annotations=16). Annotation text at 16pt is adequate but slightly small relative to the canvas.
• VQ-02: No Overlap (6/6) — All labels well-separated, no collisions.
• VQ-03: Element Visibility (6/6) — Line strokeWidth=1.8 produces sharp, well-resolved peaks with visible splitting patterns.
• VQ-04: Color Accessibility (4/4) — Single blue color with strong contrast against white background.
• VQ-05: Layout & Canvas (3/4) — Correct 4800×2700 output. Peaks are clustered in the rightmost ~40% of the x-axis; the 5–12 ppm region is empty baseline. Scientifically standard but visually underutilizes the canvas.
• VQ-06: Axis Labels & Title (2/2) — Both axes have descriptive labels with units: "Chemical Shift (ppm)" and "Intensity (a.u.)".

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above library defaults: Python Blue color, muted axis styling ([area-basic] plotnine implementation #333/feat(plotly): implement donut-labeled #555/#aaa), removed grid, custom title font. Thoughtful but not yet publication-level exceptional.
• DE-02: Visual Refinement (4/6) — Grid removed, view stroke removed, subtle domain lines (0.6px, #aaa), custom tick styling. Good refinement visible.
• DE-03: Data Storytelling (4/6) — Peak labels with functional group assignments and splitting pattern names guide viewer understanding. Clear visual hierarchy with CH₃ triplet as tallest peak drawing attention first.

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct NMR spectrum as line plot.
• SC-02: Required Features (4/4) — Reversed x-axis ✓, sharp peaks with splitting ✓, labeled peaks ✓, TMS at 0 ppm ✓, clean baseline ✓.
• SC-03: Data Mapping (3/3) — X = chemical shift, Y = intensity, correct orientation.
• SC-04: Title & Legend (2/3) — Title includes required components but prepends "Ethanol ¹H NMR" before the spec format. No legend needed for single series.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Demonstrates singlet (TMS, OH), triplet (CH₃), and quartet (CH₂) splitting patterns with correct intensity ratios (1:2:1 and 1:3:3:1).
• DQ-02: Realistic Context (5/5) — Ethanol ¹H NMR is a classic, universally-used chemistry example. Chemical shifts match published data.
• DQ-03: Appropriate Scale (4/4) — Realistic ppm values, correct J-coupling constants (~7 Hz ≈ 0.07 ppm), appropriate intensity ratios.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data generation → chart → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — altair, numpy, pandas all used.
• CQ-04: Code Elegance (2/2) — Clean Lorentzian peak generation, well-organized code with clear comments.
• CQ-05: Output & API (1/1) — Saves as plot.png with scale_factor=3.0, plus plot.html.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of alt.Chart, mark_line, mark_text, alt.layer for composition, proper encoding types and scale definitions.
• LM-02: Distinctive Features (3/5) — Uses alt.layer() for multi-layer composition, mark_text with lineBreak for multi-line labels, .interactive() for zoom/pan, tooltips, and HTML export alongside PNG.

Score Caps Applied

• None

Strengths

• Scientifically accurate NMR data with correct Lorentzian lineshapes, splitting patterns, and coupling constants
• All spec requirements fully implemented including reversed x-axis and TMS reference
• Clean visual design with removed grid, subtle axis styling, and consistent color use
• Excellent use of Altair layer composition for combining spectrum line with text annotations

Weaknesses

• Title format prepends "Ethanol ¹H NMR" beyond the required {spec-id} · {library} · pyplots.ai format
• Large empty baseline region (5–12 ppm) underutilizes the canvas; consider narrowing the x-domain or adding a break
• Annotation font size (16pt) could be increased for better prominence at full resolution
• Could push design excellence further with background shading for peak regions or more typographic refinement

Issues Found

1. SC-04 MINOR: Title format has extra descriptive prefix — should be spectrum-nmr · altair · pyplots.ai exactly
   • Fix: Remove "Ethanol ¹H NMR" prefix or move it to a subtitle
2. VQ-05 MINOR: Canvas underutilized due to wide empty baseline region
   • Fix: Consider narrowing x-domain to ~[-0.5, 5.0] or adding region-of-interest emphasis
3. DE-01 MODERATE: Good styling but not yet publication-exceptional
   • Fix: Add subtle background region highlighting, refine typography hierarchy, or add integration curves

AI Feedback for Next Attempt

To reach 90+: (1) Fix title to exact spec format spectrum-nmr · altair · pyplots.ai. (2) Consider narrowing the x-axis domain to focus on the peaks (0–5 ppm range) to better utilize canvas space. (3) Increase annotation font size to 18-20pt. (4) Push design excellence with subtle region shading, a secondary descriptive subtitle, or integration curve overlays to enhance scientific storytelling.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

The plot displays a synthetic ¹H NMR spectrum of ethanol with chemical shift (ppm) on the x-axis (reversed, running from 5.0 on the left to -0.4 on the right) and Intensity (a.u.) on the y-axis (0 to 1.30). The title reads "spectrum-nmr · altair · pyplots.ai" with a subtitle "Ethanol ¹H NMR — Synthetic 300 MHz Spectrum". Four peak groups are visible, each highlighted by a light blue shaded rectangular region spanning the full chart height: CH₂ quartet at 3.69 ppm (4 distinct peaks), OH singlet at 2.61 ppm (single peak), CH₃ triplet at 1.18 ppm (3 peaks with 1:2:1 pattern), and TMS reference at 0.00 ppm (single peak). All peaks are drawn in Python Blue (#306998) with bold labels above each group showing the functional group assignment and chemical shift value. The baseline is clean with minimal noise. Grid lines are absent, view borders are removed, and axis styling uses subtle gray tones.

Score: 88/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	88	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) - Title 28pt, axis titles 22pt, tick labels 18pt, peak labels 20pt bold — all explicitly set and readable. Minor: tick labels could be slightly larger for perfect score.
• VQ-02: No Overlap (6/6) - All text is well-spaced with no overlapping elements
• VQ-03: Element Visibility (6/6) - Line strokeWidth=1.8 produces sharp, well-resolved peaks; splitting patterns clearly visible
• VQ-04: Color Accessibility (4/4) - Single-color scheme (Python Blue) with no accessibility concerns
• VQ-05: Layout & Canvas (3/4) - Good canvas utilization overall, but the full-height shaded regions (extending to y=1.30) create unnecessary visual weight above the peaks and waste vertical space
• VQ-06: Axis Labels & Title (2/2) - "Chemical Shift (ppm)" and "Intensity (a.u.)" — descriptive with units

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) - Consistent Python Blue scheme, Helvetica Neue typography, shaded peak regions add visual organization, subtitle provides scientific context. Clearly above library defaults but not yet publication-level exceptional.
• DE-02: Visual Refinement (4/6) - Grid disabled, view stroke removed, subtle gray domain/tick colors, opacity-based region shading. Good refinement visible.
• DE-03: Data Storytelling (4/6) - Peak labels with functional group assignments and splitting pattern names guide the viewer. Shaded regions create visual grouping. Subtitle contextualizes the data. Good visual hierarchy.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct: line-based NMR spectrum
• SC-02: Required Features (4/4) - All features present: reversed x-axis, sharp peaks with realistic splitting (singlet/triplet/quartet), labeled peaks with chemical shift values, TMS reference at 0 ppm, clean baseline
• SC-03: Data Mapping (3/3) - X/Y correctly assigned, axes show full data range
• SC-04: Title & Legend (3/3) - Correct format "spectrum-nmr · altair · pyplots.ai", no legend needed for single-series

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Demonstrates singlet, triplet, and quartet splitting patterns with appropriate intensity ratios (1:2:1 for triplet, 1:3:3:1 for quartet), plus TMS reference
• DQ-02: Realistic Context (5/5) - Ethanol ¹H NMR is a classic, well-known real-world chemistry scenario with accurate chemical shifts
• DQ-03: Appropriate Scale (4/4) - Chemical shifts match real ethanol NMR data; Lorentzian peak shapes with realistic linewidths

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean imports → data → plot → save structure, no functions/classes
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set for noise generation
• CQ-03: Clean Imports (2/2) - All three imports (altair, numpy, pandas) are used
• CQ-04: Code Elegance (2/2) - Lorentzian peak model is elegant and physically accurate; clean data construction
• CQ-05: Output & API (1/1) - Saves as plot.png with scale_factor=3.0 and plot.html

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of Altair's declarative grammar: layered composition with alt.layer(), proper encoding types (:Q, :N), alt.Title object, configure_axis/configure_view. Could better leverage Altair's selection/condition mechanisms.
• LM-02: Distinctive Features (3/5) - Uses Altair-specific features: layer composition, interactive(), tooltips, mark_rect for region shading, mark_text for annotations, HTML export. These patterns leverage Altair's grammar of graphics approach.

Score Caps Applied

• None — no score caps triggered

Strengths

• Excellent scientific accuracy with Lorentzian peak shapes and correct splitting patterns for ethanol
• Strong spec compliance — all required features implemented perfectly
• Good design with shaded peak regions, functional group labels, and informative subtitle
• Clean, elegant code with appropriate use of Altair's layered composition

Weaknesses

• Full-height shaded regions (y=0 to y=1.30) are visually heavier than needed — limiting them to just above the peak heights would look more refined
• DE-01 could improve with more sophisticated typography hierarchy or a more distinctive visual treatment
• Tick label font size (18pt) is adequate but could be larger for maximum readability

Issues Found

1. VQ-05 MINOR: Shaded regions span full chart height unnecessarily
   • Fix: Limit region height to just above the tallest peak in each group, or reduce region opacity further
2. DE-01 MODERATE: Design is good but not yet publication-exceptional
   • Fix: Consider adding thin vertical drop lines from peak tops to baseline, or a more refined color treatment for the shaded regions
3. LM-01 MINOR: Could leverage more Altair-specific patterns
   • Fix: Consider using alt.condition() or selection parameters for the HTML interactive version

AI Feedback for Next Attempt

To reach 90+: (1) Limit the shaded region height to just above each peak group rather than spanning the full y-axis — this will look more polished and professional. (2) Consider adding subtle baseline tick marks or thin vertical drop lines from peak labels to peaks for a more refined scientific appearance. (3) Explore whether a slightly different shade or border treatment for the regions would add visual sophistication. The implementation is very close to the threshold — small design refinements should push it over.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

The plot displays a synthetic ¹H NMR spectrum of ethanol with a reversed x-axis running from 5.0 to -0.4 ppm (high ppm on the left, following standard NMR convention). Four distinct peak groups are visible: a CH₂ quartet at 3.69 ppm (4 peaks with 1:3:3:1 intensity), an OH singlet at 2.61 ppm, a CH₃ triplet at 1.18 ppm (3 peaks with 1:2:1 intensity), and a TMS reference peak at 0.00 ppm. Each peak group has a subtle light-blue shaded region behind it, dashed vertical drop-lines, and bold dark-blue text labels identifying the functional group, multiplicity, and chemical shift value. The line is drawn in Python Blue (#306998) against a clean white background with no gridlines. The title reads "spectrum-nmr · altair · pyplots.ai" with an italic subtitle "Ethanol ¹H NMR — Synthetic 300 MHz Spectrum". Axis labels are "Chemical Shift (ppm)" and "Intensity (a.u.)". The overall design is clean and professional.

Score: 92/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	15	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	92	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title 28pt, subtitle 17pt, axis titles 22pt, axis labels 18pt, peak labels 18pt bold. All perfectly readable.
• VQ-02: No Overlap (6/6) - No overlapping text anywhere. Peak labels are well-positioned above their respective peaks with adequate spacing.
• VQ-03: Element Visibility (6/6) - Spectrum line at strokeWidth 1.8 is clearly visible. Splitting patterns (triplet, quartet) are sharp and well-resolved. Peak heights are well-differentiated.
• VQ-04: Color Accessibility (4/4) - Single-series using Python Blue (#306998) with excellent contrast against white background. No colorblind concerns.
• VQ-05: Layout & Canvas (4/4) - Plot fills approximately 65% of canvas area. Balanced margins, nothing cut off.
• VQ-06: Axis Labels & Title (2/2) - "Chemical Shift (ppm)" and "Intensity (a.u.)" — both descriptive with units.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) - Strong design with cohesive blue palette, custom typography (Helvetica Neue), informative subtitle, shaded peak regions with corner radius, dashed drop-lines. Clearly above defaults and professional-looking.
• DE-02: Visual Refinement (4/6) - Grid removed, view stroke removed, subtle domain lines ([bullet-basic] Basic Bullet Chart #999, 0.8 width), refined tick marks. Good refinement but top/right axis boundaries still present.
• DE-03: Data Storytelling (5/6) - Clear narrative: ethanol NMR with labeled functional groups and splitting patterns. Shaded regions and labels create visual hierarchy that guides the viewer through the spectrum. Subtitle adds instrument context.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct NMR spectrum as a line plot with sharp peaks from baseline.
• SC-02: Required Features (4/4) - Reversed x-axis ✓, sharp well-resolved peaks with splitting patterns (singlet/triplet/quartet) ✓, peak labels with chemical shift values ✓, TMS reference at 0 ppm ✓, clean baseline with minimal noise ✓.
• SC-03: Data Mapping (3/3) - Chemical shift on x-axis, intensity on y-axis. All data visible with appropriate scale.
• SC-04: Title & Legend (3/3) - Title format "spectrum-nmr · altair · pyplots.ai" correct. No legend needed for single-series spectrum.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Shows singlet (OH, TMS), triplet (CH₃), and quartet (CH₂) — covering the key splitting patterns. Demonstrates the fundamentals of 1H NMR interpretation.
• DQ-02: Realistic Context (5/5) - Ethanol ¹H NMR is a classic, real-world example from organic chemistry. Chemical shifts and splitting patterns match literature values.
• DQ-03: Appropriate Scale (4/4) - Chemical shifts 0–5 ppm correct for ¹H NMR range. Peak positions (1.18, 2.61, 3.69 ppm) and coupling constants (~7 Hz / 0.07 ppm at 300 MHz) are scientifically accurate.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → data generation → chart layers → combine → save. No functions or classes.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set before noise generation.
• CQ-03: Clean Imports (2/2) - altair, numpy, pandas — all three are used.
• CQ-04: Code Elegance (2/2) - Clean Lorentzian peak generation, well-organized layer composition, clear variable names. Appropriate complexity for the visualization.
• CQ-05: Output & API (1/1) - Saves as plot.png with scale_factor=3.0. Also saves HTML for interactive version. Current API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Excellent use of Altair's declarative grammar: layered composition, encoding types, scale configuration, configure_* methods. Very idiomatic.
• LM-02: Distinctive Features (3/5) - Uses interactive selection (selection_point with nearest/pointerover), transform_filter for crosshair and hover point, tooltips with formatted values, HTML export. These are distinctive Altair capabilities.

Score Caps Applied

• None

Strengths

• Scientifically accurate ethanol ¹H NMR spectrum with correct chemical shifts, coupling constants, and splitting patterns
• Excellent peak labeling with functional group assignments and multiplicity
• Clean, professional design with cohesive blue palette, shaded peak regions, and refined typography
• Effective use of Altair's interactive capabilities (hover crosshair, tooltips, nearest-point selection)
• Well-structured code with clear Lorentzian peak generation

Weaknesses

• Minor: top/right axis boundaries still visible (Altair limitation makes removal difficult)

Issues Found

None significant — implementation is polished and meets all spec requirements.

AI Feedback for Next Attempt

Implementation is approved. The NMR spectrum is scientifically accurate, well-labeled, and professionally designed. Interactive features effectively leverage Altair's strengths.

Verdict: APPROVED