commsubspace 0.3.0__tar.gz → 0.4.0__tar.gz

{commsubspace-0.3.0 → commsubspace-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commsubspace
-Version: 0.3.0
+Version: 0.4.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

{commsubspace-0.3.0 → commsubspace-0.4.0}/commsubspace/__init__.py

@@ -5,6 +5,6 @@ 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.3.0"
+__version__ = "0.4.0"
 
 __all__ = ["cCS", "CrossDecomposition", "ReducedRankRegress", "__version__"]

{commsubspace-0.3.0 → commsubspace-0.4.0}/commsubspace/contrastive_communication_subspace.py

@@ -24,12 +24,21 @@ condition, of either sign, lies inside it. By default the basis is truncated
 by numerical rank (condition number; ``basis_truncation='condition_number'``,
 tolerance ``max(shape) * eps`` like ``numpy.linalg.matrix_rank``).
 
-Noise floor (advanced, off by default)
---------------------------------------
-``noise_floor`` ('none' by default; 'analytic', 'shuffle', or a number) lets users
-who want to control weakly coupled directions put a lower bound on the singular
-values that enter the denominators of the generalized objectives. With the
-default 'none' the denominators are used as estimated. See the class docstring.
+Noise floor (on by default)
+---------------------------
+``noise_floor`` ('analytic' by default; 'shuffle', 'none', or a number) puts a lower
+bound on the singular values that enter the denominators of the generalized
+objectives, so directions that are pure noise in one condition cannot reach large
+contrast values. With 'none' the denominators are used as estimated. See the
+class docstring.
+
+Component order
+---------------
+Components are sorted by signed sigma, sigma * sign(dominance_), descending:
+components whose coupling is stronger in A come first, in decreasing sigma;
+components stronger in B come last, the one with the largest sigma at the very end.
+A component whose coupling flips sign between conditions has |a| ~ |b|, so its
+dominance_ is near 0 and its sign, hence its position (front or end), is arbitrary.
 
 Attributes set by ``fit`` (trailing underscore = fitted):
     region1_loadings_, region2_loadings_ : unit-norm loadings, (p, N_dim) and (q, N_dim),
@@ -40,7 +49,11 @@ Attributes set by ``fit`` (trailing underscore = fitted):
         > 0: coupling stronger in A, < 0: stronger in B
     sign_reversal_ : bool, (N_dim,); True where a * b < 0 (coupling flips sign between
         conditions; dominance_ is then near 0 although sigma can be large)
-    All component-wise attributes are sorted by dominance_, descending (A-dominant first).
+    signed_sigma_ : sigma * sign(dominance_) per component, (N_dim,), units of sigma;
+        the sort key of the components (non-increasing): > 0 for A-dominant,
+        < 0 for B-dominant components
+    All component-wise attributes are sorted by sigma * sign(dominance_), descending
+        (A-dominant first by sigma, B-dominant last; see "Component order").
     region{1,2}_scores_cond{A,B} : fitted data projected on the loadings, (n_samples, N_dim)
     region1_basis_, region2_basis_ : orthonormal support bases, (p, m1) and (q, m2)
     basis_dims_ : (m1, m2)
@@ -63,7 +76,10 @@ from ._linalg import floored_polar_roots, psd_inverse_sqrt_factor
 from ._noise_floor import (analytic_noise_floor, random_circular_shift,
                            shuffle_noise_floor)
 
-ANALYSIS_VERSION = "cCS-0.3.0"  # 0.3.0: components sorted by dominance_ instead of contrast value
+# 0.3.0: components sorted by dominance_ instead of contrast value.
+# 0.4.0: components sorted by signed sigma (sigma * sign(dominance_)); noise_floor
+#        defaults to 'analytic' instead of 'none'.
+ANALYSIS_VERSION = "cCS-0.4.0"
 
 _METHODS = ('difference', 'ratio', 'normalized_difference', 'normalized_index')
 _NOISE_FLOOR_MODES = ('analytic', 'shuffle', 'none')
@@ -112,20 +128,20 @@ class cCS:
         for ``shuffle_null``.
     random_state : int
         Seed of the random generator used by the shuffle procedures.
-    noise_floor : {'none', 'analytic', 'shuffle'}, float or (float, float)
-        Advanced option, off by default. Controls a lower bound ("floor") on the
-        singular values of each condition's cross-covariance as they enter the
-        denominators of the generalized objectives ('ratio',
-        'normalized_difference', 'normalized_index'); it does not change the
-        numerator, the support basis (unless ``basis_truncation='noise_floor'``)
-        or the 'difference' method.
-        'none' (default): denominators are used as estimated; directions in which a
-        denominator is numerically zero (``condition_number_tol`` rule) are left
-        out of the solution.
-        'analytic': floor from a random-matrix estimate of the cross-covariance
-        estimation error, see ``_noise_floor``. It is a coarse, global estimate
-        that assumes independent samples and can penalize weak but real
-        directions, so compare against 'none' before relying on it.
+    noise_floor : {'analytic', 'shuffle', 'none'}, float or (float, float)
+        Lower bound ("floor") on the singular values of each condition's
+        cross-covariance as they enter the denominators of the generalized
+        objectives ('ratio', 'normalized_difference', 'normalized_index'); it does
+        not change the numerator, the support basis (unless
+        ``basis_truncation='noise_floor'``) or the 'difference' method.
+        'analytic' (default since 0.4.0): floor from a random-matrix estimate of
+        the cross-covariance estimation error, see ``_noise_floor``. It is a
+        coarse, global estimate that assumes independent samples (set
+        ``effective_n`` for autocorrelated data, otherwise the floor is too low)
+        and can penalize weak but real directions.
+        'none' (default up to 0.3.0): denominators are used as estimated;
+        directions in which a denominator is numerically zero
+        (``condition_number_tol`` rule) are left out of the solution.
         'shuffle': floor from circularly shifted data (``n_shuffles`` shifts,
         seeded).
         A float, or a (tau_A, tau_B) pair, is used as given, in the units of the
@@ -138,7 +154,7 @@ class cCS:
     def __init__(self, method='difference', normalize=True, alpha=1.0,
                  max_cond_number=None, basis_truncation='condition_number',
                  condition_number_tol=None, truncate_basis=True, max_basis_dim=None,
-                 effective_n=None, n_shuffles=50, random_state=0, noise_floor='none'):
+                 effective_n=None, n_shuffles=50, random_state=0, noise_floor='analytic'):
         if max_cond_number is not None:
             warnings.warn("max_cond_number is deprecated and ignored; regularization is "
                           "now controlled by noise_floor.", DeprecationWarning, stacklevel=2)
