canns 0.15.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

canns/analyzer/data/asa/__init__.py

@@ -2,15 +2,9 @@ from __future__ import annotations
 
 from .cohomap import (
     cohomap,
-    cohomap_upgrade,
-    ecohomap,
     fit_cohomap_stripes,
-    fit_cohomap_stripes_upgrade,
     plot_cohomap,
-    plot_cohomap_upgrade,
-    plot_ecohomap,
 )
-from .cohomap_scatter import plot_cohomap_scatter, plot_cohomap_scatter_multi
 from .cohomap_vectors import (
     cohomap_vectors,
     plot_cohomap_stripes,
@@ -18,14 +12,8 @@ from .cohomap_vectors import (
 )
 from .cohospace import (
     cohospace,
-    cohospace_upgrade,
-    ecohospace,
     plot_cohospace,
     plot_cohospace_skewed,
-    plot_cohospace_upgrade,
-    plot_cohospace_upgrade_skewed,
-    plot_ecohospace,
-    plot_ecohospace_skewed,
 )
 from .cohospace_phase_centers import (
     cohospace_phase_centers,
@@ -81,6 +69,8 @@ from .path import (
 from .plotting import (
     plot_2d_bump_on_manifold,
     plot_3d_bump_on_torus,
+    plot_cohomap_scatter,
+    plot_cohomap_scatter_multi,
     plot_path_compare_1d,
     plot_path_compare_2d,
     plot_projection,
@@ -109,22 +99,11 @@ __all__ = [
     "plot_3d_bump_on_torus",
     "plot_2d_bump_on_manifold",
     "cohomap",
-    "cohomap_upgrade",
     "fit_cohomap_stripes",
-    "fit_cohomap_stripes_upgrade",
     "plot_cohomap",
-    "plot_cohomap_upgrade",
     "cohospace",
-    "cohospace_upgrade",
     "plot_cohospace",
     "plot_cohospace_skewed",
-    "plot_cohospace_upgrade",
-    "plot_cohospace_upgrade_skewed",
-    "ecohomap",
-    "ecohospace",
-    "plot_ecohomap",
-    "plot_ecohospace",
-    "plot_ecohospace_skewed",
     "cohomap_vectors",
     "plot_cohomap_stripes",
     "plot_cohomap_vectors",

canns/analyzer/data/asa/coho.py

@@ -2,96 +2,20 @@
 
 from __future__ import annotations
 
-import os
-from typing import Any
-
-import numpy as np
-from scipy.ndimage import gaussian_filter
-
-from ...visualization.core import PlotConfig
-from .path import find_coords_matrix, find_times_box
-
-
-def _ensure_plot_config(
-    config: PlotConfig | None,
-    factory,
-    *args,
-    **defaults,
-) -> PlotConfig:
-    if config is None:
-        return factory(*args, **defaults)
-    return config
-
-
-def _ensure_parent_dir(save_path: str | None) -> None:
-    if save_path:
-        parent = os.path.dirname(save_path)
-        if parent:
-            os.makedirs(parent, exist_ok=True)
-
-
-def _circmean(x: np.ndarray) -> float:
-    return float(np.arctan2(np.mean(np.sin(x)), np.mean(np.cos(x))))
-
-
-def _smooth_circular_map(
-    mtot: np.ndarray,
-    smooth_sigma: float,
-    *,
-    fill_nan: bool = False,
-    fill_sigma: float | None = None,
-    fill_min_weight: float = 1e-3,
-) -> np.ndarray:
-    mtot = np.asarray(mtot, dtype=float)
-    nans = np.isnan(mtot)
-    mask = (~nans).astype(float)
-    sintot = np.sin(mtot)
-    costot = np.cos(mtot)
-    sintot[nans] = 0.0
-    costot[nans] = 0.0
-
-    if fill_nan:
-        if fill_sigma is None:
-            fill_sigma = smooth_sigma if smooth_sigma and smooth_sigma > 0 else 1.0
-        weight = gaussian_filter(mask, fill_sigma)
-        sintot = gaussian_filter(sintot * mask, fill_sigma)
-        costot = gaussian_filter(costot * mask, fill_sigma)
-        min_weight = max(float(fill_min_weight), 0.0)
-        valid = weight > min_weight
-        sintot = np.divide(sintot, weight, out=np.zeros_like(sintot), where=valid)
-        costot = np.divide(costot, weight, out=np.zeros_like(costot), where=valid)
-        mtot = np.arctan2(sintot, costot)
-        if fill_min_weight > 0:
-            mtot[~valid] = np.nan
-        return mtot
-
-    if smooth_sigma and smooth_sigma > 0:
-        sintot = gaussian_filter(sintot, smooth_sigma)
-        costot = gaussian_filter(costot, smooth_sigma)
-    mtot = np.arctan2(sintot, costot)
-    mtot[nans] = np.nan
-    return mtot
-
-
-def _extract_coords_and_times(
-    decoding_result: dict[str, Any],
-    coords_key: str | None = None,
-) -> tuple[np.ndarray, np.ndarray | None]:
-    if coords_key is not None:
-        if coords_key not in decoding_result:
-            raise KeyError(f"coords_key '{coords_key}' not found in decoding_result.")
-        coords = np.asarray(decoding_result[coords_key])
-    elif "coordsbox" in decoding_result:
-        coords = np.asarray(decoding_result["coordsbox"])
-    else:
-        coords, _ = find_coords_matrix(decoding_result)
-
-    times_box, _ = find_times_box(decoding_result)
-    return coords, times_box
-
-
-def _phase_map_valid_fraction(phase_map: np.ndarray) -> float:
-    valid = np.isfinite(phase_map)
-    if valid.size == 0:
-        return 0.0
-    return float(np.mean(valid))
+from .utils import (
+    _circmean,
+    _ensure_parent_dir,
+    _ensure_plot_config,
+    _extract_coords_and_times,
+    _phase_map_valid_fraction,
+    _smooth_circular_map,
+)
+
+__all__ = [
+    "_ensure_plot_config",
+    "_ensure_parent_dir",
+    "_circmean",
+    "_smooth_circular_map",
+    "_extract_coords_and_times",
+    "_phase_map_valid_fraction",
+]

canns/analyzer/data/asa/cohomap.py

@@ -57,6 +57,36 @@ def _rot_coord(
     c2: np.ndarray,
     p: tuple[int, int],
 ) -> np.ndarray:
+    """Transform and align decoded coordinates based on stripe orientation.
+
+    This function rotates and aligns coordinates to match the dominant stripe
+    orientation in the CohoMap. It handles the torus geometry by choosing the
+    appropriate coordinate system and applying reflections/rotations.
+
+    Parameters
+    ----------
+    params1 : np.ndarray
+        Stripe fit parameters for first dimension (includes orientation angle).
+    params2 : np.ndarray
+        Stripe fit parameters for second dimension (includes orientation angle).
+    c1 : np.ndarray
+        Decoded coordinates for first dimension.
+    c2 : np.ndarray
+        Decoded coordinates for second dimension.
+    p : tuple[int, int]
+        Direction indicators (1 or -1) for each dimension, controlling reflections.
+
+    Returns
+    -------
+    np.ndarray
+        Aligned coordinates of shape (N, 2), wrapped to [0, 2π).
+
+    Notes
+    -----
+    The function selects the coordinate system based on which dimension has
+    stronger horizontal alignment (larger |cos(angle)|), then applies geometric
+    transformations to align the coordinates with the stripe pattern.
+    """
     if abs(np.cos(params1[0])) < abs(np.cos(params2[0])):
         cc1 = c2.copy()
         cc2 = c1.copy()
@@ -96,6 +126,46 @@ def _toroidal_align_coords(
     trim: int,
     grid_size: int | None,
 ) -> tuple[np.ndarray, float, float]:
+    """Align decoded coordinates to CohoMap stripe patterns.
+
+    This function fits stripe patterns to both phase maps, determines the
+    optimal orientation and phase signs, then transforms the decoded coordinates
+    to align with the detected stripe structure.
+
+    Parameters
+    ----------
+    coords : np.ndarray
+        Decoded coordinates of shape (N, 2+). Only first two columns are used.
+    phase_map1 : np.ndarray
+        Phase map for first dimension (2D grid).
+    phase_map2 : np.ndarray
+        Phase map for second dimension (2D grid), must match phase_map1 shape.
+    trim : int
+        Number of edge bins to trim when fitting stripes.
+    grid_size : int, optional
+        Grid size for stripe fitting. If None, inferred from phase_map shape.
+
+    Returns
+    -------
+    aligned : np.ndarray
+        Aligned coordinates of shape (N, 2), wrapped to [0, 2π).
+    f1 : float
+        Fit quality score for first dimension (higher is better).
+    f2 : float
+        Fit quality score for second dimension (higher is better).
+
+    Raises
+    ------
+    ValueError
+        If phase_map shapes don't match or coords has wrong shape.
+
+    Notes
+    -----
+    The alignment process:
+    1. Fits stripe patterns to both phase maps using FFT-based detection
+    2. Determines phase signs (±1) for each dimension
+    3. Applies geometric transformations via `_rot_coord()` to align coordinates
+    """
     if phase_map1.shape != phase_map2.shape:
         raise ValueError("phase_map shapes do not match for alignment")
     coords = np.asarray(coords)
@@ -381,28 +451,3 @@ def plot_cohomap(
     _ensure_parent_dir(config.save_path)
     finalize_figure(fig, config)
     return fig
-
-
-def cohomap_upgrade(*args, **kwargs) -> dict[str, Any]:
-    """Legacy alias for EcohoMap (formerly cohomap_upgrade)."""
-    return cohomap(*args, **kwargs)
-
-
-def ecohomap(*args, **kwargs) -> dict[str, Any]:
-    """Alias for EcohoMap (GridCellTorus-style)."""
-    return cohomap(*args, **kwargs)
-
-
-def fit_cohomap_stripes_upgrade(*args, **kwargs) -> tuple[np.ndarray, float]:
-    """Legacy alias for EcohoMap stripe fitting."""
-    return fit_cohomap_stripes(*args, **kwargs)
-
-
-def plot_cohomap_upgrade(*args, **kwargs) -> plt.Figure:
-    """Legacy alias for EcohoMap plotting (formerly plot_cohomap_upgrade)."""
-    return plot_cohomap(*args, **kwargs)
-
-
-def plot_ecohomap(*args, **kwargs) -> plt.Figure:
-    """Alias for EcohoMap plotting."""
-    return plot_cohomap(*args, **kwargs)

canns/analyzer/data/asa/cohomap_vectors.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import os
 from typing import Any
 
 import matplotlib.pyplot as plt
@@ -11,27 +10,37 @@ from scipy.ndimage import rotate
 
 from ...visualization.core import PlotConfig, finalize_figure
 from .cohomap import fit_cohomap_stripes
-
-
-def _ensure_plot_config(
-    config: PlotConfig | None,
-    factory,
-    *args,
-    **defaults,
-) -> PlotConfig:
-    if config is None:
-        return factory(*args, **defaults)
-    return config
-
-
-def _ensure_parent_dir(save_path: str | None) -> None:
-    if save_path:
-        parent = os.path.dirname(save_path)
-        if parent:
-            os.makedirs(parent, exist_ok=True)
+from .utils import _ensure_parent_dir, _ensure_plot_config
 
 
 def _rot_para(params1: np.ndarray, params2: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Transform stripe fit parameters to canonical orientation.
+
+    This function adjusts the orientation angles of stripe fit parameters to
+    align them with a canonical coordinate system. Unlike `_rot_coord()` which
+    transforms actual coordinate data, this operates on the fit parameters
+    themselves (orientation angles, wavelengths, etc.).
+
+    Parameters
+    ----------
+    params1 : np.ndarray
+        Stripe fit parameters for first dimension. First element is orientation angle.
+    params2 : np.ndarray
+        Stripe fit parameters for second dimension. First element is orientation angle.
+
+    Returns
+    -------
+    x : np.ndarray
+        Transformed parameters for the dimension with stronger horizontal alignment.
+    y : np.ndarray
+        Transformed parameters for the other dimension.
+
+    Notes
+    -----
+    The function selects which parameter set becomes 'x' and 'y' based on which
+    has larger |cos(angle)|, then applies angle adjustments to ensure the stripe
+    vectors are in a canonical orientation for visualization and analysis.
+    """
     if abs(np.cos(params1[0])) < abs(np.cos(params2[0])):
         y = params1.copy()
         x = params2.copy()
@@ -204,12 +213,57 @@ def plot_cohomap_vectors(
 
 
 def _resolve_grid_size(phase_map: np.ndarray, grid_size: int | None, trim: int) -> int:
+    """Determine grid size for stripe fitting.
+
+    Parameters
+    ----------
+    phase_map : np.ndarray
+        Phase map array (2D grid).
+    grid_size : int, optional
+        Explicit grid size. If None, inferred from phase_map shape.
+    trim : int
+        Number of edge bins to trim.
+
+    Returns
+    -------
+    int
+        Grid size to use for stripe fitting.
+    """
     if grid_size is None:
         return int(phase_map.shape[0]) + 2 * trim + 1
     return int(grid_size)
 
 
 def _stripe_fit_map(params: np.ndarray, grid_size: int, trim: int) -> np.ndarray:
+    """Generate a synthetic stripe pattern from fit parameters.
+
+    Creates a 2D cosine stripe pattern based on the fitted parameters (orientation,
+    phase, and spatial frequency). Used for visualizing the fitted stripe model
+    and comparing it with the actual phase map.
+
+    Parameters
+    ----------
+    params : np.ndarray
+        Stripe fit parameters: [angle, phase, frequency].
+        - angle: Orientation angle in radians
+        - phase: Phase offset in radians
+        - frequency: Spatial frequency (inverse wavelength)
+    grid_size : int
+        Size of the grid to generate (before trimming).
+    trim : int
+        Number of edge bins to trim from the generated pattern.
+
+    Returns
+    -------
+    np.ndarray
+        2D array of shape (grid_size-2*trim, grid_size-2*trim) containing
+        the cosine stripe pattern with values in [-1, 1].
+
+    Notes
+    -----
+    The pattern is generated on a [0, 3π] × [0, 3π] domain to cover the
+    extended torus space, then rotated by the fitted angle and trimmed.
+    """
     numangsint = grid_size
     x, _ = np.meshgrid(
         np.linspace(0, 3 * np.pi, numangsint - 1),

canns/analyzer/data/asa/cohospace.py

@@ -219,33 +219,3 @@ def plot_cohospace_skewed(
     _ensure_parent_dir(config.save_path)
     finalize_figure(fig, config)
     return fig
-
-
-def cohospace_upgrade(*args, **kwargs) -> dict[str, Any]:
-    """Legacy alias for EcohoSpace (formerly cohospace_upgrade)."""
-    return cohospace(*args, **kwargs)
-
-
-def ecohospace(*args, **kwargs) -> dict[str, Any]:
-    """Alias for EcohoSpace (GridCellTorus-style)."""
-    return cohospace(*args, **kwargs)
-
-
-def plot_cohospace_upgrade(*args, **kwargs) -> plt.Figure:
-    """Legacy alias for EcohoSpace plotting (formerly plot_cohospace_upgrade)."""
-    return plot_cohospace(*args, **kwargs)
-
-
-def plot_cohospace_upgrade_skewed(*args, **kwargs) -> plt.Figure:
-    """Legacy alias for EcohoSpace skewed plotting."""
-    return plot_cohospace_skewed(*args, **kwargs)
-
-
-def plot_ecohospace(*args, **kwargs) -> plt.Figure:
-    """Alias for EcohoSpace plotting."""
-    return plot_cohospace(*args, **kwargs)
-
-
-def plot_ecohospace_skewed(*args, **kwargs) -> plt.Figure:
-    """Alias for EcohoSpace skewed plotting."""
-    return plot_cohospace_skewed(*args, **kwargs)

canns/analyzer/data/asa/cohospace_phase_centers.py

@@ -2,32 +2,14 @@
 
 from __future__ import annotations
 
-import os
 from typing import Any
 
 import matplotlib.pyplot as plt
 import numpy as np
 
 from ...visualization.core import PlotConfig, finalize_figure
-from .cohospace_scatter import skew_transform_torus_scatter
-
-
-def _ensure_plot_config(
-    config: PlotConfig | None,
-    factory,
-    *args,
-    **defaults,
-) -> PlotConfig:
-    if config is None:
-        return factory(*args, **defaults)
-    return config
-
-
-def _ensure_parent_dir(save_path: str | None) -> None:
-    if save_path:
-        parent = os.path.dirname(save_path)
-        if parent:
-            os.makedirs(parent, exist_ok=True)
+from .path import skew_transform
+from .utils import _ensure_parent_dir, _ensure_plot_config
 
 
 def cohospace_phase_centers(cohospace_result: dict[str, Any]) -> dict[str, Any]:
@@ -40,7 +22,7 @@ def cohospace_phase_centers(cohospace_result: dict[str, Any]) -> dict[str, Any]:
         Output from `data.cohospace(...)` (must include `centers`).
     """
     centers = np.asarray(cohospace_result["centers"], dtype=float) % (2 * np.pi)
-    centers_skew = skew_transform_torus_scatter(centers)
+    centers_skew = skew_transform(centers)
     return {
         "centers": centers,
         "centers_skew": centers_skew,

canns/analyzer/data/asa/cohospace_scatter.py

@@ -2,38 +2,13 @@
 
 from __future__ import annotations
 
-import os
-
 import matplotlib.pyplot as plt
 import numpy as np
 from scipy.stats import circvar
 
 from ...visualization.core import PlotConfig, finalize_figure
-
-
-def _ensure_plot_config(
-    config: PlotConfig | None,
-    factory,
-    *,
-    kwargs: dict | None = None,
-    **defaults,
-) -> 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 _ensure_parent_dir(save_path: str | None) -> None:
-    if save_path:
-        parent = os.path.dirname(save_path)
-        if parent:
-            os.makedirs(parent, exist_ok=True)
+from .path import _align_activity_to_coords, skew_transform
+from .utils import _ensure_parent_dir, _ensure_plot_config
 
 
 # =====================================================================
@@ -48,51 +23,6 @@ def _coho_coords_to_degrees(coords: np.ndarray) -> np.ndarray:
     return np.degrees(coords % (2 * np.pi))
 
 
-def _align_activity_to_coords(
-    coords: np.ndarray,
-    activity: np.ndarray,
-    times: np.ndarray | None = None,
-    *,
-    label: str = "activity",
-    auto_filter: bool = True,
-) -> np.ndarray:
-    """
-    Align activity to coords by optional time indices and validate lengths.
-    """
-    coords = np.asarray(coords)
-    activity = np.asarray(activity)
-
-    if times is not None:
-        times = np.asarray(times)
-        try:
-            activity = activity[times]
-        except Exception as exc:
-            raise ValueError(
-                f"Failed to index {label} with `times`. Ensure `times` indexes the original time axis."
-            ) from exc
-
-    if activity.shape[0] != coords.shape[0]:
-        # Try to reproduce decode's zero-spike filtering if lengths mismatch.
-        if auto_filter and times is None and activity.ndim == 2:
-            mask = np.sum(activity > 0, axis=1) >= 1
-            if mask.sum() == coords.shape[0]:
-                activity = activity[mask]
-            else:
-                raise ValueError(
-                    f"{label} length must match coords length. Got {activity.shape[0]} vs {coords.shape[0]}. "
-                    "If coords are computed on a subset of timepoints (e.g., decode['times']), pass "
-                    "`times=decoding['times']` or slice the activity accordingly."
-                )
-        else:
-            raise ValueError(
-                f"{label} length must match coords length. Got {activity.shape[0]} vs {coords.shape[0]}. "
-                "If coords are computed on a subset of timepoints (e.g., decode['times']), pass "
-                "`times=decoding['times']` or slice the activity accordingly."
-            )
-
-    return activity
-
-
 def plot_cohospace_scatter_trajectory_2d(
     coords: np.ndarray,
     times: np.ndarray | None = None,
@@ -802,41 +732,6 @@ def compute_cohoscore_scatter_1d(
     return scores
 
 
-def skew_transform_torus_scatter(coords):
-    """
-    Convert torus angles (theta1, theta2) into coordinates in a skewed parallelogram fundamental domain.
-
-    Given theta1, theta2 in radians, map:
-        x = theta1 + 0.5 * theta2
-        y = (sqrt(3)/2) * theta2
-
-    This is a linear change of basis that turns the square [0, 2π)×[0, 2π) into a 60-degree
-    parallelogram, which is convenient for visualizing wrap-around behavior on a 2-torus.
-
-    Parameters
-    ----------
-    coords : ndarray, shape (T, 2)
-        Angles (theta1, theta2) in radians.
-
-    Returns
-    -------
-    xy : ndarray, shape (T, 2)
-        Skewed planar coordinates.
-    """
-    coords = np.asarray(coords)
-    if coords.ndim != 2 or coords.shape[1] != 2:
-        raise ValueError(f"coords must be (T,2), got {coords.shape}")
-
-    theta1 = coords[:, 0]
-    theta2 = coords[:, 1]
-
-    # Linear change of basis (NO nonlinear scaling)
-    x = theta1 + 0.5 * theta2
-    y = (np.sqrt(3) / 2.0) * theta2
-
-    return np.stack([x, y], axis=1)
-
-
 def draw_torus_parallelogram_grid_scatter(ax, n_tiles=1, color="0.7", lw=1.0, alpha=0.8):
     """
     Draw parallelogram grid corresponding to torus fundamental domain.
@@ -874,7 +769,7 @@ def tile_parallelogram_points_scatter(xy, n_tiles=1):
     Parameters
     ----------
     points : ndarray, shape (T, 2)
-        Points in the skewed plane (same coordinates as returned by `skew_transform_torus_scatter`).
+        Points in the skewed plane (same coordinates as returned by `skew_transform`).
     n_tiles : int
         Number of tiles to extend around the base domain.
         - n_tiles=1 produces a 3x3 tiling
@@ -1020,7 +915,7 @@ def plot_cohospace_scatter_neuron_skewed(
         )
 
     # --- skew transform
-    xy = skew_transform_torus_scatter(coords[mask])
+    xy = skew_transform(coords[mask])
 
     # Tiling: if points are tiled, values must be tiled too (FR mode) to keep lengths consistent
     if n_tiles and n_tiles > 0:
@@ -1165,7 +1060,7 @@ def plot_cohospace_scatter_population_skewed(
             thr = np.percentile(a, 100 - top_percent)
             mask = a >= thr
 
-        xy = skew_transform_torus_scatter(coords[mask])
+        xy = skew_transform(coords[mask])
 
         if n_tiles and n_tiles > 0:
             xy = tile_parallelogram_points_scatter(xy, n_tiles=n_tiles)

canns/analyzer/data/asa/embedding.py

@@ -6,7 +6,6 @@ import numpy as np
 from scipy.ndimage import gaussian_filter1d
 
 from .config import DataLoadError, ProcessingError, SpikeEmbeddingConfig
-from .filters import _gaussian_filter1d
 
 
 def embed_spike_trains(spike_trains, config: SpikeEmbeddingConfig | None = None, **kwargs):
@@ -262,8 +261,8 @@ def _load_pos(t, x, y, res=100000, dt=1000):
     xx = np.interp(tt, t, x)
     yy = np.interp(tt, t, y)
 
-    xxs = _gaussian_filter1d(xx - np.min(xx), sigma=100)
-    yys = _gaussian_filter1d(yy - np.min(yy), sigma=100)
+    xxs = gaussian_filter1d(xx - np.min(xx), sigma=100)
+    yys = gaussian_filter1d(yy - np.min(yy), sigma=100)
     dx = (xxs[1:] - xxs[:-1]) * 100
     dy = (yys[1:] - yys[:-1]) * 100
     speed = np.sqrt(dx**2 + dy**2) / 0.01

canns/analyzer/data/asa/fr.py

@@ -1,18 +1,11 @@
 from __future__ import annotations
 
-import os
 from dataclasses import dataclass
 
 import numpy as np
 
 from ...visualization.core import PlotConfig, finalize_figure
-
-
-def _ensure_parent_dir(save_path: str | None) -> None:
-    if save_path:
-        parent = os.path.dirname(save_path)
-        if parent:
-            os.makedirs(parent, exist_ok=True)
+from .utils import _ensure_parent_dir
 
 
 def _slice_range(r: tuple[int, int] | None, length: int) -> slice: