update(chord-basic): matplotlib — comprehensive review

[MarkusNeusinger]

Summary

Updated matplotlib implementation for chord-basic.

Changes: Comprehensive review — code quality, data choice, visual design, spec compliance, library feature 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

[Copilot]

Pull request overview

Updates the matplotlib implementation and metadata for the chord-basic plot, aligning the spec tags with the diagram’s “proportional flow” focus and refreshing implementation details.

Changes:

• Updated chord-basic spec metadata/tags (timestamps, data_type, features).
• Refreshed matplotlib metadata (generator, Python version, updated timestamp).
• Reworked matplotlib chord rendering (arc geometry, chord path construction, labeling, styling).

Reviewed changes

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

File	Description
plots/chord-basic/specification.yaml	Updates spec timestamp and classification tags/features.
plots/chord-basic/metadata/matplotlib.yaml	Refreshes implementation metadata (generator/version fields), but introduces an invalid quality_score.
plots/chord-basic/implementations/matplotlib.py	Updates chord diagram drawing logic and styling, but header metadata is malformed and there is dead code.

[Copilot]

quality_score is set to null even though this metadata file has review.verdict: APPROVED. Across the repo, quality_score is consistently an integer (e.g., plots/band-basic/metadata/matplotlib.yaml:12), and null may break tooling that expects a numeric score (labels, dashboards, etc.). Set quality_score to the evaluated integer score for this implementation.

Suggested change

	quality_score: null
	quality_score: 90

[Copilot]

Header metadata looks malformed: Quality: /100 is missing the numeric score. This likely breaks any parsers that extract quality/created/updated info from the standard 4-line header. Fill in the quality score (or use the established pending pattern if it truly isn’t available).

Suggested change

	Quality: /100 | Updated: 2026-04-06
	Quality: pending | Updated: 2026-04-06

[Copilot]

arc_cursors is assigned but never used. Since plots/ is excluded from Ruff checks, this won’t be caught automatically but still adds dead code and confusion. Remove it, or use it consistently for chord placement if that was the intent.

Suggested change

	# Track angular position within each arc for chord placement
	arc_cursors = start_angles.copy()
	# Angular span per unit of flow for chord placement

[Copilot]

flows is computed and sorted but never used (the code renders based on chord_params instead). Remove flows and/or update the surrounding comment so it matches the actual draw-order logic.

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a chord diagram showing continental migration flows between six continents: Africa (dark blue, top-right), Asia (amber/gold, right), Europe (teal, bottom), N. America (burnt orange, left), S. America (light blue, upper-left), and Oceania (pink/mauve, top). Each continent has a proportional arc segment around the circle perimeter with white edge separation. Chords connect arcs with widths proportional to flow magnitude. Chord colors match their source continent with alpha transparency varying by flow size. Larger chords (e.g., Asia↔Europe, Africa↔Asia) are drawn on top for visual prominence. Entity labels are bold, colored to match their arcs, positioned outside the circle. Title reads "Continental Migration Flows · chord-basic · matplotlib · pyplots.ai" at the top. White background, axes turned off, clean layout.

Score: 88/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — Title at 24pt, labels at 18pt bold. All readable but entity labels slightly under the 20pt guideline.
• VQ-02: No Overlap (6/6) — All labels well-positioned with no collisions.
• VQ-03: Element Visibility (5/6) — Most chords clearly visible; some smaller flows (e.g., Oceania connections) are quite thin and harder to distinguish.
• VQ-04: Color Accessibility (4/4) — Colorblind-safe Wong palette. Good contrast between all six colors.
• VQ-05: Layout & Canvas (3/4) — 16:9 aspect ratio creates wasted horizontal space for a circular chart. A square format would utilize canvas better.
• VQ-06: Axis Labels & Title (2/2) — Descriptive title with proper format. No axes needed for chord diagrams.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom colorblind-safe palette, colored labels matching arcs, alpha variation by magnitude, white arc edges. Clearly above defaults with intentional design choices.
• DE-02: Visual Refinement (4/6) — Axes hidden, clean white background, white edge separation on arcs. Good refinement but could push further with subtle background tinting or more polished typography.
• DE-03: Data Storytelling (4/6) — Alpha variation and draw order (largest chords on top) create effective visual hierarchy. Dominant flows (Asia↔Europe, Africa↔Asia) are immediately apparent.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct chord diagram with entities around a circle connected by chords.
• SC-02: Required Features (4/4) — Distinct colors per entity ✓, chord width proportional to flow ✓, bidirectional flows as separate chords ✓.
• SC-03: Data Mapping (3/3) — 6 continents with bidirectional flow matrix correctly mapped to arcs and chords.
• SC-04: Title & Legend (3/3) — Title follows {desc} · {spec-id} · {library} · pyplots.ai format. Colored labels serve as legend for chord diagrams.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows bidirectional flows, varying magnitudes, asymmetric relationships. Could show more extreme variation to highlight differences.
• DQ-02: Realistic Context (5/5) — Intercontinental migration flows — real, neutral, comprehensible scenario.
• DQ-03: Appropriate Scale (4/4) — Values in millions, realistic magnitudes for intercontinental migration.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data → geometry → plot → save. No functions/classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic with hardcoded flow matrix.
• CQ-03: Clean Imports (2/2) — All imports used: matplotlib.patches, pyplot, numpy, Path.
• CQ-04: Code Elegance (2/2) — Well-structured Bezier chord construction. Appropriate complexity for a chord diagram.
• CQ-05: Output & API (1/1) — Saves as plot.png with dpi=300 and bbox_inches='tight'.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Uses matplotlib's patches (Wedge) and Path with Bezier curves — the correct approach since matplotlib has no high-level chord API. Well-executed but some geometric calculations could be more streamlined.
• LM-02: Distinctive Features (4/5) — Path with CURVE4 Bezier control points, mpatches.Wedge, custom PathPatch — distinctively matplotlib low-level drawing capabilities.

