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

junifer/data/parcellations/tests/test_parcellations.py

@@ -7,6 +7,7 @@
 
 from pathlib import Path
 
+import nibabel as nib
 import numpy as np
 import pytest
 from nilearn.image import new_img_like, resample_to_img
@@ -19,7 +20,10 @@ from junifer.data import (
     load_data,
     register_data,
 )
-from junifer.data.parcellations import merge_parcellations
+from junifer.data.parcellations import (
+    ParcellationRegistry,
+    merge_parcellations,
+)
 from junifer.data.parcellations._parcellations import (
     _retrieve_aicha,
     _retrieve_brainnetome,
@@ -38,6 +42,9 @@ from junifer.testing.datagrabbers import (
 )
 
 
+pytestmark = pytest.mark.external
+
+
 def test_register_built_in_check() -> None:
     """Test parcellation registration check for built-in parcellations."""
     with pytest.raises(ValueError, match=r"built-in parcellation"):
@@ -1032,6 +1039,120 @@ def test_retrieve_julich_brain_incorrect_version() -> None:
         )
 
 
+# Parcellations whose labels are only numbers
+NUMBERED_PARCELLATIONS = ("Shen_2015_268", "Shen_2019_368")
+
+
+@pytest.mark.parametrize("name", ParcellationRegistry().list)
+def test_built_in_labels(name: str) -> None:
+    """Test built-in parcellations have one unique label per region.
+
+    Parameters
+    ----------
+    name : str
+        The parametrized parcellation name.
+
+    """
+    space = ParcellationRegistry()._registry[name]["space"]
+    img, labels, _, _ = load_data(
+        kind="parcellation",
+        name=name,
+        target_space=space,
+        # Lower resolution to make it faster; Shen 2019 is only in 1mm
+        resolution=1 if name == "Shen_2019_368" else 2,
+    )
+    values = np.unique(np.asarray(img.dataobj))
+    assert len(labels) == np.count_nonzero(values)
+    assert len(set(labels)) == len(labels)
+    if name not in NUMBERED_PARCELLATIONS:
+        assert all(isinstance(x, str) and x for x in labels)
+
+
+@pytest.mark.parametrize(
+    "name, value, label",
+    [
+        # Labels are read from look-up tables
+        ("Yan100xYeo7", 1, "7networks_LH_Default_FPole"),
+        ("Yan1000xKong17", 1000, "17networks_RH_VisualA_TempOcc_8"),
+        # The label file is sorted by name, not by value
+        ("Shen_2013_100", 1, "R.BA40.3"),
+        ("Shen_2013_150", 1, "R.BA6.9"),
+        # Repeated names are numbered
+        ("Shen_2013_50", 1, "No_BA_region-1"),
+        # Odd values are in the left hemisphere, even in the right one
+        ("Brainnetome_thr0", 1, "SFG_L_7_1"),
+        ("Brainnetome_thr0", 2, "SFG_R_7_1"),
+        ("Brainnetome_thr0", 246, "Tha_R_8_8"),
+        # Labels are the region names, ordered by value
+        ("Julich-Brain_V1_18", 1, "Area 45 (IFG) right"),
+        ("Julich-Brain_V3_0_3", 1, "Area 45 (IFG) left"),
+    ],
+)
+def test_labels_by_value(name: str, value: int, label: str) -> None:
+    """Test built-in parcellation labels match their values.
+
+    Parameters
+    ----------
+    name : str
+        The parametrized parcellation name.
+    value : int
+        The parametrized value of the region in the parcellation.
+    label : str
+        The parametrized expected label of the region.
+
+    """
+    space = ParcellationRegistry()._registry[name]["space"]
+    img, labels, _, _ = load_data(
+        kind="parcellation",
+        name=name,
+        target_space=space,
+    )
+    # Labels are in the order of the (sorted) values in the image
+    values = np.unique(np.asarray(img.dataobj).astype(int))
+    values = values[values != 0].tolist()
+    assert labels[values.index(value)] == label
+
+
+def test_get_lost_regions(tmp_path: Path) -> None:
+    """Test regions lost in resampling keep their labels.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    data = np.zeros((12, 12, 12), dtype=np.int16)
+    data[:6] = 1
+    # A single voxel, not sampled by the 3mm grid (voxels 0, 3, 6 and 9)
+    data[7, 7, 7] = 2
+    data[8:] = 3
+    parcellation_path = tmp_path / "lost.nii.gz"
+    nib.save(nib.Nifti1Image(data, np.eye(4)), parcellation_path)
+    register_data(
+        kind="parcellation",
+        name="LostRegion",
+        parcellation_path=parcellation_path,
+        parcels_labels=["a", "b", "c"],
+        space="MNI152NLin6Asym",
+    )
+    target = {
+        "data": nib.Nifti1Image(
+            np.zeros((4, 4, 4)), np.diag([3.0, 3.0, 3.0, 1.0])
+        ),
+        "space": "MNI152NLin6Asym",
+    }
+    with pytest.warns(RuntimeWarning, match=r"1 region\(s\) .* \['b'\]"):
+        img, labels = get_data(
+            kind="parcellation", names="LostRegion", target_data=target
+        )
+    deregister_data(kind="parcellation", name="LostRegion")
+    # The lost region is not in the image but keeps its label, and the
+    # following region keeps its own label
+    assert 2 not in np.unique(img.get_fdata())
+    assert labels == {1: "a", 2: "b", 3: "c"}
+
+
 def test_merge_parcellations() -> None:
     """Test merging parcellations."""
     # load some parcellations for testing

junifer/data/template_spaces.py

@@ -3,29 +3,51 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+import re
+from functools import cache
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Union
 
 import nibabel as nib
 import numpy as np
+import structlog
 from junifer_data import get
 from templateflow import api as tflow
 
-from ..utils import logger, raise_error
+from ..typing import SpaceLike
+from ..utils import raise_error
 from .utils import JUNIFER_DATA_PARAMS, closest_resolution, get_dataset_path
 
 
 __all__ = ["get_template", "get_xfm"]
 
+_log = structlog.get_logger("junifer")
+logger = _log.bind(pkg="data")
 
-def get_xfm(src: str, dst: str) -> Path:  # pragma: no cover
+
+@cache
+def _get_templateflow_templates() -> frozenset[str]:
+    """Get the available templateflow template spaces.
+
+    Querying templateflow scans its whole layout, so the result is cached.
+
+    Returns
+    -------
+    frozenset of str
+        The available template spaces.
+
+    """
+    return frozenset(tflow.templates())
+
+
+def get_xfm(src: SpaceLike, dst: SpaceLike) -> Path:  # pragma: no cover
     """Fetch warp files to convert from ``src`` to ``dst``.
 
     Parameters
     ----------
