junifer 0.0.7.dev332__py3-none-any.whl → 0.0.8__py3-none-any.whl

junifer/datagrabber/dmcc13_benchmark.py

@@ -3,16 +3,92 @@
 # Authors: Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
-from itertools import product
-from pathlib import Path
-from typing import Union
+from enum import StrEnum
+from typing import Annotated, ClassVar, Literal
+
+from pydantic import AnyUrl, BeforeValidator
 
 from ..api.decorators import register_datagrabber
-from ..utils import raise_error
+from ..typing import DataGrabberPatterns
+from ..utils import ensure_list
+from .base import DataType
+from .pattern import ConfoundsFormat
 from .pattern_datalad import PatternDataladDataGrabber
 
 
-__all__ = ["DMCC13Benchmark"]
+__all__ = [
+    "DMCC13Benchmark",
+    "DMCCPhaseEncoding",
+    "DMCCRun",
+    "DMCCSession",
+    "DMCCTask",
+]
+
+
+class DMCCSession(StrEnum):
+    """Accepted DMCC sessions."""
+
+    Wave1Bas = "ses-wave1bas"
+    Wave1Pro = "ses-wave1pro"
+    Wave1Rea = "ses-wave1rea"
+
+
+class DMCCTask(StrEnum):
+    """Accepted DMCC tasks."""
+
+    Rest = "Rest"
+    Axcpt = "Axcpt"
+    Cuedts = "Cuedts"
+    Stern = "Stern"
+    Stroop = "Stroop"
+
+
+class DMCCPhaseEncoding(StrEnum):
+    """Accepted DMCC phase encoding directions."""
+
+    AP = "AP"
+    PA = "PA"
+
+
+class DMCCRun(StrEnum):
+    """Accepted DMCC runs."""
+
+    One = "1"
+    Two = "2"
+
+
+_types = Literal[
+    DataType.BOLD,
+    DataType.T1w,
+    DataType.VBM_CSF,
+    DataType.VBM_GM,
+    DataType.VBM_WM,
+    DataType.Warp,
+]
+
+_sessions = Literal[
+    DMCCSession.Wave1Bas,
+    DMCCSession.Wave1Pro,
+    DMCCSession.Wave1Rea,
+]
+
+_tasks = Literal[
+    DMCCTask.Rest,
+    DMCCTask.Axcpt,
+    DMCCTask.Cuedts,
+    DMCCTask.Stern,
+    DMCCTask.Stroop,
+]
+
+_phase_encodings = Literal[
+    DMCCPhaseEncoding.AP,
+    DMCCPhaseEncoding.PA,
+]
+
+_runs = Literal[
+    DMCCRun.One,
+    DMCCRun.Two,
+]
 
 
 @register_datagrabber
@@ -21,191 +97,149 @@ class DMCC13Benchmark(PatternDataladDataGrabber):
 
     Parameters
     ----------
