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

[MarkusNeusinger]

Summary

Updated LIB_PLACEHOLDER implementation for scatter-basic.

Changes: Comprehensive quality review — improved variable naming, realistic data context, white marker edges for point definition, subtler grid styling, and explicit font sizing for large canvas.

Changes

• Descriptive variable names with realistic data context
• White marker edges for better point definition
• Subtler grid styling (opacity ~0.15-0.2)
• Explicit font sizing for 4800x2700 canvas
• Library-specific improvements for idiomatic usage

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

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a scatter chart with steel-blue filled circular markers (#306998 Python Blue) with white edge strokes, plotting "Study Hours per Day" (x-axis, range ~1.0–8.0) against "Exam Score (%)" (y-axis, range ~40–104). The title "scatter-basic · altair · pyplots.ai" appears centered at the top in a large font. A clear positive correlation is visible — students who study more hours tend to score higher. Grid lines are present but subtle (low opacity). The background is clean white with no view border. Points have moderate transparency (opacity 0.7) revealing some overlap in the denser middle region (4–6 hours). No legend is shown (single series). The layout uses canvas space reasonably well, though there is some empty space on the left side between ~1.0 and ~2.0 hours.

Quality Score: 81/100

Criteria Checklist

Visual Quality (24/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title 28pt, axis labels 22pt, tick labels 18pt. All perfectly readable.
• VQ-02: No Overlap (6/6) - No overlapping text elements anywhere.
• VQ-03: Element Visibility (5/6) - 100 points with size=150, opacity=0.7. Appropriate for the data density, markers slightly large but acceptable.
• VQ-04: Color Accessibility (4/4) - Single Python Blue color with good contrast on white. Colorblind-safe.
• VQ-05: Layout Balance (3/4) - Decent canvas utilization. Some wasted space on the left where data is sparse (gap between 1.0–2.0 hours).
• VQ-06: Axis Labels & Title (2/2) - Descriptive labels with units: "Study Hours per Day", "Exam Score (%)".

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) - Clean Python Blue, white marker edges, subtle grid — looks like a well-configured default. Not yet publication-level design.
• DE-02: Visual Refinement (4/6) - Grid opacity 0.2 (subtle), view stroke removed. Some refinement visible but still has default axis styling.
• DE-03: Data Storytelling (2/6) - Data is displayed but no annotations, trend line, correlation value, or narrative emphasis. Viewer must find the story themselves.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct 2D scatter plot.
• SC-02: Required Features (4/4) - Transparency, axis labels, title, grid lines all present per spec.
• SC-03: Data Mapping (3/3) - X/Y correctly assigned (hours → x, scores → y).
• SC-04: Title Format (3/3) - Correct format "scatter-basic · altair · pyplots.ai". No legend needed.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows positive correlation with noise, natural spread. Could benefit from a few more distinct outliers or clusters.
• DQ-02: Realistic Context (5/5) - Study hours vs exam scores is a real, neutral educational scenario.
• DQ-03: Appropriate Scale (4/4) - Hours 1–10/day and scores 40–100% are realistic values.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean imports → data → plot → save flow.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) - All imports (altair, numpy, pandas) are used.
• CQ-04: Code Elegance (2/2) - Clean, Pythonic, appropriate complexity.
• CQ-05: Output & API (1/1) - Saves as plot.png and plot.html.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) - Declarative encoding with type annotations (:Q), method chaining, configure_axis, properties, interactive().
• LM-02: Distinctive Features (3/5) - Uses tooltips, interactive() zoom/pan, and HTML export — Altair-specific features.

Strengths

• Perfect spec compliance (15/15) with correct title format, all required features, and proper data mapping
• Idiomatic Altair usage with declarative encoding, type annotations, and method chaining
• Excellent code quality with KISS structure, fixed seed, clean imports
• Realistic educational scenario with appropriate data ranges
• Tooltips and interactive zoom/pan leverage Altair's interactive strengths
• Font sizes explicitly set for readability at full resolution

Weaknesses