-    src : str
+    src : str or Enum
         The template space to transform from.
-    dst : str
+    dst : str or Enum
         The template space to transform to.
 
     Returns
@@ -34,6 +56,9 @@ def get_xfm(src: str, dst: str) -> Path:  # pragma: no cover
         The path to the transformation file.
 
     """
+    # Normalise enum-based spaces (e.g. `AOMICSpace`) to their values
+    src = getattr(src, "value", src)
+    dst = getattr(dst, "value", dst)
     # Set file path to retrieve
     xfm_file_path = Path(f"xfms/{src}_to_{dst}/{src}_to_{dst}_Composite.h5")
     # Retrieve file
@@ -44,18 +69,57 @@ def get_xfm(src: str, dst: str) -> Path:  # pragma: no cover
     )
 
 
+def _get_template_resolutions(
+    space: str, entities: dict[str, str | None]
+) -> dict[int, float]:
+    """Get the resolutions of a template that have the given files.
+
+    Not every resolution of a template has every file (e.g., in
+    templateflow 25, MNI152NLin2009cAsym lists resolutions 3 and 4, but has
+    no brain mask for them), and the resolution index is not the voxel size
+    (e.g., resolution 3 of MNI152NLin6Asym is 0.5mm).
+
+    Parameters
+    ----------
+    space : str
+        The name of the template space.
+    entities : dict
+        The templateflow entities of the files (e.g., ``suffix``).
+
+    Returns
+    -------
+    dict
+        The voxel size (in mm) of each resolution index with files.
+
+    """
+    # The voxel size of each resolution index. Indices are compared as
+    # integers, as file names can use "1" while metadata uses "01"
+    voxel_sizes = {
+        int(index): float(min(info["zooms"]))
+        for index, info in tflow.get_metadata(space)["res"].items()
+    }
+    # List the files without downloading them and keep their resolutions
+    resolutions = {}
+    for path in tflow.ls(space, extension="nii.gz", **entities):
+        match = re.search(r"_res-(\d+)_", Path(path).name)
+        if match is not None and int(match.group(1)) in voxel_sizes:
+            index = int(match.group(1))
+            resolutions[index] = voxel_sizes[index]
+    return resolutions
+
+
 def get_template(
-    space: str,
+    space: SpaceLike,
     target_img: nib.Nifti1Image,
-    extra_input: Optional[dict[str, Any]] = None,
+    extra_input: dict[str, Any] | None = None,
     template_type: str = "T1w",
-    resolution: Optional[Union[int, "str"]] = None,
+    resolution: Union[int, "str"] | None = None,
 ) -> nib.Nifti1Image:
     """Get template for the space, tailored for the target image.
 
     Parameters
     ----------
