feat(bokeh): implement titration-curve

[github-actions]

Implementation: titration-curve - bokeh

Implements the bokeh version of titration-curve.

File: plots/titration-curve/implementations/bokeh.py

Parent Issue: #4407

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot shows a classic S-shaped acid-base titration curve plotted with Bokeh. The main pH curve is drawn in blue (#306998) as a solid line against a light gray (#FAFAFA) background. The x-axis is labeled "Volume of NaOH added (mL)" ranging from 0 to 50, and the left y-axis shows "pH" from 0 to 14. A secondary right y-axis in orange displays "dpH/dV (mL⁻¹)" for the derivative curve, which is shown as a dot-dash orange line (#D55E00) with a sharp peak at the equivalence point (~25 mL). The equivalence point is marked with a green (#009E73) dashed vertical line and a green diamond marker at pH 7.0, accompanied by a green text annotation reading "Equivalence Point / 25 mL, pH 7.0". A subtle horizontal dotted gray line marks pH 7. The legend in the top-left corner shows entries for "dpH/dV" and "pH". The title reads "HCl + NaOH Titration · titration-curve · bokeh · pyplots.ai". Grid lines are subtle dashed lines. The curve shows the characteristic sharp rise around the equivalence point, starting near pH 1 and plateauing above pH 12.

Score: 84/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) - Font sizes explicitly set (28pt title, 22pt labels, 18pt ticks) but text appears slightly small in rendered image
• VQ-02: No Overlap (6/6) - No overlapping elements, legend and annotation well-positioned
• VQ-03: Element Visibility (5/6) - Main curve visible at line_width=5, derivative curve slightly thin with alpha=0.6
• VQ-04: Color Accessibility (4/4) - Okabe-Ito colorblind-safe colors with good contrast
• VQ-05: Layout & Canvas (3/4) - Plot fills canvas reasonably but right axis area slightly cramped
• VQ-06: Axis Labels & Title (2/2) - All axes labeled with units

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) - Custom color palette, removed tick marks, light background — above defaults but not yet publication-ready
• DE-02: Visual Refinement (4/6) - Tick marks removed, subtle dashed grid, outline removed, generous borders
• DE-03: Data Storytelling (4/6) - Equivalence point highlighted as focal point with marker, annotation, and vertical line; derivative adds analytical depth

Spec Compliance (13/15)

• SC-01: Plot Type (5/5) - Correct line plot showing pH vs volume titration curve
• SC-02: Required Features (3/4) - Has equivalence point marking, derivative curve on secondary axis. Missing buffer region shading
• SC-03: Data Mapping (3/3) - X=volume, Y=pH, full pH range 0-14
• SC-04: Title & Legend (2/3) - Title includes spec-id and library but has extra "HCl + NaOH Titration" prefix before required format

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows full S-curve, equivalence point, derivative peak. Could demonstrate buffer region
• DQ-02: Realistic Context (5/5) - Real chemistry: 25 mL of 0.1M HCl titrated with 0.1M NaOH
• DQ-03: Appropriate Scale (4/4) - Realistic concentrations, volumes, and pH range

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear structure: data → plot → style → save
• CQ-02: Reproducibility (2/2) - Fully deterministic, no random data
• CQ-03: Clean Imports (2/2) - All imports used
• CQ-04: Code Elegance (2/2) - Clean, appropriate complexity
• CQ-05: Output & API (1/1) - Saves as plot.png and plot.html

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of ColumnDataSource, figure, Span, Label, LinearAxis
• LM-02: Distinctive Features (3/5) - HoverTool, HTML export, extra_y_ranges for dual axis

Score Caps Applied

• None

Strengths

• Correct S-shaped titration curve with realistic HCl/NaOH chemistry data and proper pH calculation
• Derivative curve on secondary y-axis with color-coded axis labels for clear association
• Colorblind-safe palette (Okabe-Ito) with excellent contrast between curve types
• Clean, deterministic code with no unnecessary complexity
• Good use of Bokeh-specific features: HoverTool, HTML export, ColumnDataSource

Weaknesses

• Missing buffer region shading as specified (semi-transparent fill around buffer zone)
• Title format has extra prefix — should be titration-curve · bokeh · pyplots.ai not HCl + NaOH Titration · titration-curve · bokeh · pyplots.ai
• Derivative curve line could be thicker/more prominent for better visibility
• Design could push further toward publication quality with more refined typography and spacing

Issues Found

1. SC-02 PARTIAL: Missing buffer region shading requested by spec
   • Fix: Add a semi-transparent VArea or Patch fill around the buffer region. For strong acid/strong base, consider adding a weak acid titration curve to demonstrate the buffer region, or shade the region where pH changes slowly (before equivalence point)
