update(band-basic): altair — comprehensive quality review

[MarkusNeusinger]

Summary

Updated altair implementation for band-basic.

Changes: Comprehensive quality review — improved data context, axis labels, visual design.

Test Plan

• Preview images uploaded to GCS staging
• Implementation file passes ruff format/check
• Metadata YAML updated with current versions
• Automated review triggered

---

Generated with Claude Code /update command

[Copilot]

Pull request overview

This pull request updates the altair implementation for the band-basic plot type as part of a comprehensive quality review. The changes include improvements to visual design (reduced line width, grid opacity), enhanced axis labeling with units, and updates to specification metadata. However, several issues need to be addressed before merging.

Changes:

• Updated specification to mark y_center as required instead of optional and added new taxonomy tags
• Modified visual design parameters (strokeWidth, gridOpacity) for better aesthetics
• Enhanced axis labels with unit information (mV for signal amplitude)
• Updated metadata with new Python version (3.14), AI model version, and reset quality score to null

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
plots/band-basic/specification.yaml	Updated timestamp, added timeseries, general, engineering domain tags, and 2d feature tag
plots/band-basic/specification.md	Changed y_center from optional to required parameter
plots/band-basic/metadata/altair.yaml	Updated Python version to 3.14, model to claude-opus-4-6, reset quality score to null, and updated timestamp
plots/band-basic/implementations/altair.py	Fixed header format spacing, improved visual design parameters, added units to axis label

[Copilot]

The header docstring format is inconsistent with the codebase convention. The opening triple quotes should be followed by a space before "pyplots.ai". The standard format used throughout the codebase is """ pyplots.ai not """pyplots.ai.

Suggested change

	"""pyplots.ai
	""" pyplots.ai

[Copilot]

The quality score line shows an incomplete value "Quality: /100" instead of a numeric score. While this may be intentional for work-in-progress, it's inconsistent with other implementations that show complete quality scores (e.g., "Quality: 88/100", "Quality: 91/100"). The metadata file also sets quality_score to null which is consistent with this, but the header should either show the actual score or be updated after quality evaluation.

Suggested change

	Quality: /100 | Updated: 2026-02-23
	Quality: 90/100 | Updated: 2026-02-23

[Copilot]

The specification change from "optional" to required for y_center represents a potentially breaking change. The original specification marked y_center as "(numeric, optional)" but now it's marked as "(numeric)" without the optional qualifier. This should be verified against existing implementations in other libraries to ensure consistency, as some implementations may have been built without including the center line based on the original "optional" specification.

Suggested change

	- `y_center` (numeric) - Central trend line values (mean/median), shown as a contrasting line
	- `y_center` (numeric, optional) - Central trend line values (mean/median), shown as a contrasting line

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a band chart on a white background with a light blue semi-transparent filled region (confidence band) between upper and lower boundaries, and a darker blue central trend line running through the middle. The x-axis is labeled "Time (s)" ranging from 0.0 to 10.0 with tick marks at 0.4 intervals. The y-axis is labeled "Signal Amplitude (mV)" ranging from approximately -3.0 to 10.0. The title "band-basic · altair · pyplots.ai" appears at the top in a large font. The central line follows a sinusoidal pattern with upward linear growth, creating two peaks (around x=1.8 and x=8.0) and a trough (around x=4.5). The confidence band widens progressively from left to right, starting narrow (~1 mV wide) at x=0 and expanding to ~4 mV wide at x=10, realistically depicting growing uncertainty over time. The grid is very subtle (low opacity) and view borders are removed, giving a clean appearance.

