HyperTools 2.0: architecture refactor + bug hunt

[jeremymanning]

HyperTools 2.0 — architecture refactor + bug hunt

This PR merges the completed HyperTools 2.0 class-based refactor into dev-2.0, together with a broad bug hunt (open-issue triage + two animation-rendering fixes you reported + a legend-clipping fix) and the CI fixes needed to get all platforms green.

⚠️ Please do not merge. Opened for your review; I'll proceed however you decide. Base: dev-2.0 ← Head: dev-2.0-refactor.

---

1. Architecture refactor (Plans 1–8)

Reorganized the working dev-2.0 code into the class-based structure, on modern deps, with DataGeometry removed from the public API:

• Deps modernized: numpy ≥2, pandas ≥3, scikit-learn ≥1.4, matplotlib ≥3.8, plotly 6.x, via datawrangler 0.5 (funnel/stack/unstack/format-detection/model-dispatch). Supports pandas 3.0+.
• Class-based modules: core (eval-free apply_model), external (vendored PPCA + brainiak SRM/DetSRM/RSRM), manip (Normalize/ZScore/Smooth/Resample), reduce/align/cluster (generic sklearn dispatch by name), io, plot (matplotlib + plotly backends). Old tools/ names remain as shims.
• DataGeometry removed from the public API (kept only as a hidden unpickle shim so legacy hosted .geo datasets still load). plot() returns a Figure / (fig, ani); plot(..., return_model=True) returns {'fig','xform_data','models','animation'}; load() returns raw data.
• Docs/gallery/tutorials migrated to the 2.0 API and rebuilt.

---

2. Reported animation fixes

Animated bounding box "crowded / cut off on the right." Animated 3D plots zoomed the cube in too far. Fix: set_box_aspect zoom 1.25→1.125 + full-canvas axes. Min cube-to-edge margin over the full save_movie rotation: right 80→96px, bottom 51→72px.

before (crowded)	after (margin)

Duplicate animation-legend entries (GH #207). Faint "trail" artists carried the dataset label, so each label appeared twice. Fix: trails tagged _nolegend_; legend is now the static union of in-focus datasets. Verified ['first','second'].

Clipped static gallery legends. Wide legends (long labels / many entries) clipped off the right edge. Root cause: the fit routine measured the legend under seaborn's (narrower) font, but the figure is saved downstream under the default (wider) font. Fix: _fit_right_legend now measures the rasterized pixels under default rcParams and widens the figure (keeping the plot's size) until the legend has a margin. Regenerated plot_legend/plot_PPCA/plot_missing_data; pixel-based regression test added.

---

3. Open-issue triage → close-on-merge

Triaged all 67 open issues against this branch with real repros (see notes/issues-to-close-on-merge.md): 28 ADDRESSED + 6 OBSOLETE + 6 bugs fixed here = 40 to close on merge; 27 stay open (feature requests / design decisions), each documented.

Bugs fixed from triage (all regression-tested):

#	bug	fix
#259	import hypertools mutated global rcParams['pdf.fonttype']	removed import-time mutation; editable-PDF default set inside manage_backend's snapshot/restore
#223	get_proj crash on 2D labeled plots	guard get_proj; match annotate/update tuple shapes for 2D vs 3D
#146/#190	DBSCAN/MeanShift/OPTICS crash on n_clusters	inject n_clusters only when the model's signature accepts it; register those clusterers
#148	show=False leaked the figure into pyplot	plt.close(fig) for static figures (skipped when the user passed ax, and for animated figures, whose timer must stay alive)
#214	wiki-model docstring vs wiki_model key	docstring corrected
—	reduce=<class/instance> → UnboundLocalError	initialize model_params in the custom-estimator branch

---

4. CI fixes (get all platforms green)

The first CI run surfaced two platform issues (unrelated to the features above); both fixed:

• Windows (all Pythons) — collection error. datawrangler 0.5.0 evaluates os.getenv('HOME') at import time to build its data dir; HOME is unset on Windows, so os.path.join(None, …) crashed dw's (and hypertools') import. Fixed hypertools-side by setting HOME=expanduser('~') before importing dw; filed upstream as Import crashes on Windows: config datadir evals os.getenv('HOME') which is None data-wrangler#32, fixed in dw 0.5.1 (released; verified import datawrangler works with HOME unset). The pydata-wrangler pin is bumped to >=0.5.1; the one-line HOME guard stays as belt-and-suspenders for environments still on 0.5.0.
• macOS/Ubuntu Python 3.11+ — 3 tests. matplotlib 3.11 (Python 3.11+ only) resets a figure's canvas after plt.close() (the disabling the figure doesn't work as intended #148 fix), so tests/callbacks that read fig.canvas.renderer/buffer_rgba() failed. Fixed by guarding the renderer in update_position and rendering the affected tests through an explicit Agg canvas. (savefig after close still works, so users are unaffected.)
• Windows — animated-figure draw crash. On Windows the animate backend switch to TkAgg actually succeeds (headless Linux/mac fall back to Agg), so the disabling the figure doesn't work as intended #148 plt.close() destroyed the FuncAnimation's real Tk timer and any later draw of the returned figure crashed ('NoneType' object has no attribute 'start'). Animated figures are now exempt from the show=False close — the disabling the figure doesn't work as intended #148 complaint was about static figures, and animations need their timer alive for playback.
• Ubuntu 3.12 — screenshot-verification step. The screenshot harness discovered figures via plt.get_fignums(), which the disabling the figure doesn't work as intended #148 close empties; it now uses the figure(s) returned by plot() (13/13 cases pass).

---

Testing

• Local suite: 343 passed, 0 failed (pytest -q); 6 plotly→kaleido image-export tests deselected locally only — they deadlock Chromium in this sandbox but run fine in CI (CI runs all 349).
• CI: all 12 jobs green (ubuntu/macos/windows × Python 3.10–3.13) after the §4 fixes — run 28721072551; see this PR's checks for the head commit.
• Docs rebuilt (make html succeeds); animated + legend gallery figures regenerated.

🤖 Generated with Claude Code