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

canns/analyzer/data/cell_classification/utils/circular_stats.py

@@ -0,0 +1,383 @@
+"""
+Circular Statistics Utilities
+
+Python port of CircStat MATLAB toolbox functions for circular statistics.
+
+References:
+    - Statistical analysis of circular data, N.I. Fisher
+    - Topics in circular statistics, S.R. Jammalamadaka et al.
+    - Biostatistical Analysis, J. H. Zar
+    - CircStat MATLAB toolbox by Philipp Berens (2009)
+"""
+
+import numpy as np
+
+
+def circ_r(
+    alpha: np.ndarray, w: np.ndarray | None = None, d: float = 0.0, axis: int = 0
+) -> float | np.ndarray:
+    """
+    Compute mean resultant vector length for circular data.
+
+    This is a measure of circular variance (concentration). Values near 1 indicate
+    high concentration, values near 0 indicate uniform distribution.
+
+    Parameters
+    ----------
+    alpha : np.ndarray
+        Sample of angles in radians
+    w : np.ndarray, optional
+        Weights for each angle (e.g., for binned data). If None, uniform weights assumed.
+    d : float, optional
+        Spacing of bin centers for binned data. If supplied, correction factor is used
+        to correct for bias in estimation of r (in radians). Default is 0 (no correction).
+    axis : int, optional
+        Compute along this dimension. Default is 0.
+
+    Returns
+    -------
+    r : float or np.ndarray
+        Mean resultant vector length
+
+    Examples
+    --------
+    >>> angles = np.array([0, 0.1, 0.2, -0.1, -0.2])  # Concentrated around 0
+    >>> r = circ_r(angles)
+    >>> print(f"MVL: {r:.3f}")  # Should be close to 1
+
+    >>> angles = np.linspace(0, 2*np.pi, 100)  # Uniform distribution
+    >>> r = circ_r(angles)
+    >>> print(f"MVL: {r:.3f}")  # Should be close to 0
+
+    Notes
+    -----
+    Based on CircStat toolbox circ_r.m by Philipp Berens (2009)
+    """
+    if w is None:
+        w = np.ones_like(alpha)
+
+    # Compute weighted sum of complex exponentials
+    r = np.sum(w * np.exp(1j * alpha), axis=axis)
+
+    # Obtain length normalized by sum of weights
+    r = np.abs(r) / np.sum(w, axis=axis)
+
+    # Apply correction factor for binned data if spacing is provided
+    if d != 0:
+        c = d / (2 * np.sin(d / 2))
+        r = c * r
+
+    return r
+
+
+def circ_mean(alpha: np.ndarray, w: np.ndarray | None = None, axis: int = 0) -> float | np.ndarray:
+    """
+    Compute mean direction for circular data.
+
+    Parameters
+    ----------
+    alpha : np.ndarray
+        Sample of angles in radians
+    w : np.ndarray, optional
+        Weights for each angle (e.g., for binned data). If None, uniform weights assumed.
+    axis : int, optional
+        Compute along this dimension. Default is 0.
+
+    Returns
+    -------
+    mu : float or np.ndarray
+        Mean direction in radians, range [-π, π]
+
+    Examples
+    --------
+    >>> angles = np.array([0, 0.1, 0.2, -0.1, -0.2])
+    >>> mean_angle = circ_mean(angles)
+    >>> print(f"Mean direction: {mean_angle:.3f} rad")
+
+    >>> # Weighted mean
+    >>> angles = np.array([0, np.pi])
+    >>> weights = np.array([3, 1])  # 3x more weight on 0
+    >>> mean_angle = circ_mean(angles, w=weights)
+
+    Notes
+    -----
+    Based on CircStat toolbox circ_mean.m by Philipp Berens (2009)
+    """
+    if w is None:
+        w = np.ones_like(alpha)
+    else:
+        if alpha.ndim > 0 and w.shape != alpha.shape:
+            raise ValueError("Input dimensions do not match")
+
+    # Compute weighted sum of complex exponentials
+    r = np.sum(w * np.exp(1j * alpha), axis=axis)
+
+    # Obtain mean angle from complex sum
+    mu = np.angle(r)
+
+    return mu
+
+
+def circ_std(
+    alpha: np.ndarray, w: np.ndarray | None = None, d: float = 0.0, axis: int = 0
+) -> tuple[float | np.ndarray, float | np.ndarray]:
+    """
+    Compute circular standard deviation for circular data.
+
+    Parameters
+    ----------
+    alpha : np.ndarray
+        Sample of angles in radians
+    w : np.ndarray, optional
+        Weights for each angle. If None, uniform weights assumed.
+    d : float, optional
+        Spacing of bin centers for binned data (correction factor). Default is 0.
+    axis : int, optional
+        Compute along this dimension. Default is 0.
+
+    Returns
+    -------
+    s : float or np.ndarray
+        Angular deviation (equation 26.20, Zar)
+    s0 : float or np.ndarray
+        Circular standard deviation (equation 26.21, Zar)
+
+    Examples
+    --------
+    >>> angles = np.array([0, 0.1, 0.2, -0.1, -0.2])
+    >>> s, s0 = circ_std(angles)
+    >>> print(f"Angular deviation: {s:.3f} rad")
+
+    Notes
+    -----
+    Based on CircStat toolbox circ_std.m by Philipp Berens (2009)
+    References: Biostatistical Analysis, J. H. Zar
+    """
+    if w is None:
+        w = np.ones_like(alpha)
+    else:
+        if w.shape != alpha.shape:
+            raise ValueError("Input dimensions do not match")
+
+    # Compute mean resultant vector length
+    r = circ_r(alpha, w=w, d=d, axis=axis)
+
+    # Compute standard deviations (equations from Zar)
+    s = np.sqrt(2 * (1 - r))  # 26.20 - angular deviation
+    s0 = np.sqrt(-2 * np.log(r))  # 26.21 - circular standard deviation
+
+    return s, s0
+
+
+def circ_dist(x: np.ndarray, y: np.ndarray) -> np.ndarray:
+    """
+    Pairwise angular distance between angles (x_i - y_i) around the circle.
+
+    Computes the shortest signed angular distance from y to x, respecting
+    circular topology (wrapping at ±π).
+
+    Parameters
+    ----------
+    x : np.ndarray
+        First set of angles in radians
+    y : np.ndarray
+        Second set of angles in radians (must be same shape as x, or scalar)
+
+    Returns
+    -------
+    r : np.ndarray
+        Angular distances in radians, range [-π, π]
+
+    Examples
+    --------
+    >>> x = np.array([0.1, np.pi])
+    >>> y = np.array([0.0, -np.pi])  # -π and π are same location
+    >>> dist = circ_dist(x, y)
+    >>> print(dist)  # [0.1, 0.0]
+
+    >>> # Distance wraps around at ±π
+    >>> x = np.array([np.pi - 0.1])
+    >>> y = np.array([-np.pi + 0.1])
+    >>> dist = circ_dist(x, y)
+    >>> print(dist)  # Small value, not 2π - 0.2
+
+    Notes
+    -----
+    Based on CircStat toolbox circ_dist.m by Philipp Berens (2009)
+    References: Biostatistical Analysis, J. H. Zar, p. 651
+    """
+    # Compute angular difference using complex exponentials
+    # This automatically wraps to [-π, π]
+    r = np.angle(np.exp(1j * x) / np.exp(1j * y))
+
+    return r
+
+
+def circ_dist2(x: np.ndarray, y: np.ndarray | None = None) -> np.ndarray:
+    """
+    All pairwise angular distances (x_i - y_j) around the circle.
+
+    Computes the matrix of all pairwise angular distances between two sets
+    of angles, or within one set if y is not provided.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        First set of angles in radians (will be treated as column vector)
+    y : np.ndarray, optional
+        Second set of angles in radians (will be treated as column vector).
+        If None, computes pairwise distances within x. Default is None.
+
+    Returns
+    -------
+    r : np.ndarray
+        Matrix of pairwise angular distances, shape (len(x), len(y))
+        Element (i, j) contains the distance from y[j] to x[i]
+
+    Examples
+    --------
+    >>> x = np.array([0, np.pi/2, np.pi])
+    >>> D = circ_dist2(x)  # All pairwise distances within x
+    >>> print(D.shape)  # (3, 3)
+
+    >>> y = np.array([0, np.pi])
+    >>> D = circ_dist2(x, y)  # All distances from y to x
+    >>> print(D.shape)  # (3, 2)
+
+    Notes
+    -----
+    Based on CircStat toolbox circ_dist2.m by Philipp Berens (2009)
+    """
+    if y is None:
+        y = x
+
+    # Ensure column vectors
+    x = np.atleast_1d(x)
+    y = np.atleast_1d(y)
+
+    if x.ndim == 1:
+        x = x[:, np.newaxis]
+    elif x.shape[1] > x.shape[0]:
+        x = x.T
+
+    if y.ndim == 1:
+        y = y[:, np.newaxis]
+    elif y.shape[1] > y.shape[0]:
+        y = y.T
+
+    # Compute all pairwise distances using broadcasting
+    # Shape: (len(x), len(y))
+    r = np.angle(np.exp(1j * x) / np.exp(1j * y.T))
+
+    return r
+
+
+def circ_rtest(alpha: np.ndarray, w: np.ndarray | None = None) -> float:
+    """
+    Rayleigh test for non-uniformity of circular data.
+
+    H0: The population is uniformly distributed around the circle.
+    HA: The population is not uniformly distributed.
+
+    Parameters
+    ----------
+    alpha : np.ndarray
+        Sample of angles in radians
+    w : np.ndarray, optional
+        Weights for each angle. If None, uniform weights assumed.
+
+    Returns
+    -------
+    pval : float
+        p-value of Rayleigh test. Small values (< 0.05) indicate
+        significant deviation from uniformity.
+
+    Examples
+    --------
+    >>> # Concentrated distribution
+    >>> angles = np.random.normal(0, 0.1, 100)
+    >>> p = circ_rtest(angles)
+    >>> print(f"p-value: {p:.4f}")  # Should be < 0.05
+
+    >>> # Uniform distribution
+    >>> angles = np.random.uniform(-np.pi, np.pi, 100)
+    >>> p = circ_rtest(angles)
+    >>> print(f"p-value: {p:.4f}")  # Should be > 0.05
+
+    Notes
+    -----
+    Test statistic: Z = n * r^2, where n is sample size and r is MVL
+    Approximation for p-value: p ≈ exp(-Z) * (1 + (2*Z - Z^2)/(4*n))
+
+    References: Topics in Circular Statistics, S.R. Jammalamadaka et al., p. 48
+    """
+    if w is None:
+        w = np.ones_like(alpha)
+
+    # Compute MVL
+    r = circ_r(alpha, w=w)
+
+    # Sample size
+    n = len(alpha)
+
+    # Rayleigh test statistic
+    Z = n * r**2
+
+    # Approximate p-value (good for n > 50, reasonable for n > 20)
+    pval = np.exp(-Z) * (
+        1 + (2 * Z - Z**2) / (4 * n) - (24 * Z - 132 * Z**2 + 76 * Z**3 - 9 * Z**4) / (288 * n**2)
+    )
+
+    return pval
+
+
+# Convenience aliases for compatibility
+mvl = circ_r  # Mean Vector Length is same as resultant length
+angular_mean = circ_mean
+angular_std = circ_std
+angular_distance = circ_dist
+
+
+if __name__ == "__main__":
+    # Simple tests
+    print("Testing circular statistics functions...")
+
+    # Test 1: Concentrated distribution
+    angles = np.random.normal(0, 0.1, 100)
+    r = circ_r(angles)
+    mu = circ_mean(angles)
+    s, s0 = circ_std(angles)
+    p = circ_rtest(angles)
+
+    print("\nConcentrated distribution (mean=0, std=0.1):")
+    print(f"  MVL: {r:.3f} (should be close to 1)")
+    print(f"  Mean direction: {mu:.3f} rad (should be close to 0)")
+    print(f"  Angular deviation: {s:.3f} rad")
+    print(f"  Rayleigh test p-value: {p:.4f} (should be < 0.05)")
+
+    # Test 2: Uniform distribution
+    angles = np.random.uniform(-np.pi, np.pi, 100)
+    r = circ_r(angles)
+    p = circ_rtest(angles)
+
+    print("\nUniform distribution:")
+    print(f"  MVL: {r:.3f} (should be close to 0)")
+    print(f"  Rayleigh test p-value: {p:.4f} (should be > 0.05)")
+
+    # Test 3: Angular distances
+    x = np.array([0.1, np.pi])
+    y = np.array([0.0, -np.pi])
+    dist = circ_dist(x, y)
+
+    print("\nAngular distances:")
+    print(f"  dist([0.1, π], [0, -π]) = {dist}")
+    print("  Note: π and -π are the same location, so distance is 0")
+
+    # Test 4: Pairwise distances
+    angles = np.array([0, np.pi / 2, np.pi, -np.pi / 2])
+    D = circ_dist2(angles)
+
+    print(f"\nPairwise distance matrix shape: {D.shape}")
+    print(f"Diagonal should be all zeros: {np.diag(D)}")
+
+    print("\nAll tests completed!")