• No data storytelling: add a trend line, correlation annotation (r=0.XX), or callout for interesting patterns to guide the viewer
• Design could be elevated beyond "well-configured default" — consider background color, custom axis formatting, or annotation styling
• Some wasted canvas space on the left side where data is sparse (1.0–2.0 range has only one point)
• Markers could be slightly smaller to better show individual points in the dense center region

Verdict: REJECTED

[Copilot]

Pull request overview

This PR updates the altair implementation of the scatter-basic plot with comprehensive quality improvements. The changes focus on improving code quality, data context, and visual styling while maintaining compatibility with the project's established patterns.

Changes:

• Updated variable names from generic x/y to descriptive study_hours/exam_scores with realistic educational context
• Added white marker edges (stroke="white", strokeWidth=0.5) for better point definition
• Reduced grid opacity from 0.3 to 0.2 for subtler styling
• Added .interactive() method for enhanced interactivity in HTML output
• Updated metadata with Python 3.14 version and reset quality_score to null for re-evaluation

Reviewed changes

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

File	Description
plots/scatter-basic/implementations/altair.py	Core implementation updated with better variable naming, white marker edges, improved grid styling, and interactive functionality
plots/scatter-basic/metadata/altair.yaml	Metadata updated to reflect Python 3.14, new timestamp, generator version, and null quality_score for pending review

[Copilot]

The docstring is missing a space after the opening triple quotes. According to the codebase convention, the format should be """ pyplots.ai (with a space) rather than """pyplots.ai (without a space). This pattern is consistently used across all other plot implementations in the repository.

Suggested change

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

[Copilot]

The PR description contains "LIB_PLACEHOLDER" which appears to be a template placeholder that was not replaced with the actual library name "altair". This should be updated in the PR description for clarity.

