Correctness bug bundle: distance, posterior, transitions, sim, viz, HPD (+ position-dim refactor)

[edeno]

Summary

A bundle of correctness fixes plus small follow-ups surfaced by a full-repo review and three filed issues (#40–#42). Changes are organized into focused, independently-revertible commits. No public API removals; model snapshot and golden-regression outputs are unchanged.

Closes #40
Closes #41
Closes #42

Fixed

Review findings

• analysis.distance1D.get_map_speed: trailing boundary speed was inserted before the last sample (np.insert(arr, -1, val)), misordering the final two speeds for any chunk with ≥3 time bins. Now appended.
• _DetectorBase.estimate_parameters: post-EM cleanup of _encoding_model_data never ran (hasattr attribute-name mismatch); fitted models retained spike-time/waveform arrays.
• ContFrag{SortedSpikes,Clusterless}Classifier.get_posterior: raised on 2D environments (summed a position dim that only exists in 1D). Now collapses every position/*_position dim, guards against an empty dim list, and the two identical bodies are de-duplicated into one helper. state output dim preserved.
• Environment.fit_place_grid: a tuple place_bin_size with a track_graph crashed deep inside np.linspace; now raises a clear ValidationError with an example.
• RandomWalk direction-aware transitions: crashed with AttributeError in networkx when no N-D track graph was available; now raises ConfigurationError.
• figurl_2D.process_decoded_data: the uint16 grid guard had an off-by-one — it rejected valid 256×256 grids (65536 bins, max index 65535 fits). Fixed to key on the largest index (overflow begins at 65537 bins) and extracted into a sortingview-free, unit-testable validate_grid_within_uint16 helper.
• make_simulated_run_data: hardcoded mark_spacing=10 while replay generators default to MARK_SPACING=5; unified on the module constant.
• get_HPD_spatial_coverage: only handled 1D; now integrates over the product of per-axis bin widths, supporting 1D (length), 2D (area), 3D (volume), and beyond. 1D/2D results numerically identical to before.

Filed issues

• get_ahead_behind_distance2D(precomputed_distance=True) crashes under networkx>=3 (.items() on generator) #40 distance2D.get_map_estimate_direction_from_track_graph (precomputed_distance=True): the all-pairs nx.shortest_path is a generator under networkx≥3, not a dict — .items() raised AttributeError. Now iterated directly (also avoids materializing the full O(n_nodes²) dict).
• make_single_environment_movie: multiunit panel disappears after first parallel chunk (ax1 limits gated on frame_idx==0) #42 make_single_environment_movie: the multiunit panel went blank after the first parallel chunk because ax1 limits were gated on frame_idx == 0. Now initialized per-worker.

Latent

• base._convert_seq_to_df position naming capped labels at 4 (x/y/z/w) and silently dropped position columns for 5-6D environments. Convention centralized in non_local_detector._position_dims and shared by all consumers; truncation fixed.

Comprehensive-review follow-ups (silent → loud)

• distance2D.get_map_estimate_direction_from_track_graph (precomputed_distance=True): on a disconnected track graph an unreachable head/MAP pair kept the -1 path sentinel and silently indexed node_positions[-1], emitting a wrong heading. Unreachable pairs now warn and return NaN (mirrors get_2D_distance).
• RandomWalk.make_state_transition: a direction= argument was silently ignored unless use_manifold_distance=True on an N-D grid (the default use_manifold_distance=False, or a track_graph, dropped it). Now raises ConfigurationError up front rather than returning an unconstrained walk.

Added

• get_HPD_spatial_coverage gained an optional bin_width parameter for non-uniform 1D (linearized track-graph) grids. Multi-segment tracks with unequal arms produce on-track bins of different widths (plus edge_spacing gap bins); the uniform default used the first bin's width for every bin, biasing coverage. Pass per-bin widths — e.g. np.diff(environment.edges_[0]) — for the exact integral. Default unchanged (uniform), restricted to a single position dim since multidimensional grids are uniformly spaced. (Determined by tracing every grid path: open-field/single-segment tracks are uniform → center-derived widths equal the true edges; only unequal-arm track graphs are non-uniform, and there the widths must come from the real edges.)

Changed

• head_direction_simliarity / get_ahead_behind_distance2D: head_direction docstring says (n_time, 2) but code requires a 1-D angle array #41 head_direction_simliarity / get_ahead_behind_distance2D: corrected the head_direction docstring from (n_time, 2) to a 1-D heading-angle array (n_time,). No code change.
• posterior_consistency_hpd_overlap: Notes block clarifies the asymmetric containment coefficient |A∩B| / min(|A|,|B|). No code change.
• posterior_consistency_{kl_divergence,hpd_overlap}: corrected the input-shape docstrings (both require flattened (n_time, n_position_bins), not the previously-documented (n_time, n_x_bins, n_y_bins) which raises) and added the missing factor of 2 to the Sørensen-Dice formula. Docstrings only.

Removed

• environment.order_boundary and get_track_boundary_points: relied on nx.from_scipy_sparse_matrix (removed in NetworkX 3.0) and were unused; the unused NearestNeighbors import was removed too.

Refactor / internal

• New non_local_detector._position_dims centralizes the position-dim naming convention (get_position_dim_names / get_position_dims), shared by both base.py results constructors, ContFrag*.get_posterior, and get_HPD_spatial_coverage (previously re-derived with three different rules). Direct unit tests pin the 5-6D and >6D branches.
• Shared synthetic-results test factory (conftest.make_state_bins_results) replaces near-duplicate builders across two test modules.

Test plan

• uv run pytest -m "not slow" — 849 passed, 3 skipped, 1 xfailed (pre-existing)
• uv run pytest -m snapshot and test_golden_regression.py — no diffs
• HPD 1D/2D coverage numerically identical to the prior formula (max|diff| = 0); added 3D and non-uniform-bin_width regression tests
• ruff check src/ and ruff format --check src/ — clean
• Each fix has an isolated regression test; the figurl off-by-one, distance2D get_ahead_behind_distance2D(precomputed_distance=True) crashes under networkx>=3 (.items() on generator) #40, disconnected-graph, RandomWalk-direction, and movie make_single_environment_movie: multiunit panel disappears after first parallel chunk (ax1 limits gated on frame_idx==0) #42 tests were verified RED against the pre-fix code
• CI green

🤖 Generated with Claude Code