junifer 0.0.7.dev332__py3-none-any.whl → 0.0.8__py3-none-any.whl

junifer/data/parcellations/_ants_parcellation_warper.py

@@ -4,12 +4,13 @@
 # License: AGPL
 
 import uuid
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 import nibabel as nib
 
 from ...pipeline import WorkDirManager
-from ...utils import logger, raise_error, run_ext_cmd
+from ...typing import SpaceLike
+from ...utils import raise_error, run_ext_cmd
 from ..template_spaces import get_template, get_xfm
 
 
@@ -31,10 +32,10 @@ class ANTsParcellationWarper:
         self,
         parcellation_name: str,
         parcellation_img: "Nifti1Image",
-        src: str,
-        dst: str,
+        src: SpaceLike,
+        dst: SpaceLike,
         target_data: dict[str, Any],
-        warp_data: Optional[dict[str, Any]],
+        warp_data: dict[str, Any] | None,
     ) -> "Nifti1Image":
         """Warp ``parcellation_img`` to correct space.
 
@@ -44,10 +45,10 @@ class ANTsParcellationWarper:
             The name of the parcellation.
         parcellation_img : nibabel.nifti1.Nifti1Image
             The parcellation image to transform.
-        src : str
+        src : str or Enum
             The data type or template space to warp from.
             It should be empty string if ``dst="T1w"``.
-        dst : str
+        dst : str or Enum
             The data type or template space to warp to.
             `"T1w"` is the only allowed data type and it uses the resampled T1w
             found in ``target_data.reference``. The ``"reference"``
@@ -71,6 +72,9 @@ class ANTsParcellationWarper:
             If ``warp_data`` is None when ``dst="T1w"``.
 
         """
+        # Imported here to avoid circular import
+        from ._parcellations import logger
+
         # Create element-scoped tempdir so that warped parcellation is
         # available later as nibabel stores file path reference for
         # loading on computation
@@ -97,19 +101,20 @@ class ANTsParcellationWarper:
 
             # Save existing parcellation image to a tempfile
             prewarp_parcellation_path = (
-                element_tempdir / "prewarp_parcellation.nii.gz"
+                element_tempdir / "prewarp_parcellation.nii"
             )
             nib.save(parcellation_img, prewarp_parcellation_path)
 
             # Create a tempfile for warped output
             warped_parcellation_path = (
-                element_tempdir / "parcellation_warped.nii.gz"
+                element_tempdir / "parcellation_warped.nii"
             )
             # Set antsApplyTransforms command
             apply_transforms_cmd = [
                 "antsApplyTransforms",
                 "-d 3",
                 "-e 3",
+                "--float 1",
                 "-n 'GenericLabel[NearestNeighbor]'",
                 f"-i {prewarp_parcellation_path.resolve()}",
                 # use resampled reference
@@ -135,24 +140,25 @@ class ANTsParcellationWarper:
                 extra_input=None,
             )
             # Save template to a tempfile
