feat(altair): implement line-reaction-coordinate

[github-actions]

Implementation: line-reaction-coordinate - altair

Implements the altair version of line-reaction-coordinate.

File: plots/line-reaction-coordinate/implementations/altair.py

Parent Issue: #4409

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a reaction coordinate energy diagram with a smooth dark blue curve (#306998) tracing from reactants at 50 kJ/mol through a transition state peak at ~120 kJ/mol down to products at 20 kJ/mol. The title reads "line-reaction-coordinate · altair · pyplots.ai" with subtitle "Exothermic Reaction · Single-Step Energy Profile" in gray. An orange double-headed arrow on the left side shows Ea = 70 kJ/mol between the reactant level and transition state. A green double-headed arrow on the right shows ΔH = −30 kJ/mol between reactant and product levels. Bold dark labels mark "Reactants", "Transition State ‡", and "Products". Gray dashed horizontal lines extend at the 50, 120, and 20 kJ/mol energy levels. Small italic gray text shows energy values (50, 120, 20 kJ/mol). The x-axis is "Reaction Coordinate" and y-axis "Energy (kJ/mol)". Grid is removed, view borders are removed, and the overall look is clean.

Score: 87/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) - Font sizes explicitly set throughout (title 28pt, axes 22pt, ticks 18pt, labels 20pt). Energy value labels at 14pt are slightly small but still readable.
• VQ-02: No Overlap (5/6) - Minor crowding around the Ea annotation area where the orange arrow, label text, and dashed lines converge. "120 kJ/mol" italic label sits close to the dashed line.
• VQ-03: Element Visibility (6/6) - Main curve at strokeWidth=4 is clearly visible. Triangle arrow markers (size=200) are well-sized. All annotation elements distinct.
• VQ-04: Color Accessibility (4/4) - Blue/orange/green palette is colorblind-safe with good contrast against the white background.
• VQ-05: Layout & Canvas (3/4) - Good use of canvas space but x-axis extends from -0.08 to 1.12 adding some unnecessary padding. The plot fills the canvas reasonably well.
• VQ-06: Axis Labels & Title (2/2) - "Energy (kJ/mol)" with units, "Reaction Coordinate" is descriptive (dimensionless by convention).

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) - Thoughtful color choices with semantic meaning (orange=Ea, green=ΔH, blue=curve), custom Helvetica Neue typography, professional appearance. Above defaults but not publication-level polish.
• DE-02: Visual Refinement (4/6) - Grid removed, view borders removed (strokeWidth=0), subtle domain lines (#aaa, 0.6 width), tick marks refined. Good refinement but y-axis has many tick marks creating visual noise.
• DE-03: Data Storytelling (5/6) - Clear narrative with color-coded arrows guiding the viewer through activation energy and enthalpy change. Subtitle provides context ("Exothermic Reaction · Single-Step Energy Profile"). Visual hierarchy: bold curve → colored arrows → labels → dashed lines.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct reaction coordinate energy diagram with smooth curve and single maximum.
• SC-02: Required Features (4/4) - All spec features present: labeled reactants/products/transition state, Ea double-headed arrow, ΔH double-headed arrow, horizontal dashed lines, smooth curve with clear maximum, clean minimal style.
• SC-03: Data Mapping (3/3) - X=reaction coordinate (0-1), Y=energy (kJ/mol). Correct mapping with all data visible.
• SC-04: Title & Legend (3/3) - Title format "line-reaction-coordinate · altair · pyplots.ai" correct. No legend needed for single-series plot.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Shows all aspects: reactant/product energy levels, transition state peak, activation energy barrier, enthalpy change, smooth energy profile.
• DQ-02: Realistic Context (5/5) - Standard chemistry example with realistic energy values for a single-step exothermic reaction. Neutral scientific context.
• DQ-03: Appropriate Scale (4/4) - 50 kJ/mol reactants, 120 kJ/mol transition state, 20 kJ/mol products are reasonable values for a chemical reaction.

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) - Follows imports → data → plot → save pattern with no functions or classes.
• CQ-02: Reproducibility (2/2) - Fully deterministic data generation (no randomness).
• CQ-03: Clean Imports (2/2) - All imports (altair, numpy, pandas) are used.
• CQ-04: Code Elegance (1/2) - Quite verbose with many individual DataFrames for each annotation element (ea_line_df, ea_label_df, dh_line_df, etc.). Could consolidate some repetitive chart layer definitions.
• CQ-05: Output & API (1/1) - Saves as plot.png with scale_factor=3.0 and plot.html. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of alt.layer() for composition, proper encoding types (:Q, :N), alt.Title with subtitle, configure_axis/configure_view/configure_title. Could use alt.datum or calculated transforms for some annotations.
• LM-02: Distinctive Features (3/5) - Uses .interactive() for zoom/pan, tooltips on the curve, HTML export, layered grammar-of-graphics composition.

