junifer 0.0.6.dev175__tar.gz → 0.0.6.dev194__tar.gz

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/.github/workflows/docs.yml

@@ -8,16 +8,13 @@ on:
     # Sequence of patterns matched against refs/tags
     tags:
       - v*
-    workflow_dispatch: {}
+  workflow_dispatch: {}
 
 jobs:
   build-docs:
     runs-on: ubuntu-latest
     # Use custom docs CI image
-    container:
-      image: ghcr.io/juaml/junifer-docs:main
-      # https://github.com/actions/runner/issues/2033#issuecomment-1598547465
-      options: --user 1001
+    container: ghcr.io/juaml/junifer-docs:main
     steps:
     - name: Check ANTs
       run: |
@@ -63,6 +60,8 @@ jobs:
     - name: Build docs
       # Use the args we normally pass to sphinx-build, but run sphinx-multiversion
       run: |
+        # https://github.com/actions/checkout/issues/1169#issuecomment-2291682583
+        git config --system --add safe.directory $(pwd)
         make -C docs/ html
         touch docs/_build/.nojekyll
         cp docs/redirect.html docs/_build/index.html

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/Dockerfile-ci

@@ -63,9 +63,9 @@ RUN ln -s /usr/lib/x86_64-linux-gnu/libgsl.so.27 /usr/lib/x86_64-linux-gnu/libgs
 RUN curl https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/fslinstaller.py | \
     python - -d /opt/fsl/ --skip_registration
 # Set env vars for FSL
-ENV FSLDIR="/opt/fsl" \
-    FSLOUTPUTTYPE="NIFTI_GZ" \
-    PATH="/opt/fsl/bin:$PATH"
+ENV FSLDIR=/opt/fsl \
+    FSLOUTPUTTYPE=NIFTI_GZ \
+    PATH="/opt/fsl/share/fsl/bin:$PATH"
 
 # Clean apt cache
 RUN apt-get autoremove --purge && apt-get clean

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.6.dev175
+Version: 0.0.6.dev194
 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>

junifer-0.0.6.dev194/docs/api/data.rst

@@ -0,0 +1,6 @@
+Data
+====
+
+.. automodule:: junifer.data
+   :members:
+   :imported-members:

junifer-0.0.6.dev194/docs/changes/newsfragments/387.change

@@ -0,0 +1 @@
+``get_parcellation``, ``load_parcellation``, ``list_parcellation``, ``register_parcellation`` , ``get_coordinates``, ``load_coordinates``, ``list_coordinates``, ``register_coordinates``, ``get_mask``, ``load_mask``, ``list_mask``, ``register_mask`` have been removed in favour of :func:`.get_data`, :func:`.load_data`, :func:`.list_data`, :func:`.register_data` and :func:`.deregister_data` by `Synchon Mandal`_

junifer-0.0.6.dev194/docs/changes/newsfragments/387.feature

@@ -0,0 +1 @@
+Introduce :class:`junifer.data.CoordinatesRegistry`, :class:`junifer.data.ParcellationRegistry` and :class:`junifer.data.MaskRegistry` to centralise data management by `Synchon Mandal`_

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/docs/extending/coordinates.rst

@@ -18,19 +18,28 @@ provides them already.
 If you checked the in-built coordinates, and they are not there already (for
 example if you came up with your own set of coordinates), then ``junifer``
 provides an easy way for you to register them using the
-:func:`.register_coordinates` function, so you can use your own set of
+:func:`.register_data` function, so you can use your own set of
 coordinates within a ``junifer`` pipeline.
 