2. SC-04 PARTIAL: Title format incorrect — has extra descriptive prefix
   • Fix: Change title to titration-curve · bokeh · pyplots.ai
3. DE-01 MEDIUM: Design is good but not yet publication-quality
   • Fix: Consider adding region labels (acidic/basic), use a more refined title font weight, increase visual polish
4. LM-02 MEDIUM: Could leverage more Bokeh-specific features
   • Fix: Consider using Band glyph for buffer region, or ColorBar for additional visual interest

AI Feedback for Next Attempt

Add buffer region shading using Bokeh's VArea or Band glyph to fulfill the spec requirement. Fix the title format to titration-curve · bokeh · pyplots.ai. Consider adding subtle region labels (e.g., "Acidic" / "Basic") to improve data storytelling. Make the derivative curve slightly more prominent (increase line_width or alpha). These changes should push the score above 90.

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 shows an acid-base titration curve on a light gray background (#F7F7F7). A blue (#306998) S-shaped pH curve runs from ~pH 1 at 0 mL to ~pH 12.5 at 50 mL, with a sharp vertical transition near 25 mL. An orange (#D55E00) dot-dash derivative curve (dpH/dV) sits mostly flat near zero, with a dramatic spike at the equivalence point. A vertical green (#009E73) dashed line marks the equivalence point at 25 mL, with a green diamond marker at pH 7.0 and a bold green annotation reading "Equivalence Point, 25 mL, pH 7.0". Two shaded regions appear: a light orange/yellow "Acidic Buffer Region" (0–15 mL) and a light blue "Basic Buffer Region" (35–50 mL), both with faint italic labels. The left y-axis shows pH (0–14), the right y-axis shows dpH/dV in orange, and the x-axis reads "Volume of NaOH added (mL)". A legend in the top-left lists "dpH/dV" and "pH". Title reads "titration-curve · bokeh · pyplots.ai". A subtle dotted horizontal line marks pH 7.

Score: 86/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	8	10
Total	86	100

Visual Quality (26/30)

• VQ-01: Text Legibility (6/8) — Font sizes explicitly set (title 30pt, axes 24pt, ticks 18pt), but buffer region labels at 16pt with alpha=0.65 are too faint to read comfortably in the rendered output
• VQ-02: No Overlap (5/6) — Mostly clean, but the equivalence point area is visually congested: the derivative spike, vertical dashed line, diamond marker, and two-line annotation all converge in a narrow region
• VQ-03: Element Visibility (5/6) — Main curve and marker are well-sized; derivative curve is nearly invisible for 90% of the plot (flat near zero) making the legend entry somewhat misleading until the spike
• VQ-04: Color Accessibility (4/4) — Excellent use of Okabe-Ito colorblind-safe palette (#306998 blue, #D55E00 orange, #009E73 green)
• VQ-05: Layout & Canvas (4/4) — Good proportions, explicit margins, plot fills canvas well
• VQ-06: Axis Labels & Title (2/2) — "Volume of NaOH added (mL)", "pH", "dpH/dV (mL⁻¹)" — all descriptive with units

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom Okabe-Ito palette, light gray background, styled legend with border, above configured defaults but lacks the typography refinement and polish of publication-ready work
• DE-02: Visual Refinement (4/6) — Tick marks removed, outline removed, subtle dashed grid at low alpha, custom background. Buffer region dashed borders add slight visual noise
• DE-03: Data Storytelling (4/6) — Good visual hierarchy: buffer regions provide chemical context, equivalence point is the clear focal point with marker + annotation, derivative curve confirms the inflection. Viewer immediately identifies the key features

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct S-shaped titration curve
• SC-02: Required Features (4/4) — All spec features present: equivalence point with vertical dashed line and annotation, derivative curve on secondary y-axis, buffer region shading, pH 0–14 range
• SC-03: Data Mapping (3/3) — X = volume (mL), Y = pH, secondary Y = dpH/dV — all correct
• SC-04: Title & Legend (3/3) — Title "titration-curve · bokeh · pyplots.ai" correct, legend labels "dpH/dV" and "pH" match data

Data Quality (14/15)

• DQ-01: Feature Coverage (6/6) — Shows full S-curve with slow initial rise, sharp transition at equivalence, and high plateau — demonstrates all characteristic titration curve features
• DQ-02: Realistic Context (5/5) — Real chemistry scenario: 25 mL of 0.1 M HCl titrated with 0.1 M NaOH, textbook example
• DQ-03: Appropriate Scale (3/4) — pH 0–14 and volume 0–50 mL are realistic. However, labeling regions "Acidic/Basic Buffer Region" for a strong acid/strong base system is chemically imprecise — strong acids don't form buffer solutions. These are better described as "excess acid" and "excess base" regions

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data → plot → styling → save
• CQ-02: Reproducibility (2/2) — Fully deterministic (calculated from chemistry equations, no random)
• CQ-03: Clean Imports (2/2) — All imports used
• CQ-04: Code Elegance (2/2) — Appropriate complexity, the for-loop for pH calculation is necessary and clear
• CQ-05: Output & API (1/1) — Saves plot.png via export_png, also saves interactive HTML

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Good use of ColumnDataSource, figure API, BoxAnnotation, Span, Label, LinearAxis for twin axes. Could use transforms or more advanced data binding
• LM-02: Distinctive Features (4/5) — HoverTool for interactive tooltips, HTML export with CDN resources, BoxAnnotation — leverages Bokeh's interactive and annotation strengths well

Score Caps Applied

• None — no caps triggered

Strengths

• Excellent colorblind-safe palette from Okabe-Ito (keep this)
• Full spec compliance with all required features including derivative curve on secondary axis
• Realistic, deterministic chemistry data with proper pH calculations
• Good use of Bokeh-specific features: HoverTool, BoxAnnotation, dual HTML+PNG output
• Clean visual hierarchy with equivalence point as focal point

Weaknesses

• Buffer region labels are too faint (16pt at alpha=0.65) — hard to read in rendered output
• Equivalence point area is visually congested with overlapping elements
• Buffer region labels ("Acidic/Basic Buffer Region") are chemically imprecise for a strong acid/strong base system
• Title and legend text could be larger for the 4800×2700 canvas

Issues Found

1. VQ-01 MEDIUM: Buffer region labels at 16pt with alpha=0.65 are too faint
   • Fix: Increase to 20pt and raise alpha to 0.8
2. VQ-02 MINOR: Equivalence point area congested with derivative spike, vertical line, marker, and annotation
   • Fix: Offset annotation further from the convergence zone or adjust layout
3. DE-01 MEDIUM: Good but not publication-level polish — typography could be more refined
   • Fix: Increase title size, add more whitespace between title and plot area, consider font weight variation
4. DQ-03 MINOR: "Buffer Region" labels are chemically inaccurate for strong acid/base
   • Fix: Rename to "Excess Acid Region" and "Excess Base Region", or "Slow pH Change Region"

AI Feedback for Next Attempt

To reach 90+: (1) Make buffer region labels more legible — increase font size to 20pt and alpha to 0.8+. (2) Reduce visual congestion at equivalence point by offsetting the annotation further right or upward. (3) Rename "Buffer Region" labels to "Excess Acid/Base Region" for chemical accuracy. (4) Push title to 34pt+ for a more commanding presence on the large canvas. These targeted fixes should lift VQ-01, VQ-02, DE-01, and DQ-03 scores.

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 an acid-base titration curve (HCl + NaOH) with a characteristic S-shaped sigmoidal curve in blue (#306998) plotting pH (y-axis, 0-14) against volume of NaOH added in mL (x-axis, 0-50). A secondary y-axis on the right shows the derivative dpH/dV (mL⁻¹) in orange (#D55E00) as a dot-dash line, with a sharp spike at the equivalence point. The equivalence point at 25 mL, pH 7.0 is marked with a green diamond marker and a vertical dashed green line, accompanied by a bold annotation label. Two semi-transparent shaded regions indicate the "Excess HCl Region" (0-15 mL, yellow tint) and "Excess NaOH Region" (35-50 mL, blue tint) with italic labels. A subtle dotted gray line marks pH 7. The legend in the top-left corner shows entries for dpH/dV and pH with a white background and thin gray border. The background is light gray (#F7F7F7) with subtle dashed gridlines. Title reads "titration-curve · bokeh · pyplots.ai" in dark gray.

Score: 91/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set well above minimums (title 36pt, axis labels 26pt, ticks 20pt, legend 22pt, region labels 20pt). All text clearly readable at full resolution.
• VQ-02: No Overlap (6/6) — No overlapping text elements. Legend positioned in top-left away from data. Equivalence annotation offset to avoid collision with marker.
• VQ-03: Element Visibility (5/6) — Main curve (line_width=5) and derivative (line_width=4) are clearly visible. Equivalence diamond (size=26) is prominent. The derivative spike is inherently narrow due to the sharp pH transition, making it slightly hard to appreciate at full scale.
• VQ-04: Color Accessibility (4/4) — Uses colorblind-safe palette (Wong palette): blue curve, orange derivative, green equivalence point. All colors have good contrast against the light background.
• VQ-05: Layout & Canvas (4/4) — Generous borders (min_border: left=120, right=180, bottom=80, top=60). Plot fills canvas well with balanced whitespace. Nothing cut off.
• VQ-06: Axis Labels & Title (2/2) — X-axis: "Volume of NaOH added (mL)" with units. Y-axis: "pH". Right y-axis: "dpH/dV (mL⁻¹)" with units. All descriptive and appropriate.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom colorblind-safe palette with intentional color assignments (blue=main, orange=derivative, green=equivalence). Custom background, styled legend with border, professional typography. Clearly above defaults but not quite publication-level polish.
• DE-02: Visual Refinement (4/6) — Tick marks removed, subtle dashed grid with low alpha (0.18/0.12), outline removed, generous whitespace. Good refinement visible but not every detail is perfectly polished.
• DE-03: Data Storytelling (4/6) — Shaded regions label chemical domains, equivalence point annotation provides the key insight, derivative overlay shows analytical technique. Visual hierarchy guides the reader to the equivalence point as the focal element.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct S-shaped titration curve with all characteristic features.
• SC-02: Required Features (4/4) — Equivalence point marked with vertical dashed line ✓, text annotation with volume and pH ✓, derivative curve on secondary y-axis ✓, shaded regions (adapted for strong acid/base as excess regions) ✓, realistic HCl+NaOH data ✓, y-axis spans 0-14 ✓.
• SC-03: Data Mapping (3/3) — X=volume (mL), Y=pH. Full pH scale 0-14 shown. All data visible.
• SC-04: Title & Legend (3/3) — Title "titration-curve · bokeh · pyplots.ai" in correct format. Legend labels "pH" and "dpH/dV" are clear and match data.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows complete S-curve with all regions: initial low pH, slow rise, steep transition at equivalence, and high pH plateau. Derivative spike confirms equivalence point. Excess acid and base regions shaded.
• DQ-02: Realistic Context (5/5) — Real chemistry scenario: 25 mL of 0.1 M HCl titrated with 0.1 M NaOH. Chemically accurate calculation using stoichiometry and equilibrium.
• DQ-03: Appropriate Scale (4/4) — pH starts ~1, equivalence at pH 7.0 at 25 mL, plateaus ~12.5. All values are chemically accurate for this system.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data generation → plot creation → styling → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic data generation using stoichiometric calculations. No random elements.
• CQ-03: Clean Imports (2/2) — All imports are used: numpy, bokeh.io (export_png, save), bokeh.models (BoxAnnotation, ColumnDataSource, HoverTool, Label, LinearAxis, Range1d, Span), bokeh.plotting (figure), bokeh.resources (CDN).
• CQ-04: Code Elegance (2/2) — Appropriate complexity. Chemistry calculations are clear. No over-engineering or fake UI elements.
• CQ-05: Output & API (1/1) — Saves as plot.png via export_png and plot.html via save. Current Bokeh API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expert Bokeh usage: ColumnDataSource for data binding, extra_y_ranges for dual axes, BoxAnnotation for region shading, Label for annotations, Span for reference lines, LinearAxis for secondary axis configuration.
• LM-02: Distinctive Features (4/5) — HoverTool with vline mode (interactive tooltips, a distinctive Bokeh feature), HTML export alongside PNG with CDN resources, BoxAnnotation for declarative region shading. These features leverage Bokeh's interactive and declarative model system.

Score Caps Applied

• None — no score caps triggered.

Strengths

• Chemically accurate stoichiometric calculations produce a realistic titration curve
• Excellent use of Bokeh's model system (BoxAnnotation, Span, Label, HoverTool, extra_y_ranges)
• Colorblind-safe Wong palette with intentional color assignments
• Clean visual hierarchy with shaded regions, equivalence point annotation, and derivative overlay
• Dual output (PNG + interactive HTML) leverages Bokeh's strengths

Weaknesses

• Derivative spike is extremely narrow due to the nature of the data, making it slightly hard to appreciate visually at full scale
• Design could reach publication-level with more typographic refinement (e.g., title weight/positioning)

Issues Found

None critical. Minor visual refinements possible but overall quality is high.

AI Feedback for Next Attempt

Implementation meets quality standards. The titration curve is chemically accurate, all spec features are present, and the Bokeh-specific features (HoverTool, HTML export, BoxAnnotation) are well utilized. The design is professional with a custom colorblind-safe palette and thoughtful visual hierarchy.

Verdict: APPROVED