Score Caps Applied

• None

Strengths

• Perfect spec compliance with all required features (Ea arrow, ΔH arrow, labels, dashed lines)
• Semantically meaningful color coding (orange for Ea, green for ΔH, blue for curve)
• Good data storytelling with clear visual hierarchy guiding the viewer
• Clean, grid-free design with subtle axis styling
• Deterministic data with realistic chemistry values

Weaknesses

• Y-axis has excessive tick marks (every 5 kJ/mol) creating visual noise — reduce to key values or wider intervals
• Energy value labels (14pt italic gray) are slightly small compared to other text elements
• Minor crowding around the Ea annotation area where arrow, label, and dashed lines converge
• Code is verbose with many individual DataFrames that could be consolidated

Issues Found

1. DE-01 MODERATE: Good color semantics but not yet publication-quality polish — typography hierarchy could be stronger
   • Fix: Increase contrast between primary labels and secondary annotations, consider a slightly more refined color palette
2. DE-02 MODERATE: Y-axis tick density creates visual noise
   • Fix: Use manual tick values at key energy levels (0, 20, 50, 120) or wider intervals (every 20 kJ/mol)
3. VQ-02 MINOR: Crowding near Ea annotation
   • Fix: Reposition Ea label slightly or adjust spacing between arrow and nearby dashed lines
4. CQ-04 MINOR: Verbose code with many separate DataFrames
   • Fix: Consolidate similar annotation elements where possible

AI Feedback for Next Attempt

