junifer 0.0.5.dev110__tar.gz → 0.0.5.dev131__tar.gz

junifer-0.0.5.dev131/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "junifer/external/h5io"]
+	path = junifer/external/h5io
+	url = https://github.com/juaml/h5io
+[submodule "junifer/external/BrainPrint"]
+	path = junifer/external/BrainPrint
+	url = https://github.com/juaml/BrainPrint.git

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.5.dev110
+Version: 0.0.5.dev131
 Summary: JUelich NeuroImaging FEature extractoR
 Author-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
 Maintainer-email: Fede Raimondo <f.raimondo@fz-juelich.de>, Synchon Mandal <s.mandal@fz-juelich.de>
@@ -41,6 +41,7 @@ Requires-Dist: h5py>=3.10
 Requires-Dist: httpx[http2]==0.26.0
 Requires-Dist: tqdm==4.66.1
 Requires-Dist: templateflow>=23.0.0
+Requires-Dist: lapy<2.0.0,>=1.0.0
 Requires-Dist: importlib_metadata; python_version < "3.10"
 Requires-Dist: looseversion==1.3.0; python_version >= "3.12"
 Provides-Extra: all

junifer-0.0.5.dev131/docs/changes/newsfragments/344.feature

@@ -0,0 +1 @@
+Add support for `BrainPrint <https://github.com/Deep-MI/BrainPrint?tab=readme-ov-file>`_ marker by `Synchon Mandal`_

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/ignore_words.txt

@@ -4,3 +4,4 @@ chang
 sepulcre
 arange
 sinc
+whit

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/junifer/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.5.dev110'
-__version_tuple__ = version_tuple = (0, 0, 5, 'dev110')
+__version__ = version = '0.0.5.dev131'
+__version_tuple__ = version_tuple = (0, 0, 5, 'dev131')

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/junifer/api/tests/test_api_utils.py

@@ -45,6 +45,7 @@ def test_get_dependency_information_short() -> None:
         "httpx",
         "tqdm",
         "templateflow",
+        "lapy",
         "looseversion",
     ]
 
@@ -74,6 +75,7 @@ def test_get_dependency_information_long() -> None:
         "httpx",
         "tqdm",
         "templateflow",
+        "lapy",
     ]
     for key in dependency_list:
         assert key in dependency_information_keys

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/junifer/data/tests/test_masks.py

@@ -350,7 +350,7 @@ def test_get_mask_errors() -> None:
         with pytest.raises(ValueError, match=r"callable params"):
             get_mask(masks={"GM_prob0.2": {"param": 1}}, target_data=vbm_gm)
 
-        # Pass only parametesr to the intersection function
+        # Pass only parameters to the intersection function
         with pytest.raises(
             ValueError, match=r" At least one mask is required."
         ):

{junifer-0.0.5.dev110 → junifer-0.0.5.dev131}/junifer/datagrabber/pattern.py

@@ -6,6 +6,7 @@
 # License: AGPL
 
 import re
+from copy import deepcopy
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple, Union
 
@@ -364,7 +365,7 @@ class PatternDataGrabber(BaseDataGrabber):
             # Data type dictionary
             t_pattern = self.patterns[t_type]
             # Copy data type dictionary in output
-            out[t_type] = t_pattern.copy()
+            out[t_type] = deepcopy(t_pattern)
             # Iterate to check for nested "types" like mask
             for k, v in t_pattern.items():
                 # Resolve pattern for base data type

junifer-0.0.5.dev131/junifer/external/BrainPrint/brainprint/__init__.py

@@ -0,0 +1,4 @@
+from ._version import __version__  # noqa: F401
+from .brainprint import compute_asymmetry, compute_brainprint  # noqa: F401
+from .surfaces import surf_to_vtk  # noqa: F401
+from .utils._config import sys_info  # noqa: F401

junifer-0.0.5.dev131/junifer/external/BrainPrint/brainprint/_version.py

@@ -0,0 +1,3 @@
+"""Version number."""
+
+__version__ = "0.4.0"

junifer-0.0.5.dev131/junifer/external/BrainPrint/brainprint/asymmetry.py

