feat(altair): implement facet-grid

[github-actions]

Implementation: facet-grid - python/altair

Implements the python/altair version of facet-grid.

File: plots/facet-grid/implementations/python/altair.py

Parent Issue: #2696

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The faceted grid displays on a warm off-white surface (#FAF8F1) with clear typography. Title "facet-grid · altair · anyplot.ai" is prominent and dark. Row headers (Sandy, Clay, Loam) and column headers (Spring, Summer, Fall) are well-sized (22–28px) and easily readable. Axes labeled "Water Usage (mm)" and "Yield (tons/ha)" with units are clear. The 3×3 grid of scatter plots shows three crop types color-coded as teal (#009E73), orange (#D55E00), and blue (#0072B2)—proper Okabe-Ito order. Grid lines are subtle (~10% opacity). Legend frame uses elevated background (#FFFDF6) with clear labels. All text is readable against the light background—no legibility issues detected.

Dark render (plot-dark.png): Same layout on warm near-black surface (#1A1A17) with light text. Title, headers, axis labels, and tick labels are all rendered in appropriate light tones (INK=#F0EFE8, INK_SOFT=#B8B7B0) and are fully readable. The data colors are identical to the light render—teal, orange, blue in identical positions—confirming theme-invariant data colors. Grid lines remain subtle. Legend frame uses dark elevated background (#242420) with light text and dark borders. No dark-on-dark failures; all chrome elements adapt properly to the dark theme. Both renders pass legibility checks.

Score: 91/100

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

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) - All font sizes explicitly set; title (28px), headers (22px), axis labels (20px), tick labels (18px). Readable in both themes.
• VQ-02: No Overlap (6/6) - No overlapping text; headers and labels well-spaced.
• VQ-03: Element Visibility (6/6) - 540 data points with size=150, opacity=0.7; markers well-adapted to density.
• VQ-04: Color Accessibility (2/2) - Three distinct Okabe-Ito colors with good contrast; CVD-safe.
• VQ-05: Layout & Canvas (4/4) - Grid layout fills canvas well; balanced margins; legend well-positioned.
• VQ-06: Axis Labels & Title (2/2) - Both axes labeled with units ("mm", "tons/ha").
• VQ-07: Palette Compliance (2/2) - First series #009E73, followed by #D55E00, #0072B2 (Okabe-Ito order). Backgrounds correct (#FAF8F1 light, #1A1A17 dark). Theme-adaptive chrome (text, grid, legend) flips properly; data colors remain identical across themes.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (4/8) - Well-configured library defaults with Okabe-Ito palette; lacks custom design beyond configuration.
• DE-02: Visual Refinement (5/6) - Subtle grid, explicit header/axis sizing, generous whitespace, refined legend configuration.
• DE-03: Data Storytelling (4/6) - Faceting creates visual hierarchy showing patterns across soil types and seasons; encourages comparison, though no explicit emphasis technique.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Faceted grid with scatter plots is correct.
• SC-02: Required Features (4/4) - Row faceting (Soil Type), column faceting (Season), base scatter plot all present.
• SC-03: Data Mapping (3/3) - X=Water Usage, Y=Yield, color=Crop, row=Soil Type, column=Season. Axes show all data.
• SC-04: Title & Legend (3/3) - Title format "facet-grid · altair · anyplot.ai" correct. Legend labels (Wheat, Corn, Soybean) match data.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) - Shows variation across all three dimensions (soil, season, crop). Demonstrates faceting feature well.
• DQ-02: Realistic Context (5/5) - Crop yield scenario is realistic, neutral, and comprehensible.
• DQ-03: Appropriate Scale (4/4) - Yields (3–11 tons/ha) and water usage (20–90 mm) are plausible for agricultural context.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Linear: imports → theme tokens → data → plot → save. No functions/classes.
• CQ-02: Reproducibility (2/2) - Uses np.random.seed(42).
• CQ-03: Clean Imports (2/2) - Only necessary imports (os, altair, numpy, pandas).
• CQ-04: Code Elegance (2/2) - Clean, Pythonic. No over-engineering or fake functionality.
• CQ-05: Output & API (1/1) - Saves as plot-{THEME}.png and plot-{THEME}.html.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) - Uses Altair's idiomatic .facet() for small multiples, proper .encode() patterns, .configure_*() for theme adaptation.
• LM-02: Distinctive Features (3/5) - Leverages Altair's faceting (alt.facet() with row/column), which is distinctive to Vega-Lite; could explore more advanced techniques like selections or cross-filtering.

Score Caps Applied

• None

Strengths

• Perfect visual quality: explicit font sizing, readable in both themes, no overlaps.
• Proper Okabe-Ito palette with correct color ordering; theme-adaptive chrome flips correctly.
• Idiomatic Altair usage: .facet(), .encode(), configure methods all appropriate.
• Clean code structure and reproducible data generation.
• Faceted layout effectively demonstrates the plot type.

Weaknesses

• Design Excellence is modest (13/20): well-configured defaults but lacks custom aesthetic sophistication or visual storytelling beyond the faceting structure.
• Library Mastery could be deeper: implementation uses core faceting but doesn't explore Altair-specific features like interactive selection or linked brushing.

Issues Found

None blocking approval. The implementation is technically sound and meets all requirements.

AI Feedback for Next Attempt

No repair needed. This implementation passes all quality criteria with strong visual quality and spec compliance. The modest Design Excellence score reflects competent but conventional styling—typical for well-configured defaults. Future enhancements could include subtle color adjustments, custom fonts, or interactive cross-filtering (if the spec evolved to include interactivity).

Verdict: APPROVED