Score: 86/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title=28pt, axis labels=22pt, ticks=18pt, all clearly readable
• VQ-02: No Overlap (6/6) - No overlapping text elements, tick labels well-spaced
• VQ-03: Element Visibility (6/6) - Band clearly visible at 0.3 opacity, central line at strokeWidth=2.5 is distinct
• VQ-04: Color Accessibility (4/4) - Single Python Blue hue (#306998), no colorblind issues, good contrast
• VQ-05: Layout & Canvas (4/4) - Plot fills canvas well, balanced margins, no content cut off
• VQ-06: Axis Labels & Title (2/2) - "Time (s)" and "Signal Amplitude (mV)" both descriptive with units

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) - Clean, well-configured default with Python Blue and subtle grid, but single-color scheme lacks sophisticated palette or intentional hierarchy
• DE-02: Visual Refinement (4/6) - View strokes removed, grid opacity at 0.2, reasonable whitespace — shows intentional refinement beyond defaults
• DE-03: Data Storytelling (2/6) - Data is displayed correctly but no visual hierarchy or emphasis guides the viewer; the widening band is inherent to the data, not a design choice

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct band plot with filled region between boundaries and central trend line
• SC-02: Required Features (4/4) - Semi-transparent fill (alpha 0.3), central line, smooth interpolation, 100 data points
• SC-03: Data Mapping (3/3) - X maps to time, Y maps to signal amplitude, band boundaries correct
• SC-04: Title & Legend (3/3) - Title format "band-basic · altair · pyplots.ai" correct, no legend needed for single series

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows sinusoidal + linear trend, widening uncertainty, both peaks and troughs; could benefit from additional complexity (e.g., narrowing band at some point)
• DQ-02: Realistic Context (5/5) - Signal amplitude in mV with 95% confidence interval over time — plausible scientific measurement context
• DQ-03: Appropriate Scale (4/4) - mV range (-3 to 10) and time (0-10s) are realistic for electronic signal measurements

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean Imports → Data → Plot → Save structure, no functions or classes
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set, data is actually deterministic (no random calls needed but seed doesn't hurt)
• CQ-03: Clean Imports (2/2) - All three imports (altair, numpy, pandas) are used
• CQ-04: Code Elegance (2/2) - Clean, concise Pythonic code with good layer composition
• CQ-05: Output & API (1/1) - Saves as plot.png and plot.html, uses current Altair 6.x API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of mark_area/mark_line, alt.X/Y/Y2 encodings, layer composition with + operator, properties/configure chain
• LM-02: Distinctive Features (3/5) - Y2 encoding for band area and + operator for layer composition are distinctive to Altair's grammar; but doesn't leverage interactive features (tooltips, selections) in the HTML export

Score Caps Applied

• None — no cap conditions triggered (DE-01=4 > 2, so "correct but boring" cap does not apply)

Strengths

• Perfect visual quality with all font sizes explicitly set and no overlap issues
• Correct title format and descriptive axis labels with appropriate units
• Realistic scientific data context with widening confidence intervals demonstrating band utility
• Clean, idiomatic Altair code with proper KISS structure
• Good use of Y2 encoding for the band area, which is a distinctive Altair feature

Weaknesses

• Design stays at configured-default level with single Python Blue color for both band and line
• No visual hierarchy or data storytelling beyond what the data inherently shows
• Central line uses same color (#306998) as the band — a darker shade would create stronger visual separation
• Does not leverage Altair's interactive capabilities (tooltips, zoom/pan) in the HTML export

Issues Found

1. DE-01 MEDIUM (4/8): Single-color scheme looks like a well-configured default, not a polished design
   • Fix: Use a darker shade for the central line (e.g., #1a3a5c) to create stronger contrast with the lighter band
2. DE-03 LOW (2/6): No visual hierarchy or storytelling emphasis
   • Fix: Consider using color variation, gradient effects, or strategic data annotations to guide the viewer's eye to the key insight (widening uncertainty)
3. LM-02 MEDIUM (3/5): Doesn't fully leverage Altair's distinctive features
   • Fix: Add interactive tooltips or selection-based highlighting in the HTML export to demonstrate Altair's interactive capabilities

AI Feedback for Next Attempt

Improve design excellence: use a darker line color (e.g., #1a3a5c) for the central trend to create stronger contrast with the semi-transparent band. Add visual hierarchy through strategic emphasis — consider highlighting the region where uncertainty grows most rapidly. For library mastery, leverage Altair's interactive features (tooltips showing exact values, zoom/pan) in the HTML export. The plot is technically excellent but needs more aesthetic sophistication and data storytelling to reach publication quality.

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 band chart titled "band-basic · altair · pyplots.ai" with a dark navy central trend line showing a sinusoidal pattern combined with linear growth (from ~0 at x=0 to ~4 at x=10). Two semi-transparent blue bands surround the central line: an inner narrower band (50% CI) with medium blue opacity and an outer wider band (95% CI) with lighter blue opacity. Both bands widen progressively from left to right, demonstrating growing uncertainty over time. The x-axis is labeled "Time (s)" ranging from 0.0 to 10.0, and the y-axis is labeled "Signal Amplitude (mV)" ranging from approximately -3.0 to 10.0. The grid is very subtle (low opacity), the view border is removed, and all text is clearly readable. The color scheme is monochromatic blue throughout (#306998 for bands, #1a3a5c for the line).

Score: 88/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title=28pt, axis titles=22pt, tick labels=18pt. All clearly readable.
• VQ-02: No Overlap (6/6) - No overlapping text elements. Tick labels well-spaced on both axes.
• VQ-03: Element Visibility (5/6) - Central line and inner band clearly visible. Outer band edges are quite faint at 0.2 opacity; at the extremes the boundary is hard to discern against the white background.
• VQ-04: Color Accessibility (4/4) - Monochromatic blue scheme is inherently colorblind-safe with good contrast between line and bands.
• VQ-05: Layout & Canvas (4/4) - Plot fills canvas well at 1600x900 (16:9). Balanced margins, no wasted space.
• VQ-06: Axis Labels & Title (2/2) - "Time (s)" and "Signal Amplitude (mV)" — descriptive with units.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) - Cohesive monochromatic blue palette with dual CI bands creating layered depth. Above well-configured defaults but still relatively simple — the design is fundamentally one color at different opacities. Needs richer visual treatment to reach "strong design" level.
• DE-02: Visual Refinement (4/6) - View strokes removed, grid opacity at 0.2 (subtle), monotone interpolation for smooth curves. Good refinement but could push further (e.g., axis-specific grid styling, more generous whitespace).
• DE-03: Data Storytelling (3/6) - The widening uncertainty bands implicitly communicate growing uncertainty over time, which is meaningful. However, there's no explicit focal point or visual emphasis — the viewer must discover the widening pattern on their own. An annotation or color gradient highlighting the uncertainty growth region could strengthen the narrative.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct band plot with filled region between boundaries and central trend line. Exceeds spec with dual-band (50% + 95% CI).
• SC-02: Required Features (4/4) - Semi-transparent fill (alpha=0.2), central line in contrasting darker color, smooth monotone interpolation, 100 data points.
• SC-03: Data Mapping (3/3) - X=time (independent), Y=signal amplitude (dependent). Axes show full data range.
• SC-04: Title & Legend (3/3) - Title "band-basic · altair · pyplots.ai" in correct format. No legend needed for single-series band plot.

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) - Shows widening CI (growing uncertainty), dual confidence bands (50% and 95%), sinusoidal pattern with linear growth. Covers band plot features well but only demonstrates one type of uncertainty pattern.
• DQ-02: Realistic Context (4/5) - "Signal Amplitude (mV)" is a plausible scientific/engineering scenario. Growing uncertainty over time is realistic. However, context remains somewhat generic — a more specific domain (e.g., sensor drift, oscilloscope measurement) would strengthen it.
• DQ-03: Appropriate Scale (4/4) - Signal in millivolt range, time in seconds, uncertainty scaling factor of 0.5+0.15x — all realistic for the domain.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean Imports → Data → Plot layers → Combine → Save structure. No functions or classes.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set. Data is actually deterministic (np.sin, np.linspace) so fully reproducible.
• CQ-03: Clean Imports (2/2) - All three imports (altair, numpy, pandas) are used.
• CQ-04: Code Elegance (2/2) - Clean, well-organized. Interactive elements (tooltips, hover) are legitimate Altair features for the HTML export, not fake UI.
• CQ-05: Output & API (1/1) - Saves as plot.png with scale_factor=3.0 and plot.html. Uses current Altair 6.x API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) - Declarative layered composition with + operator, proper encoding types (:Q), mark_area with y/y2 for bands, configure_axis/configure_view for global styling.
• LM-02: Distinctive Features (4/5) - Uses selection_point(nearest=True) for interactive hover, alt.condition for conditional encoding, alt.Tooltip with formatting, y2 encoding for bands, HTML export. These are distinctively Altair features. Loses 1 point because the interactive features are invisible in the PNG output.

Score Caps Applied

• None — no cap conditions triggered

Strengths

• Dual confidence bands (50% + 95% CI) creating layered visual depth — exceeds spec requirements
• Excellent Altair idioms: declarative layer composition, selection/condition for interactivity, y2 encoding
• Clean monochromatic color palette with consistent Python Blue theme
• Growing uncertainty bands convey realistic time-series behavior
• Dual output (PNG + HTML) leverages Altair's web-native strengths
• All font sizes explicitly configured for readability

Weaknesses

• Design sophistication is limited by the monochromatic-only approach — needs richer visual treatment
• No visual emphasis or focal point to guide the viewer's attention to the key insight (growing uncertainty)
• Outer band edges are quite faint at 0.2 opacity, reducing visual clarity at the extremes
• Data context is somewhat generic ("Signal Amplitude") — a more specific scenario would improve realism

Issues Found

1. DE-01 MEDIUM: Monochromatic palette with single-color opacity layering is cohesive but lacks the richness for 6+ score
   • Fix: Consider a subtle color shift between inner/outer bands (e.g., slightly different hue for inner band) or add a subtle background tint to increase visual depth
2. DE-03 LOW: No explicit focal point or visual emphasis on the key insight
   • Fix: Use color intensity, an annotation, or a subtle highlight at the right side where uncertainty is widest to draw the viewer's eye to the storytelling element
3. VQ-03 MINOR: Outer band boundaries are faint at low opacity
   • Fix: Slightly increase outer band opacity to 0.25-0.3, or add a very thin border stroke to the outer band area

AI Feedback for Next Attempt

To reach 90+, focus on Design Excellence (+2 points needed). (1) Strengthen DE-01 by introducing subtle color variation between inner/outer bands or adding a complementary accent — the current single-hue approach is clean but visually monotone. (2) Improve DE-03 by adding a visual focal point — e.g., a small annotation at x=10 showing "±2.5 mV" to make the growing uncertainty explicit, or use a subtle color gradient in the outer band. (3) Consider increasing outer band opacity slightly (0.25-0.3) so the band boundaries are crisper. The implementation is technically excellent; the gap to 90 is purely in design polish and storytelling.

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 band chart with an oscilloscope signal theme over a 0–10 second time range. A dark navy center line traces a sinusoidal wave with upward linear drift (approximately 2·sin(x) + 0.5x), ranging from about −2.5 mV to 6 mV. Two semi-transparent blue confidence bands surround it: a lighter outer band (95% CI, teal-blue #4a8db7 at 0.25 opacity) and a darker inner band (50% CI, #306998 at 0.3 opacity). Both bands visibly widen from left to right, illustrating growing uncertainty over time. At x ≈ 9.1 s, a red dashed vertical rule spans the full 95% CI width, with bold red annotation text "95% CI: ±3.7 mV" offset to the right. The title reads "band-basic · altair · pyplots.ai" in 28pt at the top. Axes are labeled "Time (s)" (x) and "Oscilloscope Signal (mV)" (y) with explicit font sizing. Grid lines are very subtle (0.15 opacity, light gray). The view border is removed. The layout fills the 4800×2700 canvas well with balanced margins.

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 28pt, axis titles 22pt, tick labels 18pt, annotation 16pt bold. All perfectly readable.
• VQ-02: No Overlap (6/6) — No overlapping text elements. Annotation positioned with dx=10 to avoid collision with rule.
• VQ-03: Element Visibility (6/6) — Center line (strokeWidth=2.5) clearly visible against bands. Bands distinguishable via different blue tones and opacity levels. Monotone interpolation creates smooth, clean curves.
• VQ-04: Color Accessibility (4/4) — Monochromatic blue scheme is inherently colorblind-safe. Red accent used only for annotation (not data comparison), good contrast against blue.
• VQ-05: Layout & Canvas (4/4) — 1600×900 at scale_factor=3.0 produces 4800×2700. Plot fills canvas well with balanced margins.
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" and "Oscilloscope Signal (mV)" both descriptive with units.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Cohesive monochromatic blue palette with three intentional tones (#4a8db7 outer, #306998 inner, #1a3a5c center) creating visual depth. Red accent (#c0392b) for annotation provides strong contrast. Clearly above configured defaults.
• DE-02: Visual Refinement (4/6) — Subtle grid (opacity=0.15, light gray), view border removed (strokeWidth=0), smooth monotone interpolation. Axis line styling remains at Altair defaults, preventing a higher score.
• DE-03: Data Storytelling (5/6) — The widening band immediately communicates growing uncertainty over time. Dual-band approach (50% + 95% CI) adds analytical depth. Red annotation at x≈9 creates a clear focal point quantifying the spread. Viewer is guided through the data narrative.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct band plot with filled region between boundary lines.
• SC-02: Required Features (4/4) — Semi-transparent fill (alpha 0.25/0.3 within spec range), contrasting center line (#1a3a5c dark navy), smooth monotone interpolation. Exceeds spec with bonus 50% CI inner band.
• SC-03: Data Mapping (3/3) — x=Time, y_lower/y_upper boundaries, y_center trend line all correctly mapped. 100 data points within 20–200 range. Axes show full data extent.
• SC-04: Title & Legend (3/3) — Title "band-basic · altair · pyplots.ai" matches required format. No legend required for single-series band plot; annotation serves as CI label.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Demonstrates widening uncertainty over time, sinusoidal + linear trend, dual confidence intervals (50% and 95%), and annotated callout. Shows all aspects of band plot functionality.
• DQ-02: Realistic Context (5/5) — Oscilloscope voltage measurement with sensor drift uncertainty is a real-world scientific scenario. Neutral topic.
• DQ-03: Appropriate Scale (4/4) — Millivolt range (−3 to 10 mV) and 0–10 second timespan are realistic for oscilloscope measurements. Uncertainty growth (±1 to ±3.7 mV) is plausible sensor drift.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data generation → plot layers → combine → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Data is deterministic (np.linspace, np.sin). Seed set for good practice.
• CQ-03: Clean Imports (2/2) — All three imports (altair, numpy, pandas) are used.
• CQ-04: Code Elegance (2/2) — Clean and well-structured. Interactive features (selection, tooltips) are legitimate Altair capabilities that work in HTML export and are invisible in static PNG. No fake functionality.
• CQ-05: Output & API (1/1) — Saves plot.png with scale_factor=3.0. Also saves plot.html for interactive version. Uses current Altair 6.x API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Declarative grammar of graphics: mark_area, mark_line, mark_rule, mark_text, mark_point all correctly used. Proper encoding with type shorthand (:Q, :N). Layer composition with + operator. configure_axis/configure_view for styling.
• LM-02: Distinctive Features (4/5) — alt.selection_point with nearest=True for interactive hover, alt.condition for conditional encoding, rich alt.Tooltip specifications, HTML export alongside PNG. These are distinctive Altair features not easily replicated in other libraries. Does not reach 5 as the core visualization (area+line) is standard.

Score Caps Applied

• None — no cap conditions triggered

Strengths

• Cohesive monochromatic blue palette with three intentional tones creates visual depth and professional polish
• Dual confidence bands (50% + 95% CI) exceed spec requirements and add analytical value
• Growing uncertainty narrative is immediately apparent and reinforced by the red annotation callout
• Interactive features (tooltips, hover guide) work in HTML export without polluting static PNG output
• All text sizes explicitly set with appropriate hierarchy (28/22/18/16pt)

Weaknesses

• Axis line/tick styling remains at Altair defaults rather than being refined (DE-02)
• Interactive features (selection, tooltips) are invisible in the static PNG — only benefit the HTML export (LM-02)

Issues Found

1. DE-02 MINOR: Axis lines and tick marks use default Altair styling. Configure axis domain and tick properties for more polish.
   • Fix: Use configure_axis with domainColor, tickColor, or domainWidth to refine axis appearance
2. LM-02 MINOR: Core band visualization uses standard area+line marks. Could leverage Altair-specific features like fold transform or calculated fields to demonstrate deeper library knowledge.

AI Feedback for Next Attempt

Strong implementation at attempt 3. The monochromatic blue scheme, dual CI bands, annotation callout, and interactive features demonstrate both design thought and library understanding. Minor remaining gap is axis styling refinement and deeper use of Altair-specific transforms. Overall publication-quality work.

Verdict: APPROVED