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

canns/analyzer/data/asa/path.py

@@ -216,7 +216,31 @@ def interp_coords_to_full(idx_map: np.ndarray, coords2: np.ndarray, T_full: int)
     return np.mod(out, 2 * np.pi)
 
 
-def align_coords_to_position(
+def interp_coords_to_full_1d(idx_map: np.ndarray, coords1: np.ndarray, T_full: int) -> np.ndarray:
+    """Interpolate (K,) circular coords back to full length (T_full,1)."""
+    idx_map = np.asarray(idx_map).astype(int).ravel()
+    coords1 = np.asarray(coords1, float)
+    if coords1.ndim == 2 and coords1.shape[1] == 1:
+        coords1 = coords1[:, 0]
+    if coords1.ndim != 1:
+        raise ValueError(f"coords1 must have shape (K,) or (K,1), got {coords1.shape}")
+
+    order = np.argsort(idx_map)
+    idx_map = idx_map[order]
+    coords1 = coords1[order]
+
+    uniq_idx, uniq_pos = np.unique(idx_map, return_index=True)
+    coords1 = coords1[uniq_pos]
+    idx_map = uniq_idx
+
+    ang = np.unwrap(coords1)
+    full_i = np.arange(T_full, dtype=float)
+    out = np.interp(full_i, idx_map.astype(float), ang)
+
+    return np.mod(out, 2 * np.pi)[:, None]
+
+
+def align_coords_to_position_2d(
     t_full: np.ndarray,
     x_full: np.ndarray,
     y_full: np.ndarray,
@@ -248,7 +272,7 @@ def align_coords_to_position(
 
     Examples
     --------
-    >>> t, x, y, coords2, tag = align_coords_to_position(  # doctest: +SKIP
+    >>> t, x, y, coords2, tag = align_coords_to_position_2d(  # doctest: +SKIP
     ...     t_full, x_full, y_full, coords2,
     ...     use_box=True, times_box=decoding["times_box"], interp_to_full=True
     ... )
@@ -320,6 +344,84 @@ def align_coords_to_position(
     )
 
 
+def align_coords_to_position_1d(
+    t_full: np.ndarray,
+    x_full: np.ndarray,
+    y_full: np.ndarray,
+    coords1: np.ndarray,
+    use_box: bool,
+    times_box: np.ndarray | None,
+    interp_to_full: bool,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, str]:
+    """Align 1D decoded coordinates to the original (x, y, t) trajectory."""
+    t_full = np.asarray(t_full).ravel()
+    x_full = np.asarray(x_full).ravel()
+    y_full = np.asarray(y_full).ravel()
+    coords1 = np.asarray(coords1, float)
+    if coords1.ndim == 2 and coords1.shape[1] == 1:
+        coords1 = coords1[:, 0]
+    if coords1.ndim != 1:
+        raise ValueError(f"coords1 must have shape (T,) or (T,1), got {coords1.shape}")
+
+    T_full = len(t_full)
+
+    if not use_box:
+        if len(coords1) != T_full:
+            raise ValueError(
+                f"coords length {len(coords1)} != t length {T_full} "
+                f"(set --use-box if you have times_box)"
+            )
+        return t_full, x_full, y_full, coords1[:, None], "full(no-box)"
+
+    if times_box is None:
+        if len(coords1) == T_full:
+            return (
+                t_full,
+                x_full,
+                y_full,
+                coords1[:, None],
+                "full(use-box but no times_box; treated as full)",
+            )
+        raise KeyError("use_box=True but times_box not found, and coords is not full-length.")
+
+    idx_map, kind = parse_times_box_to_indices(times_box, t_full)
+
+    if len(coords1) == T_full and len(idx_map) == T_full:
+        return (
+            t_full,
+            x_full,
+            y_full,
+            coords1[:, None],
+            f"full(coords already full; times_box kind={kind} ignored)",
+        )
+
+    if len(idx_map) != len(coords1):
+        raise ValueError(f"times_box length {len(idx_map)} != coords length {len(coords1)}")
+
+    order = np.argsort(idx_map)
+    idx_map = idx_map[order]
+    coords1 = coords1[order]
+
+    if interp_to_full:
+        coords_full = interp_coords_to_full_1d(idx_map, coords1, T_full)
+        return (
+            t_full,
+            x_full,
+            y_full,
+            coords_full,
+            f"interp_to_full(times_box kind={kind}, K={len(idx_map)})",
+        )
+
+    idx_map = np.clip(idx_map, 0, T_full - 1)
+    return (
+        t_full[idx_map],
+        x_full[idx_map],
+        y_full[idx_map],
+        coords1[:, None],
+        f"subset(times_box kind={kind}, K={len(idx_map)})",
+    )
+
+
 def snake_wrap_trail_in_parallelogram(
     xy_base: np.ndarray, e1: np.ndarray, e2: np.ndarray
 ) -> np.ndarray:

canns/analyzer/data/asa/plotting.py

@@ -237,7 +237,7 @@ def plot_projection(
     return fig
 
 
-def plot_path_compare(
+def plot_path_compare_2d(
     x: np.ndarray,
     y: np.ndarray,
     coords: np.ndarray,
@@ -248,14 +248,14 @@ def plot_path_compare(
     show: bool = True,
     save_path: str | None = None,
 ) -> tuple[plt.Figure, np.ndarray]:
-    """Plot physical path vs decoded coho-space path side-by-side.
+    """Plot physical path vs decoded coho-space path (2D) side-by-side.
 
     Parameters
     ----------
     x, y : np.ndarray
         Physical position arrays of shape (T,).
     coords : np.ndarray
-        Decoded circular coordinates, shape (T, 1) or (T, 2).
+        Decoded circular coordinates, shape (T, 2) or (T, 2+).
     config : PlotConfig, optional
         Plot configuration. If None, a default config is created.
     title, figsize, show, save_path : optional
@@ -268,7 +268,7 @@ def plot_path_compare(
 
     Examples
     --------
-    >>> fig, axes = plot_path_compare(x, y, coords, show=False)  # doctest: +SKIP
+    >>> fig, axes = plot_path_compare_2d(x, y, coords, show=False)  # doctest: +SKIP
     """
     from .path import draw_base_parallelogram, skew_transform, snake_wrap_trail_in_parallelogram
 
@@ -276,8 +276,8 @@ def plot_path_compare(
     y = np.asarray(y).ravel()
     coords = np.asarray(coords)
 
-    if coords.ndim != 2 or coords.shape[1] < 1:
-        raise ValueError(f"coords must be 2D with at least 1 column, got {coords.shape}")
+    if coords.ndim != 2 or coords.shape[1] < 2:
+        raise ValueError(f"coords must be 2D with at least 2 columns, got {coords.shape}")
 
     config = _ensure_plot_config(
         config,
@@ -314,19 +314,88 @@ def plot_path_compare(
     ax1.set_aspect("equal", "box")
     ax1.axis("off")
 
-    if coords.shape[1] >= 2:
-        theta2 = coords[:, :2] % (2 * np.pi)
-        xy = skew_transform(theta2)
-        draw_base_parallelogram(ax1)
-        trail = snake_wrap_trail_in_parallelogram(
-            xy, np.array([2 * np.pi, 0.0]), np.array([np.pi, np.sqrt(3) * np.pi])
-        )
-        ax1.plot(trail[:, 0], trail[:, 1], lw=0.9, alpha=0.9)
-    else:
-        th = coords[:, 0] % (2 * np.pi)
-        ax1.plot(np.cos(th), np.sin(th), lw=0.9, alpha=0.9)
-        ax1.set_xlim(-1.2, 1.2)
-        ax1.set_ylim(-1.2, 1.2)
+    theta2 = coords[:, :2] % (2 * np.pi)
+    xy = skew_transform(theta2)
+    draw_base_parallelogram(ax1)
+    trail = snake_wrap_trail_in_parallelogram(
+        xy, np.array([2 * np.pi, 0.0]), np.array([np.pi, np.sqrt(3) * np.pi])
+    )
+    ax1.plot(trail[:, 0], trail[:, 1], lw=0.9, alpha=0.9)
+
+    fig.tight_layout()
+    _ensure_parent_dir(config.save_path)
+    finalize_figure(fig, config)
+    return fig, axes
+
+
+def plot_path_compare_1d(
+    x: np.ndarray,
+    y: np.ndarray,
+    coords: np.ndarray,
+    config: PlotConfig | None = None,
+    *,
+    title: str = "Path Compare (1D)",
+    figsize: tuple[int, int] = (12, 5),
+    show: bool = True,
+    save_path: str | None = None,
+) -> tuple[plt.Figure, np.ndarray]:
+    """Plot physical path vs decoded coho-space path (1D) side-by-side."""
+    x = np.asarray(x).ravel()
+    y = np.asarray(y).ravel()
+    coords = np.asarray(coords)
+    if coords.ndim == 2 and coords.shape[1] == 1:
+        coords = coords[:, 0]
+    if coords.ndim != 1:
+        raise ValueError(f"coords must have shape (T,) or (T, 1), got {coords.shape}")
+
+    config = _ensure_plot_config(
+        config,
+        PlotConfig.for_static_plot,
+        title=title,
+        figsize=figsize,
+        save_path=save_path,
+        show=show,
+    )
+
+    fig, axes = plt.subplots(1, 2, figsize=config.figsize)
+    if config.title:
+        fig.suptitle(config.title)
+
+    ax0 = axes[0]
+    ax0.set_title("Physical path (x,y)")
+    ax0.set_aspect("equal", "box")
+    ax0.plot(x, y, lw=0.9, alpha=0.8)
+    ax0.set_xticks([])
+    ax0.set_yticks([])
+    for spine in ax0.spines.values():
+        spine.set_visible(True)
+    x_min, x_max = np.min(x), np.max(x)
+    y_min, y_max = np.min(y), np.max(y)
+    pad_x = (x_max - x_min) * 0.03 if x_max > x_min else 1.0
+    pad_y = (y_max - y_min) * 0.03 if y_max > y_min else 1.0
+    ax0.set_xlim(x_min - pad_x, x_max + pad_x)
+    ax0.set_ylim(y_min - pad_y, y_max + pad_y)
+
+    ax1 = axes[1]
+    ax1.set_title("Decoded coho path (1D)")
+    ax1.set_aspect("equal", "box")
+    ax1.axis("off")
+
+    theta = coords % (2 * np.pi)
+    x_unit = np.cos(theta)
+    y_unit = np.sin(theta)
+    sc = ax1.scatter(
+        x_unit,
+        y_unit,
+        c=np.arange(len(theta)),
+        cmap="viridis",
+        s=4,
+        alpha=0.8,
+    )
+    cbar = plt.colorbar(sc, ax=ax1, fraction=0.046, pad=0.04)
+    cbar.set_label("Time")
+    ax1.set_xlim(-1.2, 1.2)
+    ax1.set_ylim(-1.2, 1.2)
 
     fig.tight_layout()
     _ensure_parent_dir(config.save_path)

canns/analyzer/data/asa/tda.py

@@ -41,7 +41,7 @@ def tda_vis(embed_data: np.ndarray, config: TDAConfig | None = None, **kwargs) -
     **kwargs : Any
         Legacy keyword parameters (``dim``, ``num_times``, ``active_times``, ``k``,
         ``n_points``, ``metric``, ``nbs``, ``maxdim``, ``coeff``, ``show``,
-        ``do_shuffle``, ``num_shuffles``, ``progress_bar``).
+        ``do_shuffle``, ``num_shuffles``, ``progress_bar``, ``standardize``).
 
     Returns
     -------
@@ -77,6 +77,7 @@ def tda_vis(embed_data: np.ndarray, config: TDAConfig | None = None, **kwargs) -
             do_shuffle=kwargs.get("do_shuffle", False),
             num_shuffles=kwargs.get("num_shuffles", 1000),
             progress_bar=kwargs.get("progress_bar", True),
+            standardize=kwargs.get("standardize", True),
         )
 
     try:
@@ -120,7 +121,7 @@ def _compute_real_persistence(embed_data: np.ndarray, config: TDAConfig) -> dict
 
     # Step 3: PCA dimensionality reduction
     logging.info("Step 3/5: PCA dimensionality reduction")
-    dimred = _apply_pca_reduction(embed_data, movetimes, config.dim)
+    dimred = _apply_pca_reduction(embed_data, movetimes, config.dim, config.standardize)
 
     # Step 4: Point cloud sampling (denoising)
     logging.info("Step 4/5: Point cloud denoising")
@@ -156,9 +157,15 @@ def _select_active_timepoints(
     return times_cube[movetimes]
 
 
-def _apply_pca_reduction(embed_data: np.ndarray, movetimes: np.ndarray, dim: int) -> np.ndarray:
+def _apply_pca_reduction(
+    embed_data: np.ndarray, movetimes: np.ndarray, dim: int, standardize: bool
+) -> np.ndarray:
     """Apply PCA dimensionality reduction."""
-    scaled_data = preprocessing.scale(embed_data[movetimes, :])
+    subset = embed_data[movetimes, :]
+    if standardize:
+        scaled_data = preprocessing.scale(subset)
+    else:
+        scaled_data = np.asarray(subset, dtype=np.float32)
     dimred, *_ = _pca(scaled_data, dim=dim)
     return dimred
 

canns/analyzer/data/cell_classification/__init__.py

@@ -0,0 +1,97 @@
+"""
+Cell Classification Package
+
+Python implementation of grid cell and head direction cell classification algorithms.
+
+Based on the MATLAB code from:
+Vollan, Gardner, Moser & Moser (Nature, 2025)
+"Left-right-alternating sweeps in entorhinal-hippocampal maps of space"
+"""
+
+__version__ = "0.1.0"
+
+from .core import (  # noqa: F401
+    GridnessAnalyzer,
+    GridnessResult,
+    HDCellResult,
+    HeadDirectionAnalyzer,
+    compute_2d_autocorrelation,
+    compute_field_statistics,
+    compute_grid_spacing,
+    compute_rate_map,
+    compute_rate_map_from_binned,
+    compute_spatial_information,
+    identify_grid_modules_and_stats,
+)
+from .io import MATFileLoader, TuningCurve, Unit  # noqa: F401
+from .utils import (  # noqa: F401
+    autocorrelation_2d,
+    cart2pol,
+    circ_dist,
+    circ_dist2,
+    circ_mean,
+    circ_r,
+    circ_rtest,
+    circ_std,
+    fit_ellipse,
+    label_connected_components,
+    normalized_xcorr2,
+    pearson_correlation,
+    pol2cart,
+    polyarea,
+    regionprops,
+    rotate_image,
+    squared_distance,
+    wrap_to_pi,
+)
+from .visualization import (  # noqa: F401
+    plot_autocorrelogram,
+    plot_grid_score_histogram,
+    plot_gridness_analysis,
+    plot_hd_analysis,
+    plot_polar_tuning,
+    plot_rate_map,
+    plot_temporal_autocorr,
+)
+
+__all__ = [
+    "GridnessAnalyzer",
+    "GridnessResult",
+    "HeadDirectionAnalyzer",
+    "HDCellResult",
+    "compute_2d_autocorrelation",
+    "compute_rate_map",
+    "compute_rate_map_from_binned",
+    "compute_spatial_information",
+    "compute_field_statistics",
+    "compute_grid_spacing",
+    "identify_grid_modules_and_stats",
+    "MATFileLoader",
+    "TuningCurve",
+    "Unit",
+    "circ_r",
+    "circ_mean",
+    "circ_std",
+    "circ_dist",
+    "circ_dist2",
+    "circ_rtest",
+    "pearson_correlation",
+    "normalized_xcorr2",
+    "autocorrelation_2d",
+    "fit_ellipse",
+    "squared_distance",
+    "polyarea",
+    "wrap_to_pi",
+    "cart2pol",
+    "pol2cart",
+    "rotate_image",
+    "label_connected_components",
+    "regionprops",
+    "plot_autocorrelogram",
+    "plot_gridness_analysis",
+    "plot_rate_map",
+    "plot_grid_score_histogram",
+    "plot_polar_tuning",
+    "plot_temporal_autocorr",
+    "plot_hd_analysis",
+]

canns/analyzer/data/cell_classification/core/__init__.py

@@ -0,0 +1,26 @@
+"""Core analysis modules."""
+
+from .grid_cells import GridnessAnalyzer, GridnessResult, compute_2d_autocorrelation
+from .grid_modules_leiden import identify_grid_modules_and_stats
+from .head_direction import HDCellResult, HeadDirectionAnalyzer
+from .spatial_analysis import (
+    compute_field_statistics,
+    compute_grid_spacing,
+    compute_rate_map,
+    compute_rate_map_from_binned,
+    compute_spatial_information,
+)
+
+__all__ = [
+    "GridnessAnalyzer",
+    "compute_2d_autocorrelation",
+    "GridnessResult",
+    "HeadDirectionAnalyzer",
+    "HDCellResult",
+    "compute_rate_map",
+    "compute_rate_map_from_binned",
+    "compute_spatial_information",
+    "compute_field_statistics",
+    "compute_grid_spacing",
+    "identify_grid_modules_and_stats",
+]