junifer 0.0.8.dev24__tar.gz → 0.0.8.dev189__tar.gz

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: junifer
-Version: 0.0.8.dev24
+Version: 0.0.8.dev189
 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>
@@ -46,6 +46,9 @@ Requires-Dist: importlib_metadata; python_version < "3.9"
 Requires-Dist: looseversion==1.3.0; python_version >= "3.12"
 Requires-Dist: junifer_data==1.3.0
 Requires-Dist: structlog<26.0.0,>=25.0.0
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: aenum<3.2.0,>=3.1.0
+Requires-Dist: typing_extensions<4.16.0,>=4.15.0; python_version < "3.12"
 Provides-Extra: all
 Requires-Dist: bctpy==0.6.0; extra == "all"
 Requires-Dist: neurokit2>=0.1.7; extra == "all"
@@ -72,6 +75,8 @@ Requires-Dist: towncrier<=25.8.0,>=24.7.0; extra == "docs"
 Requires-Dist: sphinxcontrib-mermaid<=1.0.0,>=0.8.1; extra == "docs"
 Requires-Dist: sphinxcontrib-towncrier==0.5.0a0; extra == "docs"
 Requires-Dist: setuptools-scm>=8; extra == "docs"
+Requires-Dist: autodoc_pydantic>=2.0.0; extra == "docs"
+Requires-Dist: enum-tools[sphinx]<0.14.0,>=0.13.0; extra == "docs"
 Dynamic: license-file
 
 ![Junifer logo](docs/images/junifer_logo.png "junifer logo")

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/api/onthefly.rst

@@ -5,5 +5,5 @@ On-the-fly
    :members:
    :imported-members:
 
-.. automodule:: junifer.onthefly.brainprint
+.. automodule:: junifer.onthefly._brainprint
    :members:

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/builtin.rst

@@ -158,16 +158,16 @@ Available
        | (subject-native or other template spaces)
      - Done
      - 0.0.4
-   * - ``Smoothing``
+   * - :class:`.Smoothing`
      - | Apply smoothing to data, particularly useful when dealing with
        | ``fMRIPrep``-ed data
      - In Progress
      - :gh:`161`
-   * - ``TemporalSlicer``
+   * - :class:`.TemporalSlicer`
      - Slice ``BOLD`` data temporally
      - | Done
      - :gh:`443`
-   * - ``TemporalFilter``
+   * - :class:`.TemporalFilter`
      - Filter (clean) ``BOLD`` data temporally
      - | Done
      - :gh:`432`

junifer-0.0.8.dev189/docs/changes/newsfragments/239.enh

@@ -0,0 +1 @@
+Improve logging consistency of components by `Synchon Mandal`_

junifer-0.0.8.dev189/docs/changes/newsfragments/364.doc

@@ -0,0 +1 @@
+Add documentation on adding confounds format by `Synchon Mandal`_

junifer-0.0.8.dev189/docs/changes/newsfragments/364.enh

@@ -0,0 +1 @@
+Adopt Pydantic for user-facing core objects to perform automatic validation using typing annotations by `Synchon Mandal`_

junifer-0.0.8.dev189/docs/changes/newsfragments/364.feature

@@ -0,0 +1 @@
+Enable confounds format to be added by introducing :func:`.register_confounds_format` by `Synchon Mandal`_

junifer-0.0.8.dev189/docs/changes/newsfragments/502.bugfix

@@ -0,0 +1 @@
+Fix type issues and update model configs for :class:`.BaseDataGrabber`, :class:`.BasePreprocessor`, :class:`.BaseMarker` and :class:`.BaseStorage` by `Synchon Mandal`_

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/conf.py

@@ -65,6 +65,8 @@ extensions = [
     "sphinx_copybutton",  # copy button for code blocks
     "sphinxcontrib.mermaid",  # mermaid support
     "sphinxcontrib.towncrier.ext",  # towncrier fragment support
+    "sphinxcontrib.autodoc_pydantic",  # autodoc support for pydantic models
+    "enum_tools.autoenum",  # enum support
 ]
 
 if use_multiversion:
