ability to change label opacity

[andrewheusser]

when plotting many labels on a single plot, its difficult to see the data because they become covered with labels. We could add a flag to adjust the opacity of the labels.

[jeremymanning]

Current status (1.0 update): not addressed. annotate_plot() in hypertools/plot/matplotlib_backend.py hardcodes bbox=dict(..., fc="white", alpha=0.5) at both its 2-D and 3-D call sites (~lines 466/483). The plotly backend's parallel code path, _build_point_annotations() in hypertools/plot/plotly_backend.py, independently hardcodes bgcolor='rgba(255,255,255,0.5)'. Point-label annotations themselves already exist in both backends (labels=, added for GH #205) — only the opacity is unconfigurable.

How this could be built on the 1.0 architecture: Add one scalar kwarg, e.g. label_alpha=None, to plot()'s signature in hypertools/plot/plot.py. This is a single value per plot (not per-dataset), so it should follow the simple "resolve once, hand to both backends" shape already used for font=/resolve_font() (hypertools/plot/fonts.py) rather than the per-dataset bool/dict/list broadcast pattern used for surface=/density=. Default None resolves to the current 0.5 for backward compatibility. Thread the resolved value into:

• matplotlib_backend.annotate_plot() — replace both hardcoded alpha=0.5 bbox entries.
• plotly_backend._build_point_annotations() — format the value into the bgcolor rgba string's alpha channel.

Both matplotlib (bbox=dict(alpha=...)) and plotly (bgcolor='rgba(r,g,b,a)') already natively support variable alpha, so no new dependency is needed.

Alternatives / prior art:

• None needed — this is parameter plumbing using APIs both backends already expose.

Note: the underlying label-annotation feature (GH #205) already shipped in the 1.0 update in both backends; this issue only asks for the missing opacity knob on top of it.

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

[jeremymanning]

Addressed in PR #272 (HyperTools 1.0).

plot() now takes a label_alpha=None kwarg that controls the opacity of point-label annotation backgrounds in both backends. None resolves to the historical default (0.5), matching prior behavior byte-for-byte when omitted; any other value must be a non-bool number in [0, 1] or a ValueError is raised.

Implemented in hypertools/plot/plot.py, hypertools/plot/matplotlib_backend.py (annotate_plot()'s two hardcoded bbox=dict(..., alpha=0.5) sites now use alpha=label_alpha), and hypertools/plot/plotly_backend.py (_build_point_annotations()'s bgcolor='rgba(255,255,255,{label_alpha})'). Commit b513bca7.

import hypertools as hyp

hyp.plot(data, labels=my_labels, label_alpha=0.2)   # faint backgrounds
hyp.plot(data, labels=my_labels, label_alpha=0.9)   # near-opaque

Evidence (real renders, alpha values baked into the filenames):

• matplotlib, alpha=0.2: https://raw.githubusercontent.com/ContextLab/hypertools/dev-1.0-refactor/docs/images/v1.0-round17/task7_mpl_3d_labels_alpha02.png
• plotly, alpha=0.3: https://raw.githubusercontent.com/ContextLab/hypertools/dev-1.0-refactor/docs/images/v1.0-round17/task7_plotly_3d_labels_alpha03.png

22 new tests in tests/test_plot_kwargs_round17.py cover the mpl case by reading the rendered annotation bbox patch's .get_alpha() directly, the plotly case via the bgcolor string, and 5 invalid-value cases (-0.1, 1.1, 2, True, "0.5") all raising ValueError. Full suite: ~1275 tests passing.