feat(letsplot): implement eye-diagram-basic

[github-actions]

Implementation: eye-diagram-basic - letsplot

Implements the letsplot version of eye-diagram-basic.

File: plots/eye-diagram-basic/implementations/letsplot.py

Parent Issue: #4561

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays an eye diagram on a dark (#1a1a1a) background. It uses a 2D density heatmap (geom_raster) to show overlaid NRZ signal traces. The x-axis is labeled "Time (UI)" ranging from 0 to 2, and the y-axis is labeled "Voltage (V)" with ticks at 0.0, 0.5, and 1.0. The title reads "eye-diagram-basic · letsplot · pyplots.ai" in bold light gray text. A vertical color bar on the right labeled "Trace Density" maps density values from ~0.2 (dark red) to 1.0 (white), using a custom hot colormap that transitions through dark red, bright red, orange, yellow, and white. Two characteristic eye openings are clearly visible — dense horizontal bands cluster at the 0V and 1V signal levels, with transition regions connecting them at approximately 0.5 and 1.5 UI. The eye openings are wide and clean, indicating good simulated signal quality. The overall aesthetic is professional with a dark-themed design appropriate for engineering visualization.

Score: 85/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	7	10
Total	85	100

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=28, axis titles=20, ticks=16, legend=14-16). All text readable. Minor: title could benefit from slightly larger size for dark-on-dark contrast.
• VQ-02: No Overlap (6/6) — No overlapping text elements anywhere.
• VQ-03: Element Visibility (5/6) — Density heatmap pattern is clear and the eye shape is well-defined, but the raster cells appear slightly granular/pixelated in lower-density transition regions.
• VQ-04: Color Accessibility (3/4) — Hot colormap provides excellent contrast on dark background for sequential density data. Not a standard perceptually-uniform palette (viridis/cividis), but works well for this specific use case.
• VQ-05: Layout & Canvas (3/4) — Good proportions, nothing cut off. Slight vertical wasted space below the 0V level and above 1V level due to the -0.3 to 1.3 voltage range.
• VQ-06: Axis Labels & Title (2/2) — "Time (UI)" and "Voltage (V)" with proper units. Title in correct format.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (6/8) — Dark theme with custom 15-stop hot color palette is well-suited for eye diagrams and clearly above defaults. Professional engineering aesthetic. Color transitions are smooth and intentional. Not quite publication-ready polish (would need annotations and finer detail).
• DE-02: Visual Refinement (4/6) — Spines removed (element_blank), grid removed, dark backgrounds coordinated between plot and panel, good whitespace via plot_margin. Some refinement clearly visible.
• DE-03: Data Storytelling (3/6) — The eye shape naturally creates a focal point and the density colormap draws attention to high-trace-density areas. However, no annotations for eye height/width metrics and no additional visual hierarchy beyond the colormap.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Eye diagram implemented as density heatmap of overlaid traces — correct approach.
• SC-02: Required Features (4/4) — Density heatmap coloring ✓, time in UI ✓, voltage axis with signal levels ✓, NRZ signal with noise (5% sigma) and jitter (3% sigma) ✓, smooth sigmoid transitions ✓. Eye annotations are listed as optional in spec.
• SC-03: Data Mapping (3/3) — X=time(UI), Y=voltage(V), fill=density. All correct.
• SC-04: Title & Legend (3/3) — Title "eye-diagram-basic · letsplot · pyplots.ai" ✓. Legend "Trace Density" appropriate ✓.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows 400 overlaid traces with clear eye openings, transition regions, noise effects, and jitter. Good overall coverage. Could benefit from slightly varied signal quality to show partial eye closure.
• DQ-02: Realistic Context (5/5) — NRZ signal simulation with realistic engineering parameters. Neutral technology/engineering context.
• DQ-03: Appropriate Scale (4/4) — 0–2 UI time range, 0–1V amplitude, 5% noise sigma, 3% jitter sigma — all realistic for digital signal integrity analysis.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script: imports → data generation → binning → plotting → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set at the start.
• CQ-03: Clean Imports (2/2) — All imports are used. No unused imports.
• CQ-04: Code Elegance (2/2) — Clean, well-structured. Appropriate complexity for the 2D histogram approach. No fake UI or over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png with scale=3 for 4800×2700 output. Also saves HTML.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of ggplot grammar: geom_raster for density heatmap, scale_fill_gradientn with custom colors, comprehensive theme customization. Import style uses explicit imports rather than wildcard which is fine.
• LM-02: Distinctive Features (3/5) — Uses layer_tooltips with formatted tooltip lines (lets-plot specific interactive feature), guide_colorbar with custom dimensions, and HTML export alongside PNG. These are lets-plot distinctive features.

