canns 0.14.3__py3-none-any.whl → 0.15.1__py3-none-any.whl

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

@@ -0,0 +1,241 @@
+"""BTN visualization utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from matplotlib import pyplot as plt
+from scipy.ndimage import gaussian_filter1d
+
+from canns.analyzer.data.asa.utils import _ensure_plot_config
+from canns.analyzer.visualization.core.config import PlotConfig, finalize_figure
+
+_DEFAULT_BTN_COLORS = {
+    "B": "#1f77b4",
+    "T": "#000000",
+    "N": "#2ca02c",
+}
+
+
+def _canonical_label(label: str) -> str:
+    lab = label.strip().lower()
+    if lab in ("b", "bursty"):
+        return "B"
+    if lab in ("t", "theta", "theta-modulated", "theta_modulated", "theta modulated"):
+        return "T"
+    if lab in ("n", "nonbursty", "non-bursty", "non_bursty"):
+        return "N"
+    return label
+
+
+def _cluster_order(labels: np.ndarray, mapping: dict[int, str] | None) -> list[int]:
+    cids = [int(c) for c in np.unique(labels)]
+    if mapping is None:
+        return sorted(cids)
+
+    def _key(cid: int) -> tuple[int, str]:
+        lab = _canonical_label(mapping.get(int(cid), str(cid)))
+        order = {"B": 0, "T": 1, "N": 2}.get(lab, 999)
+        return (order, str(lab))
+
+    return sorted(cids, key=_key)
+
+
+def _label_color(
+    label: str,
+    colors: dict[str, str] | None,
+    fallback_idx: int,
+) -> str:
+    if colors and label in colors:
+        return colors[label]
+    if label in _DEFAULT_BTN_COLORS:
+        return _DEFAULT_BTN_COLORS[label]
+    cmap = plt.get_cmap("tab10")
+    return cmap(fallback_idx % 10)
+
+
+def _normalize_rows(acorr: np.ndarray, mode: str | None) -> np.ndarray:
+    if mode is None or mode == "none":
+        return acorr
+    if mode == "probability":
+        denom = acorr.sum(axis=1, keepdims=True)
+    elif mode == "peak":
+        denom = acorr.max(axis=1, keepdims=True)
+    elif mode == "first":
+        denom = acorr[:, :1]
+    else:
+        raise ValueError(f"Unknown normalize mode: {mode!r}")
+    denom = np.where(denom == 0, 1.0, denom)
+    return acorr / denom
+
+
+def plot_btn_distance_matrix(
+    *,
+    dist: np.ndarray | None = None,
+    labels: np.ndarray | None = None,
+    mapping: dict[int, str] | None = None,
+    sort_by_label: bool = True,
+    title: str = "BTN distance matrix",
+    cmap: str = "afmhot",
+    figsize: tuple[int, int] = (5, 5),
+    save_path: str | None = None,
+    show: bool = True,
+    ax: plt.Axes | None = None,
+    config: PlotConfig | None = None,
+) -> tuple[plt.Figure, plt.Axes, np.ndarray]:
+    """Plot a distance matrix heatmap sorted by BTN cluster labels."""
+    if dist is None or labels is None:
+        raise ValueError("dist and labels are required.")
+
+    labels = np.asarray(labels).astype(int)
+
+    if sort_by_label:
+        cids = _cluster_order(labels, mapping)
+        order = np.concatenate([np.where(labels == c)[0] for c in cids])
+    else:
+        order = np.arange(len(labels))
+
+    dist_sorted = dist[np.ix_(order, order)]
+
+    config = _ensure_plot_config(
+        config,
+        PlotConfig.for_static_plot,
+        title=title,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+        kwargs={},
+    )
+
+    created_fig = False
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=config.figsize)
+        created_fig = True
+    else:
+        fig = ax.figure
+
+    im = ax.imshow(dist_sorted, cmap=cmap, origin="lower", interpolation="nearest")
+    fig.colorbar(im, ax=ax, label="Cosine distance")
+    ax.set_title(config.title)
+    ax.set_xlabel("Neuron")
+    ax.set_ylabel("Neuron")
+
+    if sort_by_label:
+        sizes = [np.sum(labels == c) for c in cids]
+        boundaries = np.cumsum(sizes)[:-1]
+        for b in boundaries:
+            ax.axhline(b - 0.5, color="w", linewidth=0.6, alpha=0.7)
+            ax.axvline(b - 0.5, color="w", linewidth=0.6, alpha=0.7)
+
+    if created_fig:
+        fig.tight_layout()
+        finalize_figure(fig, config, rasterize_artists=[im] if config.rasterized else None)
+
+    return fig, ax, order
+
+
+def plot_btn_autocorr_summary(
+    *,
+    acorr: np.ndarray | None = None,
+    labels: np.ndarray | None = None,
+    bin_times: np.ndarray | None = None,
+    res: float | None = None,
+    mapping: dict[int, str] | None = None,
+    colors: dict[str, str] | None = None,
+    normalize: str | None = "probability",
+    smooth_sigma: float | None = None,
+    long_max_ms: float | None = 200.0,
+    short_max_ms: float | None = None,
+    title: str = "BTN temporal autocorr",
+    figsize: tuple[int, int] = (8, 3),
+    save_path: str | None = None,
+    show: bool = True,
+    config: PlotConfig | None = None,
+) -> plt.Figure:
+    """Plot class-averaged ISI autocorr curves (mean +/- SEM)."""
+    if acorr is None or labels is None:
+        raise ValueError("acorr and labels are required.")
+
+    labels = np.asarray(labels).astype(int)
+    acorr = np.asarray(acorr)
+    acorr_plot = _normalize_rows(acorr.astype(float, copy=False), normalize)
+    if smooth_sigma is not None:
+        acorr_plot = gaussian_filter1d(acorr_plot, sigma=float(smooth_sigma), axis=1)
+
+    if bin_times is not None:
+        bin_times = np.asarray(bin_times)
+        x = 0.5 * (bin_times[:-1] + bin_times[1:])
+    elif res is not None:
+        x = np.arange(acorr.shape[1]) * float(res)
+    else:
+        raise ValueError("Provide bin_times or res to define lag axis.")
+
+    x_ms = x * 1000.0
+
+    cids = _cluster_order(labels, mapping)
+    label_strings = []
+    for c in cids:
+        if mapping is not None:
+            label_strings.append(_canonical_label(mapping.get(int(c), str(c))))
+        else:
+            label_strings.append(str(c))
+
+    show_short = short_max_ms is not None
+    ncols = 2 if show_short else 1
+
+    config = _ensure_plot_config(
+        config,
+        PlotConfig.for_static_plot,
+        title=title,
+        figsize=figsize if ncols == 1 else (figsize[0] * 1.6, figsize[1]),
+        save_path=save_path,
+        show=show,
+        kwargs={},
+    )
+
+    fig, axes = plt.subplots(1, ncols, figsize=config.figsize)
+    if ncols == 1:
+        axes = [axes]
+
+    def _plot_panel(ax: plt.Axes, max_ms: float | None, panel_title: str):
+        if max_ms is None:
+            mask = np.ones_like(x_ms, dtype=bool)
+        else:
+            mask = x_ms <= max_ms
+
+        for idx, (cid, label_str) in enumerate(zip(cids, label_strings, strict=False)):
+            rows = acorr_plot[labels == cid]
+            if rows.size == 0:
+                continue
+            mean = rows.mean(axis=0)
+            sem = rows.std(axis=0) / np.sqrt(rows.shape[0])
+            color = _label_color(label_str, colors, idx)
+            ax.plot(x_ms[mask], mean[mask], color=color, lw=2, label=label_str)
+            ax.fill_between(
+                x_ms[mask],
+                (mean - sem)[mask],
+                (mean + sem)[mask],
+                color=color,
+                alpha=0.25,
+                linewidth=0,
+            )
+
+        ax.set_xlabel("Lag (ms)")
+        ax.set_title(panel_title)
+        ax.grid(False)
+
+    _plot_panel(axes[0], long_max_ms, "Long lag")
+    ylabel = "Probability" if normalize == "probability" else "Autocorr (norm)"
+    axes[0].set_ylabel(ylabel)
+
+    if show_short:
+        _plot_panel(axes[1], float(short_max_ms), "Short lag")
+
+    for ax in axes:
+        ax.legend(frameon=False)
+
+    fig.suptitle(config.title)
+    fig.tight_layout()
+    finalize_figure(fig, config)
+    return fig

canns/analyzer/visualization/__init__.py

@@ -34,6 +34,7 @@ from .theta_sweep_plots import (
     create_theta_sweep_grid_cell_animation,
     create_theta_sweep_place_cell_animation,
     plot_grid_cell_manifold,
+    plot_internal_position_trajectory,
     plot_population_activity_with_theta,
 )
 from .tuning_plots import tuning_curve
@@ -70,5 +71,6 @@ __all__ = [
     "create_theta_sweep_grid_cell_animation",
     "create_theta_sweep_place_cell_animation",
     "plot_grid_cell_manifold",
+    "plot_internal_position_trajectory",
     "plot_population_activity_with_theta",
 ]

canns/analyzer/visualization/core/config.py

@@ -469,6 +469,26 @@ class PlotConfigs:
         defaults.update(kwargs)
         return PlotConfig.for_static_plot(**defaults)
 
+    @staticmethod
+    def internal_position_trajectory_static(**kwargs: Any) -> PlotConfig:
+        defaults: dict[str, Any] = {
+            "title": "Internal Position vs. Real Trajectory",
+            "figsize": (6, 4),
+        }
+        plot_kwargs: dict[str, Any] = {
+            "cmap": "cool",
+            "add_colorbar": True,
+            "colorbar": {"label": "Max GC activity"},
+            "trajectory_color": "black",
+            "trajectory_linewidth": 1.0,
+            "scatter_size": 4,
+            "scatter_alpha": 0.9,
+        }
+        plot_kwargs.update(kwargs.pop("kwargs", {}))
+        defaults["kwargs"] = plot_kwargs
+        defaults.update(kwargs)
+        return PlotConfig.for_static_plot(**defaults)
+
     @staticmethod
     def direction_cell_polar(**kwargs: Any) -> PlotConfig:
         """Configuration for direction cell polar plot visualization.