Score Caps Applied

• None

Strengths

• Excellent use of matplotlib's low-level Path/Patch API to build a chord diagram from scratch
• Colorblind-safe Wong palette with colored entity labels matching arcs
• Alpha variation by flow magnitude and draw-order sorting create effective visual hierarchy
• Clean, well-structured code with deterministic data and proper geometry calculations
• Bidirectional flows correctly represented as separate chords

Weaknesses

• Entity label font size (18pt) slightly below the 20pt guideline for optimal legibility
• 16:9 aspect ratio wastes horizontal space for a circular chart — square would be more appropriate
• Some smaller chords (Oceania connections) are very thin and hard to distinguish
• Could benefit from additional visual polish to reach publication quality

Issues Found

1. VQ-01 MINOR: Entity labels at fontsize=18, below 20pt guideline
   • Fix: Increase entity label fontsize to 20 or higher
2. VQ-05 MINOR: 16:9 aspect ratio suboptimal for circular chord diagram
   • Fix: Use square figsize (e.g., 12×12) for better canvas utilization
3. VQ-03 MINOR: Smallest chords barely visible
   • Fix: Set a minimum chord width or increase arc_width slightly
4. DE-02 MODERATE: Visual refinement could be pushed further
   • Fix: Consider subtle background color, refined typography, or additional visual polish

AI Feedback for Next Attempt

Increase entity label fontsize to 20+. Switch to a square aspect ratio (e.g., figsize=(12, 12)) for better canvas utilization of the circular chart. Consider setting a minimum visible chord width so Oceania's small flows remain distinguishable. For visual refinement, consider adding a subtle legend showing flow magnitude scale or adding minor polish like a light background tint.

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 chord diagram showing continental migration flows between 6 continents arranged clockwise from top-right: Africa (dark blue), Asia (amber/gold), Europe (teal), N. America (red-orange), S. America (light blue), and Oceania (pink). Outer arcs are proportional to each continent's total flow volume — Asia and Europe have the largest arcs. Chords connect continents with widths proportional to migration magnitude and alpha-blended by flow size (larger flows more opaque). The background is a subtle off-white (#FAFAFA). Title reads "Continental Migration Flows · chord-basic · matplotlib · pyplots.ai" at the top. Labels are bold, colored to match their arc segments.

