commsubspace 0.1.0__tar.gz

commsubspace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Eliezyer de Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commsubspace-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: commsubspace
+Version: 0.1.0
+Summary: Communication subspaces between neural populations: CCA, reduced-rank regression and contrastive communication subspaces (cCS).
+Author-email: Eliezyer de Oliveira <eliezyer.deoliveira@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eliezyer/commsubspace
+Project-URL: Issues, https://github.com/eliezyer/commsubspace/issues
+Keywords: neuroscience,communication subspace,CCA,reduced rank regression,contrastive
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Dynamic: license-file
+
+# contrastive communication subspace
+
+Python code for **contrastive communication subspace** and also implementations of regular communication subspace (CS) analysis between two neural populations (region 1 and region 2):
+
+- `ReducedRankRegress` - reduced-rank regression (RRR) from region 1 to region 2. The original method used for CS in Semedo et al., 2019
+- `CrossDecomposition` - CCA (`method='correlation'`) and PLS-SVD (`method='covariance'`). Other ways of achieving CS
+- `cCS` - **contrastive communication subspace**: finds pairs of directions whose coupling between the two regions differs most between two conditions (A and B). Objectives: `'difference'`, `'ratio'`, `'normalized_difference'` and `'normalized_index'`.
+
+All data arrays are `(n_samples, n_features)`.
+
+## Installation
+
+```bash
+pip install commsubspace
+```
+
+Requires Python >= 3.10, NumPy, SciPy and scikit-learn.
+
+## Quick start
+
+```python
+import numpy as np
+from commsubspace import cCS, CrossDecomposition, ReducedRankRegress
+
+rng = np.random.default_rng(0)
+region1_A, region2_A = rng.standard_normal((500, 20)), rng.standard_normal((500, 15))  # condition A
+region1_B, region2_B = rng.standard_normal((400, 20)), rng.standard_normal((400, 15))  # condition B
+
+# Contrastive communication subspace: coupling that differs between conditions A and B.
+ccs = cCS(method="normalized_index").fit(region1_A, region2_A, region1_B, region2_B)
+print(ccs.region1_loadings_.shape, ccs.contrast_values_.shape)  # (20, N_dim), (N_dim,)
+
+# Canonical correlation analysis between the two regions (condition A only).
+cca = CrossDecomposition(method="correlation").fit(region1_A, region2_A)
+scores_region1, scores_region2 = cca.transform(region1_A, region2_A)
+
+# Reduced-rank regression of region 2 on region 1, with 3 predictive dimensions.
+rrr = ReducedRankRegress(rank=3).fit(region1_A, region2_A)
+predicted_region2 = rrr.predict(region1_A)
+```
+
+See the docstrings of `cCS`, `CrossDecomposition` and `ReducedRankRegress` for all options, fitted attributes and
+units. Fitted `cCS` objects carry a `meta_` dictionary with the parameters, random seed and analysis version.
+
+## License
+
+MIT, see `LICENSE`.

commsubspace-0.1.0/README.md

@@ -0,0 +1,47 @@
+# contrastive communication subspace
+
+Python code for **contrastive communication subspace** and also implementations of regular communication subspace (CS) analysis between two neural populations (region 1 and region 2):
+
+- `ReducedRankRegress` - reduced-rank regression (RRR) from region 1 to region 2. The original method used for CS in Semedo et al., 2019
+- `CrossDecomposition` - CCA (`method='correlation'`) and PLS-SVD (`method='covariance'`). Other ways of achieving CS
+- `cCS` - **contrastive communication subspace**: finds pairs of directions whose coupling between the two regions differs most between two conditions (A and B). Objectives: `'difference'`, `'ratio'`, `'normalized_difference'` and `'normalized_index'`.
+
+All data arrays are `(n_samples, n_features)`.
+
+## Installation
+
+```bash
+pip install commsubspace
+```
+
+Requires Python >= 3.10, NumPy, SciPy and scikit-learn.
+
+## Quick start
+
+```python
+import numpy as np
+from commsubspace import cCS, CrossDecomposition, ReducedRankRegress
+
+rng = np.random.default_rng(0)
+region1_A, region2_A = rng.standard_normal((500, 20)), rng.standard_normal((500, 15))  # condition A
+region1_B, region2_B = rng.standard_normal((400, 20)), rng.standard_normal((400, 15))  # condition B
+
+# Contrastive communication subspace: coupling that differs between conditions A and B.
+ccs = cCS(method="normalized_index").fit(region1_A, region2_A, region1_B, region2_B)
+print(ccs.region1_loadings_.shape, ccs.contrast_values_.shape)  # (20, N_dim), (N_dim,)
+
+# Canonical correlation analysis between the two regions (condition A only).
+cca = CrossDecomposition(method="correlation").fit(region1_A, region2_A)
+scores_region1, scores_region2 = cca.transform(region1_A, region2_A)
+
+# Reduced-rank regression of region 2 on region 1, with 3 predictive dimensions.
+rrr = ReducedRankRegress(rank=3).fit(region1_A, region2_A)
+predicted_region2 = rrr.predict(region1_A)
+```
+
+See the docstrings of `cCS`, `CrossDecomposition` and `ReducedRankRegress` for all options, fitted attributes and
+units. Fitted `cCS` objects carry a `meta_` dictionary with the parameters, random seed and analysis version.
+
+## License
+
+MIT, see `LICENSE`.

commsubspace-0.1.0/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-0.1.0/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-0.1.0/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())