junifer 0.0.4.dev565__tar.gz → 0.0.4.dev587__tar.gz

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.4.dev565
+Version: 0.0.4.dev587
 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>
@@ -40,6 +40,7 @@ Requires-Dist: importlib_metadata; python_version < "3.10"
 Requires-Dist: h5py<3.10,>=3.8.0
 Requires-Dist: httpx[http2]==0.26.0
 Requires-Dist: tqdm==4.66.1
+Requires-Dist: templateflow>=23.0.0
 Provides-Extra: all
 Requires-Dist: bctpy==0.6.0; extra == "all"
 Requires-Dist: neurokit2>=0.1.7; extra == "all"

junifer-0.0.4.dev587/docs/changes/newsfragments/298.feature

@@ -0,0 +1 @@
+Introduce :func:`.get_template` to fetch template space image tailored to a target data by `Synchon Mandal`_

junifer-0.0.4.dev587/docs/changes/newsfragments/302.enh

@@ -0,0 +1 @@
+Allow :class:`.BOLDWarper` to warp BOLD data to other MNI spaces by `Synchon Mandal`_

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.4.dev565'
-__version_tuple__ = version_tuple = (0, 0, 4, 'dev565')
+__version__ = version = '0.0.4.dev587'
+__version_tuple__ = version_tuple = (0, 0, 4, 'dev587')

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/api/tests/test_api_utils.py

@@ -44,6 +44,7 @@ def test_get_dependency_information_short() -> None:
         "ruamel.yaml",
         "httpx",
         "tqdm",
+        "templateflow",
     ]
     if int(pl.python_version_tuple()[1]) < 10:
         dependency_list.append("importlib_metadata")
@@ -68,6 +69,7 @@ def test_get_dependency_information_long() -> None:
         "ruamel.yaml",
         "httpx",
         "tqdm",
+        "templateflow",
     ]
     for key in dependency_list:
         assert key in dependency_information_keys

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/data/__init__.py

@@ -25,6 +25,6 @@ from .masks import (
     get_mask,
 )
 
-from .template_spaces import get_xfm
+from .template_spaces import get_template, get_xfm
 
 from . import utils

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/data/template_spaces.py

@@ -4,11 +4,15 @@
 # License: AGPL
 
 from pathlib import Path
-from typing import Union
+from typing import Any, Dict, Optional, Union
 
 import httpx
+import nibabel as nib
+import numpy as np
+from templateflow import api as tflow
 
 from ..utils import logger, raise_error