@@ -0,0 +1,91 @@
+"""
+Contains asymmetry estimation functionality.
+"""
+from typing import Dict
+
+import numpy as np
+from lapy import shapedna
+
+
+def compute_asymmetry(
+    eigenvalues, distance: str = "euc", skip_cortex: bool = False
+) -> Dict[str, float]:
+    """
+    Compute lateral shape distances from BrainPrint analysis results.
+
+    Parameters
+    ----------
+    eigenvalues : _type_
+        BrainPrint analysis results.
+    distance : str, optional
+        ShapeDNA distance, by default "euc".
+    skip_cortex : bool, optional
+        Whether to skip white matter and pial surfaces, by default False.
+
+    Returns
+    -------
+    Dict[str, float]
+        {left_label}_{right_label}, distance.
+    """
+    # Define structures
+
+    # combined and individual aseg labels:
+    # - Left  Striatum: left  Caudate + Putamen + Accumbens
+    # - Right Striatum: right Caudate + Putamen + Accumbens
+    # - CorpusCallosum: 5 subregions combined
+    # - Cerebellum: brainstem + (left+right) cerebellum WM and GM
+    # - Ventricles: (left+right) lat.vent + inf.lat.vent + choroidplexus + 3rdVent + CSF
+    # - Lateral-Ventricle: lat.vent + inf.lat.vent + choroidplexus
+    # - 3rd-Ventricle: 3rd-Ventricle + CSF
+
+    structures_left_right = [
+        ("Left-Striatum", "Right-Striatum"),
+        ("Left-Lateral-Ventricle", "Right-Lateral-Ventricle"),
+        (
+            "Left-Cerebellum-White-Matter",
+            "Right-Cerebellum-White-Matter",
+        ),
+        ("Left-Cerebellum-Cortex", "Right-Cerebellum-Cortex"),
+        ("Left-Thalamus-Proper", "Right-Thalamus-Proper"),
+        ("Left-Caudate", "Right-Caudate"),
+        ("Left-Putamen", "Right-Putamen"),
+        ("Left-Pallidum", "Right-Pallidum"),
+        ("Left-Hippocampus", "Right-Hippocampus"),
+        ("Left-Amygdala", "Right-Amygdala"),
+        ("Left-Accumbens-area", "Right-Accumbens-area"),
+        ("Left-VentralDC", "Right-VentralDC"),
+    ]
+
+    cortex_2d_left_right = [
+        ("lh-white-2d", "rh-white-2d"),
+        ("lh-pial-2d", "rh-pial-2d"),
+    ]
+
+    structures = structures_left_right
+    if not skip_cortex:
+        structures += cortex_2d_left_right
+
+    distances = dict()
+    for left_label, right_label in structures:
+        left_eigenvalues, right_eigenvalues = (
+            eigenvalues[left_label][2:],
+            eigenvalues[right_label][2:],
+        )
+        has_nan = np.isnan(left_eigenvalues).any() or np.isnan(right_eigenvalues).any()
+        key = f"{left_label}_{right_label}"
+        if has_nan:
+            message = (
+                "NaNs found for {left_label} or {right_label}, "
+                "skipping asymmetry computation...".format(
+                    left_label=left_label, right_label=right_label
+                )
+            )
+            print(message)
+            distances[key] = np.nan
+        else:
+            distances[key] = shapedna.compute_distance(
+                left_eigenvalues,
+                right_eigenvalues,
+                dist=distance,
+            )
+    return distances

junifer-0.0.5.dev131/junifer/external/BrainPrint/brainprint/brainprint.py

