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

junifer/data/coordinates.py

@@ -1,17 +1,19 @@
 """Provide functions for list of coordinates."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
 import typing
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
 from numpy.typing import ArrayLike
 
-from ..utils.logging import logger, raise_error
+from ..pipeline import WorkDirManager
+from ..utils import logger, raise_error, run_ext_cmd, warn_with_log
 
 
 # Path to the VOIs
@@ -23,29 +25,95 @@ _vois_meta_path = _vois_path / "meta"
 # A dictionary containing all supported coordinates and their respective file
 # or data.
 
+# Each entry is a dictionary that must contain at least the following keys:
+# * 'space': the coordinates' space (e.g., 'MNI')
+
 # The built-in coordinates are files that are shipped with the package in the
 # data/VOIs directory. The user can also register their own coordinates, which
 # will be stored as numpy arrays in the dictionary.
 _available_coordinates: Dict[
-    str, Union[Path, Dict[str, Union[ArrayLike, List[str]]]]
+    str, Dict[str, Union[Path, ArrayLike, List[str]]]
 ] = {
-    "CogAC": _vois_meta_path / "CogAC_VOIs.txt",
-    "CogAR": _vois_meta_path / "CogAR_VOIs.txt",
-    "DMNBuckner": _vois_meta_path / "DMNBuckner_VOIs.txt",
-    "eMDN": _vois_meta_path / "eMDN_VOIs.txt",
-    "Empathy": _vois_meta_path / "Empathy_VOIs.txt",
-    "eSAD": _vois_meta_path / "eSAD_VOIs.txt",
-    "extDMN": _vois_meta_path / "extDMN_VOIs.txt",
-    "Motor": _vois_meta_path / "Motor_VOIs.txt",
-    "MultiTask": _vois_meta_path / "MultiTask_VOIs.txt",
-    "PhysioStress": _vois_meta_path / "PhysioStress_VOIs.txt",
-    "Rew": _vois_meta_path / "Rew_VOIs.txt",
-    "Somatosensory": _vois_meta_path / "Somatosensory_VOIs.txt",
-    "ToM": _vois_meta_path / "ToM_VOIs.txt",
-    "VigAtt": _vois_meta_path / "VigAtt_VOIs.txt",
-    "WM": _vois_meta_path / "WM_VOIs.txt",
-    "Power": _vois_meta_path / "Power2011_MNI_VOIs.txt",
-    "Dosenbach": _vois_meta_path / "Dosenbach2010_MNI_VOIs.txt",
+    "CogAC": {
+        "path": _vois_meta_path / "CogAC_VOIs.txt",
+        "space": "MNI",
+    },
+    "CogAR": {
+        "path": _vois_meta_path / "CogAR_VOIs.txt",
+        "space": "MNI",
+    },
+    "DMNBuckner": {
+        "path": _vois_meta_path / "DMNBuckner_VOIs.txt",
+        "space": "MNI",
+    },
+    "eMDN": {
+        "path": _vois_meta_path / "eMDN_VOIs.txt",
+        "space": "MNI",
+    },
+    "Empathy": {
+        "path": _vois_meta_path / "Empathy_VOIs.txt",
+        "space": "MNI",
+    },
+    "eSAD": {
+        "path": _vois_meta_path / "eSAD_VOIs.txt",
+        "space": "MNI",
+    },
+    "extDMN": {
+        "path": _vois_meta_path / "extDMN_VOIs.txt",
+        "space": "MNI",
+    },
+    "Motor": {
+        "path": _vois_meta_path / "Motor_VOIs.txt",
+        "space": "MNI",
+    },
+    "MultiTask": {
+        "path": _vois_meta_path / "MultiTask_VOIs.txt",
+        "space": "MNI",
+    },
+    "PhysioStress": {
+        "path": _vois_meta_path / "PhysioStress_VOIs.txt",
+        "space": "MNI",
+    },
+    "Rew": {
+        "path": _vois_meta_path / "Rew_VOIs.txt",
+        "space": "MNI",
+    },
+    "Somatosensory": {
+        "path": _vois_meta_path / "Somatosensory_VOIs.txt",
+        "space": "MNI",
+    },
+    "ToM": {
+        "path": _vois_meta_path / "ToM_VOIs.txt",
+        "space": "MNI",
+    },
+    "VigAtt": {
+        "path": _vois_meta_path / "VigAtt_VOIs.txt",
+        "space": "MNI",
+    },
+    "WM": {
+        "path": _vois_meta_path / "WM_VOIs.txt",
+        "space": "MNI",
+    },
+    "Power": {
+        "path": _vois_meta_path / "Power2011_MNI_VOIs.txt",
+        "space": "MNI",
+    },
+    "Power2011": {
+        "path": _vois_meta_path / "Power2011_MNI_VOIs.txt",
+        "space": "MNI",
+    },
+    "Dosenbach": {
+        "path": _vois_meta_path / "Dosenbach2010_MNI_VOIs.txt",
+        "space": "MNI",
+    },
+    "Power2013": {
+        "path": _vois_meta_path / "Power2013_MNI_VOIs.tsv",
+        "space": "MNI",
+    },
+    "AutobiographicalMemory": {
+        "path": _vois_meta_path / "AutobiographicalMemory_VOIs.txt",
+        "space": "MNI",
+    },
 }
 
 
@@ -53,9 +121,10 @@ def register_coordinates(
     name: str,
     coordinates: ArrayLike,
     voi_names: List[str],
+    space: str,
     overwrite: Optional[bool] = False,
 ) -> None:
-    """Register coordinates.
+    """Register a custom user coordinates.
 
     Parameters
     ----------
@@ -68,12 +137,26 @@ def register_coordinates(
         z-coordinates).
     voi_names : list of str
         The names of the VOIs.
+    space : str
+        The space of the coordinates, for e.g., "MNI".
     overwrite : bool, optional
         If True, overwrite an existing list of coordinates with the same name.
         Does not apply to built-in coordinates (default False).
+
+    Raises
+    ------
+    ValueError
+        If the coordinates name is already registered and overwrite is set to
+        False or if the coordinates name is a built-in coordinates or if the
+        ``coordinates`` is not a 2D array or if coordinate value does not have
+        3 components or if the ``voi_names`` shape does not match the
+        ``coordinates`` shape.
+    TypeError
+        If ``coordinates`` is not a ``numpy.ndarray``.
+
     """
     if name in _available_coordinates:
