commsubspace 0.1.0__py3-none-any.whl

commsubspace/__init__.py

@@ -0,0 +1,10 @@
+# commsubspace/__init__.py
+# Public API of the commsubspace package (communication subspaces between two neural populations).
+
+from .communication_subspace import CrossDecomposition, ReducedRankRegress
+from .contrastive_communication_subspace import cCS
+
+# Keep in sync with ``version`` in pyproject.toml (checked by tests/test_packaging.py).
+__version__ = "0.1.0"
+
+__all__ = ["cCS", "CrossDecomposition", "ReducedRankRegress", "__version__"]

commsubspace/_linalg.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""Small linear-algebra helpers shared by the contrastive communication subspace."""
+
+import numpy as np
+
+
+def psd_inverse_sqrt_factor(matrix, relative_tolerance):
+    """Whitening factor F of a PSD matrix on its numerical range: F^T M F = I.
+
+    With M = Q diag(lambda) Q^T, F = Q_r diag(lambda_r)^(-1/2) where only the
+    eigenvalues above ``relative_tolerance * max(lambda)`` are kept (numerical rank,
+    the same condition-number rule as ``numpy.linalg.matrix_rank``). Directions in
+    which M is numerically zero are left out, so no ridge is needed.
+
+    Parameters
+    ----------
+    matrix : ndarray, shape (m, m)
+        Symmetric positive semi-definite matrix (units: those of the matrix).
+    relative_tolerance : float
+        Relative eigenvalue cutoff in (0, 1).
+
+    Returns
+    -------
+    ndarray, shape (m, r)
+        Factor with r = numerical rank of ``matrix``; columns are Q_r / sqrt(lambda_r).
+        Units: 1 / sqrt(units of ``matrix``).
+    """
+    eigenvalues, eigenvectors = np.linalg.eigh(matrix)
+    kept = eigenvalues > relative_tolerance * eigenvalues.max()
+    return eigenvectors[:, kept] / np.sqrt(eigenvalues[kept])
+
+
+def floored_polar_roots(matrix, floor):
+    """Square roots sqrt(M M^T) and sqrt(M^T M) of a rectangular matrix via its SVD.
+
+    Taking the SVD of ``M`` directly (instead of eigen-decomposing M M^T) keeps small
+    singular values accurate: forming M M^T squares the round-off error, so a true
+    singular value of 1e-12 would be reported as about 1e-8.
+
+    Parameters
+    ----------
+    matrix : ndarray, shape (m, n)
+        Real matrix (e.g. a cross-covariance between region 1 and region 2).
+    floor : float
+        Lower bound applied to every eigenvalue of both roots, including those of
+        directions outside the range of ``matrix`` (whose singular value is 0). Same
+        units as the singular values of ``matrix``. ``0`` gives the plain roots.
+
+    Returns
+    -------
+    left_root : ndarray, shape (m, m)
+        U diag(max(s, floor)) U^T, equal to sqrt(M M^T) when floor = 0.
+    right_root : ndarray, shape (n, n)
+        V diag(max(s, floor)) V^T, equal to sqrt(M^T M) when floor = 0.
+    """
+    left_vectors, singular_values, right_vectors_t = np.linalg.svd(matrix, full_matrices=True)
+    n_rows, n_cols = matrix.shape
+    left_values = np.full(n_rows, 0.0)
+    left_values[:singular_values.size] = singular_values
+    right_values = np.full(n_cols, 0.0)
+    right_values[:singular_values.size] = singular_values
+    left_root = (left_vectors * np.maximum(left_values, floor)) @ left_vectors.T
+    right_root = (right_vectors_t.T * np.maximum(right_values, floor)) @ right_vectors_t
+    return left_root, right_root

commsubspace/_noise_floor.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""Noise floors for cross-covariance matrices.
+
+A "noise floor" is the size (largest singular value) that a cross-covariance
+matrix of two *unrelated* populations would reach just from finite-sample
+estimation error. Singular values below it cannot be told apart from noise.
+
+Two estimates are provided:
+
+* analytic: random-matrix edge  (sqrt(p) + sqrt(q)) for a p x q matrix of
+  independent unit-variance entries (Davidson & Szarek 2001; Vershynin 2018,
+  High-Dimensional Probability, Sec. 4.4; asymptotics: Bai & Yin 1993).
+  Assumes independent samples and white signals (see ``effective_n``).
+* shuffle: top singular value of the cross-covariance after circularly shifting
+  one region in time; preserves autocorrelation of each region and destroys
+  their coupling.
+
+All cross-covariances here are "sum type", C = R1^T R2 (no division by the number
+of samples), the same convention used by ``cCS``.
+"""
+
+import numpy as np
+
+
+def analytic_noise_floor(n_samples, n_features_1, n_features_2, std_1, std_2,
+                         effective_n=None):
+    """Analytic noise floor of the sum-type cross-covariance R1^T R2.
+
+    For independent, white signals the entries of R1^T R2 have standard
+    deviation sqrt(n_samples) * std_1 * std_2, and the largest singular value of
+    such a matrix is about (sqrt(p) + sqrt(q)) times that. With autocorrelated
+    samples, the effective number of independent samples ``effective_n`` replaces
+    ``n_samples`` inside the square root of the estimation error:
+    floor = n_samples * std_1 * std_2 * (sqrt(p) + sqrt(q)) / sqrt(effective_n).
+
+    Parameters
+    ----------
+    n_samples : int
+        Number of samples T of the condition.
+    n_features_1, n_features_2 : int
+        Number of features p (region 1) and q (region 2).
+    std_1, std_2 : float
+        Root-mean-square column standard deviation of region 1 and region 2
+        (same units as the data). For unit-norm columns this is 1/sqrt(T).
+    effective_n : float or None
+        Effective number of independent samples. ``None`` means ``n_samples``.
+
+    Returns
+    -------
+    float
+        Noise floor in the units of R1^T R2 (data units squared, or
+        correlation units when columns have unit norm).
+    """
+    if effective_n is None:
+        effective_n = n_samples
+    edge = np.sqrt(n_features_1) + np.sqrt(n_features_2)
+    return float(n_samples * std_1 * std_2 * edge / np.sqrt(effective_n))
+
+
+def random_circular_shift(data, rng, min_fraction=0.1):
+    """Circularly shift ``data`` along time by a random lag.
+
+    Parameters
+    ----------
+    data : ndarray, shape (n_samples, n_features)
+    rng : numpy.random.Generator
+    min_fraction : float
+        The shift is drawn uniformly from [min_fraction * n_samples,
+        (1 - min_fraction) * n_samples] so the shifted copy is never nearly
+        aligned with the original.
+
+    Returns
+    -------
+    ndarray, shape (n_samples, n_features)
+        Row-rolled copy of ``data`` (same units).
+    """
+    n_samples = data.shape[0]
+    lowest = max(1, int(min_fraction * n_samples))
+    highest = max(lowest + 1, n_samples - lowest + 1)
+    return np.roll(data, int(rng.integers(lowest, highest)), axis=0)
+
+
+def shuffle_noise_floor(region1, region2, n_shuffles, rng):
+    """Noise floor from circularly shifting region 2 relative to region 1.
+
+    Parameters
+    ----------
+    region1 : ndarray, shape (n_samples, p)
+    region2 : ndarray, shape (n_samples, q)
+        Same rows as ``region1`` (simultaneous samples), same units as used for
+        the cross-covariance being floored.
+    n_shuffles : int
+        Number of random circular shifts.
+    rng : numpy.random.Generator
+        Source of the random shifts (seed it for reproducibility).
+
+    Returns
+    -------
+    float
+        Mean over shuffles of the largest singular value of
+        region1^T shift(region2), in the units of region1^T region2.
+    """
+    top_singular_values = np.empty(n_shuffles)
+    for index in range(n_shuffles):
+        shifted = random_circular_shift(region2, rng)
+        top_singular_values[index] = np.linalg.svd(region1.T @ shifted, compute_uv=False)[0]
+    return float(top_singular_values.mean())