Score Caps Applied

• None — no score caps triggered.

Strengths

• Excellent dark theme design with custom hot colormap that is very appropriate for eye diagram visualization
• Clean signal simulation with realistic NRZ parameters (noise, jitter, sigmoid transitions)
• Full spec compliance — all required features implemented correctly
• Perfect code quality with KISS structure and reproducible seed
• Good use of lets-plot specific features (layer_tooltips, guide_colorbar, HTML export)

Weaknesses

• Raster cells appear slightly granular in transition regions — increasing bin resolution could help
• No eye height/width annotations (optional per spec but would elevate design excellence)
• Hot colormap, while effective, is not perceptually uniform — viridis or inferno variants could improve accessibility
• Data storytelling could be stronger with visual emphasis on the eye opening region

Issues Found

1. DE-03 MODERATE: Limited data storytelling — the plot displays data correctly but doesn't guide the viewer to specific insights
   • Fix: Add annotations showing eye height and eye width measurements to create focal points and tell the signal quality story
2. VQ-03 MINOR: Slightly granular raster appearance in low-density transition regions
   • Fix: Increase n_time_bins and n_voltage_bins for smoother rendering
3. VQ-04 MINOR: Custom hot colormap not perceptually uniform
   • Fix: Consider using a perceptually uniform warm palette or lets-plot's built-in gradient options

AI Feedback for Next Attempt