-    datadir : str or Path or None, optional
-        The directory where the datalad dataset will be cloned. If None,
-        the datalad dataset will be cloned into a temporary directory
-        (default None).
-    types: {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM"} or \
-           list of the options, optional
-        DMCC data types. If None, all available data types are selected.
-        (default None).
-    sessions: {"ses-wave1bas", "ses-wave1pro", "ses-wave1rea"} or \
-              list of the options, optional
-        DMCC sessions. If None, all available sessions are selected
-        (default None).
-    tasks: {"Rest", "Axcpt", "Cuedts", "Stern", "Stroop"} or \
-           list of the options, optional
-        DMCC task sessions. If None, all available task sessions are selected
-        (default None).
+    types : {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM", "Warp"} or \
+            list of the options, optional
+        The data type(s) to grab.
+    datadir : pathlib.Path, optional
+        That path where the datalad dataset will be cloned.
+        If not specified, the datalad dataset will be cloned into a temporary
+        directory.
+    sessions : {"ses-wave1bas", "ses-wave1pro", "ses-wave1rea"} or \
+               list of the options, optional
+        DMCC sessions.
+        By default, all available sessions are selected.
+    tasks : {"Rest", "Axcpt", "Cuedts", "Stern", "Stroop"} or \
+            list of the options, optional
+        DMCC tasks.
+        By default, all available tasks are selected.
     phase_encodings : {"AP", "PA"} or list of the options, optional
-        DMCC phase encoding directions. If None, all available phase encodings
-        are selected (default None).
+        DMCC phase encoding directions.
+        By default, all available phase encodings are selected.
     runs : {"1", "2"} or list of the options, optional
-        DMCC runs. If None, all available runs are selected (default None).
+        DMCC runs.
+        By default, all available runs are selected.
     native_t1w : bool, optional
         Whether to use T1w in native space (default False).
 
-    Raises
-    ------
-    ValueError
-        If invalid value is passed for:
-         * ``sessions``
-         * ``tasks``
-         * ``phase_encodings``
-         * ``runs``
-
     """
 
-    def __init__(
-        self,
-        datadir: Union[str, Path, None] = None,
-        types: Union[str, list[str], None] = None,
-        sessions: Union[str, list[str], None] = None,
-        tasks: Union[str, list[str], None] = None,
-        phase_encodings: Union[str, list[str], None] = None,
-        runs: Union[str, list[str], None] = None,
-        native_t1w: bool = False,
-    ) -> None:
-        # Declare all sessions
-        all_sessions = [
-            "ses-wave1bas",
-            "ses-wave1pro",
-            "ses-wave1rea",
-        ]
-        # Set default sessions
-        if sessions is None:
-            sessions = all_sessions
-        else:
-            # Convert single session into list
-            if isinstance(sessions, str):
-                sessions = [sessions]
-            # Verify valid sessions
-            for s in sessions:
-                if s not in all_sessions:
-                    raise_error(
-                        f"{s} is not a valid session in the DMCC dataset"
-                    )
-        self.sessions = sessions
-        # Declare all tasks
-        all_tasks = [
-            "Rest",
-            "Axcpt",
-            "Cuedts",
-            "Stern",
-            "Stroop",
-        ]
-        # Set default tasks
-        if tasks is None:
-            tasks = all_tasks
-        else:
-            # Convert single task into list
-            if isinstance(tasks, str):
-                tasks = [tasks]
-            # Verify valid tasks
-            for t in tasks:
-                if t not in all_tasks:
-                    raise_error(f"{t} is not a valid task in the DMCC dataset")
-        self.tasks = tasks
-        # Declare all phase encodings
-        all_phase_encodings = ["AP", "PA"]
-        # Set default phase encodings
-        if phase_encodings is None:
-            phase_encodings = all_phase_encodings
-        else:
-            # Convert single phase encoding into list
-            if isinstance(phase_encodings, str):
-                phase_encodings = [phase_encodings]
-            # Verify valid phase encodings
-            for p in phase_encodings:
-                if p not in all_phase_encodings:
-                    raise_error(
-                        f"{p} is not a valid phase encoding in the DMCC "
-                        "dataset"
-                    )
-        self.phase_encodings = phase_encodings
-        # Declare all runs
-        all_runs = ["1", "2"]
-        # Set default runs
-        if runs is None:
-            runs = all_runs
-        else:
-            # Convert single run into list
-            if isinstance(runs, str):
-                runs = [runs]
-            # Verify valid runs
-            for r in runs:
-                if r not in all_runs:
-                    raise_error(f"{r} is not a valid run in the DMCC dataset")
-        self.runs = runs
-        # The patterns
-        patterns = {
-            "BOLD": {
+    uri: AnyUrl = AnyUrl("https://github.com/OpenNeuroDatasets/ds003452.git")
+    types: Annotated[_types | list[_types], BeforeValidator(ensure_list)] = [  # noqa: RUF012
+        DataType.BOLD,
+        DataType.T1w,
+        DataType.VBM_CSF,
+        DataType.VBM_GM,
+        DataType.VBM_WM,
+    ]
+    sessions: Annotated[
+        _sessions | list[_sessions], BeforeValidator(ensure_list)
+    ] = [  # noqa: RUF012
+        DMCCSession.Wave1Bas,
+        DMCCSession.Wave1Pro,
+        DMCCSession.Wave1Rea,
+    ]
+    tasks: Annotated[_tasks | list[_tasks], BeforeValidator(ensure_list)] = [  # noqa: RUF012
+        DMCCTask.Rest,
+        DMCCTask.Axcpt,
+        DMCCTask.Cuedts,
+        DMCCTask.Stern,
+        DMCCTask.Stroop,
+    ]
+    phase_encodings: Annotated[
+        _phase_encodings | list[_phase_encodings],
+        BeforeValidator(ensure_list),
+    ] = [  # noqa: RUF012
+        DMCCPhaseEncoding.AP,
+        DMCCPhaseEncoding.PA,
+    ]
+    runs: Annotated[_runs | list[_runs], BeforeValidator(ensure_list)] = [  # noqa: RUF012
+        DMCCRun.One,
+        DMCCRun.Two,
+    ]
+    native_t1w: bool = False
+    patterns: DataGrabberPatterns = {  # noqa: RUF012
+        "BOLD": {
+            "pattern": (
+                "derivatives/fmriprep-1.3.2/{subject}/{session}/"
+                "func/{subject}_{session}_task-{task}_acq-mb4"
+                "{phase_encoding}_run-{run}_"
+                "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
+            ),
+            "space": "MNI152NLin2009cAsym",
+            "mask": {
                 "pattern": (
                     "derivatives/fmriprep-1.3.2/{subject}/{session}/"
                     "func/{subject}_{session}_task-{task}_acq-mb4"
                     "{phase_encoding}_run-{run}_"
-                    "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
+                    "space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "mask": {
-                    "pattern": (
-                        "derivatives/fmriprep-1.3.2/{subject}/{session}/"
-                        "func/{subject}_{session}_task-{task}_acq-mb4"
-                        "{phase_encoding}_run-{run}_"
-                        "space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
-                    ),
-                    "space": "MNI152NLin2009cAsym",
-                },
-                "confounds": {
-                    "pattern": (
-                        "derivatives/fmriprep-1.3.2/{subject}/{session}/"
-                        "func/{subject}_{session}_task-{task}_acq-mb4"
-                        "{phase_encoding}_run-{run}_desc-confounds_regressors.tsv"
-                    ),
-                    "format": "fmriprep",
-                },
             },
-            "T1w": {
+            "confounds": {
                 "pattern": (
-                    "derivatives/fmriprep-1.3.2/{subject}/anat/"
-                    "{subject}_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz"
-                ),
-                "space": "MNI152NLin2009cAsym",
-                "mask": {
-                    "pattern": (
-                        "derivatives/fmriprep-1.3.2/{subject}/anat/"
-                        "{subject}_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
-                    ),
-                    "space": "MNI152NLin2009cAsym",
-                },
-            },
-            "VBM_CSF": {
-                "pattern": (
-                    "derivatives/fmriprep-1.3.2/{subject}/anat/"
-                    "{subject}_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz"
+                    "derivatives/fmriprep-1.3.2/{subject}/{session}/"
+                    "func/{subject}_{session}_task-{task}_acq-mb4"
+                    "{phase_encoding}_run-{run}_desc-confounds_regressors.tsv"
                 ),
-                "space": "MNI152NLin2009cAsym",
+                "format": "fmriprep",
             },
-            "VBM_GM": {
+        },
+        "T1w": {
+            "pattern": (
+                "derivatives/fmriprep-1.3.2/{subject}/anat/"
+                "{subject}_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz"
+            ),
+            "space": "MNI152NLin2009cAsym",
+            "mask": {
                 "pattern": (
                     "derivatives/fmriprep-1.3.2/{subject}/anat/"
-                    "{subject}_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz"
+                    "{subject}_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
             },
-            "VBM_WM": {
-                "pattern": (
-                    "derivatives/fmriprep-1.3.2/{subject}/anat/"
-                    "{subject}_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz"
-                ),
-                "space": "MNI152NLin2009cAsym",
-            },
-        }
-        # Use native T1w assets
-        self.native_t1w = False
-        if native_t1w:
-            self.native_t1w = True
-            patterns.update(
+        },
+        "VBM_CSF": {
+            "pattern": (
+                "derivatives/fmriprep-1.3.2/{subject}/anat/"
+                "{subject}_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz"
+            ),
+            "space": "MNI152NLin2009cAsym",
+        },
+        "VBM_GM": {
+            "pattern": (
+                "derivatives/fmriprep-1.3.2/{subject}/anat/"
+                "{subject}_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz"
+            ),
+            "space": "MNI152NLin2009cAsym",
+        },
+        "VBM_WM": {
+            "pattern": (
+                "derivatives/fmriprep-1.3.2/{subject}/anat/"
+                "{subject}_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz"
+            ),
+            "space": "MNI152NLin2009cAsym",
+        },
+    }
+    replacements: list[str] = [  # noqa: RUF012
+        "subject",
+        "session",
+        "task",
+        "phase_encoding",
+        "run",
+    ]
+    # Only grab the specified sessions, tasks, phase encodings and runs
+    _REPLACEMENT_FIELDS: ClassVar[dict[str, str]] = {
+        "session": "sessions",
+        "task": "tasks",
+        "phase_encoding": "phase_encodings",
+        "run": "runs",
+    }
+    confounds_format: ConfoundsFormat = ConfoundsFormat.FMRIPrep
+
+    def validate_datagrabber_params(self) -> None:
+        """Run extra logical validation for datagrabber."""
+        if self.native_t1w:
+            self.patterns.update(
                 {
                     "T1w": {
                         "pattern": (
@@ -245,124 +279,5 @@ class DMCC13Benchmark(PatternDataladDataGrabber):
                     ],
                 }
             )
-        # Set default types
-        if types is None:
-            types = list(patterns.keys())
-        # Convert single type into list
-        else:
-            if not isinstance(types, list):
-                types = [types]
-        # The replacements
-        replacements = ["subject", "session", "task", "phase_encoding", "run"]
-        uri = "https://github.com/OpenNeuroDatasets/ds003452.git"
-        super().__init__(
-            types=types,
-            datadir=datadir,
-            uri=uri,
-            patterns=patterns,
-            replacements=replacements,
-            confounds_format="fmriprep",
-        )
-
-    def get_item(
-        self,
-        subject: str,
-        session: str,
-        task: str,
-        phase_encoding: str,
-        run: str,
-    ) -> dict:
-        """Index one element in the dataset.
-
-        Parameters
-        ----------
-        subject : str
-            The subject ID.
-        session : {"ses-wave1bas", "ses-wave1pro", "ses-wave1rea"}
-            The session to get.
-        task : {"Rest", "Axcpt", "Cuedts", "Stern", "Stroop"}
-            The task to get.
-        phase_encoding : {"AP", "PA"}
-            The phase encoding to get.
-        run : {"1", "2"}
-            The run to get.
-
-        Returns
-        -------
-        out : dict
-            Dictionary of paths for each type of data required for the
-            specified element.
-
-        """
-        # Format run
-        if phase_encoding == "AP":
-            run = "1"
-        else:
-            run = "2"
-        # Fetch item
-        out = super().get_item(
-            subject=subject,
-            session=session,
-            task=task,
-            phase_encoding=phase_encoding,
-            run=run,
-        )
-        return out
-
-    def get_elements(self) -> list:
-        """Implement fetching list of subjects in the dataset.
-
-        Returns
-        -------
-        list of str
-            The list of subjects in the dataset.
-
-        """
-        subjects = [
-            "sub-f1031ax",
-            "sub-f1552xo",
-            "sub-f1659oa",
-            "sub-f1670rz",
-            "sub-f1951tt",
-            "sub-f3300jh",
-            "sub-f3720ca",
-            "sub-f5004cr",
-            "sub-f5407sl",
-            "sub-f5416zj",
-            "sub-f8113do",
-            "sub-f8570ui",
-            "sub-f9057kp",
-        ]
-        elems = []
-        # For wave1bas session
-        for subject, session, task, phase_encoding in product(
-            subjects,
-            ["ses-wave1bas"],
-            self.tasks,
-            self.phase_encodings,
-        ):
-            if phase_encoding == "AP":
-                run = "1"
-            else:
-                run = "2"
-            # Bypass for f1951tt not having run 2 for Rest
-            if subject == "sub-f1951tt" and task == "Rest" and run == "2":
-                continue
-            elems.append((subject, session, task, phase_encoding, run))
-        # For other sessions
-        for subject, session, task, phase_encoding in product(
-            subjects,
-            ["ses-wave1pro", "ses-wave1rea"],
-            ["Rest"],
-            self.phase_encodings,
-        ):
-            if phase_encoding == "AP":
-                run = "1"
-            else:
-                run = "2"
-            # Bypass for f5416zj for not having wave1rea session
-            if subject == "sub-f5416zj" and session == "ses-wave1rea":
-                continue
-            elems.append((subject, session, task, phase_encoding, run))
-
-        return elems
+            self.types.append(DataType.Warp)
+        super().validate_datagrabber_params()

junifer/datagrabber/hcp1200/__init__.pyi

@@ -1,4 +1,9 @@
-__all__ = ["HCP1200", "DataladHCP1200"]
+__all__ = [
+    "HCP1200",
+    "HCP1200Task",
+    "HCP1200PhaseEncoding",
+    "DataladHCP1200",
+]
 
-from .hcp1200 import HCP1200
+from .hcp1200 import HCP1200, HCP1200Task, HCP1200PhaseEncoding
 from .datalad_hcp1200 import DataladHCP1200

junifer/datagrabber/hcp1200/datalad_hcp1200.py

@@ -5,68 +5,63 @@
 #          Synchon Mandal <s.mandal@fz-juelich.de>
 # License: AGPL
 
+from itertools import product
 from pathlib import Path
-from typing import Union
+from typing import Annotated, Literal
 
-from junifer.datagrabber.datalad_base import DataladDataGrabber
+from pydantic import AnyUrl, BeforeValidator
 
 from ...api.decorators import register_datagrabber
+from ...typing import Elements
+from ...utils import ensure_list
+from ..base import DataType
+from ..datalad_base import DataladDataGrabber
 from .hcp1200 import HCP1200
 
 
 __all__ = ["DataladHCP1200"]
 
 
+_types = Literal[DataType.BOLD, DataType.T1w, DataType.Warp]
+
+
 @register_datagrabber
 class DataladHCP1200(DataladDataGrabber, HCP1200):
     """Concrete implementation for datalad-based data fetching of HCP1200.
 
     Parameters
     ----------
-    datadir : str or Path or None, optional
-        The directory where the datalad dataset will be cloned. If None,
-        the datalad dataset will be cloned into a temporary directory
-        (default None).
+    types : {"BOLD", "T1w", "Warp"} or list of the options, optional
+        The data type(s) to grab.
+    datadir : pathlib.Path, optional
+        That path where the datalad dataset will be cloned.
+        If not specified, the datalad dataset will be cloned into a temporary
+        directory.
     tasks : {"REST1", "REST2", "SOCIAL", "WM", "RELATIONAL", "EMOTION", \
-            "LANGUAGE", "GAMBLING", "MOTOR"} or list of the options or None \
-            , optional
-        HCP task sessions. If None, all available task sessions are selected
-        (default None).
-    phase_encodings : {"LR", "RL"} or list of the options or None, optional
-        HCP phase encoding directions. If None, both will be used
-        (default None).
+            "LANGUAGE", "GAMBLING", "MOTOR"} or list of the options, optional
+        HCP task sessions.
+        By default, all available task sessions are selected.
+    phase_encodings : {"LR", "RL"} or list of the options, optional
+        HCP phase encoding directions.
+        By default, all are used.
     ica_fix : bool, optional
         Whether to retrieve data that was processed with ICA+FIX.
-        Only "REST1" and "REST2" tasks are available with ICA+FIX (default
-        False).
-
-    Raises
-    ------
-    ValueError
-        If invalid value is passed for ``tasks`` or ``phase_encodings``.
+        Only ``HCP1200Task.REST1`` and ``HCP1200Task.REST2`` tasks
+        are available with ICA+FIX
+        (default False).
 
     """
 
-    def __init__(
-        self,
-        datadir: Union[str, Path, None] = None,
-        tasks: Union[str, list[str], None] = None,
-        phase_encodings: Union[str, list[str], None] = None,
-        ica_fix: bool = False,
-    ) -> None:
-        uri = (
-            "https://github.com/datalad-datasets/"
-            "human-connectome-project-openaccess.git"
-        )
-        rootdir = "HCP1200"
-        super().__init__(
-            datadir=datadir,
-            tasks=tasks,
-            phase_encodings=phase_encodings,
-            uri=uri,
-            rootdir=rootdir,
-            ica_fix=ica_fix,
-        )
+    uri: AnyUrl = AnyUrl(
+        "https://github.com/datalad-datasets/"
+        "human-connectome-project-openaccess.git"
+    )
+    types: Annotated[_types | list[_types], BeforeValidator(ensure_list)] = [  # noqa: RUF012
+        DataType.BOLD,
+        DataType.T1w,
+        DataType.Warp,
+    ]
+    rootdir: Path = Path("HCP1200")
 
     # Needed here as HCP1200's subjects are sub-datasets, so will not be
     # found when elements are checked.
@@ -74,3 +69,29 @@ class DataladHCP1200(DataladDataGrabber, HCP1200):
     def skip_file_check(self) -> bool:
         """Skip file check existence."""
         return True
+
+    def get_elements(self) -> Elements:
+        """Implement fetching list of elements in the dataset.
+
+        The subjects are sub-datasets, whose files are only there once they
+        are installed, so the files are not searched: the elements are all
+        the subjects (the directories of the dataset) with the tasks and
+        phase encodings to grab, even if some of them have no data.
+
+        Returns
+        -------
+        list
+            The list of elements that can be grabbed in the dataset.
+
+        """
+        subjects = sorted(
+            x.name
+            for x in self.fulldir.iterdir()
+            if x.is_dir() and not x.name.startswith(".")
+        )
+        values = {"subject": subjects, **self.get_replacement_values()}
+        element_keys = self.get_element_keys()
+        elements = list(product(*(values[k] for k in element_keys)))
+        if len(element_keys) == 1:
+            return [element[0] for element in elements]
+        return elements