canns 0.13.1__py3-none-any.whl → 0.14.0__py3-none-any.whl

canns/analyzer/data/cell_classification/visualization/grid_plots.py

@@ -0,0 +1,292 @@
+"""Grid cell visualization utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from matplotlib import patches
+from matplotlib import pyplot as plt
+
+from canns.analyzer.visualization.core.config import PlotConfig, PlotConfigs, finalize_figure
+
+
+def _ensure_plot_config(
+    config: PlotConfig | None,
+    factory,
+    *,
+    kwargs: dict[str, Any] | None = None,
+    **defaults: Any,
+) -> PlotConfig:
+    if config is None:
+        defaults.update({"kwargs": kwargs or {}})
+        return factory(**defaults)
+
+    if kwargs:
+        config_kwargs = config.kwargs or {}
+        config_kwargs.update(kwargs)
+        config.kwargs = config_kwargs
+    return config
+
+
+def plot_autocorrelogram(
+    autocorr: np.ndarray,
+    config: PlotConfig | None = None,
+    *,
+    gridness_score: float | None = None,
+    center_radius: float | None = None,
+    peak_locations: np.ndarray | None = None,
+    title: str = "Spatial Autocorrelation",
+    xlabel: str = "X Lag (bins)",
+    ylabel: str = "Y Lag (bins)",
+    figsize: tuple[int, int] = (6, 6),
+    save_path: str | None = None,
+    show: bool = True,
+    ax: plt.Axes | None = None,
+    **kwargs: Any,
+) -> tuple[plt.Figure, plt.Axes]:
+    """Plot 2D autocorrelogram with optional annotations."""
+    config = _ensure_plot_config(
+        config,
+        PlotConfigs.grid_autocorrelation,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+        kwargs=kwargs,
+    )
+
+    created_fig = False
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=config.figsize)
+        created_fig = True
+    else:
+        fig = ax.figure
+
+    # Plot autocorrelogram
+    plot_kwargs = config.to_matplotlib_kwargs()
+    plot_kwargs.setdefault("origin", "lower")
+    plot_kwargs.setdefault("interpolation", "bilinear")
+    im = ax.imshow(autocorr, **plot_kwargs)
+    fig.colorbar(im, ax=ax, label="Correlation")
+
+    # Add center circle if radius provided
+    if center_radius is not None:
+        center = np.array(autocorr.shape) / 2
+        circle = patches.Circle(
+            (center[1], center[0]),
+            center_radius,
+            fill=False,
+            edgecolor="red",
+            linewidth=2,
+            linestyle="--",
+            label="Center field",
+        )
+        ax.add_patch(circle)
+
+    # Mark peak locations if provided
+    if peak_locations is not None:
+        ax.plot(
+            peak_locations[:, 0],
+            peak_locations[:, 1],
+            "r+",
+            markersize=10,
+            markeredgewidth=2,
+            label="Grid peaks",
+        )
+
+    # Add gridness score to title
+    title_text = config.title
+    if gridness_score is not None:
+        title_text = f"{config.title} (Gridness: {gridness_score:.3f})"
+
+    ax.set_title(title_text)
+    ax.set_xlabel(config.xlabel)
+    ax.set_ylabel(config.ylabel)
+
+    if center_radius is not None or peak_locations is not None:
+        ax.legend(loc="upper right")
+
+    if created_fig:
+        fig.tight_layout()
+        finalize_figure(fig, config, rasterize_artists=[im] if config.rasterized else None)
+
+    return fig, ax
+
+
+def plot_gridness_analysis(
+    rate_map: np.ndarray,
+    autocorr: np.ndarray,
+    result,
+    config: PlotConfig | None = None,
+    *,
+    title: str = "Grid Cell Analysis",
+    figsize: tuple[int, int] = (15, 5),
+    save_path: str | None = None,
+    show: bool = True,
+) -> plt.Figure:
+    """Comprehensive grid analysis plot with rate map, autocorr, and statistics."""
+    config = _ensure_plot_config(
+        config,
+        PlotConfig.for_static_plot,
+        title=title,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+        kwargs={},
+    )
+
+    fig, axes = plt.subplots(1, 3, figsize=config.figsize)
+
+    # Plot 1: Rate map
+    im1 = axes[0].imshow(rate_map, cmap="hot", origin="lower")
+    axes[0].set_title("Firing Rate Map")
+    axes[0].set_xlabel("X (bins)")
+    axes[0].set_ylabel("Y (bins)")
+    plt.colorbar(im1, ax=axes[0], label="Rate (Hz)")
+
+    # Plot 2: Autocorrelogram with annotations
+    plot_autocorrelogram(
+        autocorr,
+        gridness_score=result.score,
+        center_radius=result.center_radius,
+        peak_locations=result.peak_locations,
+        title="Autocorrelogram",
+        ax=axes[1],
+    )
+
+    # Plot 3: Grid statistics
+    axes[2].axis("off")
+    stats_text = f"""
+Grid Cell Analysis
+
+Gridness Score: {result.score:.3f}
+Center Radius: {result.center_radius:.1f} bins
+Optimal Radius: {result.optimal_radius:.1f} bins
+
+Grid Spacing (bins):
+  {result.spacing[0]:.2f}
+  {result.spacing[1]:.2f}
+  {result.spacing[2]:.2f}
+
+Grid Orientation (°):
+  {result.orientation[0]:.1f}
+  {result.orientation[1]:.1f}
+  {result.orientation[2]:.1f}
+
+Ellipse Parameters:
+  Center: ({result.ellipse[0]:.1f}, {result.ellipse[1]:.1f})
+  Radii: ({result.ellipse[2]:.1f}, {result.ellipse[3]:.1f})
+  Angle: {result.ellipse_theta_deg:.1f}°
+    """
+    axes[2].text(0.1, 0.5, stats_text, fontsize=10, verticalalignment="center", family="monospace")
+    axes[2].set_title("Grid Statistics")
+
+    fig.suptitle(config.title, fontsize=14, fontweight="bold")
+    fig.tight_layout()
+    finalize_figure(fig, config)
+    return fig
+
+
+def plot_rate_map(
+    rate_map: np.ndarray,
+    config: PlotConfig | None = None,
+    *,
+    title: str = "Firing Field (Rate Map)",
+    xlabel: str = "X Position (bins)",
+    ylabel: str = "Y Position (bins)",
+    figsize: tuple[int, int] = (6, 6),
+    colorbar: bool = True,
+    save_path: str | None = None,
+    show: bool = True,
+    ax: plt.Axes | None = None,
+    **kwargs: Any,
+) -> tuple[plt.Figure, plt.Axes]:
+    """Plot 2D spatial firing rate map."""
+    config = _ensure_plot_config(
+        config,
+        PlotConfigs.firing_field_heatmap,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+        kwargs=kwargs,
+    )
+
+    created_fig = False
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=config.figsize)
+        created_fig = True
+    else:
+        fig = ax.figure
+
+    plot_kwargs = config.to_matplotlib_kwargs()
+    plot_kwargs.setdefault("origin", "lower")
+    plot_kwargs.setdefault("interpolation", "bilinear")
+    im = ax.imshow(rate_map, **plot_kwargs)
+
+    if colorbar:
+        fig.colorbar(im, ax=ax, label="Firing Rate (Hz)")
+
+    ax.set_title(config.title)
+    ax.set_xlabel(config.xlabel)
+    ax.set_ylabel(config.ylabel)
+
+    if created_fig:
+        fig.tight_layout()
+        finalize_figure(fig, config, rasterize_artists=[im] if config.rasterized else None)
+
+    return fig, ax
+
+
+def plot_grid_score_histogram(
+    scores: np.ndarray,
+    config: PlotConfig | None = None,
+    *,
+    bins: int = 30,
+    title: str = "Grid Score Distribution",
+    xlabel: str = "Grid Score",
+    ylabel: str = "Count",
+    figsize: tuple[int, int] = (6, 4),
+    save_path: str | None = None,
+    show: bool = True,
+    ax: plt.Axes | None = None,
+    **kwargs: Any,
+) -> tuple[plt.Figure, plt.Axes]:
+    """Plot histogram of gridness scores."""
+    config = _ensure_plot_config(
+        config,
+        PlotConfig.for_static_plot,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+        kwargs=kwargs,
+    )
+
+    scores = np.asarray(scores, dtype=float)
+    scores = scores[np.isfinite(scores)]
+
+    created_fig = False
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=config.figsize)
+        created_fig = True
+    else:
+        fig = ax.figure
+
+    ax.hist(scores, bins=bins, **config.to_matplotlib_kwargs())
+    ax.set_title(config.title)
+    ax.set_xlabel(config.xlabel)
+    ax.set_ylabel(config.ylabel)
+
+    if created_fig:
+        fig.tight_layout()
+        finalize_figure(fig, config)
+
+    return fig, ax

canns/analyzer/data/cell_classification/visualization/hd_plots.py

@@ -0,0 +1,200 @@
+"""
+Head Direction Cell Visualization
+
+Plotting functions for head direction cell analysis.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def plot_polar_tuning(
+    angles: np.ndarray,
+    rates: np.ndarray,
+    preferred_direction: float | None = None,
+    mvl: float | None = None,
+    title: str = "Directional Tuning",
+    ax: plt.Axes | None = None,
+) -> plt.Axes:
+    """
+    Plot directional tuning curve in polar coordinates.
+
+    Parameters
+    ----------
+    angles : np.ndarray
+        Angular bins in radians
+    rates : np.ndarray
+        Firing rates for each bin
+    preferred_direction : float, optional
+        Preferred direction to mark (radians)
+    mvl : float, optional
+        Mean Vector Length to display
+    title : str, optional
+        Plot title
+    ax : plt.Axes, optional
+        Polar axes to plot on. If None, creates new figure.
+
+    Returns
+    -------
+    ax : plt.Axes
+        The axes object
+    """
+    if ax is None:
+        fig = plt.figure(figsize=(6, 6))
+        ax = fig.add_subplot(111, projection="polar")
+
+    # Plot tuning curve
+    ax.plot(angles, rates, "b-", linewidth=2, label="Tuning curve")
+    ax.fill_between(angles, 0, rates, alpha=0.3)
+
+    # Mark preferred direction
+    if preferred_direction is not None:
+        max_rate = np.max(rates)
+        ax.plot(
+            [preferred_direction, preferred_direction],
+            [0, max_rate],
+            "r--",
+            linewidth=2,
+            label=f"Preferred: {np.rad2deg(preferred_direction):.1f}°",
+        )
+
+    # Add MVL to title
+    if mvl is not None:
+        title += f" (MVL: {mvl:.3f})"
+
+    ax.set_title(title, pad=20)
+    ax.set_theta_zero_location("E")  # 0° to the right
+    ax.set_theta_direction(1)  # Counterclockwise
+    ax.legend(loc="upper right", bbox_to_anchor=(1.3, 1.1))
+
+    return ax
+
+
+def plot_temporal_autocorr(
+    lags: np.ndarray,
+    acorr: np.ndarray,
+    title: str = "Temporal Autocorrelation",
+    ax: plt.Axes | None = None,
+) -> plt.Axes:
+    """
+    Plot temporal autocorrelation as bar plot.
+
+    Parameters
+    ----------
+    lags : np.ndarray
+        Time lags (ms or bins)
+    acorr : np.ndarray
+        Autocorrelation values
+    title : str, optional
+        Plot title
+    ax : plt.Axes, optional
+        Axes to plot on
+
+    Returns
+    -------
+    ax : plt.Axes
+        The axes object
+    """
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=(8, 4))
+
+    ax.bar(lags, acorr, width=np.diff(lags)[0] * 0.8, color="blue", alpha=0.7)
+    ax.axhline(y=0, color="k", linestyle="--", linewidth=0.5)
+
+    ax.set_title(title)
+    ax.set_xlabel("Time Lag (ms)")
+    ax.set_ylabel("Autocorrelation")
+    ax.grid(True, alpha=0.3)
+
+    return ax
+
+
+def plot_hd_analysis(
+    result,
+    time_stamps: np.ndarray | None = None,
+    head_directions: np.ndarray | None = None,
+    spike_times: np.ndarray | None = None,
+    figsize: tuple = (15, 5),
+) -> plt.Figure:
+    """
+    Comprehensive head direction analysis plot.
+
+    Parameters
+    ----------
+    result : HDCellResult
+        Results from HeadDirectionAnalyzer
+    time_stamps : np.ndarray, optional
+        Time stamps for plotting trajectory
+    head_directions : np.ndarray, optional
+        Head direction time series
+    spike_times : np.ndarray, optional
+        Spike times
+    figsize : tuple, optional
+        Figure size
+
+    Returns
+    -------
+    fig : plt.Figure
+        The figure object
+    """
+    fig = plt.figure(figsize=figsize)
+
+    # Plot 1: Polar tuning curve
+    ax1 = fig.add_subplot(131, projection="polar")
+    bin_centers, firing_rates = result.tuning_curve
+    plot_polar_tuning(
+        bin_centers,
+        firing_rates,
+        preferred_direction=result.preferred_direction,
+        mvl=result.mvl_hd,
+        ax=ax1,
+    )
+
+    # Plot 2: Linear tuning curve
+    ax2 = fig.add_subplot(132)
+    ax2.plot(np.rad2deg(bin_centers), firing_rates, "b-", linewidth=2)
+    ax2.fill_between(np.rad2deg(bin_centers), 0, firing_rates, alpha=0.3)
+    if result.preferred_direction is not None:
+        ax2.axvline(
+            np.rad2deg(result.preferred_direction),
+            color="r",
+            linestyle="--",
+            linewidth=2,
+            label="Preferred direction",
+        )
+    ax2.set_xlabel("Head Direction (°)")
+    ax2.set_ylabel("Firing Rate (Hz)")
+    ax2.set_title("Linear Tuning Curve")
+    ax2.grid(True, alpha=0.3)
+    ax2.legend()
+
+    # Plot 3: Statistics and trajectory (if provided)
+    ax3 = fig.add_subplot(133)
+    if time_stamps is not None and head_directions is not None:
+        ax3.plot(time_stamps, np.rad2deg(head_directions), "k-", linewidth=0.5, alpha=0.5)
+        if spike_times is not None:
+            spike_hd = np.interp(spike_times, time_stamps, head_directions)
+            ax3.plot(spike_times, np.rad2deg(spike_hd), "r.", markersize=3)
+        ax3.set_xlabel("Time (s)")
+        ax3.set_ylabel("Head Direction (°)")
+        ax3.set_title("HD Trajectory with Spikes")
+        ax3.set_ylim([-180, 180])
+    else:
+        ax3.axis("off")
+        stats_text = f"""
+Head Direction Cell Analysis
+
+Classification: {"HD Cell" if result.is_hd else "Non-HD Cell"}
+MVL (HD): {result.mvl_hd:.3f}
+{"MVL (Theta): " + f"{result.mvl_theta:.3f}" if result.mvl_theta else ""}
+Preferred Direction: {np.rad2deg(result.preferred_direction):.1f}°
+Rayleigh p-value: {result.rayleigh_p:.6f}
+
+Peak Firing Rate: {np.max(firing_rates):.2f} Hz
+Mean Firing Rate: {np.mean(firing_rates):.2f} Hz
+        """
+        ax3.text(0.1, 0.5, stats_text, fontsize=10, verticalalignment="center", family="monospace")
+        ax3.set_title("HD Statistics")
+
+    plt.tight_layout()
+    return fig

