[ENH]: Enable adding data types

docs/changes/newsfragments/451.doc

@@ -0,0 +1 @@
+Add documentation on adding data types by `Synchon Mandal`_

docs/changes/newsfragments/451.feature

@@ -0,0 +1 @@
+Enable data types to be added by introducing :func:`.register_data_type` by `Synchon Mandal`_

docs/extending/data_types.rst

@@ -0,0 +1,57 @@
+.. include:: ../links.inc
+
+.. _adding_data_types:
+
+Adding Data Types
+=================
+
+``junifer`` supports most of the :ref:`data types <data_types>` required for fMRI
+but also provides a way to add custom data types in case you work with other
+modalities like EEG.
+
+How to add a data type
+----------------------
+
+#. Check :ref:`extending junifer <extending_extension>` on how to create a
+   *junifer extension* if you have not done so.
+#. Define the data type schema in the *extension script* like so:
+
+   .. code-block:: python
+
+     from junifer.datagrabber import DataTypeSchema
+
+
+     dtype_schema: DataTypeSchema = {
+         "mandatory": ["pattern"],
+         "optional": {
+             "mask": {
+                 "mandatory": ["pattern"],
+                 "optional": [],
+             },
+         },
+     }
+
+   * The :obj:`.DataTypeSchema` has two mandatory keys:
+
+     * ``mandatory`` : list of str
+     * ``optional`` : dict of str and :obj:`.OptionalTypeSchema`
+
+   * ``mandatory`` defines the keys that must be present when defining a *pattern*
+     in a DataGrabber.
+   * ``optional`` defines the mapping from *sub-types* that are optional, to their patterns.
+     The patterns in turn require a ``mandatory`` key and an ``optional`` key both
+     just being the keys that must be there if the optional key is found. It's
+     possible that the *sub-type* (``mask`` in the example) can be absent from the dataset.
+
+#. Register the data type before defining / using a DataGrabber like so:
+
+   .. code-block:: python
+
+      from junifer.datagrabber import register_data_type
+      ...
+
+
+      # registers the data type as "dtype"
+      register_data_type(name="dtype", schema=dtype_schema)
+
+      ...

docs/extending/index.rst

@@ -32,3 +32,4 @@ DataGrabbers, Preprocessors, Markers, etc.,  following the *junifer* way.
    masks
    plugins
    data_registries
+   data_types

junifer/datagrabber/__init__.pyi

@@ -10,7 +10,11 @@ __all__ = [
     "DataladHCP1200",
     "MultipleDataGrabber",
     "DMCC13Benchmark",
+    "DataTypeManager",
+    "DataTypeSchema",
+    "OptionalTypeSchema",
     "PatternValidationMixin",
+    "register_data_type",
 ]
 
 # These 4 need to be in this order, otherwise it is a circular import
@@ -24,4 +28,10 @@ from .hcp1200 import HCP1200, DataladHCP1200
 from .multiple import MultipleDataGrabber
 from .dmcc13_benchmark import DMCC13Benchmark
 
-from .pattern_validation_mixin import PatternValidationMixin
+from .pattern_validation_mixin import (
+    DataTypeManager,
+    DataTypeSchema,
+    OptionalTypeSchema,
+    PatternValidationMixin,
+    register_data_type,
+)