junifer 0.0.6.dev175__py3-none-any.whl → 0.0.6.dev201__py3-none-any.whl

junifer/data/coordinates/_coordinates.py

@@ -0,0 +1,356 @@
+"""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, Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+
+from ...pipeline.singleton import singleton
+from ...utils import logger, raise_error
+from ..pipeline_data_registry_base import BasePipelineDataRegistry
+from ._ants_coordinates_warper import ANTsCoordinatesWarper
+from ._fsl_coordinates_warper import FSLCoordinatesWarper
+
+
+__all__ = ["CoordinatesRegistry"]
+
+
+@singleton
+class CoordinatesRegistry(BasePipelineDataRegistry):
+    """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."""
+        # 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 package
+        # in the data/VOIs directory. 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 = {}
+
+        # Path to the metadata of the VOIs
+        _vois_meta_path = Path(__file__).parent / "VOIs" / "meta"
+
+        self._builtin = {
+            "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",
+            },
+        }
+
+        # Set built-in to registry
+        self._registry = 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 already registered and
+            ``overwrite=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``.
+
+        """
+        # Check for attempt of overwriting built-in coordinates
+        if name in self._builtin:
+            if isinstance(self._registry[name].get("path"), Path):
+                raise_error(
+                    f"Coordinates: {name} already registered as built-in "
+                    "coordinates."
+                )
+            if overwrite:
+                logger.info(f"Overwriting coordinates: {name}")
+            else:
+                raise_error(
+                    f"Coordinates: {name} already registered. "
+                    "Set `overwrite=True` to update its value."
+                )
+
+        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]})."
+            )
+        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.
+
+        """
+        # 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
+        t_coord = self._registry[name]
+        # Load data
+        if isinstance(t_coord.get("path"), Path):
+            logger.debug(f"Loading coordinates {t_coord['path'].absolute()!s}")
+            # Load via pandas
+            df_coords = pd.read_csv(t_coord["path"], 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])
+        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 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, _ = 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."
+                )
+
+            # Check for warp file type to use correct tool
+            warp_file_ext = extra_input["Warp"]["path"].suffix
+            if warp_file_ext == ".mat":
+                seeds = FSLCoordinatesWarper().warp(
+                    seeds=seeds,
+                    target_data=target_data,
+                    extra_input=extra_input,
+                )
+            elif warp_file_ext == ".h5":
+                seeds = ANTsCoordinatesWarper().warp(
+                    seeds=seeds,
+                    target_data=target_data,
+                    extra_input=extra_input,
+                )
+            else:
+                raise_error(
+                    msg=(
+                        "Unknown warp / transformation file extension: "
+                        f"{warp_file_ext}"
+                    ),
+                    klass=RuntimeError,
+                )
+
+        return seeds, labels

junifer/data/coordinates/_fsl_coordinates_warper.py

@@ -0,0 +1,83 @@
+"""Provide class for coordinates space warping via FSL FLIRT."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from typing import Any, Dict
+
+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],
+        extra_input: 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.
+        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 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 {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
+        return np.loadtxt(transformed_coords_path)

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

@@ -1,26 +1,22 @@
 """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"],
@@ -29,9 +25,9 @@ def test_register_coordinates_built_in_check() -> None:
         )
 
 
-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"],
@@ -39,14 +35,14 @@ def test_register_coordinates_overwrite() -> None:
         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",
         )
 
-    register_coordinates(
+    CoordinatesRegistry().register(
         name="MyList",
         coordinates=np.ones((2, 3)),
         voi_names=["roi2", "roi3"],
@@ -54,16 +50,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 +67,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 +76,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 +84,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 +93,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 +122,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