junifer 0.0.3.dev188__py3-none-any.whl → 0.0.4__py3-none-any.whl

junifer/pipeline/update_meta_mixin.py

@@ -23,19 +23,25 @@ class UpdateMetaMixin:
             The data object to update.
         step_name : str
             The name of the pipeline step.
+
         """
+        # Initialize empty dictionary for the step's metadata
         t_meta = {}
+        # Set class name for the step
         t_meta["class"] = self.__class__.__name__
+        # Add object variables to metadata if name doesn't start with "_"
         for k, v in vars(self).items():
             if not k.startswith("_"):
                 t_meta[k] = v
-
+        # Add "meta" to the step's local context dict
         if "meta" not in input:
             input["meta"] = {}
+        # Add step name
         input["meta"][step_name] = t_meta
+        # Add step dependencies
         if "dependencies" not in input["meta"]:
             input["meta"]["dependencies"] = set()
-
+        # Update step dependencies
         dependencies = getattr(self, "_DEPENDENCIES", set())
         if dependencies is not None:
             if not isinstance(dependencies, (set, list)):

junifer/pipeline/utils.py

@@ -10,16 +10,17 @@ from typing import Any, List, Optional
 from junifer.utils.logging import raise_error, warn_with_log
 
 
-def check_ext_dependencies(name: str, optional: bool, **kwargs: Any) -> bool:
+def check_ext_dependencies(
+    name: str, optional: bool = False, **kwargs: Any
+) -> bool:
     """Check if external dependency `name` is found if mandatory.
 
     Parameters
     ----------
     name : str
         The name of the dependency.
-    optional : bool
-        Whether the dependency is optional. For external dependencies marked
-        as optional, there should be an implementation provided with junfier.
+    optional : bool, optional
+        Whether the dependency is optional (default False).
     **kwargs : dict
         Extra keyword arguments.
 
@@ -28,33 +29,49 @@ def check_ext_dependencies(name: str, optional: bool, **kwargs: Any) -> bool:
     bool
         Whether the external dependency was found.
 