@@ -97,6 +99,15 @@ nitpick_ignore_regex = [
     ("py:class", "pipeline.Pipeline"),  # nilearn
     ("py:obj", "neurokit2.*"),  # ignore neurokit2
     ("py:obj", "datalad.*"),  # ignore datalad
+    ("py:obj", "junifer.*"),  # ignore junifer internal
+    ("py:class", "annotated_types.*"),  # ignore pydantic annotated types
+    ("py:obj", "variants"),  # ignore variants
+    ("py:obj", "them"),  # ignore them
+    ("py:class", "junifer.utils.helpers.ensure_list"),  # ignore ensure_list
+    ("py:class", "junifer.utils.helpers.ensure_list_or_none"),  # ignore ensure_list_or_none
+    ("py:class", "PydanticUndefined"),  # ignore PydanticUndefined
+    ("py:class", "FieldInfo"),  # ignore FieldInfo
+    ("py:class", "NoneType"),  # ignore NoneType
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -154,6 +165,7 @@ intersphinx_mapping = {
     "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
     # "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
 }
 
 # -- sphinx.ext.extlinks configuration ---------------------------------------

junifer-0.0.8.dev189/docs/extending/confounds_format.rst

@@ -0,0 +1,22 @@
+.. include:: ../links.inc
+
+.. _adding_confounds_format:
+
+Adding Confounds Format
+=======================
+
+#. Check :ref:`extending junifer <extending_extension>` on how to create a
+   *junifer extension* if you have not done so.
+#. Register the confounds format before defining / using a DataGrabber like so:
+
+   .. code-block:: python
+
+      from junifer.datagrabber import register_confounds_format
+      ...
+
+
+      # registers the confounds format as "confounds" and accessible as
+      # ``ConfoundsFormat.Confounds``
+      register_confounds_format(name="Confounds", alias="confounds")
+
+      ...

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/extending/datagrabber.rst

@@ -140,29 +140,24 @@ With the variables defined above, we can create our DataGrabber and name it
 
     from pathlib import Path
 
-    from junifer.datagrabber import PatternDataGrabber
+    from junifer.datagrabber import PatternDataGrabber, DataType
+    from junifer.typing import DataGrabberPatterns
 
 
     class ExampleBIDSDataGrabber(PatternDataGrabber):
-        def __init__(self, datadir: str | Path) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            super().__init__(
-                datadir=datadir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        types: list[DataType] = [DataType.T1w, DataType.BOLD]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
 
 Our DataGrabber is ready to be used by ``junifer``. However, it is still unknown
 to the library. We need to register it in the library. To do so, we need to
@@ -175,29 +170,24 @@ use the :func:`.register_datagrabber` decorator.
 
     from junifer.api.decorators import register_datagrabber
     from junifer.datagrabber import PatternDataGrabber
+    from junifer.typing import DataGrabberPatterns
 
 
     @register_datagrabber
     class ExampleBIDSDataGrabber(PatternDataGrabber):
-        def __init__(self, datadir: str | Path) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            super().__init__(
-                datadir=datadir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        types: list[DataType] = [DataType.T1w, DataType.BOLD]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
 
 
 Now, we can use our DataGrabber in ``junifer``, by setting the ``datagrabber``
@@ -259,35 +249,30 @@ And we can create our DataGrabber:
 
 .. code-block:: python
 
+    from pathlib import Path
+
     from junifer.api.decorators import register_datagrabber
     from junifer.datagrabber import PatternDataladDataGrabber
+    from pydantic import AnyUrl
 
 
     @register_datagrabber
     class ExampleBIDSDataGrabber(PatternDataladDataGrabber):
-        def __init__(self) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            uri = "https://gin.g-node.org/juaml/datalad-example-bids"
-            rootdir = "example_bids_ses"
-            super().__init__(
-                datadir=None,
-                uri=uri,
-                rootdir=rootdir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        uri: AnyUrl = "https://gin.g-node.org/juaml/datalad-example-bids"
+        types: list[DataType] = ["T1w", "BOLD"]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
+        rootdir: Path = "example_bids_ses"
 
 This approach can be used directly from the YAML, like so:
 
@@ -376,8 +361,8 @@ need to implement the following methods:
 
 .. note::
 
-   The ``__init__`` method could also be implemented, but it is not mandatory.
-   This is required if the DataGrabber requires any extra parameter.
+   If the DataGrabber requires any extra parameter, they could be defined as
+   class attributes.
 
 We will now implement our BIDS example with this method.
 
@@ -494,8 +479,8 @@ more information about the format of the confounds file. Thus, the
 ``BOLD.confounds`` element is a dictionary with the following keys:
 
 - ``path``: the path to the confounds file.
-- ``format``: the format of the confounds file. Currently, this can be either
-  ``fmriprep`` or ``adhoc``.
+- ``format``: the format of the confounds file. Check :enum:`.ConfoundsFormat`
+  for options.
 
 The ``fmriprep`` format corresponds to the format of the confounds files
 generated by `fMRIPrep`_. The ``adhoc`` format corresponds to a format that is

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/extending/dependencies.rst

@@ -46,7 +46,7 @@ by having a class attribute like so:
 
     _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
         {
-            "name": "afni",
+            "name": ExtDep.AFNI,
             "commands": ["3dReHo", "3dAFNItoNIFTI"],
         },
     ]
@@ -55,7 +55,7 @@ The above example is taken from the class which computes regional homogeneity
 (ReHo) using AFNI. The general pattern is that you need to have the value of
 ``_EXT_DEPENDENCIES`` as a list of dictionary with two keys:
 
-* ``name`` (str) : lowercased name of the toolbox
+* ``name`` (:enum:`.ExtDep`) : name of the toolbox
 * ``commands`` (list of str) : actual names of the commands you need to use
 
 This is simple but powerful as we will see in the following sub-sections.
@@ -81,11 +81,11 @@ that it shows the problem a bit better and how we solve it:
         _CONDITIONAL_DEPENDENCIES: ClassVar[ConditionalDependencies] = [
             {
                 "using": "fsl",
-                "depends_on": FSLWarper,
+                "depends_on": [FSLWarper],
             },
             {
                 "using": "ants",
-                "depends_on": ANTsWarper,
+                "depends_on": [ANTSWarper],
             },
             {
                 "using": "auto",
@@ -93,18 +93,16 @@ that it shows the problem a bit better and how we solve it:
             },
         ]
 
-        def __init__(
-            self, using: str, reference: str, on: Union[List[str], str]
-        ) -> None:
-            # validation and setting up
-            ...
+        using: str
+        reference: str
+        on: List[DataType]
 
 
 Here, you see a new class attribute ``_CONDITIONAL_DEPENDENCIES`` which is a
 list of dictionaries with two keys:
 
 * ``using`` (str) : lowercased name of the toolbox
-* ``depends_on`` (object or list of objects) : a class or list of classes which \
+* ``depends_on`` (list of objects) : list of classes which \
   implements the particular tool's use
 
 It is mandatory to have the ``using`` positional argument in the constructor in
@@ -128,7 +126,7 @@ similar. ``FSLWarper`` looks like this (only the relevant part is shown here):
 
         _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
             {
-                "name": "fsl",
+                "name": ExtDep.FSL,
                 "commands": ["flirt", "applywarp"],
             },
         ]

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/extending/index.rst

@@ -23,6 +23,7 @@ DataGrabbers, Preprocessors, Markers, etc.,  following the *junifer* way.
    :caption: Contents:
 
    extension
+   logging
    datagrabber
    marker
    preprocessor
@@ -34,4 +35,5 @@ DataGrabbers, Preprocessors, Markers, etc.,  following the *junifer* way.
    plugins
    data_registries
    data_types
+   confounds_format
    data_dump_asset

junifer-0.0.8.dev189/docs/extending/logging.rst

@@ -0,0 +1,38 @@
+.. include:: ../links.inc
+
+.. _logging_in_extension:
+
+Logging in a ``junifer`` extension
+==================================
+
+It is important to have proper logging in your code and ``junifer`` makes it trivial to do so for your extensions.
+
+For DataGrabber:
+
+.. code-block:: python
+
+   from junifer.datagrabber import logger
+
+
+For Preprocessor:
+
+.. code-block:: python
+
+   from junifer.preprocess import logger
+
+
+For Marker:
+
+.. code-block:: python
+
+   from junifer.marker import logger
+
+
+For Storage:
+
+.. code-block:: python
+
+   from junifer.storage import logger
+
+
+Importing the correct logger will give you a properly set up logger which will fit right in with the rest of ``junifer``\'s log output.

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/extending/marker.rst

@@ -14,7 +14,7 @@ Most of the functionality of a ``junifer`` Marker has been taken care by the
 :class:`.BaseMarker` class. Thus, only a few methods and class attributes are
 required:
 
-#. ``__init__``: The initialisation method, where the Marker is configured.
+#. (optional) ``validate_marker_params``: The method to perform logical validation of parameters (if required).
 #. ``compute``: The method that given the data, computes the Marker.
 
 As an example, we will develop a ``ParcelMean`` Marker, a Marker that first
@@ -29,8 +29,8 @@ Step 1: Configure input and output
 This step is quite simple: we need to define the input and output of the Marker.
 Based on the current :ref:`data types <data_types>`, we can have ``BOLD``,
 ``VBM_WM`` and ``VBM_GM`` as valid inputs. The output of the Marker depends on
-the input. For ``BOLD``, it will be ``timeseries``, while for the rest of the
-inputs, it will be ``vector``. Thus, we have a class attribute like so:
+the input. For ``BOLD``, it will be ``Timeseries``, while for the rest of the
+inputs, it will be ``Vector``. Thus, we have a class attribute like so:
 
 .. code-block:: python
 
@@ -38,14 +38,14 @@ inputs, it will be ``vector``. Thus, we have a class attribute like so:
     # You can have multiple features for one data type,
     # each feature having same or different storage type
     _MARKER_INOUT_MAPPINGS = {
-        "BOLD": {
-            "parcel_mean": "timeseries",
+        DataType.BOLD: {
+            "parcel_mean": StorageType.Timeseries,
         },
-        "VBM_WM": {
-            "parcel_mean": "vector",
+        DataType.VBM_WM: {
+            "parcel_mean": StorageType.Vector,
         },
-        "VBM_GM": {
-            "parcel_mean": "vector",
+        DataType.VBM_GM: {
+            "parcel_mean": StorageType.Vector,
         },
     }
 
@@ -57,13 +57,11 @@ Step 2: Initialise the Marker
 In this step we need to define the parameters of the Marker the user can provide
 to configure how the Marker will behave.
 
-The parameters of the Marker are defined in the ``__init__`` method. The
-:class:`.BaseMarker` class requires two optional parameters:
+The parameters of the Marker are defined as class attributes. The
+:class:`.BaseMarker` class defines two optional parameters:
 
-1. ``name``: the name of the Marker. This is used to identify the Marker in the
-   configuration file.
-2. ``on``: a list or string with the data types that the Marker will be applied
-   to.
+1. ``name``: the name of the Marker. This is used to identify the Marker in the configuration file.
+2. ``on``: a list of :enum:`.DataType` with the data types that the Marker will be applied to.
 
 .. attention::
 
@@ -72,18 +70,11 @@ The parameters of the Marker are defined in the ``__init__`` method. The
    JSON format, and JSON only supports these types.
 
 In this example, only parameter required for the computation is the name of the
-parcellation to use. Thus, we can define the ``__init__`` method as follows:
+parcellation to use. Thus, we can define as follows:
 
 .. code-block:: python
 
-    def __init__(
-        self,
-        parcellation: str,
-        on: str | list[str] | None = None,
-        name: str | None = None,
-    ) -> None:
-        self.parcellation = parcellation
-        super().__init__(on=on, name=name)
+    parcellation: str
 
 .. caution::
 
@@ -121,14 +112,14 @@ and the values would be a dictionary of storage type specific key-value pairs.
 
    To simplify the ``store`` method, define keys of the dictionary based on the
    corresponding store functions in the :ref:`storage types <storage_types>`.
-   For example, if the output is a ``vector``, the keys of the dictionary should
+   For example, if the output is a ``Vector``, the keys of the dictionary should
    be ``data`` and ``col_names``.
 
 .. code-block:: python
 
     from typing import Any
 
-    from junifer.data import get_parcellation
+    from junifer.data import get_data
     from nilearn.maskers import NiftiLabelsMasker
 
 
@@ -141,8 +132,9 @@ and the values would be a dictionary of storage type specific key-value pairs.
         data = input["data"]
 
         # Get the parcellation tailored for the target
-        t_parcellation, t_labels, _ = get_parcellation(
-            name=self.parcellation_name,
+        t_parcellation, t_labels, _ = get_data(
+            kind="parcellation",
+            name=[self.parcellation],
             target_data=input,
             extra_input=extra_input,
         )
@@ -194,8 +186,10 @@ Finally, we need to register the Marker using the ``@register_marker`` decorator
     from typing import Any, ClassVar
 
     from junifer.api.decorators import register_marker
-    from junifer.data import get_parcellation
+    from junifer.data import get_data
+    from junifer.datagrabber import DataType
     from junifer.markers import BaseMarker
+    from junifer.storage import StorageType
     from junifer.typing import Dependencies, MarkerInOutMappings
     from nilearn.maskers import NiftiLabelsMasker
 
@@ -206,25 +200,18 @@ Finally, we need to register the Marker using the ``@register_marker`` decorator
         _DEPENDENCIES: ClassVar[Dependencies] = {"nilearn", "numpy"}
 
         _MARKER_INOUT_MAPPINGS: ClassVar[MarkerInOutMappings] = {
-            "BOLD": {
-                "parcel_mean": "timeseries",
+            DataType.BOLD: {
+                "parcel_mean": StorageType.Timeseries,
             },
-            "VBM_WM": {
-                "parcel_mean": "vector",
+            DataType.VBM_WM: {
+                "parcel_mean": StorageType.Vector,
             },
-            "VBM_GM": {
-                "parcel_mean": "vector",
+            DataType.VBM_GM: {
+                "parcel_mean": StorageType.Vector,
             },
         }
 
-        def __init__(
-            self,
-            parcellation: str,
-            on: str | list[str] | None = None,
-            name: str | None = None,
-        ) -> None:
-            self.parcellation = parcellation
-            super().__init__(on=on, name=name)
+        parcellation: str
 
         def compute(
             self,
@@ -235,8 +222,9 @@ Finally, we need to register the Marker using the ``@register_marker`` decorator
             data = input["data"]
 
             # Get the parcellation tailored for the target
-            t_parcellation, t_labels, _ = get_parcellation(
-                name=self.parcellation_name,
+            t_parcellation, t_labels, _ = get_data(
+                kind="parcellation",
+                name=[self.parcellation],
                 target_data=input,
                 extra_input=extra_input,
             )
@@ -280,9 +268,13 @@ Template for a custom Marker
         # TODO: add the input-output mappings
         _MARKER_INOUT_MAPPINGS = {}
 
-        def __init__(self, on=None, name=None):
-            # TODO: add marker-specific parameters
-            super().__init__(on=on, name=name)
+        # TODO: define marker-specific parameters
+
+        # optional
+        def validate_marker_params(self):
+            # TODO: add validation logic for marker parameters
+            pass
 
         def compute(self, input, extra_input):
             # TODO: compute the marker and create the output dictionary
+            return {}

{junifer-0.0.8.dev24 → junifer-0.0.8.dev189}/docs/extending/parcellations.rst

@@ -124,7 +124,7 @@ parcellation when registering it. For example, we can add a
   markers:
     - name: CustomParcellation_mean
       kind: ParcelAggregation
-      parcellation: my_custom_parcellation
+      parcellation: <my_custom_parcellation>
       method: mean
 
 Now, you can simply use this YAML file to run your pipeline.