[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 scatter plot with ~100 blue filled circular markers (#306998) with white stroke edges on a white background. The x-axis is labeled "Study Hours per Day" (range 0–11) and the y-axis "Exam Score (%)" (range 20–110). The title reads "scatter-basic · altair · pyplots.ai" in dark text (~28pt) with a gray subtitle "Positive correlation between daily study hours and exam performance." A dashed red (#c44e52) trend line runs diagonally from lower-left to upper-right showing the positive linear relationship. A bold red annotation "r = 0.92" appears in the lower-right area. The grid is subtle (dashed, low opacity). Data points cluster along the trend line with natural scatter, showing low hours (~1.5–3.5) corresponding to scores ~35–55, mid hours (~4–7) to scores ~50–85, and high hours (~8–10) to scores ~77–100 with clipping at 100.

Quality Score: 88/100

Criteria Checklist

Visual Quality (26/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title 28pt, axis titles 22pt, tick labels 18pt. Perfectly readable.
• VQ-02: No Overlap (6/6) — No overlapping text elements anywhere.
• VQ-03: Element Visibility (5/6) — Markers size=120 with opacity 0.7 for 100 points is within guidelines (100-200 for 30-100 pts) but at the lower edge; slightly larger markers would improve visibility.
• VQ-04: Color Accessibility (3/4) — Blue and red are colorblind-distinguishable, but the trend line and annotation both use the same red (#c44e52), which could be improved with a more contrast-friendly palette choice.
• VQ-05: Layout Balance (2/4) — Y-axis domain extends to 105 (data max is 100) and x-axis to 10.5, leaving unused space at extremes. The "r = 0.92" annotation is positioned in a low-data region (bottom-right) which wastes prime visual real estate.
• VQ-06: Axis Labels & Title (2/2) — "Study Hours per Day" and "Exam Score (%)" are descriptive with contextual units.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom Python Blue, white marker strokes, custom axis color hierarchy ([area-basic] plotnine implementation #333/feat(plotly): implement donut-labeled #555/[bullet-basic] Basic Bullet Chart #999), dashed grid. Clearly above defaults, but the red trend line feels slightly harsh against the softer blue palette.
• DE-02: Visual Refinement (4/6) — Good: subtle grid (opacity 0.15, dashed), view stroke removed, custom tick/domain colors. Not quite "every detail polished" level.
• DE-03: Data Storytelling (4/6) — Good: trend line shows relationship, r=0.92 annotation highlights key insight, subtitle provides narrative. Reader is guided to the correlation story.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct scatter plot.
• SC-02: Required Features (4/4) — All spec features present: transparency (0.7), axis labels, descriptive title, grid lines, appropriate point size.
• SC-03: Data Mapping (3/3) — X/Y correctly assigned.
• SC-04: Title Format (3/3) — "scatter-basic · altair · pyplots.ai" correct. No legend needed for single-series.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows correlation, spread, and some clustering at extremes. Could benefit from more visible outlier patterns or density variation.
• DQ-02: Realistic Context (5/5) — Study hours vs. exam scores is a real, neutral, comprehensible educational scenario.
• DQ-03: Appropriate Scale (4/4) — Realistic values: 1.5–9.5 hours/day, scores 25–100%.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Imports → Data → Plot → Save, no functions/classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• 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 plot.png and plot.html.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Declarative encoding with :Q types, layered composition with +, alt.Title with subtitle, configure_axis, alt.Tooltip with formatting, alt.Scale.
• LM-02: Distinctive Features (4/5) — Declarative layer composition, .interactive() for zoom/pan, tooltip encoding, alt.Title subtitle configuration — genuinely Altair-specific patterns.

Strengths

• Excellent use of Altair's declarative grammar: layer composition with +, typed encodings, and alt.Title with subtitle
• Strong data storytelling with trend line, correlation annotation (r=0.92), and descriptive subtitle
• All font sizes explicitly configured for readability at target resolution
• Clean, well-structured code following KISS principle with realistic educational data scenario
• Interactive features (.interactive(), tooltips) leverage Altair's web-native strengths

Weaknesses

• Layout has wasted space: y-axis domain extends to 105 when max data is 100, and x-axis padding is generous; tighter axis domains would improve canvas utilization
• The "r = 0.92" annotation at position (9.2, 38) sits in a visually dead zone; repositioning it closer to the trend line or in a subtitle/caption would be more effective
• Trend line and annotation share the same red (#c44e52) which, while functional, doesn't maximize the color hierarchy — a softer or contrasting color for the trend line could reduce visual competition with the data points
• Grid opacity and dash styling is good but could be further refined (e.g., removing top/right axis domain lines entirely for a cleaner look)

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 scatter plot with 100 blue filled circular markers (#306998) with white edge strokes on a clean white background. The title "scatter-basic · altair · pyplots.ai" is displayed prominently at the top in dark text (~28pt), with a gray subtitle "Positive correlation between daily study hours and exam performance" below it. The X-axis is labeled "Study Hours per Day" ranging from 1 to 10, and the Y-axis is labeled "Exam Score (%)" ranging from 20 to 100. A dashed gray trend line runs diagonally from the lower-left to upper-right, indicating the positive linear relationship. A correlation annotation "r = 0.92" is positioned near the center of the plot in gray bold text. The grid consists of subtle dashed lines at low opacity. The data points show a clear positive correlation with natural scatter — denser in the middle hours range (4-7) and sparser at the extremes, creating a realistic distribution. The overall layout is clean and professional with good use of whitespace and a cohesive muted color scheme.

Quality Score: 87/100

Criteria Checklist

Visual Quality (26/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title 28pt, axis titles 22pt, tick labels 18pt. All text perfectly readable at full size.
• VQ-02: No Overlap (6/6) - No overlapping text elements anywhere in the plot.
• VQ-03: Element Visibility (5/6) - Points size=150, opacity=0.7 for 100 data points fits guidelines well. Minor density in the 4-7 hour range causes slight visual merging.
• VQ-04: Color Accessibility (4/4) - Single blue (#306998) with gray trend line. No colorblind concerns.
• VQ-05: Layout Balance (2/4) - Plot fills canvas adequately but there is noticeable whitespace. The data distribution leaves corners underutilized.
• VQ-06: Axis Labels & Title (1/2) - Y-axis has units "Exam Score (%)" but X-axis "Study Hours per Day" lacks explicit unit notation in parenthetical form.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) - Strong design with custom Python Blue, white marker strokes, intentional color hierarchy, muted gray elements. Above defaults but not FiveThirtyEight-level.
• DE-02: Visual Refinement (4/6) - Subtle dashed grid at 0.15 opacity, view stroke removed, custom axis colors. Domain lines still present.
• DE-03: Data Storytelling (4/6) - Trend line with r = 0.92 annotation guides the viewer. Subtitle adds narrative context. Could benefit from outlier callouts or cluster annotations.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct basic 2D scatter plot.
• SC-02: Required Features (4/4) - All spec features: transparency (alpha 0.7), axis labels, descriptive title, grid lines.
• SC-03: Data Mapping (3/3) - X=study hours, Y=exam scores correctly assigned.
• SC-04: Title Format (3/3) - Exact format "scatter-basic · altair · pyplots.ai" with appropriate subtitle.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Clear positive correlation with natural spread from mixture distribution. No distinct outlier highlighting.
• DQ-02: Realistic Context (5/5) - Study hours vs exam scores is a classic, neutral educational scenario.
• DQ-03: Appropriate Scale (4/4) - Realistic values: hours 1.5-10, scores 25-100%.

Code Quality (9/10)

• CQ-01: KISS Structure (3/3) - Clean imports → data → plot → save flow with no functions/classes.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) - All imports used (altair, numpy, pandas).
• CQ-04: Code Elegance (1/2) - Slightly verbose with separate DataFrames for trend and annotation layers.
• CQ-05: Output & API (1/1) - Saves plot.png and plot.html correctly.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) - Expert use of declarative API: encoding types, alt.Scale, alt.Axis, alt.Tooltip, alt.Title with subtitle, layer composition.
• LM-02: Distinctive Features (4/5) - Layer composition (+), .interactive(), tooltip encoding, HTML export. Could use alt.Chart().transform_regression() for more idiomatic trend line.

Strengths

• Excellent use of Altair's declarative grammar with proper encoding types, layer composition, and configuration chain
• Strong data storytelling with trend line, correlation annotation (r = 0.92), and informative subtitle
• Professional aesthetic with custom color hierarchy, white marker strokes, subtle dashed grid, and muted axis styling
• Realistic educational scenario with a thoughtful mixture distribution creating natural data density variation
• Good use of Altair-specific features: interactive zoom/pan, tooltips, HTML export alongside PNG

Weaknesses

• Layout balance could be improved — some underutilized canvas space in corners
• X-axis label lacks explicit unit notation (e.g., "Study Hours per Day (hrs)")
• Trend line computed manually with np.polyfit instead of using Altair's built-in transform_regression
• Separate DataFrames for trend and annotation add verbosity to the code
• Domain lines still visible — removing them would further refine the minimal aesthetic

Verdict: APPROVED

[github-actions]

🔧 Repair Attempt 3/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 scatter chart with approximately 100 blue filled circle markers (Python Blue #306998) with white edge strokes on a clean white background. The x-axis is labeled "Study Hours per Day (hrs)" and ranges from 1 to 10. The y-axis is labeled "Exam Score (%)" and ranges from 20 to 100. A dashed gray trend line runs diagonally from lower-left to upper-right, clearly showing the positive linear relationship. A bold text annotation "r = 0.92" is positioned near the center of the plot. The title "scatter-basic · altair · pyplots.ai" is displayed prominently at the top in dark text, with a smaller gray subtitle "Positive correlation between daily study hours and exam performance" beneath it. The grid uses subtle dashed light gray lines at low opacity. Data points spread naturally around the trend line with realistic scatter, clustering denser in the 4-7 hour range (from the normal distribution component) and sparser at the extremes.

Quality Score: 88/100

Criteria Checklist

Visual Quality (26/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set: title 28pt, axis titles 22pt, tick labels 18pt. All perfectly readable.
• VQ-02: No Overlap (6/6) - No overlapping text elements anywhere.
• VQ-03: Element Visibility (5/6) - Markers size=150 with opacity=0.7 and white stroke edges. Good for 100 points, slightly on the larger side but effective.
• VQ-04: Color Accessibility (4/4) - Single-series Python Blue, colorblind-safe, good contrast against white.
• VQ-05: Layout Balance (2/4) - Plot fills canvas adequately but some wasted space in corners. Data doesn't fully utilize the defined axis domains.
• VQ-06: Axis Labels & Title (2/2) - Descriptive labels with units: "Study Hours per Day (hrs)" and "Exam Score (%)".

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) - Strong design with custom Python Blue, white stroke on markers, removed axis domains, dashed grid, custom title/subtitle hierarchy, and intentional color scheme ([area-basic] plotnine implementation #333/feat(plotly): implement donut-labeled #555/[waterfall-basic] Basic Waterfall Chart #777 text hierarchy). Above defaults but not quite publication-level perfection.
• DE-02: Visual Refinement (4/6) - Good refinement: subtle dashed grid at 0.15 opacity, view stroke removed, axis domains removed, custom tick/label colors. Minor gap from perfection.
• DE-03: Data Storytelling (4/6) - Correlation annotation (r = 0.92) and descriptive subtitle provide narrative. Trend line guides the eye through the relationship. Above default data display.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct 2D scatter plot.
• SC-02: Required Features (4/4) - All spec features present: transparency (opacity=0.7), axis labels, descriptive title, grid lines, appropriate point size.
• SC-03: Data Mapping (3/3) - X/Y correctly assigned: study hours → horizontal, exam scores → vertical.
• SC-04: Title Format (3/3) - Title "scatter-basic · altair · pyplots.ai" matches required format. No legend needed for single-series.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows clear positive correlation with realistic noise, data spread, and variation. Multi-component distribution (uniform tails + normal center) adds depth. Could benefit from a few more distinct outliers.
• DQ-02: Realistic Context (5/5) - Study hours vs exam scores: a neutral, comprehensible educational scenario.
• DQ-03: Appropriate Scale (4/4) - Realistic values: 1.5-9.5 study hours, 25-100% exam scores.

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.
• CQ-03: Clean Imports (2/2) - All imports used (altair, numpy, pandas).
• CQ-04: Code Elegance (2/2) - Appropriate complexity, clean Pythonic code, no over-engineering.
• CQ-05: Output & API (1/1) - Saves as plot.png with scale_factor=3.0 and plot.html.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) - Expert use of Altair's declarative grammar: encoding types (:Q), layered composition with +, configure_ methods, alt.Title, alt.Scale, alt.Axis.
• LM-02: Distinctive Features (4/5) - Uses transform_regression (Altair's built-in regression), layer composition, .interactive() for zoom/pan, tooltip encoding, and HTML export — features distinctive to Altair.

Strengths

• Excellent use of Altair's transform_regression for the trend line — idiomatic and avoids manual numpy polyfit for the line itself
• Strong text hierarchy with custom font sizes, colors ([line-basic] seaborn implementation #222, [area-basic] plotnine implementation #333, feat(plotly): implement donut-labeled #555, [waterfall-basic] Basic Waterfall Chart #777), and subtitle padding
• Clean layered composition (points + trend + annotation) using Altair's + operator
• Correlation annotation (r = 0.92) adds meaningful data storytelling
• Multi-component data generation (uniform tails + normal center) creates realistic-looking scatter distribution
• Dual output (PNG + HTML with interactivity) leverages Altair's web-native strengths

Weaknesses

• Layout could better utilize canvas space — the defined axis domains (1-10.5 x, 20-105 y) leave empty corners where no data exists
• Marker size=150 is at the upper boundary for 100 data points; reducing slightly could improve clarity in dense regions
• The "r = 0.92" annotation positioning relies on a manual calculation offset (+8) that could be fragile with different data

Verdict: APPROVED