-From the API reference, we can see that it has 4 positional arguments
-(``name``, ``coordinates``, ``voi_names`` and ``space``) as well as one
-optional keyword argument (``overwrite``).
+From the API reference, we can see that it has 3 positional arguments:
+
+* ``kind``
+* ``name``
+* ``space``
+
+as well as one optional keyword argument: ``overwrite``.
+As the ``kind`` needs to be ``"coordinates"``, we can check
+``CoordinatesRegistry.register`` for keyword arguments to be passed:
+
+* ``coordinates``
+* ``voi_names``
 
 The ``name`` argument takes a string indicating the name you want to give to
 this set of coordinates. This ``name`` can be used to obtain and operate on a
 set of coordinates in ``junifer``. For example, you can obtain your coordinates
-after registration by providing ``name`` to :func:`.load_coordinates`. We could
-simply call it ``"my_set_of_coordinates"``, but likely you want a more
-descriptive and more informative name most of the time.
+after registration by providing ``name`` to :func:`.load_data` with
+``kind="coordinates"``. We could simply call it ``"my_set_of_coordinates"``,
+but likely you want a more descriptive and more informative name most of the time.
 
 The ``coordinates`` argument takes the actual coordinates as a 2-dimensional
 :class:`numpy.ndarray`. It contains one row for every location, and three
@@ -57,8 +66,8 @@ packages:
 
 .. code-block:: python
 
-  from junifer.data import register_coordinates
   import numpy as np
+  from junifer.data import register_data
 
 For the sake of this example, we can create a set of coordinates that belong
 to the Default Mode Network (DMN), and register this set of coordinates with
@@ -86,8 +95,12 @@ simply use this to register our coordinates:
 
 .. code-block:: python
 
