feat(altair): implement residual-plot

[github-actions]

Implementation: residual-plot - altair

Implements the altair version of residual-plot.

File: plots/residual-plot/implementations/altair.py

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a residual plot for housing price predictions with "Fitted Values ($)" on the x-axis (ranging from 0 to ~520,000) and "Residuals ($)" on the y-axis (ranging from -50,000 to +40,000). Blue outlined circles represent "Normal" data points, while yellow outlined circles denote "Outlier (>2σ)" points. A black dashed horizontal reference line at y=0 indicates perfect predictions. Two gray dashed horizontal lines mark the ±2 standard deviation boundaries (~±31,000). A prominent red LOESS smoothing line reveals a characteristic "U-shaped" pattern in the residuals, starting high, dipping negative in the mid-range, and rising again - clearly demonstrating the non-linear relationship that the linear model failed to capture. The legend is positioned on the right side with "Point Type" header. The title correctly follows the format "residual-plot · altair · pyplots.ai".

Quality Score: 91/100

Criteria Checklist

Visual Quality (36/40 pts)

• VQ-01: Text Legibility (10/10) - Title at 28pt, axis labels at 22pt, tick labels at 18pt - all clearly readable
• VQ-02: No Overlap (8/8) - No overlapping text elements, all labels and ticks are well-spaced
• VQ-03: Element Visibility (7/8) - Points are well-sized (size=120) with good opacity (0.7), appropriate for 150 data points. Minor deduction: outlined points rather than filled could be slightly harder to see
• VQ-04: Color Accessibility (5/5) - Blue (#306998) and yellow (#FFD43B) are colorblind-safe and provide excellent contrast
• VQ-05: Layout Balance (4/5) - Good use of canvas space, minor whitespace on the left side of the plot area
• VQ-06: Axis Labels (2/2) - Descriptive labels with units: "Fitted Values ($)" and "Residuals ($)"
• VQ-07: Grid & Legend (0/2) - Grid is subtle (gridOpacity=0.3), but legend placement could be improved - it's somewhat isolated on the right

Spec Compliance (25/25 pts)

• SC-01: Plot Type (8/8) - Correct residual plot showing residuals vs fitted values
• SC-02: Data Mapping (5/5) - Y-axis shows residuals, X-axis shows fitted values as specified
• SC-03: Required Features (5/5) - All spec features present: horizontal reference line at y=0, alpha transparency, LOESS smoothing line, ±2σ bands, outlier coloring
• SC-04: Data Range (3/3) - All data points visible, axes show complete range with nice scaling
• SC-05: Legend Accuracy (2/2) - Legend correctly labels "Normal" and "Outlier (>2σ)" categories
• SC-06: Title Format (2/2) - Correctly formatted as "residual-plot · altair · pyplots.ai"

Data Quality (18/20 pts)

• DQ-01: Feature Coverage (7/8) - Shows outliers, non-linear pattern via LOESS, heteroscedasticity visible. Minor: could show more extreme outliers
• DQ-02: Realistic Context (7/7) - Housing price prediction is an excellent, comprehensible real-world scenario
• DQ-03: Appropriate Scale (4/5) - Values are realistic for housing prices ($200k-$500k fitted, residuals in $10k-$40k range). Slight deduction: the quadratic component creates a very pronounced pattern

Code Quality (9/10 pts)

• CQ-01: KISS Structure (3/3) - Simple linear flow: imports → data → plot layers → combine → save
• CQ-02: Reproducibility (3/3) - Uses np.random.seed(42)
• CQ-03: Clean Imports (2/2) - Only necessary imports: altair, numpy, pandas
• CQ-04: No Deprecated API (1/1) - Uses current Altair API
• CQ-05: Output Correct (0/1) - Saves both plot.png and plot.html (correct), but minor: ideally should only output what's needed

Library Features (3/5 pts)

• LF-01: Uses distinctive library features (3/5) - Good use of Altair's declarative layering system, transform_loess for smoothing, tooltips for interactivity. Could better leverage Altair's selection/interaction capabilities

Strengths

• Excellent implementation of all specification requirements including zero reference line, LOESS smoothing, ±2σ bands, and outlier highlighting
• Clear demonstration of non-linear residual pattern through LOESS line - educationally valuable
• Strong colorblind-safe palette with Python logo colors (blue/yellow)
• Good use of Altair's declarative layering for combining multiple visual elements
• Realistic housing price scenario makes the plot immediately comprehensible
• Proper title format and descriptive axis labels with units

Weaknesses

• Legend placement is slightly isolated from the main chart area - could be positioned closer
• Points use outlined circles which can be slightly less visible than filled circles at smaller sizes
• The grid lines behind the ±2σ dashed lines create slight visual noise

Verdict: APPROVED