+from .utils import closest_resolution
 
 
 def get_xfm(
@@ -89,3 +93,71 @@ def get_xfm(
                     f.write(chunk)
 
     return xfm_file_path
+
+
+def get_template(
+    space: str,
+    target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
+) -> nib.Nifti1Image:
+    """Get template for the space, tailored for the target image.
+
+    Parameters
+    ----------
+    space : str
+        The name of the template space.
+    target_data : dict
+        The corresponding item of the data object for which the template space
+        will be loaded.
+    extra_input : dict, optional
+        The other fields in the data object. Useful for accessing other data
+        types (default None).
+
+    Returns
+    -------
+    Nifti1Image
+        The template image.
+
+    Raises
+    ------
+    ValueError
+        If ``space`` is invalid.
+    RuntimeError
+        If template in the required resolution is not found.
+
+    """
+    # Check for invalid space; early check to raise proper error
+    if space not in tflow.templates():
+        raise_error(f"Unknown template space: {space}")
+
+    # Get the min of the voxels sizes and use it as the resolution
+    target_img = target_data["data"]
+    resolution = np.min(target_img.header.get_zooms()[:3]).astype(int)
+
+    # Fetch available resolutions for the template
+    available_resolutions = [
+        int(min(val["zooms"]))
+        for val in tflow.get_metadata(space)["res"].values()
+    ]
+    # Use the closest resolution if desired resolution is not found
+    resolution = closest_resolution(resolution, available_resolutions)
+
+    logger.info(f"Downloading template {space} in resolution {resolution}")
+    # Retrieve template
+    try:
+        template_path = tflow.get(
+            space,
+            raise_empty=True,
+            resolution=resolution,
+            suffix="T1w",
+            desc=None,
+            extension="nii.gz",
+        )
+    except Exception:  # noqa: BLE001
+        raise_error(
+            f"Template {space} not found in the required resolution "
+            f"{resolution}",
+            klass=RuntimeError,
+        )
+    else:
+        return nib.load(template_path)  # type: ignore

junifer-0.0.4.dev587/junifer/data/tests/test_template_spaces.py

@@ -0,0 +1,69 @@
+"""Provide tests for template spaces."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+import socket
+from pathlib import Path
+
+import nibabel as nib
+import pytest
+
+from junifer.data import get_template, get_xfm
+from junifer.datareader import DefaultDataReader
+from junifer.testing.datagrabbers import OasisVBMTestingDataGrabber
+
+
+@pytest.mark.skipif(
+    socket.gethostname() != "juseless",
+    reason="only for juseless",
+)
+def test_get_xfm(tmp_path: Path) -> None:
+    """Test warp file fetching.
+
+    Parameters
+    ----------
+    tmp_path : pathlib.Path
+        The path to the test directory.
+
+    """
+    xfm_path = get_xfm(
+        src="MNI152NLin6Asym", dst="MNI152NLin2009cAsym", xfms_dir=tmp_path
+    )
+    assert isinstance(xfm_path, Path)
+
+
+def test_get_template() -> None:
+    """Test tailored template image fetch."""
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = DefaultDataReader().fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        # Get tailored parcellation
+        tailored_template = get_template(
+            space=vbm_gm["space"], target_data=vbm_gm
+        )
+        assert isinstance(tailored_template, nib.Nifti1Image)
+
+
+def test_get_template_invalid_space() -> None:
+    """Test invalid space check for template fetch."""
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = DefaultDataReader().fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        # Get tailored parcellation
+        with pytest.raises(ValueError, match="Unknown template space:"):
+            _ = get_template(space="andromeda", target_data=vbm_gm)
+
+
+def test_get_template_closest_resolution() -> None:
+    """Test closest resolution check for template fetch."""
+    with OasisVBMTestingDataGrabber() as dg:
+        element = dg["sub-01"]
+        element_data = DefaultDataReader().fit_transform(element)
+        vbm_gm = element_data["VBM_GM"]
+        # Change header resolution to fetch closest resolution
+        element_data["VBM_GM"]["data"].header.set_zooms((3, 3, 3))
+        template = get_template(space=vbm_gm["space"], target_data=vbm_gm)
+        assert isinstance(template, nib.Nifti1Image)

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/data/utils.py

@@ -8,14 +8,14 @@ from ..utils.logging import logger
 
 
 def closest_resolution(
-    resolution: Optional[float],
+    resolution: Optional[Union[float, int]],
     valid_resolution: Union[List[float], List[int], np.ndarray],
 ) -> Union[float, int]:
     """Find the closest resolution.
 
     Parameters
     ----------
-    resolution : float, optional
+    resolution : float or int, optional
         The given resolution. If None, will return the highest resolution
         (default None).
     valid_resolution : list of float or int, or np.ndarray

junifer-0.0.4.dev587/junifer/preprocess/bold_warper.py

@@ -0,0 +1,244 @@
+"""Provide class for warping BOLD to other template spaces."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import nibabel as nib
+from templateflow import api as tflow
+
+from ..api.decorators import register_preprocessor
+from ..data import get_template, get_xfm
+from ..pipeline import WorkDirManager
+from ..utils import logger, raise_error, run_ext_cmd
+from .ants.ants_apply_transforms_warper import _AntsApplyTransformsWarper
+from .base import BasePreprocessor
+from .fsl.apply_warper import _ApplyWarper
+
+
+@register_preprocessor
+class BOLDWarper(BasePreprocessor):
+    """Class for warping BOLD NIfTI images.
+
+    Parameters
+    ----------
+    reference : str
+        The data type to use as reference for warping, can be either a data
+        type like "T1w" or a template space like "MNI152NLin2009cAsym".
+
+    Raises
+    ------
+    ValueError
+        If ``reference`` is invalid.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[
+        List[Dict[str, Union[str, bool, List[str]]]]
+    ] = [
+        {
+            "name": "fsl",
+            "optional": True,
+            "commands": ["flirt", "applywarp"],
+        },
+        {
+            "name": "ants",
+            "optional": True,
+            "commands": ["ResampleImage", "antsApplyTransforms"],
+        },
+    ]
+
+    def __init__(self, reference: str) -> None:
+        """Initialize the class."""
+        self.ref = reference
+        # Initialize superclass based on reference
+        if self.ref == "T1w":
+            super().__init__(
+                on="BOLD", required_data_types=["BOLD", self.ref, "Warp"]
+            )
+        elif self.ref in tflow.templates():
+            super().__init__(on="BOLD", required_data_types=["BOLD"])
+        else:
+            raise_error(f"Unknown reference: {self.ref}")
+
+    def get_valid_inputs(self) -> List[str]:
+        """Get valid data types for input.
+
+        Returns
+        -------
+        list of str
+            The list of data types that can be used as input for this
+            preprocessor.
+
+        """
+        return ["BOLD"]
+
+    def get_output_type(self, input: List[str]) -> List[str]:
+        """Get output type.
+
+        Parameters
+        ----------
+        input : list of str
+            The input to the preprocessor. The list must contain the
+            available Junifer Data dictionary keys.
+
+        Returns
+        -------
+        list of str
+            The updated list of available Junifer Data object keys after
+            the pipeline step.
+
+        """
+        # Does not add any new keys
+        return input
+
+    def preprocess(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[str, Dict[str, Any]]:
+        """Preprocess.
+
+        Parameters
+        ----------
+        input : dict
+            The BOLD input from the Junifer Data object.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object. Must include the
+            ``Warp`` and ``ref`` value's keys if native space transformation is
+            needed.
+
+        Returns
+        -------
+        str
+            The key to store the output in the Junifer Data object.
+        dict
+            The computed result as dictionary. This will be stored in the
+            Junifer Data object under the key ``data`` of the data type.
+
+        Raises
+        ------
+        ValueError
+            If ``extra_input`` is None when transforming to native space
+            i.e., using "T1w" as reference.
+        RuntimeError
+            If warp / transformation file extension is not ".mat" or ".h5"
+            when transforming to native space or
+            if the BOLD data is in the correct space and does not require
+            warping.
+
+        """
+        logger.info(f"Warping BOLD to {self.ref} space using BOLDWarper")
+        # Transform to native space
+        if self.ref == "T1w":
+            # Check for extra inputs
+            if extra_input is None:
+                raise_error(
+                    "No extra input provided, requires `Warp` and "
+                    f"`{self.ref}` data types in particular."
+                )
+            # Check for warp file type to use correct tool
+            warp_file_ext = extra_input["Warp"]["path"].suffix
+            if warp_file_ext == ".mat":
+                logger.debug("Using FSL with BOLDWarper")
+                # Initialize ApplyWarper for computation
+                apply_warper = _ApplyWarper(reference=self.ref, on="BOLD")
+                # Replace original BOLD data with warped BOLD data
+                _, input = apply_warper.preprocess(
+                    input=input,
+                    extra_input=extra_input,
+                )
+            elif warp_file_ext == ".h5":
+                logger.debug("Using ANTs with BOLDWarper")
+                # Initialize AntsApplyTransformsWarper for computation
+                ants_apply_transforms_warper = _AntsApplyTransformsWarper(
+                    reference=self.ref, on="BOLD"
+                )
+                # Replace original BOLD data with warped BOLD data
+                _, input = ants_apply_transforms_warper.preprocess(
+                    input=input,
+                    extra_input=extra_input,
+                )
+            else:
+                raise_error(
+                    msg=(
+                        "Unknown warp / transformation file extension: "
+                        f"{warp_file_ext}"
+                    ),
+                    klass=RuntimeError,
+                )
+        # Transform to template space
+        else:
+            # Check pre-requirements for space manipulation
+            if self.ref == input["space"]:
+                raise_error(
+                    (
+                        f"Skipped warping as the BOLD data is in {self.ref} "
+                        "space which would mean that you can remove the "
+                        "BOLDWarper from the preprocess step."
+                    ),
+                    klass=RuntimeError,
+                )
+            else:
+                # Get xfm file
+                xfm_file_path = get_xfm(src=input["space"], dst=self.ref)
+                # Get template space image
+                template_space_img = get_template(
+                    space=self.ref,
+                    target_data=input,
+                    extra_input=None,
+                )
+
+                # Create component-scoped tempdir
+                tempdir = WorkDirManager().get_tempdir(prefix="boldwarper")
+                # Create element-scoped tempdir so that warped BOLD is
+                # available later as nibabel stores file path reference for
+                # loading on computation
+                element_tempdir = WorkDirManager().get_element_tempdir(
+                    prefix="boldwarper"
+                )
+
+                # Save template
+                template_space_img_path = tempdir / f"{self.ref}_T1w.nii.gz"
+                nib.save(template_space_img, template_space_img_path)
+
+                # Create a tempfile for warped output
+                warped_bold_path = (
+                    element_tempdir
+                    / f"bold_warped_from_{input['space']}_to_{self.ref}.nii.gz"
+                )
+
+                logger.debug(
+                    f"Using ANTs to warp BOLD "
+                    f"from {input['space']} to {self.ref}"
+                )
+                # Set antsApplyTransforms command
+                apply_transforms_cmd = [
+                    "antsApplyTransforms",
+                    "-d 3",
+                    "-e 3",
+                    "-n LanczosWindowedSinc",
+                    f"-i {input['path'].resolve()}",
+                    f"-r {template_space_img_path.resolve()}",
+                    f"-t {xfm_file_path.resolve()}",
+                    f"-o {warped_bold_path.resolve()}",
+                ]
+                # Call antsApplyTransforms
+                run_ext_cmd(
+                    name="antsApplyTransforms", cmd=apply_transforms_cmd
+                )
+
+                # Modify target data
+                input["data"] = nib.load(warped_bold_path)
+                input["space"] = self.ref
+
+        return "BOLD", input

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer/preprocess/tests/test_bold_warper.py

@@ -7,6 +7,7 @@ import socket
 from typing import TYPE_CHECKING, List, Tuple
 
 import pytest
+from numpy.testing import assert_array_equal, assert_raises
 
 from junifer.datagrabber import DataladHCP1200, DMCC13Benchmark
 from junifer.datareader import DefaultDataReader
@@ -83,7 +84,7 @@ def test_BOLDWarper_get_output_type(input_: List[str]) -> None:
     socket.gethostname() != "juseless",
     reason="only for juseless",
 )
-def test_BOLDWarper_preprocess(
+def test_BOLDWarper_preprocess_to_native(
     datagrabber: "BaseDataGrabber", element: Tuple[str, ...]
 ) -> None:
     """Test BOLDWarper preprocess.
@@ -106,3 +107,70 @@ def test_BOLDWarper_preprocess(
         )
         assert data_type == "BOLD"
         assert isinstance(data, dict)
+
+
+@pytest.mark.parametrize(
+    "datagrabber, element, space",
+    [
+        [
+            DMCC13Benchmark(
+                types=["BOLD"],
+                sessions=["wave1bas"],
+                tasks=["Rest"],
+                phase_encodings=["AP"],
+                runs=["1"],
+                native_t1w=False,
+            ),
+            ("f9057kp", "wave1bas", "Rest", "AP", "1"),
+            "MNI152NLin2009aAsym",
+        ],
+        [
+            DMCC13Benchmark(
+                types=["BOLD"],
+                sessions=["wave1bas"],
+                tasks=["Rest"],
+                phase_encodings=["AP"],
+                runs=["1"],
+                native_t1w=False,
+            ),
+            ("f9057kp", "wave1bas", "Rest", "AP", "1"),
+            "MNI152NLin6Asym",
+        ],
+    ],
+)
+@pytest.mark.skipif(
+    _check_ants() is False, reason="requires ANTs to be in PATH"
+)
+@pytest.mark.skipif(
+    socket.gethostname() != "juseless",
+    reason="only for juseless",
+)
+def test_BOLDWarper_preprocess_to_multi_mni(
+    datagrabber: "BaseDataGrabber", element: Tuple[str, ...], space: str
+) -> None:
+    """Test BOLDWarper preprocess.
+
+    Parameters
+    ----------
+    datagrabber : DataGrabber-like object
+        The parametrized DataGrabber objects.
+    element : tuple of str
+        The parametrized elements.
+    space : str
+        The parametrized template space to transform to.
+
+    """
+    with datagrabber as dg:
+        # Read data
+        element_data = DefaultDataReader().fit_transform(dg[element])
+        pre_xfm_data = element_data["BOLD"]["data"].get_fdata().copy()
+        # Preprocess data
+        data_type, data = BOLDWarper(reference=space).preprocess(
+            input=element_data["BOLD"],
+            extra_input=element_data,
+        )
+        assert data_type == "BOLD"
+        assert isinstance(data, dict)
+        assert data["space"] == space
+        with assert_raises(AssertionError):
+            assert_array_equal(pre_xfm_data, data["data"])

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.4.dev565
+Version: 0.0.4.dev587
 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>
@@ -40,6 +40,7 @@ Requires-Dist: importlib_metadata; python_version < "3.10"
 Requires-Dist: h5py<3.10,>=3.8.0
 Requires-Dist: httpx[http2]==0.26.0
 Requires-Dist: tqdm==4.66.1
+Requires-Dist: templateflow>=23.0.0
 Provides-Extra: all
 Requires-Dist: bctpy==0.6.0; extra == "all"
 Requires-Dist: neurokit2>=0.1.7; extra == "all"

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer.egg-info/SOURCES.txt

@@ -106,9 +106,11 @@ docs/changes/newsfragments/293.misc
 docs/changes/newsfragments/294.misc
 docs/changes/newsfragments/295.feature
 docs/changes/newsfragments/297.feature
+docs/changes/newsfragments/298.feature
 docs/changes/newsfragments/300.doc
 docs/changes/newsfragments/300.enh
 docs/changes/newsfragments/300.misc
+docs/changes/newsfragments/302.enh
 docs/extending/coordinates.rst
 docs/extending/datagrabber.rst
 docs/extending/extension.rst

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/junifer.egg-info/requires.txt

@@ -10,6 +10,7 @@ ruamel.yaml<0.18,>=0.17
 h5py<3.10,>=3.8.0
 httpx[http2]==0.26.0
 tqdm==4.66.1
+templateflow>=23.0.0
 
 [:python_version < "3.10"]
 importlib_metadata

{junifer-0.0.4.dev565 → junifer-0.0.4.dev587}/pyproject.toml

@@ -48,6 +48,7 @@ dependencies = [
     "h5py>=3.8.0,<3.10",
     "httpx[http2]==0.26.0",
     "tqdm==4.66.1",
+    "templateflow>=23.0.0",
 ]
 dynamic = ["version"]
 
@@ -188,8 +189,10 @@ known-third-party =[
     "nilearn",
     "sqlalchemy",
     "yaml",
+    "importlib_metadata",
     "httpx",
     "tqdm",
+    "templateflow",
     "bct",
     "neurokit2",
     "pytest",

junifer-0.0.4.dev565/junifer/data/tests/test_template_spaces.py

@@ -1,30 +0,0 @@
-"""Provide tests for template spaces."""
-
-# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
-# License: AGPL
-
-import socket
-from pathlib import Path
-
-import pytest
-
-from junifer.data import get_xfm
-
-
-@pytest.mark.skipif(
-    socket.gethostname() != "juseless",
-    reason="only for juseless",
-)
-def test_get_xfm(tmp_path: Path) -> None:
-    """Test warp file fetching.
-
-    Parameters
-    ----------
-    tmp_path : pathlib.Path
-        The path to the test directory.
-
-    """
-    xfm_path = get_xfm(
-        src="MNI152NLin6Asym", dst="MNI152NLin2009cAsym", xfms_dir=tmp_path
-    )
-    assert isinstance(xfm_path, Path)