Score: 87/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — Title 24pt, labels 20pt bold, all explicitly set and readable. Minor: no secondary text tier (e.g., flow values) to fully utilize the sizing hierarchy.
• VQ-02: No Overlap (6/6) — Labels placed outside the circle with intelligent horizontal alignment. No collisions.
• VQ-03: Element Visibility (5/6) — Chords are mostly distinguishable; minimum chord angle (1.5°) ensures small flows are visible. Some thin chords in the center area blend together.
• VQ-04: Color Accessibility (4/4) — Uses Wong colorblind-safe palette variant. Good contrast against off-white background.
• VQ-05: Layout & Canvas (4/4) — Square 12×12 canvas, circle well-centered with balanced margins. Labels fit within bounds.
• VQ-06: Axis Labels & Title (2/2) — Descriptive title with context ("Continental Migration Flows"). No axes needed for circular layout.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom colorblind-safe palette, off-white background, alpha-scaled chords, white edge separators on arcs. Clearly above defaults — professional and cohesive. Not yet publication-level (would need more distinctive typography or subtle gradient effects).
• DE-02: Visual Refinement (4/6) — Axes hidden, custom background, white arc separators, 3° gaps between arcs. Good refinement but could push further with subtle inner ring lines or gradient arcs.
• DE-03: Data Storytelling (3/6) — Alpha scaling by magnitude creates some hierarchy (Asia↔Europe flow is visually dominant). However, the center is busy and the viewer must work to identify key relationships. Could benefit from highlighting top 2-3 flows or using a subtitle to call out the main insight.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct chord diagram with entities on circular perimeter connected by arcs.
• SC-02: Required Features (4/4) — Distinct colors per entity, chord width proportional to flow, bidirectional flows as separate chords, 6 entities.
• SC-03: Data Mapping (3/3) — Flow matrix correctly mapped to arc sizes and chord widths. Arc spans proportional to entity totals.
• SC-04: Title & Legend (3/3) — Title includes descriptive prefix + required format. Colored entity labels serve as legend.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows bidirectional asymmetric flows, varying magnitudes (1-15M), different entity sizes. Could show a zero-flow pair more prominently to demonstrate sparsity.
• DQ-02: Realistic Context (5/5) — Continental migration flows in millions — neutral, real-world scenario.
• DQ-03: Appropriate Scale (4/4) — Values 1-15 million are plausible for intercontinental migration. Relative magnitudes make sense (Asia↔Europe high, Oceania connections low).

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data → geometry → draw arcs → draw chords → title → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic hardcoded matrix.
• CQ-03: Clean Imports (2/2) — All 4 imports used: mpatches (Wedge, PathPatch), pyplot, numpy, Path.
• CQ-04: Code Elegance (2/2) — Smart pre-computation of chord positions avoids cursor interference from draw order. Alpha scaling formula is clean.
• CQ-05: Output & API (1/1) — Saves as plot.png, dpi=300, bbox_inches='tight'.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (3/5) — Uses matplotlib's patches and Path API correctly but at a very low level. The approach is necessarily manual (no built-in chord diagram), but some geometry could leverage more matplotlib helpers.
• LM-02: Distinctive Features (4/5) — Bezier curves via Path with CURVE4, mpatches.Wedge, PathPatch — these are distinctively matplotlib features for custom vector graphics. Good use of the library's strength for custom shapes.

Score Caps Applied

• None

Strengths

• Excellent custom Bezier chord rendering with proper arc-based positioning
• Alpha scaling by flow magnitude creates effective visual depth
• Colorblind-safe palette with strong contrast against off-white background
• Smart pre-computation of chord positions to decouple draw order from layout
• Perfect spec compliance — all required features implemented correctly

Weaknesses

• Center area is busy — hard to trace individual flows through the middle
• No visual emphasis on the most important relationships (top flows look similar to mid-range)
• Data storytelling could be stronger — viewer must discover insights rather than being guided

Issues Found

1. DE-03 MEDIUM: No clear focal point or data storytelling — all chords treated equally except for alpha
   • Fix: Emphasize top 2-3 flows with higher alpha/thicker rendering, or desaturate minor flows more aggressively to create contrast
2. DE-02 MEDIUM: Visual refinement could go further
   • Fix: Add subtle tick marks on arcs showing flow divisions, or use a thin inner ring line to separate chords from arc segments
3. LM-01 LOW: Very manual geometry could use more matplotlib idioms
   • Fix: Consider using Arc patches or matplotlib.collections for batch rendering of chord paths

AI Feedback for Next Attempt

