brainstat 0.5.2__tar.gz → 0.6.0__tar.gz

{brainstat-0.5.2/brainstat.egg-info → brainstat-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainstat
-Version: 0.5.2
+Version: 0.6.0
 Summary: A toolbox for statistical analysis of neuroimaging data
 Home-page: https://github.com/MICA-LAB/BrainStat
 Author: MNI-MICA Lab and MPI-CNG Lab
@@ -26,8 +26,8 @@ Requires-Dist: neurosynth
 Requires-Dist: nibabel
 Requires-Dist: nilearn>=0.7.0
 Requires-Dist: nimare
-Requires-Dist: numpy>=1.21
-Requires-Dist: pandas>=1.3
+Requires-Dist: numpy<2,>=1.21
+Requires-Dist: pandas<2.1,>=1.3
 Requires-Dist: scikit_learn>=1.0
 Requires-Dist: scipy>=1.7
 Requires-Dist: templateflow

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/__init__.py

@@ -1,2 +1,2 @@
 """Neuroimaging statistics toolbox."""
-__version__ = "0.5.2"
+__version__ = "0.6.0"

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/context/histology.py

@@ -114,6 +114,7 @@ def read_histology_profile(
     data_dir: Optional[Union[str, Path]] = None,
     template: str = "fsaverage",
     overwrite: bool = False,
+    invert: bool = True,
 ) -> np.ndarray:
     """Reads BigBrain histology profiles.
 
@@ -127,6 +128,15 @@ def read_histology_profile(
         default 'fsaverage'.
     overwrite : bool, optional
         If true, existing data will be overwrriten, by default False.
+    invert : bool, optional
+        If True (default), invert the 8-bit intensity values so that higher
+        numbers correspond to darker, more cell-dense regions, matching the
+        convention used in Paquola et al. 2021 (eLife) and most downstream
+        BigBrain analyses. The raw BigBrainWarp data uses the opposite
+        convention (0 = black). Set to False to return the raw values. MPC
+        and gradient computations (correlation-based) are invariant to this
+        flip; only direct inspection of profile intensities is affected.
+        See https://github.com/MICA-MNI/BrainStat/issues/274 for context.
 
     Returns
     -------
@@ -169,12 +179,19 @@ def read_histology_profile(
             profiles = h5_file.get("fs_LR_64k")[...]
         else:
             profiles = h5_file.get(template)[...]
-        if civet_template:
-            fsaverage_surface = fetch_template_surface("fsaverage")
-            civet_surface = fetch_template_surface(civet_template)
-            return _surf2surf(fsaverage_surface, civet_surface, profiles.T).T
-        else:
-            return profiles
+
+    if invert:
+        # Map from BigBrainWarp convention (low = dark/dense) to the
+        # literature convention (high = dark/dense). The data is unsigned
+        # 8-bit, so the inversion is `255 - x`.
+        max_value = np.iinfo(profiles.dtype).max if np.issubdtype(profiles.dtype, np.integer) else 255
+        profiles = max_value - profiles
+
+    if civet_template:
+        fsaverage_surface = fetch_template_surface("fsaverage")
+        civet_surface = fetch_template_surface(civet_template)
+        return _surf2surf(fsaverage_surface, civet_surface, profiles.T).T
+    return profiles
 
 
 def download_histology_profiles(

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/datasets/base.py

@@ -111,12 +111,15 @@ def fetch_parcellation(
         The surface template. Valid values are "fsaverage", "fsaverage5",
         "fsaverage6", "fslr32k", "civet41k", "civet164k", by default "fsaverage5".
     atlas : str
-        Name of the atlas. Valid names are "cammoun", "glasser", "schaefer", "yeo".
+        Name of the atlas. Valid names are "cammoun", "destrieux", "glasser",
+        "schaefer", "yeo".
     n_regions : int
         Number of regions of the requested atlas. Valid values for the cammoun
         atlas are 33, 60, 125, 250, 500. Valid values for the glasser atlas are
         360. Valid values for the "schaefer" atlas are 100, 200, 300, 400, 500,
-        600, 800, 1000. Valid values for "yeo" are 7 and 17.
+        600, 800, 1000. Valid values for "yeo" are 7 and 17. The
+        "destrieux" atlas (a2009s, FreeSurfer's 75 cortical labels per
+        hemisphere) ignores ``n_regions``.
     join : bool, optional
         If true, returns parcellation as a single array, if false, returns an
         array per hemisphere, by default True.
@@ -154,6 +157,8 @@ def fetch_parcellation(
         parcellations = _fetch_glasser_parcellation(template, data_dir)
     elif atlas == "yeo":
         parcellations = _fetch_yeo_parcellation(template, n_regions, data_dir)
+    elif atlas == "destrieux":
+        parcellations = _fetch_destrieux_parcellation(template, data_dir)
     else:
         raise ValueError(f"Invalid atlas: {atlas}")
 
@@ -537,6 +542,48 @@ def _fetch_glasser_parcellation(template: str, data_dir: Path) -> List[np.ndarra
     return parcellations
 
 
+def _fetch_destrieux_parcellation(
+    template: str, data_dir: Path
+) -> List[np.ndarray]:
+    """Fetches the Destrieux 2009 (FreeSurfer ``aparc.a2009s``) parcellation.
+
+    Uses :func:`nilearn.datasets.fetch_atlas_surf_destrieux`, which provides
+    the parcellation on the ``fsaverage5`` surface. For other ``fsaverage*``
+    templates we resample with nearest-neighbour interpolation; ``fslr32k``
+    is not supported because the destrieux atlas is FreeSurfer-specific.
+    """
+    from nilearn.datasets import fetch_atlas_surf_destrieux
+
+    if template == "fslr32k":
+        raise ValueError(
+            "The destrieux atlas is FreeSurfer-specific; fslr32k is not "
+            "supported. Use a fsaverage* template instead."
+        )
+
+    bunch = fetch_atlas_surf_destrieux(data_dir=str(data_dir))
+    # nilearn returns int32 arrays for fsaverage5 (10242 vertices/hemi).
+    parcellations = [np.asarray(bunch["map_left"]), np.asarray(bunch["map_right"])]
+
+    if template != "fsaverage5":
+        # Nearest-neighbour resample fsaverage5 -> requested fsaverage*.
+        from brainstat.mesh.interpolate import _surf2surf
+
+        src_left, src_right = fetch_template_surface(
+            "fsaverage5", layer="white", join=False
+        )
+        dst_left, dst_right = fetch_template_surface(
+            template, layer="white", join=False
+        )
+        parcellations[0] = _surf2surf(
+            src_left, dst_left, parcellations[0], interpolation="nearest"
+        ).astype(parcellations[0].dtype)
+        parcellations[1] = _surf2surf(
+            src_right, dst_right, parcellations[1], interpolation="nearest"
+        ).astype(parcellations[1].dtype)
+
+    return parcellations
+
+
 def _fetch_yeo_parcellation(
     template: str, n_regions: int, data_dir: Path
 ) -> List[np.ndarray]:

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/stats/SLM.py

@@ -1,7 +1,6 @@
-# type: ignore
 """ Standard Linear regression models. """
 import warnings
-from cmath import sqrt
+from math import sqrt
 from pathlib import Path
 from pprint import pformat
 from typing import Optional, Sequence, Tuple, Union
@@ -17,8 +16,11 @@ from nibabel.nifti1 import Nifti1Image
 
 from brainstat._typing import ArrayLike
 from brainstat.datasets import fetch_parcellation, fetch_template_surface
-from brainstat.datasets.base import fetch_template_surface, fetch_yeo_networks_metadata
+from brainstat.datasets.base import fetch_yeo_networks_metadata
 from brainstat.mesh.utils import _mask_edges, mesh_edges
+from brainstat.stats._linear_model import _linear_model
+from brainstat.stats._multiple_comparisons import _fdr, _random_field_theory
+from brainstat.stats._t_test import _t_test
 from brainstat.stats.terms import FixedEffect, MixedEffect
 from brainstat.stats.utils import apply_mask, undo_mask
 
@@ -26,10 +28,13 @@ from brainstat.stats.utils import apply_mask, undo_mask
 class SLM:
     """Core Class for running BrainStat linear models"""
 
-    # Import class methods
-    from ._linear_model import _linear_model
-    from ._multiple_comparisons import _fdr, _random_field_theory
-    from ._t_test import _t_test
+    # Class methods are imported at module level (above) and assigned here
+    # rather than via in-class `from ... import ...`, which trips
+    # python/mypy#10521 and previously forced a file-level `# type: ignore`.
+    _linear_model = _linear_model
+    _fdr = _fdr
+    _random_field_theory = _random_field_theory
+    _t_test = _t_test
 
     def __init__(
         self,
@@ -89,7 +94,7 @@ class SLM:
         """
         # Input arguments.
         self.model = model
-        self.contrast = np.array(contrast)
+        self.contrast = self._coerce_contrast(contrast)
 
         if isinstance(surf, str):
             self.surf_name = surf
@@ -98,7 +103,7 @@ class SLM:
             self.surf_name = None
             self.surf = surf
 
-        self.mask = mask
+        self.mask = self._coerce_mask(mask)
         self.correction = [correction] if isinstance(correction, str) else correction
         self.niter = 1
         self.thetalim = thetalim
@@ -110,12 +115,54 @@ class SLM:
         # Error check
         if self.surf is None:
             if self.correction is not None and "rft" in self.correction:
-                raise ValueError("Random Field Theory corrections require a surface.")
+                raise ValueError(
+                    "Random Field Theory corrections require a surface. For "
+                    "volumetric data, drop 'rft' from `correction` and use "
+                    "`correction='fdr'` (cluster-level RFT/TFCE on volumes is "
+                    "not supported by BrainStat — see issue #342)."
+                )
 
         # We have to initialize fit parameters for our unit tests here.
         # TODO: remove this requirement.
         self._reset_fit_parameters()
 
+    @staticmethod
+    def _coerce_contrast(contrast: ArrayLike) -> np.ndarray:
+        """Convert ``contrast`` to a numeric ndarray.
+
+        Pandas Series and categorical/object inputs are common foot-guns —
+        np.dot then raises a cryptic "can't multiply sequence by non-int"
+        error inside _t_test. Cast to float here and surface a clear
+        TypeError if that fails (see issue #342).
+        """
+        if isinstance(contrast, FixedEffect):
+            return contrast  # type: ignore[return-value]
+        arr = np.asarray(contrast)
+        if arr.dtype.kind in "biufc":
+            return arr
+        try:
+            return arr.astype(float)
+        except (ValueError, TypeError) as exc:
+            raise TypeError(
+                f"`contrast` must be numeric; got dtype {arr.dtype}. If you "
+                "passed a pandas Series with categorical/object dtype, cast "
+                "it to float first (e.g. df['col'].astype(float))."
+            ) from exc
+
+    @staticmethod
+    def _coerce_mask(mask: Optional[ArrayLike]) -> Optional[np.ndarray]:
+        """Convert ``mask`` to a 1-D boolean ndarray.
+
+        Volumetric workflows commonly produce 0/1 *integer* masks (e.g.
+        from `nib.load(...).get_fdata().astype(int)`). The downstream
+        boolean-indexing path then degenerates into fancy indexing, which
+        triggers shape-mismatch errors in `_fdr` (see issue #342). Cast to
+        bool here so callers don't have to remember.
+        """
+        if mask is None:
+            return None
+        return np.asarray(mask).astype(bool)
+
     def fit(self, Y: np.ndarray) -> None:
         """Fits the SLM model
 
@@ -322,7 +369,11 @@ class SLM:
                         )
                         yeo_names, _ = fetch_yeo_networks_metadata(7)
                         yeo_names.insert(0, "Undefined")
-                        yeo7_index = yeo7[self.P["peak"]["vertid"][i]]
+                        # vertid is stored as 1-based (inherited from SurfStat /
+                        # MATLAB conventions in peak_clus); subtract 1 before
+                        # indexing the 0-based yeo7 array (see #347).
+                        vertid = self.P["peak"]["vertid"][i]
+                        yeo7_index = yeo7[vertid - 1] if vertid is not None else None
                         if "yeo7" not in self.P["peak"]:
                             self.P["peak"]["yeo7"] = []
                         self.P["peak"]["yeo7"].append(np.take(yeo_names, yeo7_index))

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/stats/_multiple_comparisons.py

@@ -1,4 +1,3 @@
-# type: ignore
 """Multiple comparison corrections."""
 import copy
 import math

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/stats/_t_test.py

@@ -1,5 +1,4 @@
 import math
-import sys
 import warnings
 
 import numpy as np
@@ -39,7 +38,7 @@ def _t_test(self) -> None:
         if np.square(np.dot(null_space(self.X).T, c)).sum() / np.square(
             c
         ).sum() > np.spacing(1):
-            sys.exit("Contrast is not estimable :-(")
+            raise ValueError("Contrast is not estimable.")
 
     else:
         c = np.dot(pinvX, self.contrast)
@@ -173,6 +172,8 @@ def _t_test(self) -> None:
                 M[M_ef] = ef_duplicate[:, i]
                 M[M_sse] = sse_matrix.flatten()
 
-                self.t[i] = float(np.sqrt(-np.linalg.det(M) / det_sse / vf))
+                # Use .item() rather than float(): numpy >=2.0 raises
+                # TypeError when float() is applied to size-1 ndarrays.
+                self.t[i] = np.sqrt(-np.linalg.det(M) / det_sse / vf).item()
 
     self.t = np.atleast_2d(self.t)

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat/tests/test_SLM.py

@@ -180,3 +180,53 @@ def test_volumetric_input():
 
     slm = SLM(model, contrast, surf=mask_image)
     slm.fit(data)
+
+
+def test_volumetric_contrast_coercion():
+    """Pandas Series / categorical contrasts must be coerced rather than
+    crashing inside _t_test (issue #342)."""
+    model = FixedEffect(np.ones(3))
+    slm = SLM(model, pd.Series([1.0, 0.5, -0.5]))
+    assert slm.contrast.dtype == np.float64
+
+    with pytest.raises(TypeError, match="must be numeric"):
+        SLM(model, pd.Series(["a", "b", "c"]))
+
+
+def test_volumetric_int_mask_is_coerced_to_bool():
+    """Volumetric workflows commonly hand SLM a 0/1 *int* mask
+    (issue #342). It should be coerced rather than degenerating into
+    fancy indexing inside _fdr."""
+    model = FixedEffect(np.ones(3))
+    int_mask = np.array([1, 0, 1, 1, 0, 1], dtype=int)
+    slm = SLM(model, np.ones(3), mask=int_mask)
+    assert slm.mask.dtype == np.bool_
+    assert slm.mask.sum() == 4
+
+
+def test_volumetric_rft_without_surface_explains_alternatives():
+    """RFT on a volume is unsupported; the error should point users at FDR
+    rather than just refusing (issue #342)."""
+    model = FixedEffect(np.ones(3))
+    with pytest.raises(ValueError, match="fdr"):
+        SLM(model, np.ones(3), correction="rft")
+
+
+def test_volumetric_fdr_with_int_mask_runs_end_to_end():
+    """The full int-mask + FDR + non-trivial contrast path that the issue
+    reporters originally hit should now run without error (issue #342)."""
+    n_subjects, n_voxels = 8, 64
+    rng = np.random.default_rng(0)
+    data = rng.standard_normal((n_subjects, n_voxels))
+    # Half the voxels in the mask, expressed as ints (the foot-gun shape).
+    int_mask = np.zeros(n_voxels, dtype=int)
+    int_mask[: n_voxels // 2] = 1
+    model = FixedEffect(rng.standard_normal(n_subjects))
+    contrast = pd.Series(rng.standard_normal(n_subjects))  # pandas, on purpose
+    slm = SLM(model, contrast, mask=int_mask, correction="fdr")
+    slm.fit(data)
+    assert slm.t.shape[-1] == n_voxels
+    # Inside the mask the t-values must be finite; outside they're masked
+    # out and undo_mask fills them with NaN.
+    assert np.all(np.isfinite(slm.t[..., int_mask.astype(bool)]))
+    assert slm.Q.shape[-1] == n_voxels

{brainstat-0.5.2 → brainstat-0.6.0/brainstat.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainstat
-Version: 0.5.2
+Version: 0.6.0
 Summary: A toolbox for statistical analysis of neuroimaging data
 Home-page: https://github.com/MICA-LAB/BrainStat
 Author: MNI-MICA Lab and MPI-CNG Lab
@@ -26,8 +26,8 @@ Requires-Dist: neurosynth
 Requires-Dist: nibabel
 Requires-Dist: nilearn>=0.7.0
 Requires-Dist: nimare
-Requires-Dist: numpy>=1.21
-Requires-Dist: pandas>=1.3
+Requires-Dist: numpy<2,>=1.21
+Requires-Dist: pandas<2.1,>=1.3
 Requires-Dist: scikit_learn>=1.0
 Requires-Dist: scipy>=1.7
 Requires-Dist: templateflow

{brainstat-0.5.2 → brainstat-0.6.0}/brainstat.egg-info/requires.txt

@@ -7,8 +7,8 @@ neurosynth
 nibabel
 nilearn>=0.7.0
 nimare
-numpy>=1.21
-pandas>=1.3
+numpy<2,>=1.21
+pandas<2.1,>=1.3
 scikit_learn>=1.0
 scipy>=1.7
 templateflow

{brainstat-0.5.2 → brainstat-0.6.0}/setup.py

@@ -44,8 +44,11 @@ setuptools.setup(
         "nibabel",
         "nilearn>=0.7.0",
         "nimare",
-        "numpy>=1.21",
-        "pandas>=1.3",
+        # numpy<2 is required so the pinned pandas<2.1 (whose 2.0.x C
+        # extensions were built against the numpy 1.x ABI) loads cleanly.
+        # See requirements.txt for the abagen-driven rationale.
+        "numpy>=1.21,<2",
+        "pandas>=1.3,<2.1",
         "scikit_learn>=1.0",
         "scipy>=1.7",
         "templateflow",