-            template_space_img_path = element_tempdir / f"{dst}_T1w.nii.gz"
+            template_space_img_path = element_tempdir / f"{dst}_T1w.nii"
             nib.save(template_space_img, template_space_img_path)
 
             # Save existing parcellation image to a tempfile
             prewarp_parcellation_path = (
-                element_tempdir / "prewarp_parcellation.nii.gz"
+                element_tempdir / "prewarp_parcellation.nii"
             )
             nib.save(parcellation_img, prewarp_parcellation_path)
 
             # Create a tempfile for warped output
             warped_parcellation_path = (
-                element_tempdir / "parcellation_warped.nii.gz"
+                element_tempdir / "parcellation_warped.nii"
             )
             # Set antsApplyTransforms command
             apply_transforms_cmd = [
                 "antsApplyTransforms",
                 "-d 3",
                 "-e 3",
+                "--float 1",
                 "-n 'GenericLabel[NearestNeighbor]'",
                 f"-i {prewarp_parcellation_path.resolve()}",
                 f"-r {template_space_img_path.resolve()}",

junifer/data/parcellations/_fsl_parcellation_warper.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any
 import nibabel as nib
 
 from ...pipeline import WorkDirManager
-from ...utils import logger, run_ext_cmd
+from ...utils import run_ext_cmd
 
 
 if TYPE_CHECKING:
@@ -53,6 +53,9 @@ class FSLParcellationWarper:
             The transformed parcellation image.
 
         """
+        # Imported here to avoid circular import
+        from ._parcellations import logger
+
         logger.debug("Using FSL for parcellation transformation")
 
         # Create element-scoped tempdir so that warped parcellation is
@@ -64,16 +67,15 @@ class FSLParcellationWarper:
 
         # Save existing parcellation image to a tempfile
         prewarp_parcellation_path = (
-            element_tempdir / "prewarp_parcellation.nii.gz"
+            element_tempdir / "prewarp_parcellation.nii"
         )
         nib.save(parcellation_img, prewarp_parcellation_path)
 
         # Create a tempfile for warped output
-        warped_parcellation_path = (
-            element_tempdir / "parcellation_warped.nii.gz"
-        )
+        warped_parcellation_path = element_tempdir / "parcellation_warped.nii"
         # Set applywarp command
         applywarp_cmd = [
+            "FSLOUTPUTTYPE=NIFTI",
             "applywarp",
             "--interp=nn",
             f"-i {prewarp_parcellation_path.resolve()}",

junifer/data/parcellations/_parcellations.py

@@ -5,17 +5,19 @@
 #          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+from collections import Counter
 from itertools import product
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional
 
 import nibabel as nib
 import nilearn.image as nimg
 import numpy as np
 import pandas as pd
+import structlog
 from junifer_data import get
 
-from ...utils import logger, raise_error, warn_with_log
+from ...utils import raise_error, warn_with_log
 from ..pipeline_data_registry_base import BasePipelineDataRegistry
 from ..utils import (
     JUNIFER_DATA_PARAMS,
@@ -36,6 +38,9 @@ __all__ = [
     "merge_parcellations",
 ]
 
+_log = structlog.get_logger("junifer")
+logger = _log.bind(pkg="data")
+
 
 class ParcellationRegistry(BasePipelineDataRegistry):
     """Class for parcellation data registry.
@@ -58,8 +63,12 @@ class ParcellationRegistry(BasePipelineDataRegistry):
         # The built-in parcellations are files that are shipped with the
         # junifer-data dataset.
         # Make built-in and external dictionaries for validation later
-        self._builtin = {}
-        self._external = {}
+        self._builtin: dict[
+            str, dict[str, str | int | Path | list[str] | list[int]]
+        ] = {}
+        self._external: dict[
+            str, dict[str, str | int | Path | list[str] | list[int]]
+        ] = {}
 
         # Add SUIT
         self._builtin.update(
@@ -226,7 +235,7 @@ class ParcellationRegistry(BasePipelineDataRegistry):
     def register(
         self,
         name: str,
-        parcellation_path: Union[str, Path],
+        parcellation_path: str | Path,
         parcels_labels: list[str],
         space: str,
         overwrite: bool = False,
@@ -309,7 +318,7 @@ class ParcellationRegistry(BasePipelineDataRegistry):
         self,
         name: str,
         target_space: str,
-        resolution: Optional[float] = None,
+        resolution: float | None = None,
         path_only: bool = False,
     ) -> tuple[Optional["Nifti1Image"], list[str], Path, str]:
         """Load parcellation and labels.
@@ -463,9 +472,9 @@ class ParcellationRegistry(BasePipelineDataRegistry):
 
     def get(
         self,
-        parcellations: Union[str, list[str]],
+        parcellations: str | list[str],
         target_data: dict[str, Any],
-        extra_input: Optional[dict[str, Any]] = None,
+        extra_input: dict[str, Any] | None = None,
     ) -> tuple["Nifti1Image", dict[int, str]]:
         """Get parcellation, tailored for the target image.
 
@@ -539,6 +548,17 @@ class ParcellationRegistry(BasePipelineDataRegistry):
                 resolution=resolution,
                 target_space=target_space,
             )
+            # Map the labels to the values before resampling or warping,
+            # as small regions can be lost in the process
+            value_labels = dict(
+                zip(
+                    np.trim_zeros(
+                        np.unique(np.asarray(img.dataobj).astype(int))
+                    ).tolist(),
+                    labels,
+                    strict=True,
+                )
+            )
 
             # Convert parcellation spaces if required;
             # cannot be "native" due to earlier check
@@ -594,22 +614,27 @@ class ParcellationRegistry(BasePipelineDataRegistry):
                         warp_data=warper_spec,
                     )
 
