Visualisation Implementation Log

Session: 13 October 2025

✓ Completed: National Results Waterfall Chart (Priority #1)

Objective: Replace the National Results Table (Slide 11) with a waterfall chart showing cascading ECS reductions.

Status: ✓ Complete and tested

Deliverables

R Script: 01_national_results_waterfall.R
- Generates waterfall chart from national results data
- Includes colour-coding by constraint type
- Adds strategic annotations for key scenarios
Outputs:
- PNG (300 DPI): outputs/national_results_waterfall.png
- PDF (vector): outputs/national_results_waterfall.pdf
- Copy in main outputs: 03_outputs/01_figures/national_results_waterfall.png
Documentation: README.md
- Usage instructions
- Technical specifications
- Customisation guide

Design Decisions

Colour Palette (as recommended): - Baseline: Grey (#808080) - Technical: Blue (#1565C0) - Capital: Green (#2E7D32) - Labour: Red (#C62828) - Spatial: Purple (#6A1B9A)

Key Features: - Proper waterfall flow from 43.3 ECS → 32.7 ECS - Dashed connecting lines between scenarios - ECS values displayed on each bar - Change amounts shown on bars (−0.4, −0.6, −3.4, −3.7, −2.4, −0.1) - Annotations highlighting: * S3: “Big jump: Classroom limit” (green) * S4: “Critical: Labour activation” (red) * Total reduction: 10.6 ECS (24.6%)

Success Metrics

✓ 5-Second Test Passed: “Which scenario gives the biggest ECS reduction?”
→ Answer: S4 (Labour activation) - immediately visible

✓ Visual Clarity: Cascading effect clearly shows sequential constraint relaxation

✓ Narrative Impact: The “critical margin” at S4 is emphasised through colour and annotation

✓ Technical Quality: - High-resolution output (300 DPI) - Vector PDF for print - Clean, professional design

Implementation Notes

Challenges Resolved: 1. Initial error in data transformation (tibble size mismatch) - fixed by simplifying data structure 2. Waterfall positioning - solved using proper start/end coordinates for each bar 3. Annotation visibility - added arrows and positioned text above bars

Time Invested: ~30 minutes - Initial script: 10 minutes - Debugging and refinement: 15 minutes - Documentation: 5 minutes

Testing

✓ Script runs without errors
✓ Output files generated in correct locations
✓ Visual quality verified
✓ Annotations visible and clear
✓ Colour scheme matches recommendations

✓ Completed: Provincial Descriptives Visualisations (Priority #2)

Objective: Replace the Provincial Descriptives Table (Slide 10) with Cleveland dot plot and small multiples visualisations.

Status: ✓ Complete and tested

Deliverables

R Script: 02_provincial_descriptives_visualisations.R
- Generates three visualisations from provincial data
- Cleveland dot plot for metric comparison
- Small multiples showing provincial “profiles”
- Bonus: Normalized version with 0-100 scale
Outputs:
- Cleveland plot: provincial_descriptives_cleveland.{png,pdf}
- Small multiples: provincial_descriptives_small_multiples.{png,pdf}
- Normalized: provincial_descriptives_small_multiples_normalized.{png,pdf}
- All in: outputs/ folder
Features:
- Provinces ordered by ECS severity
- Colour-coded by metric type
- National average reference lines in small multiples
- Red/green colouring for above/below national average

Design Decisions

Cleveland Dot Plot: - Shows 4 key metrics: ECS, STR, TCR, Large Class Rate - Grey lines connect dots for each province - Faceted by metric for easy comparison - Immediately shows Limpopo as worst performer

Small Multiples: - One panel per province - Bars coloured green (better) or red (worse) than national - Dashed lines show national averages - Value labels on each bar

Normalized Version: - All metrics scaled 0-100 (100 = worst) - Gradient fill from green (good) to red (bad) - Allows cross-metric comparison

Success Metrics

✓ 5-Second Test Passed: “Which province has the worst crowding?”
→ Answer: Limpopo (73.1% large class rate, 49.6 ECS) - immediately visible

✓ Visual Clarity: Provincial rankings instantly recognisable

✓ Comparison Enabled: Both within-province and between-province comparisons work well

✓ Technical Quality: - High-resolution output (300 DPI) - Both PNG and PDF formats - Clean, professional design

Implementation Notes

Time Invested: ~45 minutes - Script development: 25 minutes - Testing and refinement: 15 minutes - File organisation: 5 minutes

Key Insights Made Visible

Limpopo crisis: Worst on all metrics (ECS: 49.6, 73.1% large classes)
Northern Cape success: Best performer (ECS: 37.0, 29.5% large classes)
Gauteng paradox: Mixed results (slightly worse TCR despite better outcomes)
Clear geographic pattern: Rural provinces struggle more

Remaining Visualisations (from recommendations)

Priority 1 (Quick Wins)

⏳ Fiscal Leakage Horizontal Bar Chart (Slide 26)
- Estimated time: 20-30 minutes
- High impact, low complexity

Priority 2 (Enhanced Analysis)

⏳ Variance Contribution Treemap (Slides 25/25b)
- Estimated time: 30-40 minutes
- Medium impact, medium complexity

Total Estimated Time Remaining

Phase 1: ~30 minutes
Phase 2: ~40 minutes
Total: ~70 minutes

Next Steps

Integrate completed visualisations into vu_slides.qmd:
- Waterfall chart → Slide 11
- Provincial descriptives → Slide 10
Update slide narrative to reference the visualisations
Proceed with remaining visualisations:
- Fiscal Leakage horizontal bar chart (Priority 1)
- Variance contribution treemap (Priority 2)
Consider creating interactive versions using plotly for HTML slides

Notes for Future Sessions

Data Source: Values are hardcoded from the HTML table. If underlying data changes: 1. Update waterfall_viz tibble in script (lines 17-31) 2. Re-run script to regenerate outputs 3. Verify annotations still align correctly

Alternative Approaches Considered: - Stacked bar chart: Rejected (doesn’t show sequential nature) - Line graph: Rejected (doesn’t emphasise constraint types) - Slope graph: Possible alternative, but less impactful

Feedback Loop: - Test with target audience (VU presentation) - Gather feedback on clarity and impact - Iterate if needed before wider use