-        if isinstance(_available_coordinates[name], Path):
+        if isinstance(_available_coordinates[name].get("path"), Path):
             raise_error(
                 f"Coordinates {name} already registered as built-in "
                 "coordinates."
@@ -88,7 +171,8 @@ def register_coordinates(
 
     if not isinstance(coordinates, np.ndarray):
         raise_error(
-            f"Coordinates must be a numpy.ndarray, not {type(coordinates)}."
+            f"Coordinates must be a `numpy.ndarray`, not {type(coordinates)}.",
+            klass=TypeError,
         )
     if coordinates.ndim != 2:
         raise_error(
@@ -100,27 +184,178 @@ def register_coordinates(
         )
     if len(voi_names) != coordinates.shape[0]:
         raise_error(
-            f"Length of voi_names ({len(voi_names)}) does not match the "
-            f"number of coordinates ({coordinates.shape[0]})."
+            f"Length of `voi_names` ({len(voi_names)}) does not match the "
+            f"number of `coordinates` ({coordinates.shape[0]})."
         )
     _available_coordinates[name] = {
         "coords": coordinates,
         "voi_names": voi_names,
+        "space": space,
     }
 
 
 def list_coordinates() -> List[str]:
-    """List all the available coordinates lists (VOIs).
+    """List all the available coordinates (VOIs).
 
     Returns
     -------
     list of str
         A list with all available coordinates names.
+
     """
     return sorted(_available_coordinates.keys())
 
 
-def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
+def get_coordinates(
+    coords: str,
+    target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
+) -> Tuple[ArrayLike, List[str]]:
+    """Get coordinates, tailored for the target image.
+
+    Parameters
+    ----------
+    coords : str
+        The name of the coordinates.
+    target_data : dict
+        The corresponding item of the data object to which the coordinates
+        will be applied.
+    extra_input : dict, optional
+        The other fields in the data object. Useful for accessing other data
+        kinds that needs to be used in the computation of coordinates
+        (default None).
+
+    Returns
+    -------
+    numpy.ndarray
+        The coordinates.
+    list of str
+        The names of the VOIs.
+
+    Raises
+    ------
+    RuntimeError
+        If warp / transformation file extension is not ".mat" or ".h5".
+    ValueError
+        If ``extra_input`` is None when ``target_data``'s space is native.
+
+    """
+    # Load the coordinates
+    seeds, labels, _ = load_coordinates(name=coords)
+
+    # Transform coordinate if target data is native
+    if target_data["space"] == "native":
+        # Check for extra inputs
+        if extra_input is None:
+            raise_error(
+                "No extra input provided, requires `Warp` and `T1w` "
+                "data types in particular for transformation to "
+                f"{target_data['space']} space for further computation."
+            )
+
+        # Create component-scoped tempdir
+        tempdir = WorkDirManager().get_tempdir(prefix="coordinates")
+
+        # Create element-scoped tempdir so that transformed coordinates is
+        # available later as numpy stores file path reference for
+        # loading on computation
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="coordinates"
+        )
+
+        # Check for warp file type to use correct tool
+        warp_file_ext = extra_input["Warp"]["path"].suffix
+        if warp_file_ext == ".mat":
+            # Save existing coordinates to a component-scoped tempfile
+            pretransform_coordinates_path = (
+                tempdir / "pretransform_coordinates.txt"
+            )
+            np.savetxt(pretransform_coordinates_path, seeds)
+
+            # Create an element-scoped tempfile for transformed coordinates
+            # output
+            transformed_coords_path = (
+                element_tempdir / "coordinates_transformed.txt"
+            )
+
+            logger.debug("Using FSL for coordinates transformation")
+            # Set img2imgcoord command
+            img2imgcoord_cmd = [
+                "cat",
+                f"{pretransform_coordinates_path.resolve()}",
+                "| img2imgcoord -mm",
+                f"-src {target_data['path'].resolve()}",
+                f"-dest {target_data['reference_path'].resolve()}",
+                f"-warp {extra_input['Warp']['path'].resolve()}",
+                f"> {transformed_coords_path.resolve()};",
+                f"sed -i 1d {transformed_coords_path.resolve()}",
+            ]
+            # Call img2imgcoord
+            run_ext_cmd(name="img2imgcoord", cmd=img2imgcoord_cmd)
+
+            # Load coordinates
+            seeds = np.loadtxt(transformed_coords_path)
+
+        elif warp_file_ext == ".h5":
+            # Save existing coordinates to a component-scoped tempfile
+            pretransform_coordinates_path = (
+                tempdir / "pretransform_coordinates.csv"
+            )
+            np.savetxt(
+                pretransform_coordinates_path,
+                seeds,
+                delimiter=",",
+                # Add header while saving to make ANTs work
+                header="x,y,z",
+            )
+
+            # Create an element-scoped tempfile for transformed coordinates
+            # output
+            transformed_coords_path = (
+                element_tempdir / "coordinates_transformed.csv"
+            )
+
+            logger.debug("Using ANTs for coordinates transformation")
+            # Set antsApplyTransformsToPoints command
+            apply_transforms_to_points_cmd = [
+                "antsApplyTransformsToPoints",
+                "-d 3",
+                "-p 1",
+                "-f 0",
+                f"-i {pretransform_coordinates_path.resolve()}",
+                f"-o {transformed_coords_path.resolve()}",
+                f"-t {extra_input['Warp']['path'].resolve()};",
+            ]
+            # Call antsApplyTransformsToPoints
+            run_ext_cmd(
+                name="antsApplyTransformsToPoints",
+                cmd=apply_transforms_to_points_cmd,
+            )
+
+            # Load coordinates
+            seeds = np.loadtxt(
+                # Skip header when reading
+                transformed_coords_path,
+                delimiter=",",
+                skiprows=1,
+            )
+
+        else:
+            raise_error(
+                msg=(
+                    "Unknown warp / transformation file extension: "
+                    f"{warp_file_ext}"
+                ),
+                klass=RuntimeError,
+            )
+
+        # Delete tempdir
+        WorkDirManager().delete_tempdir(tempdir)
+
+    return seeds, labels
+
+
+def load_coordinates(name: str) -> Tuple[ArrayLike, List[str], str]:
     """Load coordinates.
 
     Parameters
@@ -134,12 +369,43 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
         The coordinates.
     list of str
         The names of the VOIs.
+    str
+        The space of the coordinates.
+
+    Raises
+    ------
+    ValueError
+        If ``name`` is invalid.
+
+    Warns
+    -----
+    DeprecationWarning
+        If ``Power`` is provided as the ``name``.
+
     """
+    # Check for valid coordinates name
     if name not in _available_coordinates:
-        raise_error(f"Coordinates {name} not found.")
+        raise_error(
+            f"Coordinates {name} not found. "
+            f"Valid options are: {list_coordinates()}"
+        )
+
+    # Put up deprecation notice
+    if name == "Power":
+        warn_with_log(
+            msg=(
+                "`Power` has been replaced with `Power2011` and will be "
+                "removed in the next release. For now, it's available for "
+                "backward compatibility."
+            ),
+            category=DeprecationWarning,
+        )
+
+    # Load coordinates
     t_coord = _available_coordinates[name]
-    if isinstance(t_coord, Path):
-        df_coords = pd.read_csv(t_coord, sep="\t", header=None)
+    if isinstance(t_coord.get("path"), Path):
+        # Load via pandas
+        df_coords = pd.read_csv(t_coord["path"], sep="\t", header=None)
         coords = df_coords.iloc[:, [0, 1, 2]].to_numpy()
         names = list(df_coords.iloc[:, [3]].values[:, 0])
     else:
@@ -147,4 +413,5 @@ def load_coordinates(name: str) -> Tuple[ArrayLike, List[str]]:
         coords = typing.cast(ArrayLike, coords)
         names = t_coord["voi_names"]
         names = typing.cast(List[str], names)
-    return coords, names
+
+    return coords, names, t_coord["space"]