GSoC 2025 - Development Journal

Week 0 (Community Bonding Period)

May 15 - May 20, 2025

Outcome

Ported three visualizations from the old Animint gallery to the new Animint2 gallery and submitted a pull request.

American Temperature Maps (#55)

World Bank Paper (#41)

ChIP seq Data Unaligned (#35)

What I did

Due to ongoing exams, my time was limited, but I managed to:

Port three key visualizations from the old gallery to the new Animint2 syntax:
- #55 - American Temperature Maps
- #41 - World Bank paper visualization
- #35 - ChIP seq data unaligned visualization
Submitted PR #29 to the gallery repository
Fixed issues in the 41st and 35th visualizations
Addressed mentor feedback on the 55th visualization

Learnings

This week was incredibly educational as I:

Gained deep understanding of Animint functions and capabilities
Learned the process of converting old Animint code to new Animint2 syntax
Improved skills in making visualizations more clear, sophisticated and user-friendly
Understood how to implement better interactivity in visualizations
Learned to handle different types of geoms (points, tiles, lines) in Animint better
Improved my understanding of the gallery structure and contribution process
Explored different old visualization source codes and compiled a list of visualizations to be ported next

Confusions/Issues

Some challenges I encountered:

Geom_tile transitions aren't smooth in the visualizations
Need to investigate if this is a bug by creating a minimal reproducible example
Need to check test cases to see if smooth transitions in geom_tile are properly tested
Certain interactive elements required more work than expected to port properly

Next Week Targets

Port other visualizations
Complete remaining mentor suggestions on the 55th visualization
Create demonstration videos once visualization outlooks are finalized
Investigate the geom_tile transition issue

Links

Week 0 (Community Bonding Period)

May 21st - May 28th, 2025

Montreal Bikes Jan 2016 (#43)

Demo of Constrained PDPA (#31)

Cost/slack minimization (#30)

Segmentation model selection with BIC (#50)

Gradient descent for neural networks (#5)

Gradient descent for regression (#6)

What I did

Solved geom_tile transition issue
Created comprehensive demonstration videos for all three previously ported visualizations
Successfully got PR #29 merged into the main gallery repository
Ported six additional visualizations from old to new gallery:
- #43 - Montreal Bikes Jan 2016
- #31 - Demo of Constrained PDPA
- #30 - Cost/slack minimization over all feature thresholds
- #50 - Segmentation model selection with BIC
- #5 - Gradient descent for neural network and linear model
- #6 - Gradient descent for regression
Submitted and got PR #30 merged for these new visualizations
Ensured all visualizations maintained their original functionality while using Animint2 syntax

Learnings

Solved geom_tile transition issue by implementing a two-layer approach: (documented in PR #29)
- Base layer for smooth transitions (showSelected="time2") with fill colors but no borders
- Selection layer for click interactions (clickSelects="id") with border colors but no fill
Data format requirements for different geoms

Confusions/Issues

Initial uncertainty about the best approach to solve the geom_tile transition issue
Some visualizations required significant restructuring to work with Animint2
Ensuring consistent behavior across all browsers was occasionally challenging

Next Week Targets

Investigate geom_abline bug (#142)
Explore tooltips implementation
Port remaining high-priority visualizations

Links

Week 0 (Community Bonding Period)

May 28th - June 1, 2025

Outcome

Investigated geom_abline bug and proposed solution, implemented new D3-based tooltip system.

D3-based Tooltip Implementation

Interactive tooltips following mouse position with D3 integration

What I did

Analyzed geom_abline boundary issue (#142) with reproducible examples
Identified root cause: clipping not reapplied during update_axes
Proposed JS solution to recalculate segments post-update
Switched tooltip implementation from tippy.js to native D3
Created unified tooltip div that follows mouse position
Updated all tooltip tests for new implementation

Learnings

geom_abline behavior:
- Initial clipping done by R's pre_process function
- Boundary constraints lost during scale updates
- Need to recalculate endpoints in JS using current scale domains
Tooltip implementation:
- D3 outperforms tippy.js for Animint's use case
- Single dynamic div more efficient than multiple tooltips
- Better integration with existing D3 infrastructure
Renderer-compiler interaction during axis updates
Test case requirements for renderer bugs

Confusions

Still unsure about how to implement the js side function for clipping geom_ablines
Facing some problems with the tests for tooltips in simulating hovering over the component - to get the exact position of the component on the viewport

Next Week Targets

Create failing renderer test for geom_abline issue
Implement JS solution for abline boundary clipping
Finalize D3 tooltip PR (#191) with test fixes
Get tooltip implementation merged

Links

Week 1

June 2 - June 8, 2025

Outcome

Refined tooltip PR with all requested changes, investigated geom_abline solutions, and implemented initial geom_aligned_boxes with quadratic programming optimization.

What I did

Made all requested changes in tooltip PR, refining and improving minute details
Investigated further into geom_abline issue and identified two potential approaches for handling clipping
Opened new PR implementing geom_aligned_boxes (#203) - a custom geom for aligned rectangular labels
Implemented the core structure where each box is a <g class="geom"> group containing both <rect> (box) and <text> (label) elements
Integrated quadprog.js (JavaScript port of R's quadprog library) for label positioning optimization
Set up automatic text measurement system using browser's actual font metrics
Created bounding rectangle calculation that dynamically sizes boxes to fit measured text

Learnings

geom_abline clipping approaches:
- Option 1: Move clipping entirely to JS side, shifting pre_process function logic from R
- Option 2: Handle clipping in compiler side by modifying z_animint.js update_axes function
- Both approaches have trade-offs in terms of performance and code organization
geom_aligned_boxes architecture and use case:
- Addresses the need for non-overlapping labels in visualizations, particularly useful for time series data where multiple category labels need to appear near data points
- Takes required aesthetics: x, y, label, plus optional ones like fill, color
- Mimics R's directlabels::last.polygons functionality but adapted for animint2's JavaScript environment
- Uses quadratic programming to optimize label positions: keeps x-positions fixed while adjusting y-positions to minimize overlaps
- Solver minimizes distance from original y-values while ensuring no label collisions
- Learned how different svg elements work. eg. we cant appened a <text> in a <rect> element in svg! (which i was trying to do before for this implementation.
Integration of quadprog.js JavaScript port for optimization
Browser-based text sizing and bounding box calculations

Technical implementation insights:

Browser-based text measurement is crucial since font rendering varies across systems
Quadprog.js provides the mathematical optimization needed for clean label arrangement
Dynamic bounding box calculation ensures labels are properly contained within their rectangles
The optimization problem balances staying close to original positions vs avoiding overlaps

Confusions

The quadratic programming solver integration isn't functioning correctly yet - the optimization constraints and objective function need refinement
Need to implement proper error handling for cases where optimal positioning might not be feasible
Still evaluating which approach would be best for the geom_abline clipping issue
Debugging the quadprog.js parameter setup to ensure it correctly interprets the positioning constraints

Next Week Targets

Complete geom_aligned_boxes implementation by fixing the quadprog solver integration
Create comprehensive renderer tests for geom_aligned_boxes functionality
Get tooltip PR (#191) merged after addressing any final feedback
Implement robust error handling for edge cases in label positioning optimization
Test geom_aligned_boxes with various data scenarios to ensure reliability

Links

Week 2

June 9 - June 15, 2025

Outcome

Completed core implementation of geom_aligned_boxes with optimized label positioning, fixed remaining tooltip issues, and got PR #191 merged.

geom_aligned_boxes interactive example

geom_aligned_boxes positioned in a way that they dont collide using quadprog.js

What I did

Implemented quadratic programming solution for label positioning inspired by directlabels::qp.labels
Created comprehensive renderer tests for geom_aligned_boxes covering:
- Basic rendering
- Collision avoidance
- Interactive behavior
- Boundary constraints
Fixed final tooltip issues and got PR #191 merged
Added multiple usage examples demonstrating different configurations
Identified and documented edge cases:
- Text styling issues
- Plot boundary violations
- StyleActions conflicts

Learnings

Finally cracked the label positioning! After digging through the directlabels source code, I got the quadratic programming approach working. It's cool how it:
- Handels overlaps and avoids collisions between labels using constraints in qp solver
- Uses a constraint matrix to prevent overlaps
- Minimizes the distance from original positions
SVG structure headaches:
- Learned the hard way you can't nest text inside rect elements (facepalm)
- Had to completely restructure as <g> containing separate <rect> and <text>
- Still fighting with style inheritance - the geom group keeps grabbing styles when it shouldn't (for the geom_aligned_boxes that have ClickSelects in them)
Testing adventures:
- Built tests for every weird edge case I could think of
- Found some sneaky bugs where labels would escape the plot area during interactions
- Learned to test performance with a lot of labels
Tooltip victory lap:finally got the D3 tooltip PR merged!

Confusions/Issues

Style inheritance problem:
- Added if (g_info.geom == "aligned_boxes") return; to skip automatic styling
- But clickSelects elements still get unwanted style attributes
- Can't figure out where the styles are leaking through
Boundary issues:
- Labels near plot edges occasionally escape containment (only to a limited extent and only the left side of x limit)
- Need to add proper clipping

Next Week Targets

Finalize geom_aligned_boxes styling implementation
Begin investigating code coverage tools for animint2
Prepare geom_aligned_boxes documentation

Links

Week 3

June 16 - June 22, 2025

Outcome

Refined geom_label_aligned implementation based on mentor feedback, began setting up code coverage tools, and ported additional visualizations to the gallery.

geom_label_aligned visualization showing properly aligned labels with optimized box sizing

geom_label_aligned now with proper hjust alignment and optimized box sizing

What I did

Implemented major improvements to geom_label_aligned based on mentor feedback:
- Changed default fill from black to white
- Fixed horizontal width calculation (no more extra space!)
- Added proper hjust support (0, 0.5, 1)
- Renamed from geom_aligned_boxes to geom_label_aligned
Refactored test files into single comprehensive test:
- Created check_aligned_box_collisions helper function
- Moved vertical alignment tests to WorldBank viz
- Consolidated all test cases
Added detailed documentation about QP usage:
- Clarified it runs after showSelected filtering
- Explains vertical vs horizontal alignment modes
Began implementing code coverage:
- Setting up V8 for JS coverage
- Configuring covr for R coverage
- Integrating with Codecov
Ported visualization #9/18 (Changepoint detection) to new gallery

Learnings

Geom refinement lessons:
- Because of the unique structure of this geom, a lot of default styling structures implemented in animint2 for all geoms dont work for this one. So I had to implement some conditions in certain cases.
- Text alignment is trickier than expected (hjust wasn't working as intended). I had to implement a get_hjust function to get it working for the new geom.
- Naming conventions should match ggplot2 ecosystem
Testing insights:
- DRY principle applies to tests too - helper functions are essential
- Real-world examples (like WorldBank) make great test cases
Code coverage setup:
- V8 engine quirks when measuring JS coverage.
- How covr instruments R code
- Codecov report interpretation

Confusions/Issues

QP behavior quirk:
- Labels with same x-values affect others even when not colliding
- Need to adjust constraint matrix to be smarter about this
Code coverage challenges:
- Getting V8 to properly track JS execution paths
- Merging R and JS coverage reports

Next Week Targets

Fix QP constraint matrix for non-colliding labels
Complete initial code coverage implementation
Finalize geom_label_aligned implementation and documentation

Links

Week 4 - When Labels Learned to Behave

June 23 - June 29, 2025

Watch how labels now stay politely within plot boundaries and shrink when needed (vertical alignment)

This Week's Progress

Finally cracked the label positioning challenges! My geom_label_aligned now handles crowded plots much more gracefully:

Strict Plot Limits: No more label jailbreaks! Added firm constraints that keep all labels inside the plot area, no matter what.
Smart Shrinking: When space gets tight, labels now automatically scale down (but stay readable) until everything fits. It's like watching polite commuters adjust in a crowded train!
Group Optimization: Realized distant labels shouldn't affect each other, so I implemented proximity grouping before running the QP solver. Much faster and better results!

Horizontal alignment demo showing the same good behavior

Behind the Scenes

The shrinking mechanism was trickier than I expected. At first labels would shrink too much or not enough, but after several iterations I found the right balance. The key was:

Calculate total space needed vs available
Apply uniform shrinking for groups of labels close to each other and overlapping only when necessary

Also made progress on code coverage, though it's been a bumpy ride. Trying to merge R's covr with JS coverage from Chrome DevTools feels like teaching two pets to work together - they speak different languages!

Next Week Targets

Need to:

Refine the geom_label_aligned PR if needed and get it merged
Maybe adding some error points for geom_label_aligned like: "vjust cannot be used with vertical alignment" and vica-verca
Finalize the coverage pipeline
Write proper docs so others can use these features

Updates coming soon