To reach 90+: (1) Reduce y-axis tick density — use custom tick values at meaningful energy levels or wider intervals to reduce visual noise. (2) Increase the energy value label font size from 14pt to 16-18pt for better consistency. (3) Slightly reposition Ea label to reduce crowding. (4) Consider adding a subtle background color or more refined typography hierarchy to elevate from "good" to "publication-ready" design.

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 reaction coordinate energy diagram for a single-step exothermic reaction. A smooth blue curve (#306998) traces the energy profile from left (reactants at 50 kJ/mol) through a peak (transition state at ~120 kJ/mol) down to products (20 kJ/mol) on the right. The title "line-reaction-coordinate · altair · pyplots.ai" appears at the top in dark text with a subtitle "Exothermic Reaction · Single-Step Energy Profile" in gray. Bold dark labels mark "Reactants", "Transition State ‡", and "Products" near their respective positions. An orange vertical double-headed arrow at x≈0.16 shows Ea = 70 kJ/mol between the reactant energy level and the transition state level, connected by gray dashed horizontal reference lines. A green vertical double-headed arrow at x≈0.82 shows ΔH = −30 kJ/mol between the reactant and product energy levels, also with dashed reference lines and small tick marks. Italic gray annotations show the absolute energy values (50, 120, 20 kJ/mol) at their respective levels. The x-axis is labeled "Reaction Coordinate" and y-axis "Energy (kJ/mol)". The background is clean white with no grid, no view border, and refined axis styling.

Score: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 28, axes 22, ticks 18, species 22, arrows 19, energy vals 16). Energy value annotations at 16pt italic gray are at the minimum threshold for clear readability.
• VQ-02: No Overlap (6/6) — All labels well-spaced with no collisions. Dashed reference lines and annotations do not interfere with each other.
• VQ-03: Element Visibility (6/6) — Curve strokeWidth=4, arrows strokeWidth=2.5, arrowhead markers size=220. All elements clearly visible.
• VQ-04: Color Accessibility (4/4) — Orange (#C46210), green (#2E8B57), blue (#306998) palette is colorblind-safe with strong contrast.
• VQ-05: Layout & Canvas (3/4) — Good proportions at 1600×900, but y-axis extends to 140 when maximum content reaches ~130, creating slight unused space at the top.
• VQ-06: Axis Labels & Title (2/2) — "Energy (kJ/mol)" includes units; "Reaction Coordinate" is appropriate for arbitrary-unit axis.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom three-color palette with intentional color coding (orange=Ea, green=ΔH, blue=curve). Custom font stack, refined axis colors ([area-basic] plotnine implementation #333/feat(plotly): implement donut-labeled #555), subdued domain color. Clearly above well-configured defaults.
• DE-02: Visual Refinement (4/6) — Grid disabled, view border removed (strokeWidth=0), axis domain and ticks subtly styled. Dashed reference lines use light gray with appropriate dash pattern. Some minor visual noise from the ΔH tick marks.
• DE-03: Data Storytelling (5/6) — Strong visual hierarchy through color-coded annotations. The Ea and ΔH arrows immediately communicate the key energetic quantities. Subtitle provides educational context. Viewer understands the exothermic reaction story at a glance.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct reaction coordinate energy diagram with smooth curve and clear transition state maximum.
• SC-02: Required Features (4/4) — All spec features present: labeled reactants/products/transition state, Ea double-headed arrow, ΔH double-headed arrow, smooth curve, horizontal dashed reference lines, clean minimal style.
• SC-03: Data Mapping (3/3) — X=reaction coordinate (0-1), Y=energy (kJ/mol). All data correctly mapped.
• SC-04: Title & Legend (3/3) — Title follows exact format "line-reaction-coordinate · altair · pyplots.ai". No legend needed with direct labeling.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: reactant/product energy levels, transition state peak, activation energy barrier, enthalpy change. Smooth sigmoidal+Gaussian curve is physically appropriate.
• DQ-02: Realistic Context (5/5) — Real chemistry context with appropriate kJ/mol units. Values match the spec example (50, 120, 20 kJ/mol). Neutral scientific domain.
• DQ-03: Appropriate Scale (4/4) — Energy values are realistic for a chemical reaction. Ea=70 kJ/mol and ΔH=−30 kJ/mol are physically reasonable.

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) — Fully deterministic data using analytical functions (sigmoid + Gaussian). No randomness.
• CQ-03: Clean Imports (2/2) — altair, numpy, pandas — all used, no unused imports.
• CQ-04: Code Elegance (2/2) — Well-organized with clear variable names. Layer separation is clean and logical.
• CQ-05: Output & API (1/1) — Saves plot.png with scale_factor=3.0 and plot.html. Current Altair 6.0 API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of Altair's layered grammar with alt.layer(), proper encoding types (:Q, :N), alt.Title with subtitle, configure methods for global styling. Could leverage alt.condition or selections more.
• LM-02: Distinctive Features (3/5) — Uses .interactive() for zoom/pan, tooltips on the curve, HTML export, and shape encoding channel for directional arrowheads — features distinctive to Altair's declarative approach.

Score Caps Applied

• None

Strengths

• Excellent spec compliance with all required features (Ea arrow, ΔH arrow, labeled species, dashed reference lines)
• Strong color-coded visual storytelling — orange for Ea, green for ΔH, blue for energy curve
• Clean, deterministic data generation using sigmoid + Gaussian analytical model
• Professional axis styling with removed view border and disabled grid
• Informative subtitle adds educational context

Weaknesses

• Energy value annotations (16pt italic gray) are at the minimum readability threshold — could be slightly larger or bolder
• Y-axis domain extends to 140 when content maxes around 130, leaving unused space
• Small dashed tick marks at ΔH arrow endpoints add minor visual noise

Issues Found

1. VQ-01 MINOR: Energy value annotations at 16pt italic gray (#666666) are functional but borderline
   • Fix: Increase to 17-18pt or use a slightly darker color for better contrast
2. VQ-05 MINOR: Y-axis domain [0, 140] leaves unused space above ~130
   • Fix: Tighten to [0, 135] to better fill the canvas

AI Feedback for Next Attempt

Implementation meets quality standards. The reaction coordinate diagram is well-executed with proper color-coded annotations, clear labeling, and professional styling. All spec requirements are fulfilled. Minor improvements could include slightly larger energy value annotations and a tighter y-axis domain.

Verdict: APPROVED