To reach 90+: (1) Add eye height and eye width annotations with measurement lines to improve data storytelling (DE-03). (2) Increase histogram bin resolution (e.g., 300×180) for smoother density rendering. (3) Consider a perceptually uniform colormap variant for better accessibility. These changes would elevate the plot from "good engineering visualization" to "publication-ready."

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 an eye diagram on a dark navy/black background (#0d0d2b plot, #4 panel). A density heatmap uses an inferno-inspired color palette (dark purple → magenta → orange → yellow) to show overlaid NRZ signal traces across 2 unit intervals (0–2 UI). Dense horizontal bands at 0V and 1V represent settled bit levels. Vertical transition bands at ~0.5, 1.0, and 1.5 UI show signal crossings. A rectangular eye opening is visible in the center. Cyan annotations mark "Eye Height: 0.68 V" (vertical segment on right) and "Eye Width: 0.79 UI" (horizontal segment in center). Title reads "eye-diagram-basic · letsplot · pyplots.ai". X-axis: "Time (UI)" with ticks at 0, 0.5, 1.0, 1.5, 2.0. Y-axis: "Voltage (V)" with ticks at 0.0, 0.5, 1.0. Colorbar labeled "Trace Density" on the right.

Score: 83/100

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

Visual Quality (26/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title 28pt, axis titles 20pt, tick labels 16pt, legend text 14pt/title 16pt. All clearly readable.
• VQ-02: No Overlap (5/6) - Minor crowding between "Eye Height" annotation text and the colorbar region on the right side.
• VQ-03: Element Visibility (4/6) - The density heatmap renders the eye pattern, but transition regions appear as very thin vertical bands due to overly steep sigmoid transitions (steepness ≈ 53), making the eye opening look rectangular rather than showing smooth curved edges.
• VQ-04: Color Accessibility (4/4) - Inferno palette is perceptually uniform and colorblind-safe. Cyan annotations contrast well against the dark background.
• VQ-05: Layout & Canvas (3/4) - Good proportions, plot fills canvas well. Slight excess space on left/right margins.
• VQ-06: Axis Labels & Title (2/2) - "Time (UI)" and "Voltage (V)" both include units.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) - Strong design choices: dark background matching the inferno palette domain, custom 12-stop color gradient, cyan annotation accents. Clearly above library defaults with intentional color harmony.
• DE-02: Visual Refinement (5/6) - Spines and ticks removed via element_blank, no grid, generous margins, dark theme coherently applied. Near-perfect polish.
• DE-03: Data Storytelling (4/6) - Eye height/width annotations guide the viewer to key signal quality metrics. The bright eye opening against the dark background creates natural visual hierarchy. The density coloring adds an informative dimension.

Spec Compliance (13/15)

• SC-01: Plot Type (4/5) - Correct eye diagram approach using density heatmap of overlaid traces. However, the eye opening is rectangular rather than showing the characteristic almond/eye shape with curved edges, due to transition steepness.
• SC-02: Required Features (3/4) - Has: density heatmap coloring ✓, time in UI ✓, voltage axis with signal levels ✓, noise and jitter ✓, eye height/width annotations ✓, sigmoid transitions ✓. However, transitions are too steep to appear as "realistic bandwidth-limited signals" per spec.
• SC-03: Data Mapping (3/3) - X is time in UI [0, 2], Y is voltage in V, correct mapping with appropriate ranges.
• SC-04: Title & Legend (3/3) - Title "eye-diagram-basic · letsplot · pyplots.ai" in correct format. Colorbar labeled "Trace Density" appropriately.

Data Quality (12/15)

• DQ-01: Feature Coverage (4/6) - Shows density variation, noise effects, jitter on transitions, eye opening. But the rectangular eye shape fails to demonstrate the characteristic curved S-transitions that are the hallmark of real eye diagrams.
• DQ-02: Realistic Context (5/5) - NRZ signal simulation with additive Gaussian noise (5% sigma) and random jitter (3% sigma) is a realistic telecommunications engineering context.
• DQ-03: Appropriate Scale (3/4) - Noise and jitter parameters are sensible, but steepness = 8.0/0.15 ≈ 53.3 is too high for a bandwidth-limited signal. A value around 15-25 would produce more realistic, visible S-curve transitions.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear flow: imports → data generation → binning → annotations → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set at the start.
• CQ-03: Clean Imports (2/2) - All imports are used, no unused imports.
• CQ-04: Code Elegance (2/2) - Clean, well-structured code with appropriate complexity. Good separation of data generation, binning, annotation calculation, and plotting.
• CQ-05: Output & API (1/1) - Saves as plot.png via ggsave(plot, "plot.png", path=".", scale=3). Current API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of lets-plot grammar-of-graphics: geom_raster for density, scale_fill_gradientn with custom colors, guide_colorbar, layer_tooltips. Proper ggplot idioms throughout.
• LM-02: Distinctive Features (3/5) - Uses lets-plot-specific layer_tooltips for interactive HTML tooltip formatting, guide_colorbar with lets-plot parameters (barwidth/barheight/nbin), and dual HTML+PNG export.

Score Caps Applied

• None

Strengths

• Excellent dark theme design with coherent color palette (inferno + dark background + cyan accents)
• Eye height/width annotations add meaningful signal quality context
• Clean, well-structured code with proper reproducibility
• Good use of lets-plot features including tooltips and custom colorbar
• Perfect text legibility with all font sizes explicitly set

Weaknesses

• Sigmoid steepness is too high (~53), making transitions nearly instantaneous and the eye opening rectangular instead of showing characteristic curved S-transitions
• The eye diagram should show smooth, bandwidth-limited transitions creating an almond-shaped eye opening

Issues Found

1. VQ-03/DQ-01 MEDIUM: Rectangular eye shape due to overly steep transitions (steepness ≈ 53)
   • Fix: Reduce steepness from 8.0 / 0.15 to approximately 8.0 / 0.4 (≈20) to produce visible, smooth S-curve transitions that create the characteristic eye shape with curved edges
2. SC-02 MINOR: Spec requires "smooth transitions between bit levels using a raised-cosine or sigmoid filter to simulate realistic bandwidth-limited signals" — current steepness makes transitions too fast to appear bandwidth-limited
   • Fix: Lower steepness value will naturally address this

AI Feedback for Next Attempt

The primary issue is the sigmoid steepness parameter. Reduce it from ~53 to ~20 so that signal transitions are visibly smooth S-curves rather than near-instantaneous vertical jumps. This will transform the rectangular eye opening into the characteristic almond/eye shape with curved edges, which is the defining visual feature of an eye diagram. Everything else — design, code quality, annotations, color scheme — is strong.

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 eye diagram on a dark background (#4 panel, #0d0d2b outer) mimicking an oscilloscope display. A density heatmap rendered via geom_raster shows overlaid NRZ signal traces using an inferno-inspired colormap — dark blue/purple for low trace density, through pink/magenta, to bright yellow/orange for high density regions. The characteristic eye-shaped opening is clearly visible centered around 1.0 UI. The high-density (yellow) regions appear at the stable 0V and 1V signal levels and along the transition paths. The X-axis is labeled "Time (UI)" with ticks at 0.0, 0.5, 1.0, 1.5, 2.0. The Y-axis is labeled "Voltage (V)" with ticks at 0.0, 0.5, 1.0. Two cyan annotation lines mark the eye height (vertical, 0.68 V) and eye width (horizontal, 0.79 UI) with corresponding labels. A colorbar on the right shows "Trace Density" from 0 to 1. Title reads "eye-diagram-basic · letsplot · pyplots.ai" in light gray bold text.

Score: 91/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 28pt, axis titles 20pt, axis text 16pt, legend title 16pt, legend text 14pt. All perfectly readable.
• VQ-02: No Overlap (6/6) — No overlapping text elements. Annotations are well-positioned and clear.
• VQ-03: Element Visibility (5/6) — Density heatmap is well-rendered at 300×180 bins giving smooth results. Minor vertical streak artifacts visible at the time window boundaries (0 and 2 UI) from edge effects in data generation.
• VQ-04: Color Accessibility (4/4) — Inferno-inspired colormap is perceptually uniform and colorblind-safe. Cyan annotations provide excellent contrast against the dark background.
• VQ-05: Layout & Canvas (3/4) — Plot fills canvas well with good proportions. Minor deduction for the edge artifacts that create visual noise at the left/right boundaries.
• VQ-06: Axis Labels & Title (2/2) — "Time (UI)" and "Voltage (V)" are descriptive with appropriate units.

Design Excellence (17/20)

• DE-01: Aesthetic Sophistication (7/8) — Excellent dark oscilloscope aesthetic perfectly suited for this engineering visualization. Custom inferno-inspired palette, cyan measurement annotations, and cohesive dark theme create a professional, domain-appropriate look. Clearly above defaults.
• DE-02: Visual Refinement (5/6) — Spines removed, ticks removed, grid removed, dark themed backgrounds with subtle distinction between panel and plot area, generous margins. Well-polished detail work.
• DE-03: Data Storytelling (5/6) — Eye height and width annotations immediately communicate signal quality metrics. Density colormap creates natural visual hierarchy drawing attention to high-density stable regions. The viewer instantly understands signal integrity quality.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: density heatmap of overlaid NRZ signal traces forming an eye diagram.
• SC-02: Required Features (4/4) — All spec features present: density heatmap coloring with hot colors for high density, time axis in UI, voltage axis showing 0/1 signal levels, synthetic NRZ data with controlled noise (5%) and jitter (3%), sigmoid transitions for bandwidth-limited edges, eye height and width annotations.
• SC-03: Data Mapping (3/3) — X=time in unit intervals, Y=voltage in volts. Axes show full data range appropriately.
• SC-04: Title & Legend (3/3) — Title follows exact format "eye-diagram-basic · letsplot · pyplots.ai". Colorbar legend "Trace Density" is descriptive and appropriate.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows both stable signal levels (0V, 1V), transitions between levels, noise effects (spread at stable levels), jitter effects (spread at transitions), and clear eye opening. Minor deduction for edge artifacts from windowing.
• DQ-02: Realistic Context (5/5) — NRZ signal integrity analysis is a genuine engineering application. Parameters are realistic: 400 traces, 5% noise sigma, 3% jitter sigma.
• DQ-03: Appropriate Scale (4/4) — Voltage 0–1V for NRZ, 2 UI time window, noise and jitter magnitudes are all physically sensible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean imports → data generation → plot construction → save structure. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set at the beginning.
• CQ-03: Clean Imports (2/2) — All imports are used. Specific imports from lets_plot rather than wildcard.
• CQ-04: Code Elegance (2/2) — Appropriate complexity for the signal simulation. Clean vectorized operations, well-organized annotation data preparation.
• CQ-05: Output & API (1/1) — Saves as plot.png via ggsave() with scale=3. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good ggplot grammar usage: aes mapping, geom_raster for density, scale_fill_gradientn, comprehensive theme customization. Could have explored more advanced lets-plot patterns.
• LM-02: Distinctive Features (3/5) — Uses layer_tooltips() for interactive hover info (distinctive lets-plot feature), guide_colorbar() with custom barwidth/barheight/nbin, and HTML export alongside PNG.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Excellent dark oscilloscope aesthetic perfectly suited for the engineering domain (keep this design direction)
• Comprehensive signal generation with realistic noise, jitter, and bandwidth-limited sigmoid transitions
• Eye height/width annotations add quantitative value and tell the signal quality story
• High-resolution 300×180 bin density heatmap for smooth rendering
• Well-crafted inferno-inspired colormap with perceptually uniform progression

Weaknesses

• Minor vertical streak artifacts at time window boundaries (0 and 2 UI) from edge effects in data extraction windowing
• Could leverage more distinctive lets-plot features

Issues Found

1. VQ-03/VQ-05 MINOR: Edge artifacts at time boundaries create vertical streaks
   • Fix: Extend signal generation beyond the display window or taper edge bins

AI Feedback for Next Attempt

Strong implementation that successfully captures the oscilloscope aesthetic. The density heatmap, dark theme, and measurement annotations create a professional engineering visualization. Minor edge artifacts at time boundaries are the only notable visual issue.

Verdict: APPROVED