feat(altair): implement ternary-density

[github-actions]

Implementation: ternary-density - python/altair

Implements the python/altair version of ternary-density.

File: plots/ternary-density/implementations/python/altair.py

Parent Issue: #3696

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): A ternary density heatmap rendered on a warm off-white #FAF8F1 background. The equilateral triangle occupies the majority of the canvas with a dark #1A1A17 outline. The viridis colormap transitions from deep purple (low density) to yellow-green (high density), clearly revealing three distinct compositional clusters: one near the Sand vertex (bottom-left), one near the Silt vertex (bottom-right), and one near the Clay vertex (top). Vertex labels — "Sand (%)", "Silt (%)", "Clay (%)" — are rendered in bold dark ink at font size 24px and are fully readable. The title "Sediment Composition · ternary-density · python · altair · anyplot.ai" in dark ink at 28px is clearly legible above the triangle. A viridis colorbar legend labeled "Density" sits to the right. Subtle ternary grid lines (10% intervals) are faintly visible at 0.35 opacity inside the triangle. All text is readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same ternary density heatmap on a near-black #1A1A17 background. The triangle outline flips to light (#F0EFE8) against the dark surface. Title, vertex labels, and legend text are rendered in light ink and remain fully readable against the dark background — no dark-on-dark failures observed. The viridis colormap patterns and the three density clusters are visually identical to the light render (same yellow-green hotspots, same purple low-density areas), confirming that only the chrome flipped between themes. The colorbar legend text and title text are light-colored and clearly legible. Legibility verdict: PASS.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 90/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — Title 28px, vertex labels 24px, legend title 20px, legend labels 16px — all explicitly set and readable in both themes
• VQ-02: No Overlap (6/6) — No overlapping text; vertex labels are positioned cleanly outside the triangle
• VQ-03: Element Visibility (6/6) — Density heatmap with three distinct clusters clearly visible; viridis contrast is excellent
• VQ-04: Color Accessibility (2/2) — Viridis is perceptually uniform and colorblind-safe; high contrast across the full density range
• VQ-05: Layout & Canvas (3/4) — Good layout overall; triangle fills ~65% of canvas with balanced margins, but inherent empty space below the triangular base costs one point
• VQ-06: Axis Labels & Title (2/2) — Vertex labels include units "(%)" and legend is labeled "Density"
• VQ-07: Palette Compliance (2/2) — Viridis used correctly for continuous density data; background #FAF8F1 (light) / #1A1A17 (dark); all chrome tokens theme-adaptive

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Strong and professional: appropriate viridis for density, all theme tokens applied, clean triangular boundary — clearly above a generic default but not yet at FiveThirtyEight-level polish
• DE-02: Visual Refinement (4/6) — Grid lines at 0.35 opacity, no visible axes, styled legend with custom fill/stroke, view strokeWidth=0 — good refinement throughout
• DE-03: Data Storytelling (4/6) — The three sediment regimes (sandy, silty, clay-rich) are immediately visible via the viridis color hierarchy; viewer sees the story of compositional separation without any annotations needed

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct ternary density plot with KDE heatmap overlay
• SC-02: Required Features (4/4) — KDE with Scott's bandwidth, viridis colormap, ternary grid lines, vertex labels, triangle outline — all spec requirements met
• SC-03: Data Mapping (3/3) — Sand/Silt/Clay correctly mapped to ternary Cartesian coordinates; all three components sum to 100%
• SC-04: Title & Legend (3/3) — Title follows {Descriptive Title} · {spec-id} · python · altair · anyplot.ai format; density legend labeled correctly

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Three distinct clusters (sandy, silty, clay-rich) demonstrate all aspects of multi-modal compositional density
• DQ-02: Realistic Context (5/5) — Sediment composition (sand/silt/clay) is a well-established geological measurement domain; completely neutral
• DQ-03: Appropriate Scale (4/4) — Beta distributions produce geologically plausible proportions; all values in 0–100% range; normalization ensures components sum to exactly 100%

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear structure: imports → data generation → coordinate transformation → KDE → DataFrame construction → chart layers → save
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All five imports (os, altair, numpy, pandas, scipy.stats.gaussian_kde) are used
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; list comprehension for density grid construction; appropriate complexity for the task
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; uses Altair 6.0.0 API correctly

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Expert Altair: correct encoding type suffixes (:Q/:N/:O), alt.layer() composition, configure_* chaining, alt.Scale(domain=) for consistent axis alignment, alt.Legend() with custom sizing
• LM-02: Distinctive Features (3/5) — mark_rect with x1/x2/y1/y2 bounds for pixel-perfect density cells, detail channel for grouping grid lines without separate color encoding, alt.X2/alt.Y2 secondary position encodings — these are genuine Altair grammar-of-graphics features not trivially replicated in other libraries

Score Caps Applied

• None

Strengths

• Perfect ternary-to-Cartesian coordinate transformation with correct half-plane triangle masking
• All theme tokens (PAGE_BG, ELEVATED_BG, INK, INK_SOFT) correctly applied to every chrome element in both renders
• Full spec compliance: KDE with auto bandwidth, viridis colormap, ternary grid, vertex labels with units
• Geologically realistic three-cluster sediment dataset that tells a clear compositional story
• Expert Altair layer composition using idiomatic mark_rect bounds, detail encoding, and X2/Y2 positions

Weaknesses

• DE-01 moderate: design is professional but could push further — consider adding a subtle annotation or cluster label to highlight the three sediment regimes by name, or adding a thin contour line at a key density threshold to add a layer of analytical depth
• VQ-05 minor: some wasted space below the triangle base; tightening Y domain or shifting the canvas toward square format could improve canvas utilization for this symmetric plot shape

Issues Found

1. DE-01 MODERATE: Strong implementation but lacks the final aesthetic flourish that separates "good" from "publication-ready"
   • Fix: Add cluster region labels (e.g. "Sandy", "Silty", "Clay-rich") near each density peak, or add 1-2 viridis-matched contour lines at the 50th and 75th density percentile for interpretive depth

AI Feedback for Next Attempt

The core implementation is excellent — focus next repair on design elevation: (1) add sparse contour lines at key density levels (the spec explicitly mentions this as a consideration), and (2) consider cluster annotations or a subtle subtitle describing the three sediment regimes. These changes alone would push DE-01 from 5 to 6-7 and DE-03 from 4 to 5-6, which would bring the total above 93.

Verdict: APPROVED