docs: update extending docs

synchon · synchon · commit db6b17804aa1 · 2025-11-17T16:11:47.000+01:00
diff --git a/docs/extending/datagrabber.rst b/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 HttpUrl
 
 
     @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: HttpUrl = HttpUrl("https://gin.g-node.org/juaml/datalad-example-bids")
+        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"]
+        rootdir: Path = 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
diff --git a/docs/extending/dependencies.rst b/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,30 +81,28 @@ 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",
                 "depends_on": [FSLWarper, ANTsWarper],
             },
         ]
 
-        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"],
             },
         ]
diff --git a/docs/extending/marker.rst b/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,23 +29,23 @@ 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
 
     # NOTE: data type -> feature -> storage type
     # 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,7 +112,7 @@ 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
@@ -142,7 +133,7 @@ and the values would be a dictionary of storage type specific key-value pairs.
 
         # Get the parcellation tailored for the target
         t_parcellation, t_labels, _ = get_parcellation(
-            name=self.parcellation_name,
+            name=self.parcellation,
             target_data=input,
             extra_input=extra_input,
         )
@@ -195,7 +186,9 @@ Finally, we need to register the Marker using the ``@register_marker`` decorator
 
     from junifer.api.decorators import register_marker
     from junifer.data import get_parcellation
+    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 +199,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,
@@ -236,7 +222,7 @@ Finally, we need to register the Marker using the ``@register_marker`` decorator
 
             # Get the parcellation tailored for the target
             t_parcellation, t_labels, _ = get_parcellation(
-                name=self.parcellation_name,
+                name=self.parcellation,
                 target_data=input,
                 extra_input=extra_input,
             )
@@ -280,9 +266,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 {}
diff --git a/docs/extending/preprocessor.rst b/docs/extending/preprocessor.rst