+    Raises
+    ------
+    ValueError
+        If ``name`` is invalid.
+    RuntimeError
+        If ``name`` is mandatory and is not found.
+
     """
+    valid_ext_dependencies = ("afni", "fsl", "ants")
+    if name not in valid_ext_dependencies:
+        raise_error(
+            "Invalid value for `name`, should be one of: "
+            f"{valid_ext_dependencies}"
+        )
     # Check for afni
     if name == "afni":
         found = _check_afni(**kwargs)
-    # Went off the rails
-    else:
-        raise_error(
-            f"The external dependency {name} has no check. "
-            f"Either the name '{name}' is incorrect or you were too "
-            "adventurous. Raise an issue if it's the latter ;-)."
-        )
+    # Check for fsl
+    elif name == "fsl":
+        found = _check_fsl(**kwargs)
+    # Check for ants
+    elif name == "ants":
+        found = _check_ants(**kwargs)
+
     # Check if the dependency is mandatory in case it's not found
     if not found and not optional:
         raise_error(
-            f"{name} is not installed but is "
-            "required by one of the pipeline steps."
+            msg=(
+                f"{name} is not installed but is "
+                "required by one of the pipeline steps"
+            ),
+            klass=RuntimeError,
         )
     return found
 
 
 def _check_afni(commands: Optional[List[str]] = None) -> bool:
-    """Check if afni is present in the system.
+    """Check if AFNI is present in the system.
 
     Parameters
     ----------
     commands : list of str, optional
-        The commands to specifically check for from afni. If None, only
+        The commands to specifically check for from AFNI. If None, only
         the basic afni version would be looked up, else, would also
         check for specific commands (default None).
 
@@ -106,3 +123,125 @@ def _check_afni(commands: Optional[List[str]] = None) -> bool:
                 f"{commands_found_results}"
             )
     return afni_found
+
+
+def _check_fsl(commands: Optional[List[str]] = None) -> bool:
+    """Check if FSL is present in the system.
+
+    Parameters
+    ----------
+    commands : list of str, optional
+        The commands to specifically check for from FSL. If None, only
+        the basic FSL flirt version would be looked up, else, would also
+        check for specific commands (default None).
+
+    Returns
+    -------
+    bool
+        Whether FSL is found or not.
+
+    """
+    completed_process = subprocess.run(
+        "flirt",
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.STDOUT,
+        shell=True,  # is unsafe but kept for resolution via PATH
+        check=False,
+    )
+    fsl_found = completed_process.returncode == 1
+
+    # Check for specific commands
+    if fsl_found and commands is not None:
+        if not isinstance(commands, list):
+            commands = [commands]
+        # Store command found results
+        commands_found_results = {}
+        # Set all commands found flag to True
+        all_commands_found = True
+        # Check commands' existence
+        for command in commands:
+            command_process = subprocess.run(
+                [command],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
+                shell=True,  # is unsafe but kept for resolution via PATH
+                check=False,
+            )
+            # FSL commands are incoherent with respect to status code hence a
+            # blanket to only look for no command found
+            command_found = command_process.returncode != 127
+            commands_found_results[command] = (
+                "found" if command_found else "not found"
+            )
+            # Set flag to trigger warning
+            all_commands_found = all_commands_found and command_found
+        # One or more commands were missing
+        if not all_commands_found:
+            warn_with_log(
+                "FSL is installed but some of the required commands "
+                "were not found. These are the results: "
+                f"{commands_found_results}"
+            )
+    return fsl_found
+
+
+def _check_ants(commands: Optional[List[str]] = None) -> bool:
+    """Check if ANTs is present in the system.
+
+    Parameters
+    ----------
+    commands : list of str, optional
+        The commands to specifically check for from ANTs. If None, only
+        the basic ANTS help would be looked up, else, would also
+        check for specific commands (default None).
+
+    Returns
+    -------
+    bool
+        Whether ANTs is found or not.
+
+    """
+    completed_process = subprocess.run(
+        "ANTS --help",
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.STDOUT,
+        shell=True,  # is unsafe but kept for resolution via PATH
+        check=False,
+    )
+    ants_found = completed_process.returncode == 0
+
+    # Check for specific commands
+    if ants_found and commands is not None:
+        if not isinstance(commands, list):
+            commands = [commands]
+        # Store command found results
+        commands_found_results = {}
+        # Set all commands found flag to True
+        all_commands_found = True
+        # Check commands' existence
+        for command in commands:
+            command_process = subprocess.run(
+                [command],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
+                shell=True,  # is unsafe but kept for resolution via PATH
+                check=False,
+            )
+            command_found = command_process.returncode == 0
+            commands_found_results[command] = (
+                "found" if command_found else "not found"
+            )
+            # Set flag to trigger warning
+            all_commands_found = all_commands_found and command_found
+        # One or more commands were missing
+        if not all_commands_found:
+            warn_with_log(
+                "ANTs is installed but some of the required commands "
+                "were not found. These are the results: "
+                f"{commands_found_results}"
+            )
+    return ants_found

junifer/pipeline/workdir_manager.py

@@ -0,0 +1,246 @@
+"""Provide a work directory manager class to be used by pipeline components."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+#          Federico Raimondo <f.raimondo@fz-juelich.de>
+# License: AGPL
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional, Union
+
+from ..utils import logger
+from .singleton import singleton
+
+
+@singleton
+class WorkDirManager:
+    """Class for working directory manager.
+
+    This class is a singleton and is used for managing temporary and working
+    directories used across the pipeline by datagrabbers, preprocessors,
+    markers and so on. It maintains a single super-directory and provides
+    directories on-demand and cleans after itself thus keeping the user
+    filesystem clean.
+
+    Parameters
+    ----------
+    workdir : str or pathlib.Path, optional
+        The path to the super-directory. If None, "TMPDIR/junifer" is used
+        where TMPDIR is the platform-dependent temporary directory.
+
+    Attributes
+    ----------
+    workdir : pathlib.Path
+        The path to the working directory.
+    elementdir : pathlib.Path
+        The path to the element directory.
+    root_tempdir : pathlib.Path or None
+        The path to the root temporary directory.
+
+    """
+
+    def __init__(self, workdir: Optional[Union[str, Path]] = None) -> None:
+        """Initialize the class."""
+        self._workdir = Path(workdir) if isinstance(workdir, str) else workdir
+        self._elementdir = None
+        self._root_tempdir = None
+
+        self._set_default_workdir()
+
+    def _set_default_workdir(self) -> None:
+        """Set the default working directory if not set already."""
+        # Check and set topmost level directory if not provided
+        if self._workdir is None:
+            self._workdir = Path(tempfile.gettempdir()) / "junifer"
+            # Create directory if not found
+            if not self._workdir.is_dir():
+                logger.debug(
+                    "Creating working directory at "
+                    f"{self._workdir.resolve()!s}"
+                )
+                self._workdir.mkdir(parents=True)
+            logger.debug(
+                f"Setting working directory to {self._workdir.resolve()!s}"
+            )
+
+    def __del__(self) -> None:
+        """Destructor."""
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        """Clean up the element and temporary directories."""
+        # Remove element directory
+        self.cleanup_elementdir()
+        # Remove root temporary directory
+        if self._root_tempdir is not None:
+            logger.debug(
+                "Deleting temporary directory at "
+                f"{self._root_tempdir.resolve()!s}"
+            )
+            shutil.rmtree(self._root_tempdir, ignore_errors=True)
+            self._root_tempdir = None
+
+    @property
+    def workdir(self) -> Path:
+        """Get working directory."""
+        return self._workdir  # type: ignore
+
+    @workdir.setter
+    def workdir(self, path: Union[str, Path]) -> None:
+        """Set working directory.
+
+        The directory path is created if it doesn't exist yet.
+
+        Parameters
+        ----------
+        path : str or pathlib.Path
+            The path to the working directory.
+
+        """
+        # Check if existing working directory is same or not;
+        # if not, then clean up
+        if self._workdir != Path(path):
+            self._cleanup()
+        # Set working directory
+        self._workdir = Path(path)
+        logger.debug(
+            f"Changing working directory to {self._workdir.resolve()!s}"
+        )
+        # Create directory if not found
+        if not self._workdir.is_dir():
+            logger.debug(
+                f"Creating working directory at {self._workdir.resolve()!s}"
+            )
+            self._workdir.mkdir(parents=True)
+
+    @property
+    def elementdir(self) -> Path:
+        """Get element directory."""
+        return self._elementdir  # type: ignore
+
+    def get_element_tempdir(
+        self, prefix: Optional[str] = None, suffix: Optional[str] = None
+    ) -> Path:
+        """Get an element-scoped temporary directory.
+
+        This directory should be available only for the lifetime of an
+        element.
+
+        Parameters
+        ----------
+        prefix : str, optional
+            The temporary directory prefix. If None, a default prefix is used
+            (default None).
+        suffix : str, optional
+            The temporary directory suffix. If None, no suffix is added
+            (default None).
+
+        Returns
+        -------
+        pathlib.Path
+            The path to the temporary directory.
+
+        """
+        # Create element directory if not created already
+        if self._elementdir is None:
+            logger.debug(
+                "Setting up element directory under "
+                f"{self._workdir.resolve()!s}"  # type: ignore
+            )
+            self._elementdir = Path(tempfile.mkdtemp(dir=self._workdir))
+
+        logger.debug(
+            "Creating element temporary directory at "
+            f"{self._elementdir.resolve()!s}"
+        )
+        return Path(
+            tempfile.mkdtemp(
+                dir=self._elementdir, prefix=prefix, suffix=suffix
+            )
+        )
+
+    def delete_element_tempdir(self, tempdir: Path) -> None:
+        """Delete an element-scoped temporary directory.
+
+        Parameters
+        ----------
+        tempdir : pathlib.Path
+            The temporary directory path to be deleted.
+
+        """
+        logger.debug(f"Deleting element temporary directory at {tempdir}")
+        shutil.rmtree(tempdir, ignore_errors=True)
+
+    def cleanup_elementdir(self) -> None:
+        """Clean up element directory.
+
+        It should preferably be used after fitting a marker or something
+        similar in the element-specific scope. If called between components,
+        can lead to required intermediate files not being found.
+
+        """
+        if self._elementdir is not None:
+            logger.debug(
+                "Deleting element directory at "
+                f"{self._elementdir.resolve()!s}"
+            )
+            shutil.rmtree(self._elementdir, ignore_errors=True)
+            self._elementdir = None
+
+    @property
+    def root_tempdir(self) -> Optional[Path]:
+        """Get root temporary directory."""
+        return self._root_tempdir
+
+    def get_tempdir(
+        self, prefix: Optional[str] = None, suffix: Optional[str] = None
+    ) -> Path:
+        """Get a component-scoped temporary directory.
+
+        This directory should be available only for the lifetime of a component
+        like a preprocessor or marker.
+
+        Parameters
+        ----------
+        prefix : str, optional
+            The temporary directory prefix. If None, a default prefix is used
+            (default None).
+        suffix : str, optional
+            The temporary directory suffix. If None, no suffix is added
+            (default None).
+
+        Returns
+        -------
+        pathlib.Path
+            The path to the temporary directory.
+
+        """
+        # Create root temporary directory if not created already
+        if self._root_tempdir is None:
+            logger.debug(
+                "Setting up temporary directory under "
+                f"{self._workdir.resolve()!s}"  # type: ignore
+            )
+            self._root_tempdir = Path(tempfile.mkdtemp(dir=self._workdir))
+
+        logger.debug(
+            f"Creating temporary directory at {self._root_tempdir.resolve()!s}"
+        )
+        return Path(
+            tempfile.mkdtemp(
+                dir=self._root_tempdir, prefix=prefix, suffix=suffix
+            )
+        )
+
+    def delete_tempdir(self, tempdir: Path) -> None:
+        """Delete a component-scoped temporary directory.
+
+        Parameters
+        ----------
+        tempdir : pathlib.Path
+            The temporary directory path to be deleted.
+
+        """
+        logger.debug(f"Deleting temporary directory at {tempdir}")
+        shutil.rmtree(tempdir, ignore_errors=True)

