Warn on degenerate-KDE NaN density and large off-grid bin snaps

[edeno]

Summary

Surfaces two previously-silent degeneracies as warnings, without changing any well-behaved numerics. Scope was trimmed from the original Phase-5 work down to the two changes that actually flag (or prevent) a wrong scientific result.

Changed

• likelihoods.sorted_spikes_kde — fit_sorted_spikes_kde_encoding_model and predict_sorted_spikes_kde_log_likelihood (local branch) previously replaced NaN KDE marginal-density bins with zero silently. They now count those bins and emit a UserWarning. NaN density usually means a degenerate KDE (zero-variance / identical spike features, or position_std=0) that otherwise yields a plausible-but-wrong place field. The zeroing behavior itself is preserved — no numerical change for well-behaved inputs.

Added

• Environment.get_bin_ind now emits a UserWarning when off-grid positions are snapped to the nearest interior bin and the max snap distance exceeds 2 × place_bin_size + max(edge_spacing) (a likely tracking glitch or out-of-bounds position). The inter-arm-gap term keeps routine into-gap snaps on multi-arm linearized tracks from crying wolf; open-field grids have no gap term. The snap behavior itself is unchanged.

Trimmed from the original PR

These pieces were dropped as speculative / low-value (reverted to main exactly):

• safe_log / safe_divide return_clamp_count — an opt-in primitive with no production consumer (the consumer was explicitly deferred). YAGNI; it should land in the PR that actually uses it.
• Simulator unseeded-RNG warnings (simulate_poisson_spikes, simulate_multiunit_with_place_fields, make_fragmented_replay) — a reproducibility nudge that leans toward noise; some runs are intentionally unseeded.
• _setup_track_graph per-call-copy "edge-leak fix" — on review this was found to be a no-op refactor: every temporary edge the function adds is incident to a temporary node, so the old per-step remove_node cleanup already fully restored the graph and shortest-path distances are byte-identical before and after. Dropped as churn.

Test plan

• New targeted tests: KDE NaN warning (fit + local-predict); get_bin_ind snap (far snap warns, into-gap snap stays quiet, threshold includes edge_spacing).
• uv run pytest -m snapshot — 8 pass, no diffs.
• uv run pytest test_golden_regression.py — 4 pass, no diffs.
• ruff check / ruff format --check — clean.

Notes

• Rebased onto current main (PRs Surface silent convergence and optimizer failures during fitting #30 / Remove duplicate code paths in transitions, GMM, simulators #33 / Restore hashability and sklearn.clone() contract on detectors #34 already merged); conflicts resolved.
• Known follow-up: out-of-bounds positions in all-interior (open-field) environments are still silently clamped to the edge bin — the snap-warning path only covers gap bins. Closing it cheaply would need a bounds check against edges_.

🤖 Generated with Claude Code

[edeno]

Addressed the multi-agent review (commit 3d46b57):

• Completed the surfacing: the local-likelihood decode path in sorted_spikes_kde had a second silent NaN-zeroing site the fit-path warning didn't cover — now counted + warned.
• make_fragmented_replay: same unseeded-RNG pattern as the instrumented functions, was missed — warning added.
• Dropped a tautological test: test_setup_track_graph_no_cross_call_leak passed on the un-fixed code (the path-graph topology never leaks a load-bearing edge). Replaced with test_repeated_calls_do_not_accumulate_temp_nodes, which genuinely fails pre-fix. The mutation test already guards the core fix.
• Robustness/coverage: _snap_warn_threshold now accepts list (not just tuple); softened the snap warning message and documented the all-interior out-of-bounds gap; added the 2D-threshold and make_multiunit unseeded tests the review flagged.

Golden (4) + snapshot (8) still pass; no numerical change. The lone broad-suite failure remains the pre-existing flaky test_normalize_preserves_probability_property (untouched core.py), slated for Phase 7.