@@ -0,0 +1,441 @@
+"""
+Definition of the brainprint analysis execution functions..
+"""
+
+import shutil
+import warnings
+from pathlib import Path
+from typing import Dict, Tuple, Union
+
+import numpy as np
+from lapy import TriaMesh, shapedna
+
+from . import __version__
+from .asymmetry import compute_asymmetry
+from .surfaces import create_surfaces, read_vtk
+from .utils.utils import (
+    create_output_paths,
+    export_brainprint_results,
+    test_freesurfer,
+    validate_environment,
+    validate_subject_dir,
+)
+
+warnings.filterwarnings("ignore", ".*negative int.*")
+
+
+def apply_eigenvalues_options(
+    eigenvalues: np.ndarray,
+    triangular_mesh: TriaMesh,
+    norm: str = "none",
+    reweight: bool = False,
+) -> np.ndarray:
+    """
+    Apply BrainPrint analysis configuration options to the ShapeDNA eigenvalues.
+
+    Parameters
+    ----------
+    eigenvalues : np.ndarray
+        ShapeDNA derived eigenvalues.
+    triangular_mesh : TriaMesh
+        Surface representation.
+    norm : str, optional
+        Eigenvalues normalization method (default is "none").
+    reweight : bool, optional
+        Whether to reweight eigenvalues or not (default is False).
+
+    Returns
+    -------
+    np.ndarray
+        Fixed eigenvalues.
+    """
+    if not triangular_mesh.is_oriented():
+        triangular_mesh.orient_()
+    if norm != "none":
+        eigenvalues = shapedna.normalize_ev(
+            geom=triangular_mesh,
+            evals=eigenvalues,
+            method=norm,
+        )
+    if reweight:
+        eigenvalues = shapedna.reweight_ev(eigenvalues)
+    return eigenvalues
+
+
+def compute_surface_brainprint(
+    path: Path,
+    return_eigenvectors: bool = True,
+    num: int = 50,
+    norm: str = "none",
+    reweight: bool = False,
+    use_cholmod: bool = False,
+) -> Tuple[np.ndarray, Union[np.ndarray, None]]:
+    """
+    Compute BrainPrint eigenvalues and eigenvectors for the given surface.
+
+    Parameters
+    ----------
+    path : Path
+
+        Path to the *.vtk* surface path.
+    return_eigenvectors : bool, optional
+        Whether to store eigenvectors in the result (default is True).
+    num : int, optional
+        Number of eigenvalues to compute (default is 50).
+    norm : str, optional
+        Eigenvalues normalization method (default is "none").
+    reweight : bool, optional
+        Whether to reweight eigenvalues or not (default is False).
+    use_cholmod : bool, optional
+        If True, attempts to use the Cholesky decomposition for improved execution
+        speed. Requires the ``scikit-sparse`` library. If it can not be found, an error
+        will be thrown.
+        If False, will use slower LU decomposition. This is the default.
+
+    Returns
+    -------
+    Tuple[np.ndarray, Union[np.ndarray, None]]
+        Eigenvalues, eigenvectors (if returned).
+    """
+    triangular_mesh = read_vtk(path)
+    shape_dna = shapedna.compute_shapedna(
+        triangular_mesh,
+        k=num,
+        lump=False,
+        aniso=None,
+        aniso_smooth=10,
+        use_cholmod=use_cholmod,
+    )
+
+    eigenvectors = None
+    if return_eigenvectors:
+        eigenvectors = shape_dna["Eigenvectors"]
+
+    eigenvalues = shape_dna["Eigenvalues"]
+    eigenvalues = apply_eigenvalues_options(
+        eigenvalues, triangular_mesh, norm, reweight
+    )
+    eigenvalues = np.concatenate(
+        (
+            np.array(triangular_mesh.area(), ndmin=1),
+            np.array(triangular_mesh.volume(), ndmin=1),
+            eigenvalues,
+        )
+    )
+    return eigenvalues, eigenvectors
+
+
+def compute_brainprint(
+    surfaces: Dict[str, Path],
+    keep_eigenvectors: bool = False,
+    num: int = 50,
+    norm: str = "none",
+    reweight: bool = False,
+    use_cholmod: bool = False,
+) -> Tuple[Dict[str, np.ndarray], Union[Dict[str, np.ndarray], None]]:
+    """
+    Compute ShapeDNA descriptors over several surfaces.
+
+    Parameters
+    ----------
+    surfaces : Dict[str, Path]
+        Dictionary mapping from labels to *.vtk* paths.
+    keep_eigenvectors : bool, optional
+        Whether to also return eigenvectors or not, by default False.
+    num : int, optional
+        Number of eigenvalues to compute, by default 50.
+    norm : str, optional
+        Eigenvalues normalization method, by default "none".
+    reweight : bool, optional
+        Whether to reweight eigenvalues or not, by default False.
+    use_cholmod : bool, optional
+        If True, attempts to use the Cholesky decomposition for improved execution
+        speed. Requires the ``scikit-sparse`` library. If it can not be found, an error
+        will be thrown. If False, will use slower LU decomposition. This is the default.
+
+    Returns
+    -------
+    Tuple[Dict[str, np.ndarray], Union[Dict[str, np.ndarray], None]]
+        Surface label to eigenvalues, surface label to eigenvectors (if
+        *keep_eigenvectors* is True).
+    """
+    eigenvalues = dict()
+    eigenvectors = dict() if keep_eigenvectors else None
+    for surface_label, surface_path in surfaces.items():
+        try:
+            (
+                surface_eigenvalues,
+                surface_eigenvectors,
+            ) = compute_surface_brainprint(
+                surface_path,
+                num=num,
+                norm=norm,
+                reweight=reweight,
+                return_eigenvectors=keep_eigenvectors,
+                use_cholmod=use_cholmod,
+            )
+        except Exception as e:
+            message = (
+                "BrainPrint analysis raised the following exception:\n"
+                "{exception}".format(exception=e)
+            )
+            warnings.warn(message)
+            eigenvalues[surface_label] = ["NaN"] * (num + 2)
+        else:
+            if len(surface_eigenvalues) == 0:
+                eigenvalues[surface_label] = ["NaN"] * (num + 2)
+            else:
+                eigenvalues[surface_label] = surface_eigenvalues
+            if keep_eigenvectors:
+                eigenvectors[surface_label] = surface_eigenvectors
+    return eigenvalues, eigenvectors
+
+
+def run_brainprint(
+    subjects_dir: Path,
+    subject_id: str,
+    destination: Path = None,
+    num: int = 50,
+    skip_cortex: bool = False,
+    keep_eigenvectors: bool = False,
+    norm: str = "none",
+    reweight: bool = False,
+    asymmetry: bool = False,
+    asymmetry_distance: str = "euc",
+    keep_temp: bool = False,
+    use_cholmod: bool = False,
+):
+    """
+    Run the BrainPrint analysis.
+
+    Parameters
+    ----------
+    subjects_dir : Path
+        FreeSurfer's subjects directory.
+    subject_id : str
+        The subject identifier, as defined within the FreeSurfer's subjects
+        directory.
+    destination : Path, optional
+        If provided, will use this path as the results root directory, by
+        default None.
+    num : int, optional
+        Number of eigenvalues to compute, by default 50.
+    skip_cortex : bool, optional
+        _description_, by default False.
+    keep_eigenvectors : bool, optional
+        Whether to also return eigenvectors or not, by default False.
+    norm : str, optional
+        Eigenvalues normalization method, by default "none".
+    reweight : bool, optional
+        Whether to reweight eigenvalues or not, by default False.
+    asymmetry : bool, optional
+        Whether to calculate asymmetry between lateral structures, by default
+        False.
+    asymmetry_distance : str, optional
+        Distance measurement to use if *asymmetry* is set to True, by default
+        "euc".
+    keep_temp : bool, optional
+        Whether to keep the temporary files directory or not, by default False.
+    use_cholmod : bool, optional
+        If True, attempts to use the Cholesky decomposition for improved execution
+        speed. Requires the ``scikit-sparse`` library. If it can not be found, an error
+        will be thrown. If False, will use slower LU decomposition. This is the default.
+
+    Returns
+    -------
+    Tuple[Dict[str, np.ndarray], Union[Dict[str, np.ndarray], None], Union[Dict[str, float], None]]
+        A tuple containing dictionaries with BrainPrint analysis results.
+        - Eigenvalues
+        - Eigenvectors
+        - Distances
+    """  # noqa: E501
+    validate_environment()
+    test_freesurfer()
+    subject_dir = validate_subject_dir(subjects_dir, subject_id)
+    destination = create_output_paths(
+        subject_dir=subject_dir,
+        destination=destination,
+    )
+
+    surfaces = create_surfaces(subject_dir, destination, skip_cortex=skip_cortex)
+    eigenvalues, eigenvectors = compute_brainprint(
+        surfaces,
+        num=num,
+        norm=norm,
+        reweight=reweight,
+        keep_eigenvectors=keep_eigenvectors,
+        use_cholmod=use_cholmod,
+    )
+
+    distances = None
+    if asymmetry:
+        distances = compute_asymmetry(
+            eigenvalues,
+            distance=asymmetry_distance,
+            skip_cortex=skip_cortex,
+        )
+
+    csv_name = "{subject_id}.brainprint.csv".format(subject_id=subject_id)
+    csv_path = destination / csv_name
+    export_brainprint_results(csv_path, eigenvalues, eigenvectors, distances)
+    if not keep_temp:
+        shutil.rmtree(destination / "temp")
+    print(
+        "Returning matrices for eigenvalues, eigenvectors, and (optionally) distances."
+    )
+    print("The eigenvalue matrix contains area and volume as first two rows.")
+    return eigenvalues, eigenvectors, distances
+
+
+class Brainprint:
+    __version__ = __version__
+
+    def __init__(
+        self,
+        subjects_dir: Path,
+        num: int = 50,
+        skip_cortex: bool = False,
+        keep_eigenvectors: bool = False,
+        norm: str = "none",
+        reweight: bool = False,
+        asymmetry: bool = False,
+        asymmetry_distance: str = "euc",
+        keep_temp: bool = False,
+        environment_validation: bool = True,
+        freesurfer_validation: bool = True,
+        use_cholmod: bool = False,
+    ) -> None:
+        """
+        Initializes a new :class:`Brainprint` instance.
+
+        Parameters
+        ----------
+        subjects_dir : Path
+            FreeSurfer's subjects directory
+        num : int, optional
+            Number of eigenvalues to compute, by default 50
+        norm : str, optional
+            Eigenvalues normalization method, by default "none"
+        reweight : bool, optional
+            Whether to reweight eigenvalues or not, by default False
+        skip_cortex : bool, optional
+            _description_, by default False
+        keep_eigenvectors : bool, optional
+            Whether to also return eigenvectors or not, by default False
+        asymmetry : bool, optional
+            Whether to calculate asymmetry between lateral structures, by
+            default False
+        asymmetry_distance : str, optional
+            Distance measurement to use if *asymmetry* is set to True, by
+            default "euc"
+        keep_temp : bool, optional
+            Whether to keep the temporary files directory or not, by default False
+        use_cholmod : bool, optional
+            If True, attempts to use the Cholesky decomposition for improved execution
+            speed. Requires the ``scikit-sparse`` library. If it can not be found, an
+            error will be thrown. If False, will use slower LU decomposition. This is
+            the default.
+        """
+        self.subjects_dir = subjects_dir
+        self.num = num
+        self.norm = norm
+        self.skip_cortex = skip_cortex
+        self.reweight = reweight
+        self.keep_eigenvectors = keep_eigenvectors
+        self.asymmetry = asymmetry
+        self.asymmetry_distance = asymmetry_distance
+        self.keep_temp = keep_temp
+        self.use_cholmod = use_cholmod
+
+        self._subject_id = None
+        self._destination = None
+        self._eigenvalues = None
+        self._eigenvectors = None
+        self._distances = None
+
+        if environment_validation:
+            validate_environment()
+        if freesurfer_validation:
+            test_freesurfer()
+
+    def run(self, subject_id: str, destination: Path = None) -> Dict[str, Path]:
+        """
+        Run Brainprint analysis for a specified subject.
+
+        Parameters
+        ----------
+        subject_id : str
+            The ID of the subject to analyze.
+        destination : Path, optional
+            The destination directory for analysis results, by default None.
+
+        Returns
+        -------
+        Dict[str, Path]
+            A dictionary containing paths to the generated analysis results.
+        """
+        self._eigenvalues = self._eigenvectors = self._distances = None
+        subject_dir = validate_subject_dir(self.subjects_dir, subject_id)
+        destination = create_output_paths(
+            subject_dir=subject_dir,
+            destination=destination,
+        )
+
+        surfaces = create_surfaces(
+            subject_dir, destination, skip_cortex=self.skip_cortex
+        )
+        self._eigenvalues, self._eigenvectors = compute_brainprint(
+            surfaces,
+            num=self.num,
+            norm=self.norm,
+            reweight=self.reweight,
+            keep_eigenvectors=self.keep_eigenvectors,
+            use_cholmod=self.use_cholmod,
+        )
+
+        if self.asymmetry:
+            self._distances = compute_asymmetry(
+                self._eigenvalues,
+                distance=self.asymmetry_distance,
+                skip_cortex=self.skip_cortex,
+            )
+
+        self.cleanup(destination=destination)
+        return self.export_results(destination=destination, subject_id=subject_id)
+
+    def export_results(self, destination: Path, subject_id: str) -> None:
+        """
+        Export Brainprint analysis results to a CSV file.
+
+        Parameters
+        ----------
+        destination : Path
+            The destination directory for analysis results.
+        subject_id : str
+            The ID of the subject being analyzed.
+
+        Returns
+        -------
+        None
+        """
+        csv_name = "{subject_id}.brainprint.csv".format(subject_id=subject_id)
+        csv_path = destination / csv_name
+        return export_brainprint_results(
+            csv_path, self._eigenvalues, self._eigenvectors, self._distances
+        )
+
+    def cleanup(self, destination: Path) -> None:
+        """
+        Clean up temporary files generated during the analysis.
+
+        Parameters
+        ----------
+        destination : Path
+            The destination directory for analysis results.
+
+        Returns
+        -------
+        None
+        """
+        if not self.keep_temp:
+            shutil.rmtree(destination / "temp")