@@ -241,7 +257,7 @@ class cCS:
         -------
         ndarray, (n_shuffles, N_dim)
             Surrogate objective values (sigma) for the first ``N_dim`` components,
-            each surrogate sorted by its own ``dominance_`` like the fit
+            each surrogate sorted by its own signed sigma like the fit
             (zero-padded if a surrogate has fewer components).
         """
         n_shuffles = self.n_shuffles if n_shuffles is None else n_shuffles
@@ -361,7 +377,8 @@ class cCS:
     def _set_loadings_and_scores(self, contrast_vectors_1, contrast_vectors_2,
                                  region1_A, region2_A, region1_B, region2_B):
         """Map components back to feature space (unit norm), project the fit data, and
-        sort all components by ``dominance_`` (A-dominant first, B-dominant last)."""
+        sort all components by signed sigma, sigma * sign(dominance_), descending
+        (A-dominant first in sigma order, B-dominant last, the largest-sigma one at the end)."""
         loadings_1 = self.region1_basis_ @ contrast_vectors_1  # (p, N_dim)
         loadings_2 = self.region2_basis_ @ contrast_vectors_2  # (q, N_dim)
         self.region1_loadings_ = loadings_1 / norm(loadings_1, axis=0)
@@ -377,13 +394,15 @@ class cCS:
         self.dominance_ = (np.abs(coupling_A) - np.abs(coupling_B)) / (np.abs(coupling_A) + np.abs(coupling_B))
         self.sign_reversal_ = coupling_A * coupling_B < 0
 
-        # Reorder every component-wise output by dominance, descending.
-        order = np.argsort(-self.dominance_, kind='stable')
+        # Reorder every component-wise output by signed sigma, descending.
+        signed_sigma = self.contrast_values_ * np.sign(self.dominance_)
+        order = np.argsort(-signed_sigma, kind='stable')
         for name in ('region1_loadings_', 'region2_loadings_', 'region1_scores_condA', 'region2_scores_condA',
                      'region1_scores_condB', 'region2_scores_condB', 'contrast_values_', 'dominance_',
                      'sign_reversal_'):
             setattr(self, name, getattr(self, name)[..., order])
         self.sigma_ = self.contrast_values_
+        self.signed_sigma_ = self.contrast_values_ * np.sign(self.dominance_)  # (N_dim,) sort key, in fitted order
 
     def _build_meta(self):
         """Metadata describing how the fitted result was produced."""

{commsubspace-0.3.0 → commsubspace-0.4.0}/commsubspace.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commsubspace
-Version: 0.3.0
+Version: 0.4.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

{commsubspace-0.3.0 → commsubspace-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "commsubspace"
-version = "0.3.0"
+version = "0.4.0"
 description = "Communication subspaces between neural populations: CCA, reduced-rank regression and contrastive communication subspaces (cCS)."
 readme = "README.md"
 license = "MIT"