canns/analyzer/metrics/__init__.py

@@ -1,8 +1,9 @@
 """Model metrics computation utilities."""
 
-from . import spatial_metrics, utils
+from . import spatial_metrics, systematic_ratemap, utils
 
 __all__ = [
     "spatial_metrics",
+    "systematic_ratemap",
     "utils",
 ]

canns/analyzer/visualization/core/config.py

@@ -280,7 +280,7 @@ class PlotConfigs:
         return PlotConfig.for_static_plot(**defaults)
 
     @staticmethod
-    def cohospace_trajectory(**kwargs: Any) -> PlotConfig:
+    def cohospace_trajectory_2d(**kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {
             "title": "CohoSpace trajectory",
             "xlabel": "theta1 (deg)",
@@ -291,7 +291,18 @@ class PlotConfigs:
         return PlotConfig.for_static_plot(**defaults)
 
     @staticmethod
-    def cohospace_neuron(**kwargs: Any) -> PlotConfig:
+    def cohospace_trajectory_1d(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "CohoSpace trajectory (1D)",
+            "xlabel": "cos(theta)",
+            "ylabel": "sin(theta)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def cohospace_neuron_2d(**kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {
             "title": "Neuron activity on coho-space",
             "xlabel": "Theta 1 (deg)",
@@ -302,7 +313,18 @@ class PlotConfigs:
         return PlotConfig.for_static_plot(**defaults)
 
     @staticmethod
-    def cohospace_population(**kwargs: Any) -> PlotConfig:
+    def cohospace_neuron_1d(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Neuron activity on coho-space (1D)",
+            "xlabel": "cos(theta)",
+            "ylabel": "sin(theta)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
+    @staticmethod
+    def cohospace_population_2d(**kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {
             "title": "Population activity on coho-space",
             "xlabel": "Theta 1 (deg)",
@@ -312,6 +334,17 @@ class PlotConfigs:
         defaults.update(kwargs)
         return PlotConfig.for_static_plot(**defaults)
 
+    @staticmethod
+    def cohospace_population_1d(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Population activity on coho-space (1D)",
+            "xlabel": "cos(theta)",
+            "ylabel": "sin(theta)",
+            "figsize": (6, 6),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
     @staticmethod
     def fr_heatmap(**kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {
@@ -337,7 +370,7 @@ class PlotConfigs:
         return PlotConfig.for_static_plot(**defaults)
 
     @staticmethod
-    def path_compare(**kwargs: Any) -> PlotConfig:
+    def path_compare_2d(**kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {
             "title": "Path Compare",
             "figsize": (12, 5),
@@ -345,6 +378,15 @@ class PlotConfigs:
         defaults.update(kwargs)
         return PlotConfig.for_static_plot(**defaults)
 
+    @staticmethod
+    def path_compare_1d(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Path Compare (1D)",
+            "figsize": (12, 5),
+        }
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
     @staticmethod
     def raster_plot(mode: str = "block", **kwargs: Any) -> PlotConfig:
         defaults: dict[str, Any] = {

canns/data/__init__.py

@@ -16,11 +16,13 @@ from .datasets import (
     get_data_dir,
     get_dataset_path,
     get_huggingface_upload_guide,
+    get_left_right_data_session,
+    get_left_right_npz,
     list_datasets,
     load,
     quick_setup,
 )
-from .loaders import load_grid_data, load_roi_data
+from .loaders import load_grid_data, load_left_right_npz, load_roi_data
 
 __all__ = [
     # Dataset registry and management
@@ -31,6 +33,8 @@ __all__ = [
     "list_datasets",
     "download_dataset",
     "get_dataset_path",
+    "get_left_right_data_session",
+    "get_left_right_npz",
     "quick_setup",
     "get_huggingface_upload_guide",
     # Generic loading
@@ -38,4 +42,5 @@ __all__ = [
     # Specialized loaders
     "load_roi_data",
     "load_grid_data",
+    "load_left_right_npz",
 ]