Push data storytelling: desaturate minor flows (alpha 0.15-0.25) while boosting top 3 flows (alpha 0.7-0.85) to create a clear visual hierarchy. Add a brief subtitle or annotation calling out the dominant flow (e.g., "Asia ↔ Europe: largest corridor"). Consider adding flow-division tick marks on arcs for added refinement. These changes would push DE-03 from 3→5 and DE-02 from 4→5, reaching 90+.

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 chord diagram on a light gray (#FAFAFA) background with 6 continents arranged clockwise from the top: Africa (dark blue), Asia (amber/gold), Europe (teal/green), N. America (burnt orange), S. America (light blue), and Oceania (pink/mauve). Each entity has a colored outer arc segment proportional to its total flow, with white edge separators between segments and 3-degree gaps. Chords connect entities through the interior using cubic Bezier curves, colored by source entity with alpha and linewidth scaled by flow magnitude — the largest chords (Asia→Europe at 15M) are bold and opaque while smaller flows (Oceania connections) are faint and thin. Three annotation boxes with rounded corners highlight the top flows: "Asia → Europe: 15M" at bottom, "Africa → Asia: 12M" at upper right, and "N. America → Europe: 12M" at left. A subtitle in italic gray reads "Asia–Europe corridor dominates global flows." The title follows the required format: "Continental Migration Flows · chord-basic · matplotlib · pyplots.ai".

Score: 90/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 24pt, labels 20pt bold, subtitle 16pt). Annotations at 12-14pt are slightly small but still readable.
• VQ-02: No Overlap (5/6) — Entity labels well-positioned with smart horizontal alignment logic. No text overlap. Chord crossings are inherent to the chart type.
• VQ-03: Element Visibility (5/6) — Alpha/linewidth scaling creates good visual hierarchy. Minimum chord degree (1.5°) ensures even small flows are visible, though Oceania's connections are quite faint.
• VQ-04: Color Accessibility (4/4) — Colorblind-safe Wong palette (#306998, #E69F00, #009E73, #D55E00, #56B4E9, #CC79A7). Good contrast on light background.
• VQ-05: Layout & Canvas (4/4) — Square 12×12 canvas is ideal for circular diagram. Chart fills canvas well with room for labels and annotations.
• VQ-06: Axis Labels & Title (2/2) — Axes correctly hidden for chord diagram. Title is descriptive with context.

Design Excellence (16/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom colorblind-safe palette, entity labels colored to match their arcs, warm #FAFAFA background, white edge separators on wedges, alpha/linewidth scaling by flow magnitude. Clearly above defaults with intentional design choices.
• DE-02: Visual Refinement (5/6) — Axes turned off, custom background, white edge lines (linewidth=2) on arc segments, 3-degree gap spacing between entities, generous whitespace. Good attention to detail.
• DE-03: Data Storytelling (5/6) — Strong: subtitle "Asia–Europe corridor dominates global flows" tells the story immediately. Top 3 flows annotated with styled callout boxes. Alpha/linewidth scaling creates clear visual hierarchy where dominant flows stand out.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct chord diagram with entities on perimeter arcs and Bezier-curve chords connecting them.
• SC-02: Required Features (4/4) — Distinct color per entity ✓, chord width proportional to flow ✓, bidirectional flows as separate chords ✓, 6 continents ✓.
• SC-03: Data Mapping (3/3) — Flow matrix correctly maps source→target with proper angular span allocation.
• SC-04: Title & Legend (3/3) — Title follows "{description} · chord-basic · matplotlib · pyplots.ai" format. Entity labels serve as legend with color-matching.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows bidirectional asymmetric flows (Africa→Asia=12 vs Asia→Africa=8), varying magnitudes from 1 to 15, all 6 entities interconnected. Good variety.
• DQ-02: Realistic Context (5/5) — Continental migration flows in millions — realistic, neutral, comprehensible topic.
• DQ-03: Appropriate Scale (4/4) — Values 1-15M are plausible for continental migration flows.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data → geometry calculations → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic with hardcoded flow matrix.
• CQ-03: Clean Imports (2/2) — All imports used: matplotlib.patches, pyplot, numpy, Path.
• CQ-04: Code Elegance (2/2) — Smart pre-computation of chord positions to avoid cursor interference from draw order. Clean Bezier path construction. Appropriate complexity for a custom chord diagram.
• CQ-05: Output & API (1/1) — Saves as plot.png with dpi=300, bbox_inches='tight'.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Proper use of matplotlib's low-level rendering API (fig/ax pattern, add_patch), which is the correct approach since matplotlib has no built-in chord diagram.
• LM-02: Distinctive Features (4/5) — Leverages Path with CURVE4 cubic Bezier curves, mpatches.Wedge for arc segments, PathPatch for chord rendering — all distinctive matplotlib geometry features.

Score Caps Applied

• None — no cap conditions triggered

Strengths

• Excellent data storytelling with subtitle, annotated top flows, and alpha/linewidth hierarchy (keep these)
• Custom Bezier chord rendering with proper angular positioning and pre-computed cursor tracking
• Colorblind-safe palette with color-coordinated entity labels
• Clean, well-structured code with smart geometry calculations

Weaknesses

• Annotation boxes float without visual connection (arrows/lines) to the specific chords they describe
• Smallest chords (Oceania connections) are very faint at ~0.15 alpha

Issues Found

None critical — implementation meets quality threshold.

AI Feedback for Next Attempt

N/A — implementation approved at 90/100.

Verdict: APPROVED