feat(altair): implement histogram-capability

[github-actions]

Implementation: histogram-capability - altair

Implements the altair version of histogram-capability.

File: plots/histogram-capability/implementations/altair.py

Parent Issue: #4552

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a histogram of 200 shaft diameter measurements (mm) using blue bars (#306998) with white edge strokes. A dark blue normal distribution curve (#1F4E79) is overlaid on the histogram. Two red dashed vertical lines mark the Lower Specification Limit (LSL = 9.95) and Upper Specification Limit (USL = 10.05), with bold red text labels at the top of the chart. A green dashed vertical line marks the Target value (10.00) with a green label. In the upper-right area, bold dark gray text displays "Cp = 1.49 | Cpk = 1.45". The title reads "histogram-capability · altair · pyplots.ai" in bold at the top. The x-axis is labeled "Shaft Diameter (mm)" and y-axis "Frequency". The distribution is roughly bell-shaped, centered near 10.002, with data well within the spec limits. Background is white with no grid lines and no view border.

Score: 83/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (7/8) - Font sizes explicitly set (title=28, axis title=22, ticks=18, annotations=16-20). All readable. Spec line labels at 16pt slightly small.
• VQ-02: No Overlap (5/6) - USL label "(10.05)" is very close to the right canvas edge, minor clipping risk.
• VQ-03: Element Visibility (6/6) - All elements clearly visible. Bars at opacity 0.8, curve and rules at strokeWidth=3.
• VQ-04: Color Accessibility (2/4) - Red-green color pair for LSL/USL vs Target lines is the classic colorblind-problematic combination. Labels help but color choice is not optimal.
• VQ-05: Layout & Canvas (3/4) - Good proportions, plot fills canvas well. USL label slightly near right edge.
• VQ-06: Axis Labels & Title (2/2) - "Shaft Diameter (mm)" with units, "Frequency" is descriptive.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) - Thoughtful palette with Python Blue histogram, dark navy curve, colored spec lines. Grid removed, view border removed. Above defaults but not publication-level exceptional.
• DE-02: Visual Refinement (4/6) - Grid disabled, view strokeWidth=0, white bar edge highlighting. Some refinement visible beyond defaults.
• DE-03: Data Storytelling (3/6) - Capability indices and colored spec lines create some narrative context. Viewer can see process is capable. Above basic data display but lacks strong visual hierarchy or emphasis.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) - Correct: histogram with normal distribution overlay and specification limit lines.
• SC-02: Required Features (4/4) - All features present: histogram, normal curve, LSL/USL lines, target line, Cp/Cpk annotations.
• SC-03: Data Mapping (3/3) - X-axis is measurement, Y-axis is frequency. Correct mapping.
• SC-04: Title & Legend (3/3) - Title format "histogram-capability · altair · pyplots.ai" correct. No legend needed for this plot type.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) - Shows histogram distribution, normal overlay, both spec limits, target, and capability indices. Good but data is uniformly "capable" — no measurements near limits for visual tension.
• DQ-02: Realistic Context (5/5) - Real engineering context: shaft diameter manufacturing with realistic tolerances.
• DQ-03: Appropriate Scale (4/4) - LSL=9.95, USL=10.05, target=10.00, σ≈0.012 are realistic machining tolerances.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) - Clean imports → data → computation → plot layers → combine → save.
• CQ-02: Reproducibility (2/2) - np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) - All imports used (altair, numpy, pandas, scipy.stats).
• CQ-04: Code Elegance (2/2) - Clean, appropriate complexity for Altair's declarative layered approach.
• CQ-05: Output & API (1/1) - Saves plot.png and plot.html, current API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) - Good use of Altair's declarative grammar: layered composition with +, bin transform, encoding channels, mark types, properties/configure chain.
• LM-02: Distinctive Features (3/5) - Uses Altair-specific features: declarative layer composition, bin transform in encoding, mark_rule for reference lines, mark_text with positional encoding, HTML export.

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features (histogram, normal curve, LSL/USL, target, Cp/Cpk) are present and correctly implemented
• Excellent code quality with clean KISS structure and proper reproducibility
• Realistic engineering context with sensible shaft diameter data and tolerances
• Good use of Altair's declarative layering to compose histogram + curve + rules + annotations

Weaknesses

