Prepare v2.4.0 release with type fixes and CHANGELOG

- Fix mypy type errors across all source modules
- Add proper type annotations to track_builders interactive functions
- Fix numpy array return type issues with type: ignore comments
- Update edge list/tuple conversion to maintain type safety
- Add TypedDict for TrackBuilderState
- Update CHANGELOG.md with comprehensive v2.4.0 release notes
- All 117 tests passing
- Clean mypy check on all source files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: edeno

CHANGELOG.md

@@ -7,17 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2025-01-16
+
 ### Added
-- Pre-commit hooks configuration for automated code quality checks
-- Comprehensive CI/CD pipeline with quality, test, build, and publish jobs
-- Support for Python 3.13
-- PyPI Trusted Publishing (OIDC) support for secure releases
-- Automated GitHub release creation with changelog extraction
-- Notebook execution testing in CI
-- Modern dependency pinning with lower bounds following Scientific Python SPEC 0
-- Enhanced ruff configuration with numpy-specific and pandas-vet rules
-- Improved mypy configuration with test-specific overrides
-- pandas-stubs for better type checking
+- **Track Builders Module** (`track_builders.py`):
+  - `make_linear_track()` - Create simple linear tracks
+  - `make_circular_track()` - Create circular/annular tracks
+  - `make_tmaze_track()` - Create T-maze tracks for alternation tasks
+  - `make_plus_maze_track()` - Create plus/cross maze tracks
+  - `make_figure8_track()` - Create figure-8 tracks
+  - `make_wtrack()` - Create W-shaped tracks
+  - `make_rectangular_track()` - Create rectangular perimeter tracks
+  - `make_ymaze_track()` - Create Y-maze tracks with configurable angles
+  - `make_track_from_points()` - Create tracks from manual point specification
+  - `make_track_from_image_interactive()` - Interactive track builder from images (Jupyter-compatible)
+  - `_build_track_from_state()` - Helper for retrieving interactive builder results in Jupyter
+
+- **Validation & QC Module** (`validation.py`):
+  - `check_track_graph_validity()` - Validate track graph structure and attributes
+  - `get_projection_confidence()` - Calculate confidence scores for position projections
+  - `detect_linearization_outliers()` - Detect outliers using projection distance and jump detection
+  - `validate_linearization()` - Comprehensive quality assessment with scoring and recommendations
+
+- **Tutorial Notebooks**:
+  - `track_linearization_tutorial.ipynb` - Comprehensive pedagogical tutorial for basic usage
+  - `advanced_features_tutorial.ipynb` - Tutorial covering track builders, validation, and interactive features
+
+- **Core Functionality**:
+  - `project_1d_to_2d()` - Reverse mapping from 1D linear positions back to 2D coordinates
+  - Numba-optimized Viterbi algorithm for HMM inference (when numba available)
+  - Exposed `project_1d_to_2d` in package `__init__.py`
+
+- **Infrastructure**:
+  - Pre-commit hooks configuration for automated code quality checks
+  - Comprehensive CI/CD pipeline with quality, test, build, and publish jobs
+  - Support for Python 3.13
+  - PyPI Trusted Publishing (OIDC) support for secure releases
+  - Automated GitHub release creation with changelog extraction
+  - Notebook execution testing in CI
+  - Modern dependency pinning with lower bounds following Scientific Python SPEC 0
+  - Enhanced ruff configuration with numpy-specific and pandas-vet rules
+  - Improved mypy configuration with test-specific overrides
+  - pandas-stubs for better type checking
+  - Comprehensive test suite for track builders and validation (117 tests total)
 
 ### Changed
 - **BREAKING**: Dropped support for Python 3.9 (minimum version now 3.10)
@@ -27,15 +59,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - matplotlib >= 3.7 (was unpinned)
   - pandas >= 2.0 (was unpinned)
   - dask[array] >= 2023.5.0 (was unpinned, added array extra)
+  - networkx >= 3.2.1 (explicit minimum for compatibility)
 - Replaced deprecated pandas `.values` with `.to_numpy()` in utils module
 - Updated CI workflow to test Python 3.10, 3.11, 3.12, and 3.13
 - Replaced old test_package_build.yml with modern release.yml workflow
 - Fixed non-breaking hyphen character in error message
