junifer 0.0.5.dev110__py3-none-any.whl → 0.0.5.dev145__py3-none-any.whl

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")

junifer/external/BrainPrint/brainprint/surfaces.py

@@ -0,0 +1,258 @@
+"""
+Utility module holding surface generation related functions.
+"""
+import uuid
+from pathlib import Path
+from typing import Dict, List
+
+from lapy import TriaMesh
+
+from .utils.utils import run_shell_command
+
+
+def create_aseg_surface(
+    subject_dir: Path, destination: Path, indices: List[int]
+) -> Path:
+    """
+    Generate a surface from the aseg and label files.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's directory.
+    destination : Path
+        Path to the destination directory where the surface will be saved.
+    indices : List[int]
+        List of label indices to include in the surface generation.
+
+    Returns
+    -------
+    Path
+        Path to the generated surface in VTK format.
+    """
+    aseg_path = subject_dir / "mri/aseg.mgz"
+    norm_path = subject_dir / "mri/norm.mgz"
+    temp_name = "temp/aseg.{uid}".format(uid=uuid.uuid4())
+    indices_mask = destination / f"{temp_name}.mgz"
+    # binarize on selected labels (creates temp indices_mask)
+    # always binarize first, otherwise pretess may scale aseg if labels are
+    # larger than 255 (e.g. aseg+aparc, bug in mri_pretess?)
+    binarize_template = "mri_binarize --i {source} --match {match} --o {destination}"
+    binarize_command = binarize_template.format(
+        source=aseg_path, match=" ".join(indices), destination=indices_mask
+    )
+    run_shell_command(binarize_command)
+
+    label_value = "1"
+    # if norm exist, fix label (pretess)
+    if norm_path.is_file():
+        pretess_template = (
+            "mri_pretess {source} {label_value} {norm_path} {destination}"
+        )
+        pretess_command = pretess_template.format(
+            source=indices_mask,
+            label_value=label_value,
+            norm_path=norm_path,
+            destination=indices_mask,
+        )
+        run_shell_command(pretess_command)
+
+    # runs marching cube to extract surface
+    surface_name = "{name}.surf".format(name=temp_name)
+    surface_path = destination / surface_name
+    extraction_template = "mri_mc {source} {label_value} {destination}"
+    extraction_command = extraction_template.format(
+        source=indices_mask, label_value=label_value, destination=surface_path
+    )
+    run_shell_command(extraction_command)
+
+    # convert to vtk
+    relative_path = "surfaces/aseg.final.{indices}.vtk".format(
+        indices="_".join(indices)
+    )
+    conversion_destination = destination / relative_path
+    conversion_template = "mris_convert {source} {destination}"
+    conversion_command = conversion_template.format(
+        source=surface_path, destination=conversion_destination
+    )
+    run_shell_command(conversion_command)
+
+    return conversion_destination
+
+
+def create_aseg_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path]:
+    """
+    Create surfaces from FreeSurfer aseg labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory for saving surfaces.
+
+    Returns
+    -------
+    Dict[str, Path]
+        Dictionary of label names mapped to corresponding surface Path objects.
+    """
+    # Define aseg labels
+
+    # 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
+
+    aseg_labels = {
+        "CorpusCallosum": ["251", "252", "253", "254", "255"],
+        "Cerebellum": ["7", "8", "16", "46", "47"],
+        "Ventricles": ["4", "5", "14", "24", "31", "43", "44", "63"],
+        "3rd-Ventricle": ["14", "24"],
+        "4th-Ventricle": ["15"],
+        "Brain-Stem": ["16"],
+        "Left-Striatum": ["11", "12", "26"],
+        "Left-Lateral-Ventricle": ["4", "5", "31"],
+        "Left-Cerebellum-White-Matter": ["7"],
+        "Left-Cerebellum-Cortex": ["8"],
+        "Left-Thalamus-Proper": ["10"],
+        "Left-Caudate": ["11"],
+        "Left-Putamen": ["12"],
+        "Left-Pallidum": ["13"],
+        "Left-Hippocampus": ["17"],
+        "Left-Amygdala": ["18"],
+        "Left-Accumbens-area": ["26"],
+        "Left-VentralDC": ["28"],
+        "Right-Striatum": ["50", "51", "58"],
+        "Right-Lateral-Ventricle": ["43", "44", "63"],
+        "Right-Cerebellum-White-Matter": ["46"],
+        "Right-Cerebellum-Cortex": ["47"],
+        "Right-Thalamus-Proper": ["49"],
+        "Right-Caudate": ["50"],
+        "Right-Putamen": ["51"],
+        "Right-Pallidum": ["52"],
+        "Right-Hippocampus": ["53"],
+        "Right-Amygdala": ["54"],
+        "Right-Accumbens-area": ["58"],
+        "Right-VentralDC": ["60"],
+    }
+    return {
+        label: create_aseg_surface(subject_dir, destination, indices)
+        for label, indices in aseg_labels.items()
+    }
+
+
+def create_cortical_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path]:
+    """
+    Create cortical surfaces from FreeSurfer labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory where the surfaces will be saved.
+
+    Returns
+    -------
+    Dict[str, Path]
+        Dictionary mapping label names to associated surface Paths.
+    """
+    cortical_labels = {
+        "lh-white-2d": "lh.white",
+        "rh-white-2d": "rh.white",
+        "lh-pial-2d": "lh.pial",
+        "rh-pial-2d": "rh.pial",
+    }
+    return {
+        label: surf_to_vtk(
+            subject_dir / "surf" / name,
+            destination / "surfaces" / f"{name}.vtk",
+        )
+        for label, name in cortical_labels.items()
+    }
+
+
+def create_surfaces(
+    subject_dir: Path, destination: Path, skip_cortex: bool = False
+) -> Dict[str, Path]:
+    """
+    Create surfaces based on FreeSurfer labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory where the surfaces will be saved.
+    skip_cortex : bool, optional
+        If True, cortical surfaces will not be created (default is False).
+
+    Returns
+    -------
+    Dict[str, Path]
+        Dict mapping label names to the corresponding Path objects of created surfaces.
+    """
+    surfaces = create_aseg_surfaces(subject_dir, destination)
+    if not skip_cortex:
+        cortical_surfaces = create_cortical_surfaces(subject_dir, destination)
+        surfaces.update(cortical_surfaces)
+    return surfaces
+
+
+def read_vtk(path: Path):
+    """
+    Read a VTK file and return a triangular mesh.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the VTK file to be read.
+
+    Returns
+    -------
+    TriaMesh
+        A triangular mesh object representing the contents of the VTK file.
+
+    Raises
+    ------
+    RuntimeError
+        If there is an issue reading the VTK file or if the file is empty.
+    """
+    try:
+        triangular_mesh = TriaMesh.read_vtk(path)
+    except Exception:
+        message = "Failed to read VTK from the following path: {path}!".format(
+            path=path
+        )
+        raise RuntimeError(message)
+    else:
+        if triangular_mesh is None:
+            message = "Failed to read VTK from the following path: {path}!".format(
+                path=path
+            )
+            raise RuntimeError(message)
+        return triangular_mesh
+
+
+def surf_to_vtk(source: Path, destination: Path) -> Path:
+    """
+    Converted a FreeSurfer *.surf* file to *.vtk*.
+
+    Parameters
+    ----------
+    source : Path
+        FreeSurfer *.surf* file.
+    destination : Path
+        Equivalent *.vtk* file.
+
+    Returns
+    -------
+    Path
+        Resulting *.vtk* file.
+    """
+    TriaMesh.read_fssurf(source).write_vtk(destination)
+    return destination

junifer/external/BrainPrint/brainprint/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities module."""