• Red-green color scheme for specification lines (LSL/USL red vs Target green) is problematic for colorblind users
• Design could be more polished — lacks the refinement needed for publication quality
• Data storytelling is present but could be stronger with better visual hierarchy

Issues Found

1. VQ-04 LOW: Red-green color pair for LSL/USL vs Target lines
   • Fix: Use colorblind-safe alternatives — e.g., orange/amber for spec limits and teal/blue for target, or use different line styles more prominently
2. DE-01 MEDIUM: Good but not publication-quality design
   • Fix: Consider a more refined color palette, add subtle background shading between spec limits, or use gradient/opacity techniques
3. DE-03 LOW: Storytelling could be stronger
   • Fix: Create visual hierarchy — e.g., shade the area between LSL/USL to emphasize the spec range, or highlight the relationship between distribution and limits

AI Feedback for Next Attempt

Fix the colorblind accessibility issue by replacing the red-green color scheme for specification lines with colorblind-safe alternatives (e.g., orange for LSL/USL, teal for target). Improve design excellence by adding subtle visual elements like shading between spec limits to create a "capability zone" that tells the story more clearly. Consider emphasizing the Cp/Cpk annotation with a background box or more prominent positioning. These changes would push the score above 90.

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 histogram of 200 shaft diameter measurements (mm) rendered as blue rectangular bars with white edges and rounded top corners. A dark blue fitted normal distribution curve overlays the histogram. Two orange dashed vertical lines mark the Lower Specification Limit (LSL = 9.950, left) and Upper Specification Limit (USL = 10.050, right), with bold orange labels at the top. A purple dashed vertical line marks the Target value (10.000) with a purple label. Background shading distinguishes in-spec (light green) from out-of-spec (light peach) zones. The upper right displays "Cp = 1.49 Cpk = 1.45" in bold dark text with "CAPABLE" in green below. A gray dashed mean indicator line with italic "x̄=10.002" label appears near the bottom. The title reads "histogram-capability · altair · pyplots.ai" with a subtitle showing n=200, σ=0.0112 mm, process centered at 10.002 mm. X-axis: "Shaft Diameter (mm)", Y-axis: "Frequency".

Score: 89/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All major text sizes explicitly set (title 28pt, axis titles 22pt, ticks 18pt, annotations 17-21pt). Mean label at 14pt is below the 16pt minimum for readable text at this canvas size.
• VQ-02: No Overlap (5/6) — Minor issue: the mean label "x̄=10.002" at the chart bottom is rendered in light gray italic against the green background zone, making it partially hard to distinguish. No other overlap.
• VQ-03: Element Visibility (6/6) — Histogram bars are well-sized with good opacity (0.82), normal curve is clear (strokeWidth=3), spec lines are bold and distinct.
• VQ-04: Color Accessibility (4/4) — Excellent colorblind-safe palette: orange for LSL/USL, purple for target, avoiding red-green entirely. Good contrast throughout.
• VQ-05: Layout & Canvas (4/4) — Plot fills canvas well, balanced margins, background zones extend edge-to-edge.
• VQ-06: Axis Labels & Title (2/2) — "Shaft Diameter (mm)" with units, "Frequency" is descriptive.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom colorblind-safe palette, background shading for in-spec/out-of-spec zones, rounded bar corners, white stroke separators, thoughtful typography hierarchy. Clearly above library defaults.
• DE-02: Visual Refinement (4/6) — Grid disabled, view stroke removed, axis domain/tick colors set to subtle gray, white bar edges provide separation. Good refinement.
• DE-03: Data Storytelling (5/6) — Background zones create immediate visual narrative (green=in-spec, peach=out-of-spec). CAPABLE/NOT CAPABLE verdict provides clear conclusion. Subtitle with process statistics adds context. Strong visual hierarchy.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: histogram with normal distribution overlay and specification limit lines.
• SC-02: Required Features (4/4) — All features present: histogram, fitted normal curve, LSL/USL lines (orange dashed), target line (purple dashed), Cp/Cpk annotations, mean indicator.
• SC-03: Data Mapping (3/3) — X-axis maps to shaft diameter measurements, Y-axis maps to frequency. All data visible within axis range.
• SC-04: Title & Legend (3/3) — Title format "histogram-capability · altair · pyplots.ai" correct. No legend needed — all elements are directly labeled (LSL, USL, Target, Cp/Cpk).

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows distribution shape, spec limits, capability indices, mean offset from target. Process is slightly off-center (mean=10.002 vs target=10.000), showing realistic bias. Could show some measurements closer to spec limits for more visual tension.
• DQ-02: Realistic Context (5/5) — Shaft diameter manufacturing scenario with realistic specification limits (±0.05mm on 10mm nominal). Neutral engineering domain.
• DQ-03: Appropriate Scale (4/4) — Values realistic: 10mm shaft with ±0.05mm tolerance, σ=0.012mm, Cp=1.49/Cpk=1.45 are plausible for a capable machining process.

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.
• CQ-03: Clean Imports (2/2) — All imports used: altair, numpy, pandas, scipy.stats.
• CQ-04: Code Elegance (2/2) — Well-organized layer composition, appropriate complexity for the multi-layer visualization. Each layer is cleanly defined.
• CQ-05: Output & API (1/1) — Saves as plot.png and plot.html. Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of Altair's declarative layer composition with alt.layer(). Pre-binning data with mark_rect is an idiomatic workaround for histograms needing shared scales. Proper use of encoding types, scales, and Title configuration.
• LM-02: Distinctive Features (3/5) — Uses Altair-specific features: interactive tooltips on histogram bars, HTML export, alt.value() for pixel-based positioning, mark_rect with cornerRadius properties, configure_view(strokeWidth=0).