+- Enhanced `__init__.py` with comprehensive module docstring
+- Improved README with new features section and tutorial links
+- Interactive track builder uses two-step workflow in Jupyter (non-blocking)
+- Outlier detection uses robust statistics (median + MAD) instead of mean + std
 
 ### Fixed
 - Unused `fig` variables in plotting functions (now use `_` prefix)
 - Import sorting and organization per ruff standards
 - Regex pattern in pytest match statement (now uses raw string)
+- Dict literal style issues in track_builders.py (using `{}` instead of `dict()`)
+- Outlier detection false positives on uniform data
+- Interactive builder event loop blocking in Jupyter notebooks
 
 ### Infrastructure
 - New GitHub Actions workflow structure:
@@ -98,7 +138,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - HMM-based position classification
 - Visualization tools
 
-[Unreleased]: https://github.com/LorenFrankLab/track_linearization/compare/v2.3.2...HEAD
+[Unreleased]: https://github.com/LorenFrankLab/track_linearization/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/LorenFrankLab/track_linearization/compare/v2.3.2...v2.4.0
 [2.3.2]: https://github.com/LorenFrankLab/track_linearization/compare/v2.3.1...v2.3.2
 [2.3.1]: https://github.com/LorenFrankLab/track_linearization/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/LorenFrankLab/track_linearization/compare/v2.2.0...v2.3.0

src/track_linearization/core.py

