on-the-fly decoding

[jeremymanning]

After implementing on-the-fly interactive labels, I propose a "decoding" mode for streaming data, whereby the event closest (in Euclidean distance, or another user-specified distance function) to the current features is highlighted in some way.

[jeremymanning]

Current status (1.0 update): not addressed, and hard-blocked on GH #111 (interactive labels), also not addressed — there is no labeled-event store to decode against. hypertools/predict/predict.py implements an unrelated feature (hyp.predict, forward trajectory forecasting via a Forecaster registry: Kalman/GaussianProcess/AutoRegressor/ARIMA/Laplace/Chronos), not nearest-labeled-event lookup.

How this could be built on the 1.0 architecture: Once #111 exists and fig.stream_info['labels'] (proposed there) holds (label, position) pairs, decoding is a small addition to plot_stream()'s per-chunk _redraw() loop in hypertools/io/streaming.py:

• Maintain a scipy.spatial.cKDTree (or, for a pluggable distance function as the issue requests, a simple sklearn.neighbors.NearestNeighbors(metric=...)) built over the labeled points, rebuilt/updated whenever a new label is added.
• On each new streamed sample, query nearest labeled point; if within a threshold (or always, showing the single nearest), highlight it — reusing the existing annotation-drawing code path (matplotlib_backend.annotate_plot / plotly_backend._build_point_annotations) to redraw that one label with a distinct style (e.g. bold/larger/differently colored bbox), rather than inventing new rendering.
• This could plausibly be exposed as a decode=True/decode={'metric': ..., 'k': ...} kwarg on plot_stream, following the same bool/dict pattern surface=/density= already use for optional plot-time behavior, for consistency with the rest of the 1.0 kwarg conventions.
• A natural follow-on: since hypertools/manip (base class + registry + hyp.manip funnel dispatcher, per PR HyperTools 1.0: architecture refactor + bug hunt #272) already exists as the pattern for "resolve a spec, fit/transform data," a Decoder concept (nearest-labeled-point classifier) could eventually live as its own small module following the same common.py-base-class + registry template used by manip/ and predict/, if the maintainer wants it addressable outside the live-stream UI too (e.g. offline "decode this batch of held-out points against a saved labeled model").

Alternatives / prior art:

• sklearn.neighbors.KNeighborsClassifier/NearestNeighbors — mature, already a hypertools dependency (used elsewhere in the reduce/cluster stack), directly implements "closest labeled point by distance function."
• scipy.spatial.cKDTree — faster for repeated nearest-neighbor queries against a growing point set, no new dependency (scipy already required).

Note: the "decoding model saved to disk" and "benchmark harness for feature_extractor/decoder functions" ideas from the parent issue (#113) go beyond this issue's narrower ask and are tracked there instead.

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

[jeremymanning]

Do not implement this for now; we can decide how to proceed later