Score Caps Applied

• None

Strengths

• Excellent colorblind-safe palette (orange/purple instead of red/green) — keep this approach
• Background shading zones for in-spec/out-of-spec create strong visual storytelling
• CAPABLE/NOT CAPABLE verdict with dynamic color adds clear data narrative
• Pre-binned histogram with mark_rect avoids Altair histogram-layer scale conflicts — clever technique
• Full spec compliance with all required features present and correctly implemented

Weaknesses

• Mean label "x̄=10.002" at fontSize=14 is below the 16pt minimum and rendered in light gray italic, making it hard to read
• Could push Library Mastery higher by leveraging more Altair-distinctive features

Issues Found

1. VQ-01 MINOR: Mean label font size (14pt) is below the recommended 16pt minimum for tick-level text
   • Fix: Increase mean label fontSize to at least 16, and consider using a slightly darker color for better contrast
2. LM-01 MINOR: Some opportunities for more idiomatic Altair usage remain
   • Fix: Consider using alt.datum expressions or calculated transforms where appropriate

AI Feedback for Next Attempt

Increase the mean label font size from 14pt to at least 16pt and use a slightly darker gray (e.g., #555555) for better legibility. This single fix would push VQ-01 to 8/8. To reach 90+, also consider whether any additional Altair-distinctive features could be incorporated (e.g., selection parameters for interactivity in the HTML export, or alt.datum expressions).

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 process capability histogram for shaft diameter measurements (mm). Blue rectangular bars form the histogram distribution centered around 10.002 mm, overlaid with a dark blue fitted normal distribution curve. Orange dashed vertical lines mark the LSL (9.950) and USL (10.050) specification limits, labeled in bold orange text at the top. A purple dashed vertical line indicates the Target (10.000), labeled in purple. A light gray dashed line marks the sample mean (x̄=10.002) near the bottom. Background shading distinguishes in-spec (light green) from out-of-spec (light peach/orange) zones. The Cp=1.49 and Cpk=1.45 capability indices are annotated in bold dark text at the top-right, with a green "CAPABLE" status below. The subtitle shows n=200, σ=0.0112 mm. Axis labels read "Shaft Diameter (mm)" and "Frequency" with appropriate font sizes. The overall layout is clean with no grid lines and good use of canvas space.

Score: 91/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set throughout (title 28, axis titles 22, labels 18, annotations 17–21). Subtitle at 16pt is slightly small but still readable at full resolution.
• VQ-02: No Overlap (6/6) — All text elements are well-separated. LSL/USL labels offset outward, target label centered, mean label at bottom, Cp/Cpk annotation at top-right. No text-on-text collisions.
• VQ-03: Element Visibility (6/6) — Histogram bars clearly visible with white stroke separation. Normal curve at strokeWidth=3 stands out well. Spec lines at strokeWidth=3 with dashed pattern are prominent.
• VQ-04: Color Accessibility (4/4) — Colorblind-safe palette: blue bars, orange spec limits, purple target. Avoids red-green as sole distinguisher. Good contrast against the subtle background zones.
• VQ-05: Layout & Canvas (4/4) — Plot fills canvas well with balanced margins. Background zones extend edge-to-edge. No content cut off.
• VQ-06: Axis Labels & Title (2/2) — "Shaft Diameter (mm)" with units, "Frequency" is descriptive.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom colorblind-safe palette (blue/orange/purple), background shading zones for in-spec vs out-of-spec, rounded bar corners, intentional typography hierarchy with subtitle. Clearly above library defaults.
• DE-02: Visual Refinement (4/6) — Grid disabled, view stroke removed, custom axis colors ([area-basic] plotnine implementation #333/feat(plotly): implement donut-labeled #555), white stroke on bars for separation, subtle domain/tick colors. Good refinement but could push further with more whitespace tuning.
• DE-03: Data Storytelling (5/6) — Excellent storytelling: background zones immediately communicate in-spec vs out-of-spec regions, "CAPABLE" status in green provides instant insight, Cp/Cpk prominently displayed, mean indicator shows process centering. Viewer immediately understands process performance.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: histogram of process measurements overlaid with fitted normal distribution curve and specification limit lines.
• SC-02: Required Features (4/4) — All required: histogram ✓, normal curve ✓, LSL/USL vertical lines ✓, target line ✓, Cp/Cpk annotations ✓, capability status ✓.
• SC-03: Data Mapping (3/3) — X-axis is measurement values, Y-axis is frequency. Axes show full data range with appropriate padding.
• SC-04: Title & Legend (3/3) — Title format "histogram-capability · altair · pyplots.ai" is correct. No multi-series legend needed; inline labels on lines serve as identification.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows histogram distribution shape, normal curve fit, both spec limits, target value, mean indicator, Cp and Cpk indices, and process capability status. Comprehensive coverage of all process capability features.
• DQ-02: Realistic Context (5/5) — Shaft diameter manufacturing scenario — real-world, neutral, comprehensible. Precision machining with ±0.05mm tolerance is realistic.
• DQ-03: Appropriate Scale (4/4) — 200 measurements around 10mm nominal, σ≈0.012mm, Cp=1.49/Cpk=1.45 — realistic values for a capable manufacturing process.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data generation → layer definitions → combine → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set at the start.
• CQ-03: Clean Imports (2/2) — All imports used: altair, numpy, pandas, scipy.stats.
• CQ-04: Code Elegance (2/2) — Well-structured with clear layer separation. Hover interaction is legitimate Altair interactivity, not fake functionality. Appropriate complexity for a multi-layer chart.
• CQ-05: Output & API (1/1) — Saves as plot.png with scale_factor=3.0. Also saves plot.html (appropriate for Altair). Current API usage.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of Altair's declarative grammar: alt.layer() composition, proper encoding types (:Q, :N), alt.Title with subtitle, configure_axis/configure_view. Pre-binning with mark_rect is pragmatic for y-scale sharing with the normal curve but less idiomatic than Altair's built-in bin transform.
• LM-02: Distinctive Features (3/5) — Uses Altair-specific features: selection_point for hover interactivity with conditional encoding (alt.condition), tooltips via encoding, HTML export alongside PNG. These are distinctive to Altair's declarative interaction model.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Excellent data storytelling with background shading zones distinguishing in-spec (green) from out-of-spec (peach) regions
• Colorblind-safe palette with orange/purple/blue avoiding red-green conflicts
• Complete spec compliance with all required features including Cp/Cpk annotations and capability status
• Clean layer composition with well-separated visual elements and no text overlap
• Interactive hover highlight leveraging Altair's native selection mechanism

Weaknesses

• Pre-binned histogram approach (mark_rect) instead of Altair's built-in mark_bar with bin transform reduces idiomatic score
• Subtitle font size at 16pt is slightly small relative to other text elements

Issues Found

None critical — implementation meets quality threshold.

AI Feedback for Next Attempt

Strong implementation that effectively leverages Altair's layering and interaction capabilities. The background zones and capability annotations create a compelling quality engineering narrative. Minor improvements could include using Altair's native bin transform and slightly larger subtitle text.

Verdict: APPROVED