2d animations

[andrewheusser]

currently only 3d animations are supported, but we can add 2d

[jeremymanning]

Current status (1.0 update, PR #272): still 3D-only. matplotlib_backend.py:966 (dispatch_animate), :1390-1391 (assert x[0].shape[1] == 3, "Animations are currently only supported for 3d plots."), and :1418 all gate on 3 columns. The plotly backend has the same restriction for animate='morph' (plotly_backend.py:358-360) and plot.py:1447. No 2D animation path exists in either backend.

How this could be built on the 1.0 architecture:

• Matplotlib: add an animate_plot2D counterpart to animate_plot3D in matplotlib_backend.py, reusing the existing frame-update / trail / chemtrails / precog / bullettime logic (which is written generically over point arrays) but dropping the elev/azim rotation camera — 2D has no rotations= to animate, so the camera is simply static (or could pan/zoom instead). Update dispatch_animate (~line 966) to branch on x[0].shape[1] in (2, 3).
• Plotly: plotly_backend.py already branches statically on ndims == 2 vs == 3 (line 267); extend the animated-frame path (currently animate='morph' 3D-only guard at 358-360, frame construction ~822) to build 2D go.Scatter frames instead of go.Scatter3d.
• plot.py's morph-mode guard (line 1447) and the xform[0].shape[1] == 3 check (line 1580) need loosening to allow ndims == 2 alongside 3.
• Actually simpler than the 3D case in one respect: no rotation/elevation math needed for 2D, just a fixed viewport.

Alternatives / prior art:

• matplotlib's FuncAnimation natively supports 2D axes with no extra dependency — the existing frame-update callbacks mostly just need their z-coordinate handling made optional.
• No external library is needed; this is pure application-logic work reusing existing animation infrastructure.

Tagging as medium effort; leaving open for consideration in a future release.

[jeremymanning]

Addressed in PR #272 (HyperTools 1.0).

All animate= styles except 'spin' now work for 2-D data (ndims=2) in both the matplotlib and plotly backends, using a fixed (non-rotating) viewport. 'spin' raises a ValueError for 2-D data in both backends, naming the other styles as alternatives (spin is inherently a 3-D camera rotation). rotations=/zoom= (3-D camera controls with no 2-D equivalent) are warned-and-ignored once via a centralized UserWarning when set to a non-default value on 2-D animated data, in both backends identically.

Implemented via new animate_plot2D (matplotlib, mirrors animate_plot3D minus camera bookkeeping, uses Line2D.set_data) and extending the plotly morph/frame-builder code paths to ndims in (2, 3). Commit e02e7eb5.

import hypertools as hyp

hyp.plot(data_2d, reduce='PCA', ndims=2, animate='window')   # now works
hyp.plot(data_2d, reduce='PCA', ndims=2, animate='spin')     # raises ValueError

Evidence (real renders, mid-animation frames, fixed square viewport, no camera rotation):

• matplotlib: https://raw.githubusercontent.com/ContextLab/hypertools/dev-1.0-refactor/docs/images/v1.0-round17/task9_2danim_mpl.png
• plotly: https://raw.githubusercontent.com/ContextLab/hypertools/dev-1.0-refactor/docs/images/v1.0-round17/task9_2danim_plotly.png

22 new tests in tests/test_2d_animation.py cover frame counts and progression for parallel/serial/window/morph in both backends, exact window bounds, 2-D morph Hungarian-correspondence verification, spin-on-2D ValueError, xlabel/ylabel on animated 2-D figures, rotations=/zoom= warnings, and a real saved GIF with non-identical frames (PIL pixel comparison).

Full suite: ~1275 tests passing.