-  register_coordinates(
-      name="DMNCustom", coordinates=dmn_coords, voi_names=voi_names, space="MNI"
+  register_data(
+      kind="coordinates",
+      name="DMNCustom",
+      coordinates=dmn_coords,
+      voi_names=voi_names,
+      space="MNI",
   )
 
 Now, when we run this script, ``junifer`` registers these coordinates and we can

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/docs/extending/masks.rst

@@ -14,16 +14,25 @@ suit your needs, and you have found that they don't, you can come back here to
 learn how to use your own masks.
 
 The principle is fairly simple and quite similar to :ref:`adding_parcellations`
-and :ref:`adding_coordinates`. ``junifer`` provides a :func:`.register_mask`
+and :ref:`adding_coordinates`. ``junifer`` provides a :func:`.register_data`
 function that lets you register your own custom masks. It consists of three
-positional arguments (``name``, ``mask_path`` and ``space``) and one optional
-keyword argument (``overwrite``).
+positional arguments:
+
+* ``kind``
+* ``name``
+* ``space``
+
+and one optional keyword argument: ``overwrite``.
+As the ``kind`` needs to be ``"mask"``, we can check
+``MaskRegistry.register`` for keyword arguments to be passed:
+
+* ``mask_path``
 
 The ``name`` argument is a string indicating the name of the mask. This name
 is used to refer to that mask in ``junifer`` internally in order to obtain the
 actual mask data and perform operations on it. For example, using the name you
-can load a mask after registration using the
-:func:`.load_mask` function.
+can load a mask after registration using the :func:`.load_data` with
+``kind="mask"``.
 
 The ``mask_path`` should contain the path to a valid NIfTI image with binary
 voxel values (i.e. 0 or 1). This data can then be used by ``junifer`` to mask
@@ -42,14 +51,19 @@ look as follows:
 
   from pathlib import Path
 
-  from junifer.data import register_mask
+  from junifer.data import register_data
 
 
   # this path is only an example, of course use the correct path
   # on your system:
   mask_path = Path("..") / ".." / "my_custom_mask.nii.gz"
 
-  register_mask(name="my_custom_mask", mask_path=mask_path, space="native")
+  register_data(
+      kind="mask",
+      name="my_custom_mask",
+      mask_path=mask_path,
+      space="native",
+  )
 
 Simple, right? Now we just have to configure a YAML file to register this mask
 so we can use it for :ref:`codeless configuration of junifer <codeless>`.

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/docs/extending/parcellations.rst

@@ -17,13 +17,22 @@ this?
 
 Since both of these use-cases are quite common, and not being able to use your
 favourite parcellation is of course quite a buzzkill, ``junifer`` actually
-provides the easy-to-use :func:`.register_parcellation` function to do just that.
+provides the easy-to-use :func:`.register_data` function to do just that.
 Let's try to understand the API reference and then use this function to register our
 own parcellation.
 
-From the API reference, we can see that it has 4 positional arguments
-(``name``, ``parcellation_path``, ``parcels_labels`` and ``space``) as well as
-one optional keyword argument (``overwrite``).
+From the API reference, we can see that it has 3 positional arguments:
+
+* ``kind``
+* ``name``
+* ``space``
+
+as well as one optional keyword argument: ``overwrite``.
+As the ``kind`` needs to be ``"parcellation"``, we can check
+``ParcellationRegistry.register`` for keyword arguments to be passed:
+
+* ``parcellation_path``
+* ``parcels_labels``
 
 The ``name`` of the parcellation is up to you and will be the name that
 ``junifer`` will use to refer to this particular parcellation. You can think of
@@ -64,10 +73,11 @@ look like this:
 
 .. code-block:: python
 
-  from junifer.data import register_parcellation
-
   from pathlib import Path
+
   import numpy as np
+  from junifer.data import register_data
+
 
   # these are of course just example paths, replace it with your own:
   path_to_parcellation = (
@@ -79,7 +89,8 @@ look like this:
 
   my_labels = list(np.loadtxt(path_to_labels, dtype=str))
 
-  register_parcellation(
+  register_data(
+      kind="parcellation",
       name="my_custom_parcellation",
       parcellation_path=path_to_parcellation,
       parcels_labels=my_labels,

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/docs/using/masks.rst

@@ -13,8 +13,8 @@ ensuring that the features are not extracted from voxels that contain mostly
 white matter or cerebrospinal fluid, which could add noise to the BOLD signal.
 
 ``junifer`` provides a number of built-in masks, which can be listed using
-:func:`.list_masks`. Some masks are images, while other masks can be computed
-using :ref:`nilearn` functions.
+:func:`.list_data` with ``kind="mask"``. Some masks are images, while other
+masks can be computed using :ref:`nilearn` functions.
 
 For markers and steps that accept ``masks`` as an argument, the mask can be
 specified as a string, which will be the name of a built-in mask, or as a

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/docs/whats_new.rst

@@ -190,10 +190,10 @@ API Changes
 - Modify ``preprocessor`` to ``preprocessors`` in :func:`.run` and
   ``preprocessing`` to ``preprocessors`` in :class:`.MarkerCollection` to
   accept multiple preprocessors by `Synchon Mandal`_ (:gh:`263`)
-- Add ``space`` parameter to :func:`.register_coordinates`,
-  :func:`.register_parcellation` and :func:`.register_mask` and return space
-  from :func:`.load_coordinates`, :func:`.load_parcellation` and
-  :func:`.load_mask` by `Synchon Mandal`_ and `Fede Raimondo`_ (:gh:`268`)
+- Add ``space`` parameter to ``register_coordinates``,
+  ``register_parcellation`` and ``register_mask`` and return space
+  from ``load_coordinates``, ``load_parcellation`` and
+  ``load_mask`` by `Synchon Mandal`_ and `Fede Raimondo`_ (:gh:`268`)
 - Add ``template_type`` parameter to :func:`.get_template` by `Synchon Mandal`_
   (:gh:`299`)
 - Change :meth:`.BasePreprocessor.preprocess` return values to preprocessed
@@ -245,7 +245,7 @@ Enhancements
   :func:`.get_aggfunc_by_name` by `Synchon Mandal`_ (:gh:`287`)
 - Adapt ``BOLDWarper`` to use FSL or ANTs depending on warp file
   extension by `Synchon Mandal`_ (:gh:`293`)
-- Rewrite :func:`.compute_brain_mask` to allow variable template fetching via
+- Rewrite ``compute_brain_mask`` to allow variable template fetching via
   templateflow, according to target data by `Synchon Mandal`_ (:gh:`299`)
 - Replace ``requests`` with ``httpx`` for fetching parcellations by `Synchon
   Mandal`_ (:gh:`300`)
@@ -285,9 +285,9 @@ Features
 - Introduce :class:`junifer.pipeline.WorkDirManager` singleton class to manage
   working and temporary directories across pipeline by `Synchon Mandal`_
   (:gh:`254`)
-- Introduce :func:`.get_parcellation` to fetch parcellation tailored for the
+- Introduce ``get_parcellation`` to fetch parcellation tailored for the
   data by `Synchon Mandal`_ (:gh:`264`)
-- Introduce :func:`.get_coordinates` to fetch coordinates tailored for the data
+- Introduce ``get_coordinates`` to fetch coordinates tailored for the data
   by `Synchon Mandal`_ (:gh:`265`)
 - Introduce ``junifer.preprocess.fsl.apply_warper._ApplyWarper`` to wrap FSL's
   ``applywarp`` by `Synchon Mandal`_ (:gh:`266`)
@@ -309,7 +309,7 @@ Features
 - Introduce :func:`.get_template` to fetch template space image tailored to a
   target data by `Synchon Mandal`_ (:gh:`298`)
 - Add support for on-the-fly template space transformation in
-  :func:`.get_parcellation` and :func:`.get_mask` to allow parcellation and
+  ``get_parcellation`` and ``get_mask`` to allow parcellation and
   mask in different template spaces to work with a ``DataGrabber``'s data in a
   specified template space. (:gh:`299`)
 - Introduce :class:`.SpaceWarper` for warping ``T1w``, ``BOLD``, ``VBM_GM``,
@@ -480,7 +480,7 @@ Bugfixes
 - Fix an issue with datalad cache and locks in which the overridden settings in
   Junifer were not propagated to subprocesses, resulting in using the default
   settings by `Fede Raimondo`_ (:gh:`199`)
-- Fix a bug in which :func:`.get_mask` fails for FunctionalConnectivityBase
+- Fix a bug in which ``get_mask`` fails for ``FunctionalConnectivityBase``
   class, because of missing extra_input parameter by `Leonard Sasse`_
   (:gh:`200`)
 - Fix the output of :class:`.RSSETSMarker` to be 2D by `Synchon Mandal`_
@@ -560,7 +560,7 @@ Features
 
 - Add :class:`.EdgeCentricFCParcels` and :class:`.EdgeCentricFCSpheres` by
   `Leonard Sasse`_ (:gh:`64`)
-- Expose a :func:`.merge_parcellations` function to merge a list of
+- Expose a ``merge_parcellations`` function to merge a list of
   parcellations by `Leonard Sasse`_ (:gh:`146`)
 - Add support for HDF5 feature storage via :class:`.HDF5FeatureStorage` by
   `Synchon Mandal`_ (:gh:`147`)
@@ -670,8 +670,8 @@ Features
   connectivity using a parcellation by `Amir Omidvarnia`_ and
   `Kaustubh R. Patil`_ (:gh:`41`)
 
-- Implement :func:`.register_coordinates`, :func:`.list_coordinates` and
-  :func:`.load_coordinates` by `Fede Raimondo`_ (:gh:`11`)
+- Implement ``register_coordinates``, ``list_coordinates`` and
+  ``load_coordinates`` by `Fede Raimondo`_ (:gh:`11`)
 
 - Add :class:`.DataladAOMICID1000` datagrabber for AOMIC ID1000 dataset
   including tests and creation of mock dataset for testing by

{junifer-0.0.6.dev175 → junifer-0.0.6.dev194}/junifer/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.6.dev175'
-__version_tuple__ = version_tuple = (0, 0, 6, 'dev175')
+__version__ = version = '0.0.6.dev194'
+__version_tuple__ = version_tuple = (0, 0, 6, 'dev194')

junifer-0.0.6.dev194/junifer/data/__init__.pyi

@@ -0,0 +1,29 @@
+__all__ = [
+    "CoordinatesRegistry",
+    "ParcellationRegistry",
+    "MaskRegistry",
+    "get_data",
+    "list_data",
+    "load_data",
+    "register_data",
+    "deregister_data",
+    "get_template",
+    "get_xfm",
+    "utils",
+]
+
+from .coordinates import CoordinatesRegistry
+from .parcellations import ParcellationRegistry
+from .masks import MaskRegistry
+
+from ._dispatch import (
+    get_data,
+    list_data,
+    load_data,
+    register_data,
+    deregister_data,
+)
+
+from .template_spaces import get_template, get_xfm
+
+from . import utils

junifer-0.0.6.dev194/junifer/data/_dispatch.py

@@ -0,0 +1,251 @@
+"""Provide dispatch functions for pipeline data registries."""
+
+# Authors: Synchon Mandal <s.mandal@fz-juelich.de>
+# License: AGPL
+
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+from numpy.typing import ArrayLike
+
+from ..utils import raise_error
+from .coordinates import CoordinatesRegistry
+from .masks import MaskRegistry
+from .parcellations import ParcellationRegistry
+
+
+if TYPE_CHECKING:
+    from nibabel.nifti1 import Nifti1Image
+
+
+__all__ = [
+    "get_data",
+    "list_data",
+    "load_data",
+    "register_data",
+    "deregister_data",
+]
+
+
+def get_data(
+    kind: str,
+    names: Union[
+        str,  # coordinates, parcellation, mask
+        List[str],  # parcellation, mask
+        Dict,  # mask
+        List[Dict],  # mask
+    ],
+    target_data: Dict[str, Any],
+    extra_input: Optional[Dict[str, Any]] = None,
+) -> Union[
+    Tuple[ArrayLike, List[str]],  # coordinates
+    Tuple["Nifti1Image", List[str]],  # parcellation
+    "Nifti1Image",  # mask
+]:
+    """Get tailored ``kind`` for ``target_data``.
+
+    Parameters
+    ----------
+    kind : {"coordinates", "parcellation", "mask"}
+        Kind of data to fetch and apply.
+    names : str or dict or list of str / dict
+        The registered name(s) of the data.
+    target_data : dict
+        The corresponding item of the data object to which the data
+        will be applied.
+    extra_input : dict, optional
+        The other fields in the data object. Useful for accessing other
+        data types that need to be used in the computation of data
+        (default None).
+
+    Returns
+    -------
+    tuple of numpy.ndarray, list of str; \
+    tuple of nibabel.nifti1.Nifti1Image, list of str; \
+    nibabel.nifti1.Nifti1Image
+
+    Raises
+    ------
+    ValueError
+        If ``kind`` is invalid value.
+
+    """
+
+    if kind == "coordinates":
+        return CoordinatesRegistry().get(
+            coords=names,
+            target_data=target_data,
+            extra_input=extra_input,
+        )
+    elif kind == "parcellation":
+        return ParcellationRegistry().get(
+            parcellations=names,
+            target_data=target_data,
+            extra_input=extra_input,
+        )
+    elif kind == "mask":
+        return MaskRegistry().get(
+            masks=names,
+            target_data=target_data,
+            extra_input=extra_input,
+        )
+    else:
+        raise_error(f"Unknown data kind: {kind}")
+
+
+def list_data(kind: str) -> List[str]:
+    """List available data for ``kind``.
+
+    Parameters
+    ----------
+    kind : {"coordinates", "parcellation", "mask"}
+        Kind of data registry to list.
+
+    Returns
+    -------
+    list of str
+        Available data for the registry.
+
+    Raises
+    ------
+    ValueError
+        If ``kind`` is invalid value.
+
+    """
+
+    if kind == "coordinates":
+        return CoordinatesRegistry().list
+    elif kind == "parcellation":
+        return ParcellationRegistry().list
+    elif kind == "mask":
+        return MaskRegistry().list
+    else:
+        raise_error(f"Unknown data kind: {kind}")
+
+
+def load_data(
+    kind: str,
+    name: str,
+    **kwargs,
+) -> Union[
+    Tuple[ArrayLike, List[str], str],  # coordinates
+    Tuple[Optional["Nifti1Image"], List[str], Path, str],  # parcellation
+    Tuple[
+        Optional[Union["Nifti1Image", Callable]], Optional[Path], str
+    ],  # mask
+]:
+    """Load ``kind`` named ``name``.
+
+    Parameters
+    ----------
+    kind : {"coordinates", "parcellation", "mask"}
+        Kind of data to load.
+    name : str
+        The registered name of the data.
+    **kwargs
+        Keyword arguments are passed to respective registry class method.
+
+    Returns
+    -------
+    tuple of numpy.ndarray, list of str, str; \
+    tuple of nibabel.nifti1.Nifti1Image or None, \
+    list of str, pathlib.Path, str; \
+    tuple of nibabel.nifti1.Nifti1Image or callable or None, \
+    pathlib.Path or None, str
+
+    Raises
+    ------
+    ValueError
+        If ``kind`` is invalid value.
+
+    """
+
+    if kind == "coordinates":
+        return CoordinatesRegistry().load(name=name)
+    elif kind == "parcellation":
+        return ParcellationRegistry().load(name=name, **kwargs)
+    elif kind == "mask":
+        return MaskRegistry().load(name=name, **kwargs)
+    else:
+        raise_error(f"Unknown data kind: {kind}")
+
+
+def register_data(
+    kind: str,
+    name: str,
+    space: str,
+    overwrite: bool = False,
+    **kwargs,
+) -> None:
+    """Register ``name`` under ``kind``.
+
+    Parameters
+    ----------
+    kind : {"coordinates", "parcellation", "mask"}
+        Kind of data to register.
+    name : str
+        The name to register.
+    space : str
+        The template space of the data.
+    overwrite : bool, optional
+        If True, overwrite an existing data with the same name.
+    **kwargs
+        Keyword arguments are passed to respective registry class method.
+
+    Raises
+    ------
+    ValueError
+        If ``kind`` is invalid value.
+
+    """
+
+    if kind == "coordinates":
+        return CoordinatesRegistry().register(
+            name=name, space=space, overwrite=overwrite, **kwargs
+        )
+    elif kind == "parcellation":
+        return ParcellationRegistry().register(
+            name=name, space=space, overwrite=overwrite, **kwargs
+        )
+    elif kind == "mask":
+        return MaskRegistry().load(
+            name=name, space=space, overwrite=overwrite, **kwargs
+        )
+    else:
+        raise_error(f"Unknown data kind: {kind}")
+
+
+def deregister_data(kind: str, name: str) -> None:
+    """De-register ``name`` from ``kind``.
+
+    Parameters
+    ----------
+    kind : {"coordinates", "parcellation", "mask"}
+        Kind of data to register.
+    name : str
+        The name to de-register.
+
+    Raises
+    ------
+    ValueError
+        If ``kind`` is invalid value.
+
+    """
+
+    if kind == "coordinates":
+        return CoordinatesRegistry().deregister(name=name)
+    elif kind == "parcellation":
+        return ParcellationRegistry().register(name=name)
+    elif kind == "mask":
+        return MaskRegistry().load(name=name)
+    else:
+        raise_error(f"Unknown data kind: {kind}")

junifer-0.0.6.dev194/junifer/data/coordinates/__init__.py

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

junifer-0.0.6.dev194/junifer/data/coordinates/__init__.pyi

@@ -0,0 +1,5 @@
+__all__ = [
+    "CoordinatesRegistry",
+]
+
+from ._coordinates import CoordinatesRegistry