@@ -187,7 +187,7 @@ def project_points_to_segment(
 
     np.clip(nx_param, 0.0, 1.0, out=nx_param)
 
-    return node1[np.newaxis, ...] + (
+    return node1[np.newaxis, ...] + (  # type: ignore[no-any-return]
         nx_param[:, :, np.newaxis] * segment_diff[np.newaxis, ...]
     )
 
@@ -209,7 +209,7 @@ def find_projected_point_distance(
     distances : np.ndarray, shape (n_time, n_segments)
         Euclidean distance from each point to its projection on each segment.
     """
-    return np.linalg.norm(
+    return np.linalg.norm(  # type: ignore[no-any-return]
         position[:, np.newaxis, :]
         - project_points_to_segment(track_segments, position),
         axis=2,
@@ -235,7 +235,7 @@ def find_nearest_segment(
         Index of the nearest track segment for each time point.
     """
     distance = find_projected_point_distance(track_segments, position)
-    return np.argmin(distance, axis=1)
+    return np.argmin(distance, axis=1)  # type: ignore[no-any-return]
 
 
 def euclidean_distance_change(position: np.ndarray) -> np.ndarray:
@@ -333,7 +333,7 @@ def route_distance(
 
     track_graph.remove_nodes_from(node_names)  # Clean up graph
 
-    return dist_matrix_slice
+    return dist_matrix_slice  # type: ignore[no-any-return]
 
 
 def batch(n_samples: int, batch_size: int = 1) -> Iterator[range]:
@@ -355,7 +355,7 @@ def batch(n_samples: int, batch_size: int = 1) -> Iterator[range]:
         yield range(ind, min(ind + batch_size, n_samples))
 
 
-@dask.delayed
+@dask.delayed  # type: ignore[misc]
 def batch_route_distance(
     track_graph: "Graph",
     projected_track_position_t: np.ndarray,
@@ -414,7 +414,7 @@ def route_distance_change(position: np.ndarray, track_graph: Graph) -> np.ndarra
     projected_track_position = project_points_to_segment(track_segments, position)
     n_segments = len(track_segments)
 
-    all_distances_results: list[np.ndarray | dask.delayed.Delayed] = [
+    all_distances_results: list[np.ndarray | Any] = [
         np.full((1, n_segments, n_segments), np.nan)
     ]
 
@@ -462,7 +462,7 @@ def calculate_position_likelihood(
     projected_position_distance = find_projected_point_distance(
         track_segments, position
     )
-    return np.exp(-0.5 * (projected_position_distance / sigma) ** 2) / (
+    return np.exp(-0.5 * (projected_position_distance / sigma) ** 2) / (  # type: ignore[no-any-return]
         np.sqrt(2 * np.pi) * sigma
     )
 
@@ -484,7 +484,7 @@ def normalize_to_probability(x: np.ndarray, axis: int = -1) -> np.ndarray:
         If a sum along the axis is 0, the original values in that slice will
         result in NaNs or Infs after division.
     """
-    return x / x.sum(axis=axis, keepdims=True)
+    return x / x.sum(axis=axis, keepdims=True)  # type: ignore[no-any-return]
 
 
 def calculate_empirical_state_transition(
@@ -607,7 +607,7 @@ def viterbi_no_numba(
 
 if NUMBA_AVAILABLE:
 
-    @numba.njit(cache=True)
+    @numba.njit(cache=True)  # type: ignore[misc]
     def viterbi(
         initial_conditions: np.ndarray,
         state_transition: np.ndarray,
@@ -980,21 +980,21 @@ def _calculate_linear_position(
     edge_spacing_list = _normalize_edge_spacing(edge_spacing, len(edge_order))
 
     counter = 0.0
-    start_node_linear_position = []
+    start_node_linear_position_list: list[float] = []
 
     for ind, edge in enumerate(edge_order):
-        start_node_linear_position.append(counter)
+        start_node_linear_position_list.append(counter)
 
         try:
             counter += track_graph.edges[edge]["distance"] + edge_spacing_list[ind]
         except IndexError:
             pass
 
-    start_node_linear_position = np.asarray(start_node_linear_position)
+    start_node_linear_position = np.asarray(start_node_linear_position_list)
 
     track_segment_id_to_start_node_linear_position = {
         track_graph.edges[e]["edge_id"]: snlp
-        for e, snlp in zip(edge_order, start_node_linear_position, strict=True)
+        for e, snlp in zip(edge_order, start_node_linear_position_list, strict=True)
     }
 
     start_node_linear_position = np.asarray(
@@ -1301,4 +1301,4 @@ def project_1d_to_2d(
 
     # propagate NaNs from the input
     coords[nan_mask] = np.nan
-    return coords
+    return coords  # type: ignore[no-any-return]

src/track_linearization/track_builders.py

@@ -5,7 +5,7 @@
 """
 
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 import matplotlib.pyplot as plt
 import networkx as nx
@@ -14,6 +14,18 @@
 from track_linearization.utils import make_track_graph
 
 
+class TrackBuilderState(TypedDict):
+    """State dictionary for interactive track builder."""
+
+    nodes: list[tuple[float, float]]
+    edges: list[tuple[int, int]]
+    mode: str
+    edge_start_node: int | None
+    edge_preview_line: Any | None
+    finished: bool
+    cancelled: bool
+
+
 def make_linear_track(
     length: float, start_pos: tuple[float, float] = (0, 0)
 ) -> nx.Graph:
@@ -584,7 +596,7 @@ def make_track_from_image_interactive(
         is_jupyter = False
 
     # State variables
-    state = {
+    state: TrackBuilderState = {
         "nodes": [],  # List of (x, y) pixel coordinates
         "edges": [],  # List of (i, j) node index pairs
         "edge_start_node": None,  # For edge creation
@@ -598,7 +610,7 @@ def make_track_from_image_interactive(
     fig = plt.figure(figsize=(12, 11))
 
     # Main image axes
-    ax = fig.add_axes([0.05, 0.15, 0.9, 0.8])
+    ax = fig.add_axes((0.05, 0.15, 0.9, 0.8))
     ax.imshow(img, origin="upper")
 
     # Title with mode indicator
@@ -629,18 +641,18 @@ def make_track_from_image_interactive(
     if not is_jupyter:
         from matplotlib.widgets import Button
 
-        ax_finish = fig.add_axes([0.7, 0.02, 0.1, 0.05])
+        ax_finish = fig.add_axes((0.7, 0.02, 0.1, 0.05))
         btn_finish = Button(ax_finish, "Finish", color="lightgreen", hovercolor="green")
 
-        ax_cancel = fig.add_axes([0.82, 0.02, 0.1, 0.05])
+        ax_cancel = fig.add_axes((0.82, 0.02, 0.1, 0.05))
         btn_cancel = Button(ax_cancel, "Cancel", color="lightcoral", hovercolor="red")
 
-        def on_finish_click(event):
+        def on_finish_click(event: Any) -> None:
             state["finished"] = True
             print("\n✓ Finished! (via button) Creating track graph...")
             plt.close(fig)
 
-        def on_cancel_click(event):
+        def on_cancel_click(event: Any) -> None:
             state["cancelled"] = True
             print("\n✗ Cancelled (via button).")
             plt.close(fig)
@@ -652,10 +664,10 @@ def on_cancel_click(event):
     node_scatter = ax.scatter(
         [], [], c="red", s=100, zorder=10, marker="o", edgecolors="white", linewidths=2
     )
-    node_labels = []
-    edge_lines = []
+    node_labels: list[Any] = []
+    edge_lines: list[Any] = []
 
-    def update_mode_display():
+    def update_mode_display() -> None:
         """Update mode indicator text and color."""
         if state["mode"] == "ADD":
             mode_text.set_text("Mode: ADD NODE (Click anywhere)")
@@ -673,7 +685,7 @@ def update_mode_display():
                 {"boxstyle": "round,pad=0.5", "facecolor": "salmon", "alpha": 0.7}
             )
 
-    def update_display():
+    def update_display() -> None:
         """Redraw nodes and edges."""
         # Update nodes
         if state["nodes"]:
@@ -731,7 +743,7 @@ def update_display():
         update_mode_display()
         fig.canvas.draw_idle()
 
-    def find_closest_node(x, y, max_distance=25):
+    def find_closest_node(x: float, y: float, max_distance: float = 25) -> int | None:
         """Find closest node to coordinates within max_distance pixels."""
         if not state["nodes"]:
             return None
@@ -743,7 +755,7 @@ def find_closest_node(x, y, max_distance=25):
             return closest_idx
         return None
 
-    def on_press(event):
+    def on_press(event: Any) -> None:
         """Handle mouse press."""
         if event.inaxes != ax:
             return
@@ -783,10 +795,10 @@ def on_press(event):
                     for i, j in state["edges"]
                     if i != closest and j != closest
                 ]
-                state["edges"] = [tuple(sorted([i, j])) for i, j in state["edges"]]
+                state["edges"] = [(min(i, j), max(i, j)) for i, j in state["edges"]]
                 update_display()
 
-    def on_motion(event):
+    def on_motion(event: Any) -> None:
         """Handle mouse motion for edge preview."""
         # Note: Don't print debug here - too spammy during mouse movement
         if event.inaxes != ax or state["finished"] or state["cancelled"]:
@@ -809,7 +821,7 @@ def on_motion(event):
         state["edge_preview_line"] = line
         fig.canvas.draw_idle()
 
-    def on_release(event):
+    def on_release(event: Any) -> None:
         """Handle mouse release."""
         if event.inaxes != ax:
             return
@@ -834,7 +846,7 @@ def on_release(event):
         if closest is not None and closest != state["edge_start_node"]:
             # Create edge
             node1, node2 = state["edge_start_node"], closest
-            edge = tuple(sorted([node1, node2]))
+            edge = (min(node1, node2), max(node1, node2))
             if edge not in state["edges"]:
                 state["edges"].append(edge)
                 print(f"✓ Created edge: {node1} ↔ {node2}")
@@ -848,7 +860,7 @@ def on_release(event):
             state["edge_preview_line"] = None
         update_display()
 
-    def on_key(event):
+    def on_key(event: Any) -> None:
         """Handle key presses."""
 
         if event.key == "f":  # Finish
@@ -894,7 +906,7 @@ def on_key(event):
                 print(f"↶ Deleted last edge {edge}")
                 update_display()
 
-    def print_instructions():
+    def print_instructions() -> None:
         """Print usage instructions."""
         print("\n" + "=" * 70)
         print("INTERACTIVE TRACK BUILDER - CONTROLS")
@@ -960,7 +972,7 @@ def print_instructions():
         # JUPYTER MODE: Non-blocking approach
         # The widget is already interactive, just display it and return immediately
         # Store state in figure so user can retrieve it later
-        fig._track_builder_state = state
+        fig._track_builder_state = state  # type: ignore[attr-defined]
 
         plt.show()
         print()
@@ -1017,7 +1029,7 @@ def print_instructions():
     return _build_track_from_state(state, scale)
 
 
-def _build_track_from_state(state, scale=1.0):
+def _build_track_from_state(state: TrackBuilderState | dict[str, Any], scale: float = 1.0) -> dict[str, Any]:
     """
     Helper function to build track graph from interactive builder state.