+            # Keep the lost regions, so all elements have the same regions
+            present = set(
+                np.unique(np.asarray(img.dataobj).astype(int)).tolist()
+            )
+            lost = [
+                label
+                for value, label in value_labels.items()
+                if value not in present
+            ]
+            if lost:
+                warn_with_log(
+                    f"{len(lost)} region(s) of {name} have no voxels in the "
+                    f"target image, so they will have no data: {lost}"
+                )
             all_parcellations.append(img)
-            all_labels.append(labels)
+            all_labels.append(value_labels)
 
         # Avoid merging if there is only one parcellation
         if len(all_parcellations) == 1:
             resampled_parcellation_img = all_parcellations[0]
-            labels = dict(
-                zip(
-                    np.trim_zeros(
-                        np.unique(
-                            resampled_parcellation_img.get_fdata().astype(int)
-                        )
-                    ),
-                    all_labels[0],
-                )
-            )
+            labels = all_labels[0]
         # Parcellations are already transformed to target standard space
         else:
             logger.debug("Merging parcellations.")
@@ -623,8 +648,8 @@ class ParcellationRegistry(BasePipelineDataRegistry):
 
 
 def _retrieve_schaefer(
-    resolution: Optional[float] = None,
-    n_rois: Optional[int] = None,
+    resolution: float | None = None,
+    n_rois: int | None = None,
     yeo_networks: int = 7,
 ) -> tuple[Path, list[str]]:
     """Retrieve Schaefer parcellation.
@@ -707,8 +732,8 @@ def _retrieve_schaefer(
 
 
 def _retrieve_tian(
-    resolution: Optional[float] = None,
-    scale: Optional[int] = None,
+    resolution: float | None = None,
+    scale: int | None = None,
     space: str = "MNI152NLin6Asym",
     magneticfield: str = "3T",
 ) -> tuple[Path, list[str]]:
@@ -847,7 +872,7 @@ def _retrieve_tian(
 
 
 def _retrieve_suit(
-    resolution: Optional[float],
+    resolution: float | None,
     space: str = "MNI152NLin6Asym",
 ) -> tuple[Path, list[str]]:
     """Retrieve SUIT parcellation.