junifer/preprocess/__init__.py

@@ -2,7 +2,10 @@
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
 #          Leonard Sasse <l.sasse@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
 from .base import BasePreprocessor
 from .confounds import fMRIPrepConfoundRemover
+from .bold_warper import BOLDWarper
+from .warping import SpaceWarper

junifer/preprocess/ants/__init__.py

@@ -0,0 +1,4 @@
+"""Provide imports for ants sub-package."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL

junifer/preprocess/ants/ants_apply_transforms_warper.py

@@ -0,0 +1,185 @@
+"""Provide class for warping via ANTs antsApplyTransforms."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+import nibabel as nib
+import numpy as np
+
+from ...pipeline import WorkDirManager
+from ...utils import logger, raise_error, run_ext_cmd
+
+
+if TYPE_CHECKING:
+    from nibabel import Nifti1Image
+
+
+class _AntsApplyTransformsWarper:
+    """Class for warping NIfTI images via ANTs antsApplyTransforms.
+
+    Warps ANTs ``antsApplyTransforms``.
+
+    Parameters
+    ----------
+    reference : str
+        The data type to use as reference for warping.
+    on : str
+        The data type to use for warping.
+
+    Raises
+    ------
+    ValueError
+        If a list was passed for ``on``.
+
+    """
+
+    _EXT_DEPENDENCIES: ClassVar[List[Dict[str, Union[str, List[str]]]]] = [
+        {
+            "name": "ants",
+            "commands": ["ResampleImage", "antsApplyTransforms"],
+        },
+    ]
+
+    def __init__(self, reference: str, on: str) -> None:
+        """Initialize the class."""
+        self.ref = reference
+        # Check only single data type is passed
+        if isinstance(on, list):
+            raise_error("Can only work on single data type, list was passed.")
+        self.on = on
+
+    def _run_apply_transforms(
+        self,
+        input_data: Dict,
+        ref_path: Path,
+        warp_path: Path,
+    ) -> Tuple["Nifti1Image", Path]:
+        """Run ``antsApplyTransforms``.
+
+        Parameters
+        ----------
+        input_data : dict
+            The input data.
+        ref_path : pathlib.Path
+            The path to the reference file.
+        warp_path : pathlib.Path
+            The path to the warp file.
+
+        Returns
+        -------
+        Niimg-like object
+            The warped input image.
+        pathlib.Path
+            The path to the resampled reference image.
+
+        """
+        # Get the min of the voxel sizes from input and use it as the
+        # resolution
+        resolution = np.min(input_data["data"].header.get_zooms()[:3])
+
+        # Create element-specific tempdir for storing post-warping assets
+        tempdir = WorkDirManager().get_element_tempdir(
+            prefix="applytransforms"
+        )
+
+        # Create a tempfile for resampled reference output
+        resample_image_out_path = tempdir / "reference_resampled.nii.gz"
+        # Set ResampleImage command
+        resample_image_cmd = [
+            "ResampleImage",
+            "3",  # image dimension
+            f"{ref_path.resolve()}",
+            f"{resample_image_out_path.resolve()}",
+            f"{resolution}x{resolution}x{resolution}",
+            "0",  # option for spacing and not size
+            "3 3",  # Lanczos windowed sinc
+        ]
+        # Call ResampleImage
+        run_ext_cmd(name="ResampleImage", cmd=resample_image_cmd)
+
+        # Create a tempfile for warped output
+        apply_transforms_out_path = tempdir / "input_warped.nii.gz"
+        # Set antsApplyTransforms command
+        apply_transforms_cmd = [
+            "antsApplyTransforms",
+            "-d 3",
+            "-e 3",
+            "-n LanczosWindowedSinc",
+            f"-i {input_data['path'].resolve()}",
+            # use resampled reference
+            f"-r {resample_image_out_path.resolve()}",
+            f"-t {warp_path.resolve()}",
+            f"-o {apply_transforms_out_path.resolve()}",
+        ]
+        # Call antsApplyTransforms
+        run_ext_cmd(name="antsApplyTransforms", cmd=apply_transforms_cmd)
+
+        # Load nifti
+        output_img = nib.load(apply_transforms_out_path)
+
+        return output_img, resample_image_out_path  # type: ignore
+
+    def preprocess(
+        self,
+        input: Dict[str, Any],
+        extra_input: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[str, Dict[str, Any]]:
+        """Preprocess.
+
+        Parameters
+        ----------
+        input : dict
+            A single input from the Junifer Data object in which to preprocess.
+        extra_input : dict, optional
+            The other fields in the Junifer Data object. Must include the
+            ``Warp`` and ``ref`` value's keys.
+
+        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.
+
+        """
+        logger.debug("Warping via ANTs using antsApplyTransforms")
+        # Check for extra inputs
+        if extra_input is None:
+            raise_error(
+                f"No extra input provided, requires `Warp` and `{self.ref}` "
+                "data types in particular."
+            )
+        # Retrieve data type info to warp
+        to_warp_input = input
+        # Retrieve data type info to use as reference
+        ref_input = extra_input[self.ref]
+        # Retrieve Warp data
+        warp = extra_input["Warp"]
+        # Replace original data with warped data and add resampled reference
+        # path
+        input["data"], input["reference_path"] = self._run_apply_transforms(
+            input_data=to_warp_input,
+            ref_path=ref_input["path"],
+            warp_path=warp["path"],
+        )
+        # Use reference input's space as warped input's space
+        input["space"] = ref_input["space"]
+        return self.on, input