canns/analyzer/data/cell_classification/utils/correlation.py

@@ -0,0 +1,318 @@
+"""
+Correlation Utilities
+
+Functions for computing Pearson correlation and normalized cross-correlation,
+optimized for neuroscience data analysis.
+"""
+
+import numpy as np
+from scipy import signal
+
+
+def pearson_correlation(x: np.ndarray, y: np.ndarray) -> np.ndarray:
+    """
+    Compute Pearson correlation coefficient between x and each column of y.
+
+    This is an optimized implementation that efficiently handles multiple
+    correlations when y has multiple columns.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        First array, shape (n,) or (n, 1)
+    y : np.ndarray
+        Second array, shape (n,) or (n, m) where m is number of columns
+
+    Returns
+    -------
+    r : np.ndarray
+        Correlation coefficients. If y is 1-D, returns scalar.
+        If y is 2-D with m columns, returns array of shape (m,)
+
+    Examples
+    --------
+    >>> x = np.array([1, 2, 3, 4, 5])
+    >>> y = np.array([2, 4, 6, 8, 10])
+    >>> r = pearson_correlation(x, y)
+    >>> print(f"Correlation: {r:.3f}")  # Should be 1.0
+
+    >>> # Multiple correlations at once
+    >>> y_multi = np.column_stack([
+    ...     [2, 4, 6, 8, 10],  # Perfect positive correlation
+    ...     [5, 4, 3, 2, 1],   # Perfect negative correlation
+    ... ])
+    >>> r = pearson_correlation(x, y_multi)
+    >>> print(r)  # [1.0, -1.0]
+
+    Notes
+    -----
+    Based on corrPearson.m from the MATLAB codebase.
+    Normalization factor (n-1) omitted since we renormalize anyway.
+    """
+    # Ensure arrays are at least 2D for matrix operations
+    x = np.atleast_2d(x)
+    y = np.atleast_2d(y)
+
+    # If x or y were passed as row vectors, transpose them
+    if x.shape[0] == 1:
+        x = x.T
+    if y.shape[0] == 1:
+        y = y.T
+
+    n = x.shape[0]
+
+    # Center the data (remove mean)
+    x = x - np.sum(x, axis=0) / n
+    y = y - np.sum(y, axis=0) / n
+
+    # Compute correlation: x^T * y
+    r = x.T @ y  # Shape: (1, m) if x is column, y has m columns
+
+    # Compute norms
+    dx = np.linalg.norm(x, axis=0, keepdims=True)  # Shape: (1,) or (1, k)
+    dy = np.linalg.norm(y, axis=0, keepdims=True)  # Shape: (1, m)
+
+    # Normalize: r / (dx * dy)
+    # Broadcasting handles the division correctly
+    r = r / dx.T  # Divide by dx (column-wise)
+    r = r / dy  # Divide by dy (row-wise)
+
+    # Return as 1D array or scalar
+    r = np.squeeze(r)
+
+    return r
+
+
+def normalized_xcorr2(
+    template: np.ndarray, image: np.ndarray, mode: str = "same", min_overlap: int = 0
+) -> np.ndarray:
+    """
+    Normalized 2D cross-correlation.
+
+    Computes the normalized cross-correlation of two 2D arrays. Unlike
+    scipy.signal.correlate, this function properly handles varying overlap
+    regions and works correctly even when template and image are the same size.
+
+    Parameters
+    ----------
+    template : np.ndarray
+        2D template array
+    image : np.ndarray
+        2D image array
+    mode : str, optional
+        'full' - full correlation (default for autocorrelation)
+        'same' - output size same as image
+        'valid' - only where template fully overlaps image
+    min_overlap : int, optional
+        Minimum number of overlapping pixels required for valid correlation.
+        Locations with fewer overlapping pixels are set to 0.
+        Default is 0 (no threshold).
+
+    Returns
+    -------
+    C : np.ndarray
+        Normalized cross-correlation. Values range from -1 to 1.
+
+    Examples
+    --------
+    >>> # Autocorrelation (template = image)
+    >>> image = np.random.rand(50, 50)
+    >>> autocorr = normalized_xcorr2(image, image, mode='full')
+    >>> # Peak should be at center with value 1.0
+    >>> center = np.array(autocorr.shape) // 2
+    >>> print(f"Peak value: {autocorr[tuple(center)]:.3f}")
+
+    >>> # Template matching
+    >>> image = np.random.rand(100, 100)
+    >>> template = image[40:60, 40:60]  # Extract 20x20 patch
+    >>> corr = normalized_xcorr2(template, image)
+    >>> # Should find the template location
+
+    Notes
+    -----
+    This is a simplified Python implementation. For the full general version
+    (handling all edge cases), see normxcorr2_general.m by Dirk Padfield.
+
+    For most neuroscience applications (autocorrelation of rate maps),
+    scipy.signal.correlate with normalization is sufficient.
+
+    References
+    ----------
+    Padfield, D. "Masked FFT registration". CVPR, 2010.
+    Lewis, J.P. "Fast Normalized Cross-Correlation". Industrial Light & Magic.
+    """
+    # Convert to double for numerical stability
+    template = np.asarray(template, dtype=np.float64)
+    image = np.asarray(image, dtype=np.float64)
+
+    # Ensure arrays are 2D
+    if template.ndim != 2 or image.ndim != 2:
+        raise ValueError("Both template and image must be 2D arrays")
+
+    # Check for flat template (no variation)
+    if np.std(template) == 0:
+        raise ValueError("Template cannot have all identical values")
+
+    # For neuroscience applications, we typically use FFT-based correlation
+    # which is faster for larger arrays
+    if mode == "full":
+        # Full correlation (output larger than both inputs)
+        C = signal.correlate(image, template, mode="full", method="fft")
+
+        # Compute normalization factors
+        # This is a simplified normalization; full version would handle
+        # varying overlap regions precisely
+        n_template = template.size
+        template_mean = np.mean(template)
+        template_std = np.std(template)
+
+        image_mean = np.mean(image)
+        image_std = np.std(image)
+
+        # Normalize
+        if template_std > 0 and image_std > 0:
+            C = (C - n_template * template_mean * image_mean) / (
+                n_template * template_std * image_std
+            )
+
+    else:
+        # For 'same' or 'valid', use scipy's built-in
+        C = signal.correlate(image, template, mode=mode, method="fft")
+
+        # Simple normalization (assumes full overlap in valid region)
+        template_norm = np.sqrt(np.sum(template**2))
+        image_norm = np.sqrt(np.sum(image**2))
+
+        if template_norm > 0 and image_norm > 0:
+            C = C / (template_norm * image_norm)
+
+    # Clip to valid correlation range
+    C = np.clip(C, -1, 1)
+
+    return C
+
+
+def autocorrelation_2d(
+    array: np.ndarray, overlap: float = 0.8, normalize: bool = True
+) -> np.ndarray:
+    """
+    Compute 2D autocorrelation of an array.
+
+    This is a convenience function specifically for computing spatial
+    autocorrelation of firing rate maps, which is needed for grid cell analysis.
+
+    Parameters
+    ----------
+    array : np.ndarray
+        2D array (e.g., firing rate map)
+    overlap : float, optional
+        Percentage of overlap region to keep (0-1). Default is 0.8.
+        The autocorrelogram is cropped to this central region to avoid
+        edge artifacts.
+    normalize : bool, optional
+        Whether to normalize the correlation. Default is True.
+
+    Returns
+    -------
+    autocorr : np.ndarray
+        2D autocorrelation array
+
+    Examples
+    --------
+    >>> # Create a simple periodic pattern (grid-like)
+    >>> x = np.linspace(0, 4*np.pi, 50)
+    >>> xx, yy = np.meshgrid(x, x)
+    >>> pattern = np.cos(xx) * np.cos(yy)
+    >>> autocorr = autocorrelation_2d(pattern)
+    >>> # Autocorr should show hexagonal/grid pattern
+
+    Notes
+    -----
+    Based on autocorrelation.m from the MATLAB codebase.
+    Replaces NaN values with 0 before computing correlation.
+    """
+    # Replace NaN with 0
+    array = np.nan_to_num(array, nan=0.0)
+
+    # Compute new size for overlap region
+    new_size_v = int(np.round(array.shape[0] * (1 + overlap)))
+    new_size_h = int(np.round(array.shape[1] * (1 + overlap)))
+
+    # Ensure odd dimensions for symmetry
+    if new_size_v % 2 == 0 and new_size_v > 0:
+        new_size_v -= 1
+    if new_size_h % 2 == 0 and new_size_h > 0:
+        new_size_h -= 1
+
+    # Handle empty or all-zero arrays
+    if array.size == 0 or np.all(array == 0):
+        return np.zeros((new_size_v, new_size_h))
+
+    # Subtract mean for proper autocorrelation
+    # This is crucial for grid cell analysis - ensures the autocorrelation
+    # captures the spatial periodicity rather than the mean firing rate
+    array_demean = array - np.mean(array)
+
+    # Compute full autocorrelation
+    Rxx = signal.correlate(array_demean, array_demean, mode="full", method="fft")
+
+    # Extract central overlap region first
+    offset_v = (Rxx.shape[0] - new_size_v) // 2
+    offset_h = (Rxx.shape[1] - new_size_h) // 2
+
+    if offset_v >= 0 and offset_h >= 0:
+        Rxx = Rxx[offset_v : offset_v + new_size_v, offset_h : offset_h + new_size_h]
+    else:
+        # If requested size is larger than autocorr, just return full
+        pass
+
+    # Normalize by the center (zero-lag) value
+    if normalize:
+        center_v = Rxx.shape[0] // 2
+        center_h = Rxx.shape[1] // 2
+        center_value = Rxx[center_v, center_h]
+
+        if center_value > 0:
+            Rxx = Rxx / center_value
+
+    return Rxx
+
+
+if __name__ == "__main__":
+    # Simple tests
+    print("Testing correlation functions...")
+
+    # Test 1: Pearson correlation
+    x = np.array([1, 2, 3, 4, 5], dtype=float)
+    y = np.array([2, 4, 6, 8, 10], dtype=float)
+    r = pearson_correlation(x, y)
+    print(f"\nTest 1 - Perfect positive correlation: r = {r:.3f} (should be 1.0)")
+
+    # Test 2: Multiple correlations
+    y_multi = np.column_stack(
+        [
+            [2, 4, 6, 8, 10],  # Perfect positive
+            [5, 4, 3, 2, 1],  # Perfect negative
+            [1, 1, 1, 1, 1],  # Constant (should be NaN or 0)
+        ]
+    )
+    r_multi = pearson_correlation(x, y_multi[:, :2])  # Skip constant
+    print(f"\nTest 2 - Multiple correlations: r = {r_multi} (should be [1.0, -1.0])")
+
+    # Test 3: 2D autocorrelation
+    # Create a simple grid-like pattern
+    x_coords = np.linspace(0, 4 * np.pi, 30)
+    xx, yy = np.meshgrid(x_coords, x_coords)
+    grid_pattern = np.cos(xx) * np.cos(yy)
+
+    autocorr = autocorrelation_2d(grid_pattern)
+    print("\nTest 3 - 2D Autocorrelation:")
+    print(f"  Input shape: {grid_pattern.shape}")
+    print(f"  Autocorr shape: {autocorr.shape}")
+    print(f"  Autocorr max: {np.max(autocorr):.3f} (should be close to 1.0 at center)")
+
+    # Center should have maximum correlation
+    center = np.array(autocorr.shape) // 2
+    print(f"  Center value: {autocorr[tuple(center)]:.3f}")
+
+    print("\nAll tests completed!")