-    space : str
+    space : str or Enum
         The name of the template space.
     target_img : Nifti1Image
         The corresponding image for which the template space will be loaded.
@@ -66,9 +130,9 @@ def get_template(
     template_type : {"T1w", "brain", "gm", "wm", "csf"}, optional
         The template type to retrieve (default "T1w").
     resolution : int or "highest", optional
-        The resolution of the template to fetch. If None, the closest
-        resolution to the target image is used (default None). If "highest",
-        the highest resolution is used.
+        The resolution (voxel size in mm) of the template to fetch. If None,
+        the closest resolution to the target image is used (default None).
+        If "highest", the highest resolution is used.
 
     Returns
     -------
@@ -84,8 +148,10 @@ def get_template(
         If required template is not found.
 
     """
+    # Normalise enum-based spaces (e.g. `AOMICSpace`) to their values
+    space = getattr(space, "value", space)
     # Check for invalid space; early check to raise proper error
-    if space not in tflow.templates():
+    if space not in _get_templateflow_templates():
         raise_error(f"Unknown template space: {space}")
 
     # Check for template type
@@ -97,60 +163,61 @@ def get_template(
             "Invalid resolution value. Must be an integer or 'highest'"
         )
 
-    # Fetch available resolutions for the template
-    available_resolutions = [
-        int(min(val["zooms"]))
-        for val in tflow.get_metadata(space)["res"].values()
-    ]
+    # Get the templateflow entities of the template type
+    if template_type == "T1w":
+        entities = {"suffix": "T1w", "desc": None, "label": None}
+    elif template_type == "brain":
+        entities = {"suffix": "mask", "desc": "brain", "label": None}
+    else:
+        entities = {
+            "suffix": "probseg",
+            "desc": None,
+            "label": template_type.upper(),
+        }
 
-    # Get the min of the voxels sizes and use it as the resolution
-    if resolution is None:
-        resolution = np.min(target_img.header.get_zooms()[:3]).astype(int)
-    elif resolution == "highest":
-        resolution = 0
+    # Get the resolutions that have the template type
+    resolutions = _get_template_resolutions(space, entities)
+    if not resolutions:
+        raise_error(
+            msg=f"Template {space} ({template_type}) not found",
+            klass=RuntimeError,
+        )
+
+    # Get the desired voxel size; None means the highest resolution
+    if resolution == "highest":
+        desired_voxel_size = None
+    elif resolution is None:
+        desired_voxel_size = float(np.min(target_img.header.get_zooms()[:3]))
+    else:
+        desired_voxel_size = resolution
 
-    # Use the closest resolution if desired resolution is not found
-    resolution = closest_resolution(resolution, available_resolutions)
+    # Use the closest voxel size if the desired one is not available
+    voxel_size = closest_resolution(
+        desired_voxel_size, list(resolutions.values())
+    )
+    # Get the resolution index of that voxel size
+    res_index = {size: index for index, size in resolutions.items()}[
+        voxel_size
+    ]
 
     logger.info(
         f"Downloading template {space} ({template_type} in "
-        f"resolution {resolution})"
+        f"resolution {voxel_size}mm)"
     )
     # Retrieve template
     try:
-        suffix = None
-        desc = None
-        label = None
-        if template_type == "T1w":
-            suffix = template_type
-            desc = None
-            label = None
-        elif template_type == "brain":
-            suffix = "mask"
-            desc = "brain"
-            label = None
-        elif template_type in ["gm", "wm", "csf"]:
-            suffix = "probseg"
-            desc = None
-            label = template_type.upper()
-        # Set kwargs for fetching
-        kwargs = {
-            "suffix": suffix,
-            "desc": desc,
-            "label": label,
-        }
         template_path = tflow.get(
             space,
             raise_empty=True,
-            resolution=resolution,
+            resolution=res_index,
             extension="nii.gz",
-            **kwargs,
+            **entities,
         )
     except Exception:  # noqa: BLE001
         raise_error(
             msg=(
                 f"Template {space} ({template_type}) with resolution "
-                f"{resolution}) not found"
+                f"{voxel_size}mm not found"
             ),
             klass=RuntimeError,
         )

junifer/data/tests/test_template_spaces.py

@@ -12,11 +12,14 @@ import pytest
 from junifer.data import get_template, get_xfm
 from junifer.datareader import DefaultDataReader
 from junifer.testing.datagrabbers import (
-    OasisVBMTestingDataGrabber,
     PartlyCloudyTestingDataGrabber,
+    UCLACNPVBMTestingDataGrabber,
 )
 
 
+pytestmark = pytest.mark.external
+
+
 @pytest.mark.skipif(
     socket.gethostname() != "juseless",
     reason="only for juseless",
@@ -70,8 +73,8 @@ def test_get_template(template_type: str) -> None:
 
 def test_get_template_invalid_space() -> None:
     """Test invalid space check for template fetch."""
-    with OasisVBMTestingDataGrabber() as dg:
-        element = dg["sub-01"]
+    with UCLACNPVBMTestingDataGrabber() as dg:
+        element = dg["sub-10206"]
         element_data = DefaultDataReader().fit_transform(element)
         vbm_gm = element_data["VBM_GM"]
         # Get tailored parcellation
@@ -81,8 +84,8 @@ def test_get_template_invalid_space() -> None:
 
 def test_get_template_invalid_template_type() -> None:
     """Test invalid template type check for template fetch."""
-    with OasisVBMTestingDataGrabber() as dg:
-        element = dg["sub-01"]
+    with UCLACNPVBMTestingDataGrabber() as dg:
+        element = dg["sub-10206"]
         element_data = DefaultDataReader().fit_transform(element)
         vbm_gm = element_data["VBM_GM"]
         # Get tailored parcellation
@@ -96,8 +99,8 @@ def test_get_template_invalid_template_type() -> None:
 
 def test_get_template_closest_resolution() -> None:
     """Test closest resolution check for template fetch."""
-    with OasisVBMTestingDataGrabber() as dg:
-        element = dg["sub-01"]
+    with UCLACNPVBMTestingDataGrabber() as dg:
+        element = dg["sub-10206"]
         element_data = DefaultDataReader().fit_transform(element)
         vbm_gm = element_data["VBM_GM"]
         # Change header resolution to fetch closest resolution

junifer/data/utils.py

@@ -6,11 +6,11 @@
 
 from collections.abc import MutableMapping
 from pathlib import Path
-from typing import Optional, Union
 
 import numpy as np
+import structlog
 
-from ..utils import config, logger, raise_error
+from ..utils import config, raise_error
 
 
 __all__ = [
@@ -22,12 +22,14 @@ __all__ = [
     "get_native_warper",
 ]
 
+_log = structlog.get_logger("junifer")
+logger = _log.bind(pkg="data")
 
 # junifer-data version constant
-JUNIFER_DATA_VERSION = "7"
+JUNIFER_DATA_VERSION = "8"
 
 # junifer-data hexsha constant
-JUNIFER_DATA_HEXSHA = "f5144e6fef7d6f4f26508c3653d94a622f10207c"
+JUNIFER_DATA_HEXSHA = "c03636438bb1345299c7b79bd6428e25035102c5"
 
 JUNIFER_DATA_PARAMS = {
     "tag": JUNIFER_DATA_VERSION,
@@ -36,9 +38,9 @@ JUNIFER_DATA_PARAMS = {
 
 
 def closest_resolution(
-    resolution: Optional[Union[float, int]],
-    valid_resolution: Union[list[float], list[int], np.ndarray],
-) -> Union[float, int]:
+    resolution: float | int | None,
+    valid_resolution: list[float] | list[int] | np.ndarray,
+) -> float | int:
     """Find the closest resolution.
 
     Parameters
@@ -136,7 +138,7 @@ def get_native_warper(
     return possible_warpers[0]
 
 
-def get_dataset_path() -> Optional[Path]:
+def get_dataset_path() -> Path | None:
     """Get junifer-data dataset path.
 
     Returns

junifer/datagrabber/__init__.pyi

@@ -3,30 +3,63 @@ __all__ = [
     "DataladDataGrabber",
     "PatternDataGrabber",
     "PatternDataladDataGrabber",
+    "AOMICSpace",
+    "AOMICTask",
     "DataladAOMICID1000",
     "DataladAOMICPIOP1",
     "DataladAOMICPIOP2",
     "HCP1200",
+    "HCP1200Task",
+    "HCP1200PhaseEncoding",
     "DataladHCP1200",
     "MultipleDataGrabber",
     "DMCC13Benchmark",
+    "DMCCSession",
+    "DMCCTask",
+    "DMCCPhaseEncoding",
+    "DMCCRun",
     "DataTypeManager",
     "DataTypeSchema",
     "OptionalTypeSchema",
     "PatternValidationMixin",
     "register_data_type",
+    "DataType",
+    "ConfoundsFormat",
+    "register_confounds_format",
+    "logger",
 ]
 
 # These 4 need to be in this order, otherwise it is a circular import
-from .base import BaseDataGrabber
+from .base import BaseDataGrabber, DataType, logger
 from .datalad_base import DataladDataGrabber
-from .pattern import PatternDataGrabber
+from .pattern import (
+    PatternDataGrabber,
+    ConfoundsFormat,
+    register_confounds_format,
+)
 from .pattern_datalad import PatternDataladDataGrabber
 
-from .aomic import DataladAOMICID1000, DataladAOMICPIOP1, DataladAOMICPIOP2
-from .hcp1200 import HCP1200, DataladHCP1200
+from .aomic import (
+    AOMICSpace,
+    AOMICTask,
+    DataladAOMICID1000,
+    DataladAOMICPIOP1,
+    DataladAOMICPIOP2,
+)
+from .hcp1200 import (
+    HCP1200,
+    HCP1200Task,
+    HCP1200PhaseEncoding,
+    DataladHCP1200,
+)
 from .multiple import MultipleDataGrabber
-from .dmcc13_benchmark import DMCC13Benchmark
+from .dmcc13_benchmark import (
+    DMCC13Benchmark,
+    DMCCSession,
+    DMCCTask,
+    DMCCPhaseEncoding,
+    DMCCRun,
+)
 
 from .pattern_validation_mixin import (
     DataTypeManager,

junifer/datagrabber/aomic/__init__.pyi

@@ -1,5 +1,12 @@
-__all__ = ["DataladAOMICID1000", "DataladAOMICPIOP1", "DataladAOMICPIOP2"]
+__all__ = [
+    "AOMICSpace",
+    "AOMICTask",
+    "DataladAOMICID1000",
+    "DataladAOMICPIOP1",
+    "DataladAOMICPIOP2",
+]
 
+from ._types import AOMICSpace, AOMICTask
 from .id1000 import DataladAOMICID1000
 from .piop1 import DataladAOMICPIOP1
 from .piop2 import DataladAOMICPIOP2

junifer/datagrabber/aomic/_types.py

@@ -0,0 +1,22 @@
+"""Provide common types for AOMIC DataGrabbers."""
+
+from enum import StrEnum
+
+
+class AOMICSpace(StrEnum):
+    """Accepted spaces for AOMIC."""
+
+    Native = "native"
+    MNI152NLin2009cAsym = "MNI152NLin2009cAsym"
+
+
+class AOMICTask(StrEnum):
+    """Accepted tasks for AOMIC."""
+
+    RestingState = "restingstate"
+    Anticipation = "anticipation"
+    EmoMatching = "emomatching"
+    Faces = "faces"
+    Gstroop = "gstroop"
+    WorkingMemory = "workingmemory"
+    StopSignal = "stopsignal"