canns/analyzer/visualization/theta_sweep_plots.py

@@ -760,6 +760,148 @@ def plot_grid_cell_manifold(
         raise e
 
 
+def plot_internal_position_trajectory(
+    internal_position: np.ndarray,
+    position: np.ndarray,
+    max_activity: np.ndarray | None = None,
+    env_size: float | tuple[float, float] | tuple[float, float, float, float] | None = None,
+    config: PlotConfig | None = None,
+    ax: plt.Axes | None = None,
+    # Backward compatibility parameters
+    title: str = "Internal Position (GC bump) vs. Real Trajectory",
+    figsize: tuple[int, int] = (6, 4),
+    cmap: str = "cool",
+    show: bool = True,
+    save_path: str | None = None,
+    **kwargs,
+) -> tuple[plt.Figure, plt.Axes]:
+    """Plot internal position (GC bump) against the real trajectory.
+
+    Args:
+        internal_position: Internal decoded positions ``(T, 2)``.
+        position: Real positions ``(T, 2)``.
+        max_activity: Optional per-time max activity to color the internal position.
+        env_size: Environment size. If float, uses ``[0, env_size]`` for both axes.
+            If a tuple of 2, treats as ``(width, height)``. If a tuple of 4, treats as
+            ``(xmin, xmax, ymin, ymax)``.
+        config: PlotConfig object for unified configuration.
+        ax: Optional axis to draw on instead of creating a new figure.
+        **kwargs: Additional parameters for backward compatibility.
+
+    Returns:
+        tuple: ``(figure, axis)`` objects.
+    """
+    if internal_position.ndim != 2 or internal_position.shape[1] != 2:
+        raise ValueError(
+            f"internal_position must be (T, 2), got shape {internal_position.shape}"
+        )
+    if position.ndim != 2 or position.shape[1] != 2:
+        raise ValueError(f"position must be (T, 2), got shape {position.shape}")
+    if internal_position.shape[0] != position.shape[0]:
+        raise ValueError(
+            "internal_position and position must have the same length: "
+            f"{internal_position.shape[0]} != {position.shape[0]}"
+        )
+    if max_activity is not None and max_activity.shape[0] != internal_position.shape[0]:
+        raise ValueError(
+            "max_activity must have same length as internal_position: "
+            f"{max_activity.shape[0]} != {internal_position.shape[0]}"
+        )
+
+    if config is None:
+        config = PlotConfig(
+            title=title,
+            figsize=figsize,
+            show=show,
+            save_path=save_path,
+            kwargs={"cmap": cmap, **kwargs},
+        )
+
+    plot_kwargs = config.to_matplotlib_kwargs()
+    trajectory_color = plot_kwargs.pop("trajectory_color", "black")
+    trajectory_linewidth = plot_kwargs.pop("trajectory_linewidth", 1.0)
+    scatter_size = plot_kwargs.pop("scatter_size", 4)
+    scatter_alpha = plot_kwargs.pop("scatter_alpha", 0.9)
+    add_colorbar = bool(plot_kwargs.pop("add_colorbar", True))
+    colorbar_options = plot_kwargs.pop("colorbar", {}) if add_colorbar else {}
+    if "cmap" not in plot_kwargs:
+        plot_kwargs["cmap"] = "cool"
+
+    if max_activity is None:
+        add_colorbar = False
+
+    axis_provided = ax is not None
+    if not axis_provided:
+        fig, ax = plt.subplots(figsize=config.figsize)
+    else:
+        fig = ax.figure
+
+    try:
+        scatter = ax.scatter(
+            internal_position[:, 0],
+            internal_position[:, 1],
+            c=max_activity,
+            s=scatter_size,
+            alpha=scatter_alpha,
+            **plot_kwargs,
+        )
+        ax.plot(position[:, 0], position[:, 1], color=trajectory_color, lw=trajectory_linewidth)
+
+        ax.set_aspect("equal", adjustable="box")
+        if config.title:
+            ax.set_title(config.title, fontsize=14, fontweight="bold")
+
+        if env_size is not None:
+            if isinstance(env_size, (tuple, list, np.ndarray)):
+                if len(env_size) == 2:
+                    ax.set_xlim(0, env_size[0])
+                    ax.set_ylim(0, env_size[1])
+                elif len(env_size) == 4:
+                    ax.set_xlim(env_size[0], env_size[1])
+                    ax.set_ylim(env_size[2], env_size[3])
+                else:
+                    raise ValueError("env_size tuple must be length 2 or 4.")
+            else:
+                ax.set_xlim(0, env_size)
+                ax.set_ylim(0, env_size)
+
+        sns.despine(ax=ax)
+
+        if add_colorbar:
+            default_cbar_opts = {"pad": 0.15, "size": "5%", "label": "Max GC activity"}
+            if isinstance(colorbar_options, dict):
+                extra_cbar_kwargs = colorbar_options.get("kwargs", {})
+                for key in ("pad", "size", "label"):
+                    if key in colorbar_options:
+                        default_cbar_opts[key] = colorbar_options[key]
+            else:
+                extra_cbar_kwargs = {}
+
+            divider = make_axes_locatable(ax)
+            cax = divider.append_axes(
+                "right", size=default_cbar_opts["size"], pad=default_cbar_opts["pad"]
+            )
+            cbar = fig.colorbar(scatter, cax=cax, **extra_cbar_kwargs)
+            if default_cbar_opts["label"]:
+                cbar.set_label(default_cbar_opts["label"], fontsize=12)
+
+        if not axis_provided:
+            fig.tight_layout()
+
+        show_flag = config.show and not axis_provided
+        finalize_figure(
+            fig,
+            replace(config, show=show_flag),
+            rasterize_artists=[scatter] if config.rasterized else None,
+            always_close=not show_flag,
+        )
+        return fig, ax
+
+    except Exception as e:
+        plt.close(fig)
+        raise e
+
+
 @dataclass(slots=True)
 class _PlaceCellAnimationData:
     """Immutable container for place cell animation arrays."""

canns/pipeline/asa/runner.py

@@ -628,7 +628,7 @@ class PipelineRunner:
         self, asa_data: dict[str, Any], state: WorkflowState, log_callback
     ) -> dict[str, Path]:
         """Run CohoMap analysis (TDA + decode + plotting)."""