@@ -919,7 +944,7 @@ def _retrieve_suit(
 
 
 def _retrieve_aicha(
-    resolution: Optional[float] = None,
+    resolution: float | None = None,
     version: int = 2,
 ) -> tuple[Path, list[str]]:
     """Retrieve AICHA parcellation.
@@ -1013,7 +1038,7 @@ def _retrieve_aicha(
 
 
 def _retrieve_shen(
-    resolution: Optional[float] = None,
+    resolution: float | None = None,
     year: int = 2015,
     n_rois: int = 268,
 ) -> tuple[Path, list[str]]:
@@ -1109,16 +1134,29 @@ def _retrieve_shen(
             dataset_path=get_dataset_path(),
             **JUNIFER_DATA_PARAMS,
         )
-        labels = (
+        # The rows are sorted by name, so order them by the parcel value
+        # (first column) to match the parcellation image
+        names = (
             pd.read_csv(
                 parcellation_label_path,
                 sep=",",
                 header=None,
                 skiprows=[0],
-            )[1]
+            )
+            .sort_values(0)[1]
             .map(lambda x: x.strip())  # fix formatting
             .to_list()
         )
+        # Regions outside Brodmann areas share a name ("No_BA_region"), so
+        # number every occurrence of repeated names
+        counts = Counter(names)
+        seen: Counter = Counter()
+        labels = []
+        for name in names:
+            if counts[name] > 1:
+                seen[name] += 1
+                name = f"{name}-{seen[name]}"
+            labels.append(name)
     elif year == 2015:
         parcellation_img_path = get(
             file_path=path_prefix
@@ -1139,10 +1177,10 @@ def _retrieve_shen(
 
 
 def _retrieve_yan(
-    resolution: Optional[float] = None,
-    n_rois: Optional[int] = None,
-    yeo_networks: Optional[int] = None,
-    kong_networks: Optional[int] = None,
+    resolution: float | None = None,
+    n_rois: int | None = None,
+    yeo_networks: int | None = None,
+    kong_networks: int | None = None,
 ) -> tuple[Path, list[str]]:
     """Retrieve Yan parcellation.
 
@@ -1255,8 +1293,9 @@ def _retrieve_yan(
             **JUNIFER_DATA_PARAMS,
         )
 
-    # Load label file
-    labels = pd.read_csv(parcellation_label_path, sep=" ", header=None)[
+    # Load label file; the index is right-aligned with spaces, so split on
+    # any whitespace
+    labels = pd.read_csv(parcellation_label_path, sep=r"\s+", header=None)[
         1
     ].to_list()
 
@@ -1264,8 +1303,8 @@ def _retrieve_yan(
 
 
 def _retrieve_brainnetome(
-    resolution: Optional[float] = None,
-    threshold: Optional[int] = None,
+    resolution: float | None = None,
+    threshold: int | None = None,
 ) -> tuple[Path, list[str]]:
     """Retrieve Brainnetome parcellation.
 
@@ -1322,40 +1361,23 @@ def _retrieve_brainnetome(
         **JUNIFER_DATA_PARAMS,
     )
 
-    # Load labels
+    # Load labels (one row per label, ordered by label value)
+    parcellation_label_path = get(
+        file_path=Path("parcellations/Brainnetome/labels.csv"),
+        dataset_path=get_dataset_path(),
+        **JUNIFER_DATA_PARAMS,
+    )
     labels = (
-        sorted([f"SFG_L(R)_7_{i}" for i in range(1, 8)] * 2)
-        + sorted([f"MFG_L(R)_7_{i}" for i in range(1, 8)] * 2)
-        + sorted([f"IFG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"OrG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"PrG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"PCL_L(R)_2_{i}" for i in range(1, 3)] * 2)
-        + sorted([f"STG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"MTG_L(R)_4_{i}" for i in range(1, 5)] * 2)
-        + sorted([f"ITG_L(R)_7_{i}" for i in range(1, 8)] * 2)
-        + sorted([f"FuG_L(R)_3_{i}" for i in range(1, 4)] * 2)
-        + sorted([f"PhG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"pSTS_L(R)_2_{i}" for i in range(1, 3)] * 2)
-        + sorted([f"SPL_L(R)_5_{i}" for i in range(1, 6)] * 2)
-        + sorted([f"IPL_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"PCun_L(R)_4_{i}" for i in range(1, 5)] * 2)
-        + sorted([f"PoG_L(R)_4_{i}" for i in range(1, 5)] * 2)
-        + sorted([f"INS_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"CG_L(R)_7_{i}" for i in range(1, 8)] * 2)
-        + sorted([f"MVOcC _L(R)_5_{i}" for i in range(1, 6)] * 2)
-        + sorted([f"LOcC_L(R)_4_{i}" for i in range(1, 5)] * 2)
-        + sorted([f"LOcC_L(R)_2_{i}" for i in range(1, 3)] * 2)
-        + sorted([f"Amyg_L(R)_2_{i}" for i in range(1, 3)] * 2)
-        + sorted([f"Hipp_L(R)_2_{i}" for i in range(1, 3)] * 2)
-        + sorted([f"BG_L(R)_6_{i}" for i in range(1, 7)] * 2)
-        + sorted([f"Tha_L(R)_8_{i}" for i in range(1, 9)] * 2)
+        pd.read_csv(parcellation_label_path, sep=",")
+        .sort_values("idx")["label"]
+        .to_list()
     )
 
     return parcellation_img_path, labels
 
 
 def _retrieve_aseg(
-    resolution: Optional[float] = None,
+    resolution: float | None = None,
 ) -> tuple[Path, list[str]]:
     """Retrieve aseg generated from FreeSurfer 7.4.1 .
 
@@ -1455,7 +1477,7 @@ def _retrieve_aseg(
 
 
 def _retrieve_glasser(
-    resolution: Optional[float] = None,
+    resolution: float | None = None,
 ) -> tuple[Path, list[str]]:
     """Retrieve Glasser v1.0 .
 
@@ -1499,7 +1521,7 @@ def _retrieve_glasser(
 
 
 def _retrieve_julich_brain(
-    resolution: Optional[float] = None,
+    resolution: float | None = None,
     version: str = "v3_1",
 ) -> tuple[Path, list[str]]:
     """Retrieve Julich-Brain labelled parcellations.
@@ -1554,7 +1576,12 @@ def _retrieve_julich_brain(
         dataset_path=get_dataset_path(),
         **JUNIFER_DATA_PARAMS,
     )
-    labels = pd.read_csv(parcellation_label_path, sep=",")["label"].to_list()
+    # The "label" column is the value in the image and "region" the name
+    labels = (
+        pd.read_csv(parcellation_label_path, sep=",")
+        .sort_values("label")["region"]
+        .to_list()
+    )
 
     return parcellation_img_path, labels
 
@@ -1562,7 +1589,7 @@ def _retrieve_julich_brain(
 def merge_parcellations(
     parcellations_list: list["Nifti1Image"],
     parcellations_names: list[str],
-    labels_lists: list[list[str]],
+    labels_lists: list[list[str] | dict[int, str]],
 ) -> tuple["Nifti1Image", dict[int, str]]:
     """Merge multiple parcellations.
 
@@ -1572,9 +1599,12 @@ def merge_parcellations(
         List of parcellations to merge.
     parcellations_names: list of str
         List of names for parcellations at the corresponding indices.
-    labels_lists : list of list of str
-        A list of lists. Each list in the list contains the labels for the
-        parcellation at the corresponding index.
+    labels_lists : list of list of str or dict
+        The labels for the parcellation at the corresponding index, either
+        as a mapping of value to label or as a list of labels for the
+        (sorted) values in the parcellation. Use the mapping if regions
+        might be missing from the parcellation (e.g., after resampling), so
+        they keep their label.
 
     Returns
     -------
@@ -1585,39 +1615,42 @@ def merge_parcellations(
         Merged parcellation value to label mappings.
 
     """
+    # Get the value to label mapping of each parcellation; lists are
+    # matched to the values in the parcellation
+    label_maps = []
+    for parc, labels in zip(parcellations_list, labels_lists, strict=True):
+        if isinstance(labels, dict):
+            label_maps.append(dict(labels))
+        else:
+            values = np.trim_zeros(np.unique(parc.get_fdata().astype(int)))
+            label_maps.append(dict(zip(values.tolist(), labels, strict=True)))
+
     # Check for duplicated labels
-    labels_lists_flat = [item for sublist in labels_lists for item in sublist]
-    if len(labels_lists_flat) != len(set(labels_lists_flat)):
+    labels_flat = [label for m in label_maps for label in m.values()]
+    if len(labels_flat) != len(set(labels_flat)):
         warn_with_log(
             "The parcellations have duplicated labels. "
             "Each label will be prefixed with the parcellation name."
         )
-        for i_parcellation, t_labels in enumerate(labels_lists):
-            labels_lists[i_parcellation] = [
-                f"{parcellations_names[i_parcellation]}_{t_label}"
-                for t_label in t_labels
-            ]
+        label_maps = [
+            {value: f"{name}_{label}" for value, label in m.items()}
+            for name, m in zip(parcellations_names, label_maps, strict=True)
+        ]
     overlapping_voxels = False
     ref_parc = parcellations_list[0]
     ref_parc_data = ref_parc.get_fdata()
 
-    # Get max value for the parcellation ROIs to get a reference for ROI value
-    # increment
-    max_val = np.max(
-        np.concatenate(
-            [np.unique(p.get_fdata().astype(int)) for p in parcellations_list]
-        )
+    # Get max value for the parcellation ROIs (including the ones that might
+    # not be in the images) to get a reference for ROI value increment
+    max_val = max(
+        max(np.max(p.get_fdata().astype(int)) for p in parcellations_list),
+        max(max(m, default=0) for m in label_maps),
     )
     # Setup parcellation value to label mapping
-    val_label_map = dict(
-        zip(
-            np.trim_zeros(np.unique(ref_parc_data.astype(int))),
-            labels_lists[0],
-        ),
-    )
+    val_label_map = dict(label_maps[0])
 
     for idx, (parc, labs) in enumerate(
-        zip(parcellations_list[1:], labels_lists[1:])
+        zip(parcellations_list[1:], label_maps[1:], strict=True)
     ):
         # Resample to reference (1st in the list) parcellation
         if parc.shape != ref_parc.shape:
@@ -1636,8 +1669,9 @@ def merge_parcellations(
         # Increase the values of each ROI to match the labels
         # and update label mapping
         parc_data[parc_data != 0] += (idx + 1) * max_val
+        offset = (idx + 1) * max_val
         val_label_map.update(
-            dict(zip(np.trim_zeros(np.unique(parc_data.astype(int))), labs))
+            {value + offset: label for value, label in labs.items()}
         )
         # Only set new values for the voxels that are 0
         # This makes sure that the voxels that are in multiple