junifer 0.0.5.dev240__py3-none-any.whl → 0.0.6__py3-none-any.whl

junifer/data/coordinates/_coordinates.py

@@ -0,0 +1,385 @@
+"""Provide a class for centralized coordinates data registry."""
+
+# Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+from typing import Any, Optional
+
+import numpy as np
+import pandas as pd
+from junifer_data import get
+from numpy.typing import ArrayLike
+
+from ...utils import logger, raise_error
+from ...utils.singleton import Singleton
+from ..pipeline_data_registry_base import BasePipelineDataRegistry
+from ..utils import JUNIFER_DATA_PARAMS, get_dataset_path, get_native_warper
+from ._ants_coordinates_warper import ANTsCoordinatesWarper
+from ._fsl_coordinates_warper import FSLCoordinatesWarper
+
+
+__all__ = ["CoordinatesRegistry"]
+
+
+class CoordinatesRegistry(BasePipelineDataRegistry, metaclass=Singleton):
+    """Class for coordinates data registry.
+
+    This class is a singleton and is used for managing available coordinates
+    data in a centralized manner.
+
+    """
+
+    def __init__(self) -> None:
+        """Initialize the class."""
+        super().__init__()
+        # Each entry in registry 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
+        # junifer-data dataset. The user can also register their own
+        # coordinates, which will be stored as numpy arrays in the dictionary.
+        # Make built-in and external dictionaries for validation later
+        self._builtin = {}
+        self._external = {}
+
+        self._builtin.update(
+            {
+                "CogAC": {
+                    "file_path_suffix": "CogAC/CogAC_VOIs.txt",
+                    "space": "MNI",
+                },
+                "CogAR": {
+                    "file_path_suffix": "CogAR/CogAR_VOIs.txt",
+                    "space": "MNI",
+                },
+                "DMNBuckner": {
+                    "file_path_suffix": "DMNBuckner/DMNBuckner_VOIs.txt",
+                    "space": "MNI",
+                },
+                "eMDN": {
+                    "file_path_suffix": "eMDN/eMDN_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Empathy": {
+                    "file_path_suffix": "Empathy/Empathy_VOIs.txt",
+                    "space": "MNI",
+                },
+                "eSAD": {
+                    "file_path_suffix": "eSAD/eSAD_VOIs.txt",
+                    "space": "MNI",
+                },
+                "extDMN": {
+                    "file_path_suffix": "extDMN/extDMN_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Motor": {
+                    "file_path_suffix": "Motor/Motor_VOIs.txt",
+                    "space": "MNI",
+                },
+                "MultiTask": {
+                    "file_path_suffix": "MultiTask/MultiTask_VOIs.txt",
+                    "space": "MNI",
+                },
+                "PhysioStress": {
+                    "file_path_suffix": "PhysioStress/PhysioStress_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Rew": {
+                    "file_path_suffix": "Rew/Rew_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Somatosensory": {
+                    "file_path_suffix": "Somatosensory/Somatosensory_VOIs.txt",
+                    "space": "MNI",
+                },
+                "ToM": {
+                    "file_path_suffix": "ToM/ToM_VOIs.txt",
+                    "space": "MNI",
+                },
+                "VigAtt": {
+                    "file_path_suffix": "VigAtt/VigAtt_VOIs.txt",
+                    "space": "MNI",
+                },
+                "WM": {
+                    "file_path_suffix": "WM/WM_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Power2011": {
+                    "file_path_suffix": "Power/Power2011_MNI_VOIs.txt",
+                    "space": "MNI",
+                },
+                "Dosenbach": {
+                    "file_path_suffix": "Dosenbach/Dosenbach2010_MNI_VOIs.txt",
+                    "space": "MNI",
+                },
+                "AutobiographicalMemory": {
+                    "file_path_suffix": (
+                        "AutobiographicalMemory/AutobiographicalMemory_VOIs.txt"
+                    ),
+                    "space": "MNI",
+                },
+                "Seitzman2018": {
+                    "file_path_suffix": "Seitzman/Seitzman2018_MNI_VOIs.txt",
+                    "space": "MNI",
+                },
+            }
+        )
+
+        # Update registry with built-in ones
+        self._registry.update(self._builtin)
+
+    def register(
+        self,
+        name: str,
+        coordinates: ArrayLike,
+        voi_names: list[str],
+        space: str,
+        overwrite: Optional[bool] = False,
+    ) -> None:
+        """Register a custom user coordinates.
+
+        Parameters
+        ----------
+        name : str
+            The name of the coordinates.
+        coordinates : numpy.ndarray
+            The coordinates. This should be a 2-dimensional array with three
+            columns. Each row corresponds to a volume-of-interest (VOI) and
+            each column corresponds to a spatial dimension (i.e. x, y, and
+            z-coordinates).
+        voi_names : list of str
+            The names of the VOIs.
+        space : str
+            The space of the coordinates, 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 a built-in coordinates or
+            if the coordinates ``name`` is already registered and
+            ``overwrite=False`` 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``.
+
+        """
+        # Check for attempt of overwriting built-in coordinates
+        if name in self._builtin:
+            raise_error(
+                f"Coordinates: {name} already registered as built-in "
+                "coordinates."
+            )
+        # Check for attempt of overwriting external coordinates
+        if name in self._external:
+            if overwrite:
+                logger.info(f"Overwriting coordinates: {name}")
+            else:
+                raise_error(
+                    f"Coordinates: {name} already registered. "
+                    "Set `overwrite=True` to update its value."
+                )
+        # Further checks
+        if not isinstance(coordinates, np.ndarray):
+            raise_error(
+                "Coordinates must be a `numpy.ndarray`, "
+                f"not {type(coordinates)}.",
+                klass=TypeError,
+            )
+        if coordinates.ndim != 2:
+            raise_error(
+                f"Coordinates must be a 2D array, not {coordinates.ndim}D."
+            )
+        if coordinates.shape[1] != 3:
+            raise_error(
+                "Each coordinate must have 3 values, "
+                f"not {coordinates.shape[1]}"
+            )
+        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]})."
+            )
+        # Registration
+        logger.info(f"Registering coordinates: {name}")
+        # Add coordinates info
+        self._external[name] = {
+            "coords": coordinates,
+            "voi_names": voi_names,
+            "space": space,
+        }
+        # Update registry
+        self._registry[name] = {
+            "coords": coordinates,
+            "voi_names": voi_names,
+            "space": space,
+        }
+
+    def deregister(self, name: str) -> None:
+        """De-register a custom user coordinates.
+
+        Parameters
+        ----------
+        name : str
+            The name of the coordinates.
+
+        """
+        logger.info(f"De-registering coordinates: {name}")
+        # Remove coordinates info
+        _ = self._external.pop(name)
+        # Update registry
+        _ = self._registry.pop(name)
+
+    def load(self, name: str) -> tuple[ArrayLike, list[str], str]:
+        """Load coordinates.
+
+        Parameters
+        ----------
+        name : str
+            The name of the coordinates.
+
+        Returns
+        -------
+        numpy.ndarray
+            The coordinates.
+        list of str
+            The names of the VOIs.
+        str
+            The space of the coordinates.
+
+        Raises
+        ------
+        ValueError
+            If ``name`` is invalid.
+        RuntimeError
+            If there is a problem fetching the coordinates file.
+
+        """
+        # Check for valid coordinates name
+        if name not in self._registry:
+            raise_error(
+                f"Coordinates: {name} not found. "
+                f"Valid options are: {self.list}"
+            )
+        # Load coordinates info
+        t_coord = self._registry[name]
+
+        # Load data for in-built ones
+        if t_coord.get("file_path_suffix") is not None:
+            # Set file path to retrieve
+            coords_file_path = Path(
+                f"coordinates/{t_coord['file_path_suffix']}"
+            )
+            logger.debug(f"Loading coordinates: `{name}`")
+            # Load via pandas
+            df_coords = pd.read_csv(
+                get(
+                    file_path=coords_file_path,
+                    dataset_path=get_dataset_path(),
+                    **JUNIFER_DATA_PARAMS,
+                ),
+                sep="\t",
+                header=None,
+            )
+            # Convert dataframe to numpy ndarray
+            coords = df_coords.iloc[:, [0, 1, 2]].to_numpy()
+            # Get label names
+            names = list(df_coords.iloc[:, [3]].values[:, 0])
+        # Load data for external ones
+        else:
+            coords = t_coord["coords"]
+            names = t_coord["voi_names"]
+
+        return coords, names, t_coord["space"]
+
+    def get(
+        self,
+        coords: str,
+        target_data: dict[str, Any],
+        extra_input: Optional[dict[str, Any]] = None,
+    ) -> tuple[ArrayLike, list[str]]:
+        """Get coordinates, tailored for the target data.
+
+        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 warping specification required for warping using ANTs, is not
+            found.
+        ValueError
+            If ``extra_input`` is None when ``target_data``'s space is native.
+
+        """
+        # Load the coordinates
+        seeds, labels, _ = self.load(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."
+                )
+
+            # Get native space warper spec
+            warper_spec = get_native_warper(
+                target_data=target_data,
+                other_data=extra_input,
+            )
+            # Conditional for warping tool implementation
+            if warper_spec["warper"] == "fsl":
+                seeds = FSLCoordinatesWarper().warp(
+                    seeds=seeds,
+                    target_data=target_data,
+                    warp_data=warper_spec,
+                )
+            elif warper_spec["warper"] == "ants":
+                # Requires the inverse warp
+                inverse_warper_spec = get_native_warper(
+                    target_data=target_data,
+                    other_data=extra_input,
+                    inverse=True,
+                )
+                # Check warper
+                if inverse_warper_spec["warper"] != "ants":
+                    raise_error(
+                        klass=RuntimeError,
+                        msg=(
+                            "Warping specification mismatch for native space "
+                            "warping of coordinates using ANTs."
+                        ),
+                    )
+                seeds = ANTsCoordinatesWarper().warp(
+                    seeds=seeds,
+                    target_data=target_data,
+                    warp_data=inverse_warper_spec,
+                )
+
+        return seeds, labels

junifer/data/coordinates/_fsl_coordinates_warper.py

@@ -0,0 +1,81 @@
+"""Provide class for coordinates space warping via FSL FLIRT."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from ...pipeline import WorkDirManager
+from ...utils import logger, run_ext_cmd
+
+
+__all__ = ["FSLCoordinatesWarper"]
+
+
+class FSLCoordinatesWarper:
+    """Class for coordinates space warping via FSL FLIRT.
+
+    This class uses FSL FLIRT's ``img2imgcoord`` for transformation.
+
+    """
+
+    def warp(
+        self,
+        seeds: ArrayLike,
+        target_data: dict[str, Any],
+        warp_data: dict[str, Any],
+    ) -> ArrayLike:
+        """Warp ``seeds`` to correct space.
+
+        Parameters
+        ----------
+        seeds : array-like
+            The coordinates to transform.
+        target_data : dict
+            The corresponding item of the data object to which the coordinates
+            will be applied.
+        warp_data : dict
+            The warp data item of the data object.
+
+        Returns
+        -------
+        numpy.ndarray
+            The transformed coordinates.
+
+        """
+        logger.debug("Using FSL for coordinates transformation")
+
+        # Create element-specific tempdir for storing post-warping assets
+        element_tempdir = WorkDirManager().get_element_tempdir(
+            prefix="fsl_coordinates_warper"
+        )
+
+        # Save existing coordinates to a tempfile
+        pretransform_coordinates_path = (
+            element_tempdir / "pretransform_coordinates.txt"
+        )
+        np.savetxt(pretransform_coordinates_path, seeds)
+
+        # Create a tempfile for transformed coordinates output
+        transformed_coords_path = (
+            element_tempdir / "coordinates_transformed.txt"
+        )
+        # 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 {warp_data['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
+        return np.loadtxt(transformed_coords_path)

junifer/data/{tests → coordinates/tests}/test_coordinates.py

@@ -1,52 +1,47 @@
 """Provide tests for coordinates."""
 
 # Authors: Federico Raimondo <f.raimondo@fz-juelich.de>
+#          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
 import numpy as np
 import pytest
 from numpy.testing import assert_array_equal
 
-from junifer.data.coordinates import (
-    get_coordinates,
-    list_coordinates,
-    load_coordinates,
-    register_coordinates,
-)
+from junifer.data import CoordinatesRegistry
 from junifer.datareader import DefaultDataReader
 from junifer.testing.datagrabbers import OasisVBMTestingDataGrabber
 
 
-def test_register_coordinates_built_in_check() -> None:
+def test_register_built_in_check() -> None:
     """Test coordinates registration check for built-in coordinates."""
     with pytest.raises(ValueError, match=r"built-in"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="DMNBuckner",
             coordinates=np.zeros(2),
             voi_names=["1", "2"],
             space="MNI",
-            overwrite=True,
         )
 
 
-def test_register_coordinates_overwrite() -> None:
+def test_register_overwrite() -> None:
     """Test coordinates registration check for overwriting."""
-    register_coordinates(
+    CoordinatesRegistry().register(
         name="MyList",
         coordinates=np.zeros((2, 3)),
         voi_names=["roi1", "roi2"],
         space="MNI",
-        overwrite=True,
     )
     with pytest.raises(ValueError, match=r"already registered"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="MyList",
             coordinates=np.ones((2, 3)),
             voi_names=["roi2", "roi3"],
             space="MNI",
+            overwrite=False,
         )
 
-    register_coordinates(
+    CoordinatesRegistry().register(
         name="MyList",
         coordinates=np.ones((2, 3)),
         voi_names=["roi2", "roi3"],
@@ -54,16 +49,16 @@ def test_register_coordinates_overwrite() -> None:
         overwrite=True,
     )
 
-    coord, names, space = load_coordinates("MyList")
+    coord, names, space = CoordinatesRegistry().load("MyList")
     assert_array_equal(coord, np.ones((2, 3)))
     assert names == ["roi2", "roi3"]
     assert space == "MNI"
 
 
-def test_register_coordinates_valid_input() -> None:
+def test_register_valid_input() -> None:
     """Test coordinates registration check for valid input."""
     with pytest.raises(TypeError, match=r"numpy.ndarray"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="MyList",
             coordinates=[1, 2],
             voi_names=["roi1", "roi2"],
@@ -71,7 +66,7 @@ def test_register_coordinates_valid_input() -> None:
             overwrite=True,
         )
     with pytest.raises(ValueError, match=r"2D array"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="MyList",
             coordinates=np.zeros((2, 3, 4)),
             voi_names=["roi1", "roi2"],
@@ -80,7 +75,7 @@ def test_register_coordinates_valid_input() -> None:
         )
 
     with pytest.raises(ValueError, match=r"3 values"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="MyList",
             coordinates=np.zeros((2, 4)),
             voi_names=["roi1", "roi2"],
@@ -88,7 +83,7 @@ def test_register_coordinates_valid_input() -> None:
             overwrite=True,
         )
     with pytest.raises(ValueError, match=r"voi_names"):
-        register_coordinates(
+        CoordinatesRegistry().register(
             name="MyList",
             coordinates=np.zeros((2, 3)),
             voi_names=["roi1", "roi2", "roi3"],
@@ -97,30 +92,28 @@ def test_register_coordinates_valid_input() -> None:
         )
 
 
-def test_list_coordinates() -> None:
+def test_list() -> None:
     """Test listing of available coordinates."""
-    available_coordinates = list_coordinates()
-    assert "DMNBuckner" in available_coordinates
-    assert "MultiTask" in available_coordinates
-    assert "VigAtt" in available_coordinates
-    assert "WM" in available_coordinates
+    assert {"DMNBuckner", "MultiTask", "VigAtt", "WM"}.issubset(
+        set(CoordinatesRegistry().list)
+    )
 
 
-def test_load_coordinates() -> None:
+def test_load() -> None:
     """Test loading coordinates from file."""
-    coord, names, space = load_coordinates("DMNBuckner")
+    coord, names, space = CoordinatesRegistry().load("DMNBuckner")
     assert coord.shape == (6, 3)  # type: ignore
     assert names == ["PCC", "MPFC", "lAG", "rAG", "lHF", "rHF"]
     assert space == "MNI"
 
 
-def test_load_coordinates_nonexisting() -> None:
+def test_load_nonexisting() -> None:
     """Test loading coordinates that not exist."""
     with pytest.raises(ValueError, match=r"not found"):
-        load_coordinates("NonExisting")
+        CoordinatesRegistry().load("NonExisting")
 
 
-def test_get_coordinates() -> None:
+def test_get() -> None:
     """Test tailored coordinates fetch."""
     reader = DefaultDataReader()
     with OasisVBMTestingDataGrabber() as dg:
@@ -128,11 +121,11 @@ def test_get_coordinates() -> None:
         element_data = reader.fit_transform(element)
         vbm_gm = element_data["VBM_GM"]
         # Get tailored coordinates
-        tailored_coords, tailored_labels = get_coordinates(
+        tailored_coords, tailored_labels = CoordinatesRegistry().get(
             coords="DMNBuckner", target_data=vbm_gm
         )
         # Get raw coordinates
-        raw_coords, raw_labels, _ = load_coordinates("DMNBuckner")
+        raw_coords, raw_labels, _ = CoordinatesRegistry().load("DMNBuckner")
         # Both tailored and raw should be same for now
         assert_array_equal(tailored_coords, raw_coords)
         assert tailored_labels == raw_labels

junifer/data/masks/__init__.py

@@ -0,0 +1,9 @@
+"""Masks."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+import lazy_loader as lazy
+
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

junifer/data/masks/__init__.pyi

@@ -0,0 +1,6 @@
+__all__ = [
+    "MaskRegistry",
+    "compute_brain_mask",
+]
+
+from ._masks import MaskRegistry, compute_brain_mask