-        from canns.analyzer.data.asa import plot_cohomap_multi
+        from canns.analyzer.data.asa import plot_cohomap_scatter_multi
         from canns.analyzer.visualization import PlotConfigs
 
         tda_dir = self._results_dir(state) / "TDA"
@@ -661,7 +661,7 @@ class PipelineRunner:
         log_callback("Generating cohomology map...")
         pos = self._aligned_pos if self._aligned_pos is not None else asa_data
         config = PlotConfigs.cohomap(show=False, save_path=str(cohomap_path))
-        plot_cohomap_multi(
+        plot_cohomap_scatter_multi(
             decoding_result=decode_result,
             position_data={"x": pos["x"], "y": pos["y"]},
             config=config,
@@ -838,16 +838,16 @@ class PipelineRunner:
     ) -> dict[str, Path]:
         """Run cohomology space visualization."""
         from canns.analyzer.data.asa import (
-            plot_cohospace_neuron_1d,
-            plot_cohospace_neuron_2d,
-            plot_cohospace_population_1d,
-            plot_cohospace_population_2d,
-            plot_cohospace_trajectory_1d,
-            plot_cohospace_trajectory_2d,
+            plot_cohospace_scatter_neuron_1d,
+            plot_cohospace_scatter_neuron_2d,
+            plot_cohospace_scatter_population_1d,
+            plot_cohospace_scatter_population_2d,
+            plot_cohospace_scatter_trajectory_1d,
+            plot_cohospace_scatter_trajectory_2d,
         )
-        from canns.analyzer.data.asa.cohospace import (
-            plot_cohospace_neuron_skewed,
-            plot_cohospace_population_skewed,
+        from canns.analyzer.data.asa.cohospace_scatter import (
+            plot_cohospace_scatter_neuron_skewed,
+            plot_cohospace_scatter_population_skewed,
         )
         from canns.analyzer.visualization import PlotConfigs
 
@@ -937,7 +937,7 @@ class PipelineRunner:
         traj_path = out_dir / "cohospace_trajectory.png"
         if dim_mode == "1d":
             traj_cfg = PlotConfigs.cohospace_trajectory_1d(show=False, save_path=str(traj_path))
-            plot_cohospace_trajectory_1d(
+            plot_cohospace_scatter_trajectory_1d(
                 coords=coords2,
                 times=None,
                 subsample=subsample,
@@ -945,7 +945,7 @@ class PipelineRunner:
             )
         else:
             traj_cfg = PlotConfigs.cohospace_trajectory_2d(show=False, save_path=str(traj_path))
-            plot_cohospace_trajectory_2d(
+            plot_cohospace_scatter_trajectory_2d(
                 coords=coords2,
                 times=None,
                 subsample=subsample,
@@ -958,7 +958,7 @@ class PipelineRunner:
             log_callback(f"Plotting neuron {neuron_id}...")
             neuron_path = out_dir / f"cohospace_neuron_{neuron_id}.png"
             if unfold == "skew" and dim_mode != "1d":
-                plot_cohospace_neuron_skewed(
+                plot_cohospace_scatter_neuron_skewed(
                     coords=coordsbox2,
                     activity=activity,
                     neuron_id=int(neuron_id),
@@ -974,7 +974,7 @@ class PipelineRunner:
                     neuron_cfg = PlotConfigs.cohospace_neuron_1d(
                         show=False, save_path=str(neuron_path)
                     )
-                    plot_cohospace_neuron_1d(
+                    plot_cohospace_scatter_neuron_1d(
                         coords=coordsbox2,
                         activity=activity,
                         neuron_id=int(neuron_id),
@@ -986,7 +986,7 @@ class PipelineRunner:
                     neuron_cfg = PlotConfigs.cohospace_neuron_2d(
                         show=False, save_path=str(neuron_path)
                     )
-                    plot_cohospace_neuron_2d(
+                    plot_cohospace_scatter_neuron_2d(
                         coords=coordsbox2,
                         activity=activity,
                         neuron_id=int(neuron_id),
@@ -1001,7 +1001,7 @@ class PipelineRunner:
             pop_path = out_dir / "cohospace_population.png"
             neuron_ids = list(range(activity.shape[1]))
             if unfold == "skew" and dim_mode != "1d":
-                plot_cohospace_population_skewed(
+                plot_cohospace_scatter_population_skewed(
                     coords=coords2,
                     activity=activity,
                     neuron_ids=neuron_ids,
@@ -1017,7 +1017,7 @@ class PipelineRunner:
                     pop_cfg = PlotConfigs.cohospace_population_1d(
                         show=False, save_path=str(pop_path)
                     )
-                    plot_cohospace_population_1d(
+                    plot_cohospace_scatter_population_1d(
                         coords=coords2,
                         activity=activity,
                         neuron_ids=neuron_ids,
@@ -1029,7 +1029,7 @@ class PipelineRunner:
                     pop_cfg = PlotConfigs.cohospace_population_2d(
                         show=False, save_path=str(pop_path)
                     )
-                    plot_cohospace_population_2d(
+                    plot_cohospace_scatter_population_2d(
                         coords=coords2,
                         activity=activity,
                         neuron_ids=neuron_ids,

canns/pipeline/asa_gui/__init__.py

@@ -2,9 +2,9 @@
 
 from __future__ import annotations
 
-import sys
-import os
 import importlib.util
+import os
+import sys
 
 __all__ = ["main", "ASAGuiApp"]
 
@@ -14,7 +14,9 @@ if _pyside6_missing:
         try:  # pragma: no cover - only used in CI/test runs
             import pytest
 
-            pytest.skip("PySide6 is not installed; skipping asa_gui module.", allow_module_level=True)
+            pytest.skip(
+                "PySide6 is not installed; skipping asa_gui module.", allow_module_level=True
+            )
         except Exception:
             pass
 

canns/pipeline/asa_gui/analysis_modes/pathcompare_mode.py

@@ -250,7 +250,9 @@ class PathCompareMode(AbstractAnalysisMode):
             self.dim.setToolTip("1D decoded dimension index.")
             self.dim1.setToolTip("2D decoded dimension 1.")
             self.dim2.setToolTip("2D decoded dimension 2.")
-            self.use_box.setToolTip("Use coordsbox/times_box alignment (recommended with speed_filter).")
+            self.use_box.setToolTip(
+                "Use coordsbox/times_box alignment (recommended with speed_filter)."
+            )
             self.interp_full.setToolTip("Interpolate back to full trajectory.")
             self.coords_key.setToolTip("Optional decode coords key (default coords/coordsbox).")
             self.times_key.setToolTip("Optional times_box key.")