junifer 0.0.5.dev62__py3-none-any.whl → 0.0.5.dev86__py3-none-any.whl

junifer/datagrabber/tests/test_dmcc13_benchmark.py

@@ -93,13 +93,10 @@ def test_DMCC13Benchmark(
         # Available data types
         data_types = [
             "BOLD",
-            "BOLD_confounds",
-            "BOLD_mask",
             "VBM_CSF",
             "VBM_GM",
             "VBM_WM",
             "T1w",
-            "T1w_mask",
         ]
         # Add Warp if native T1w is accessed
         if native_t1w:
@@ -111,14 +108,6 @@ def test_DMCC13Benchmark(
                 f"sub-01_{ses}_task-{task}_acq-mb4{phase}_run-{run}_"
                 "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
             ),
-            (
-                f"sub-01_{ses}_task-{task}_acq-mb4{phase}_run-{run}_"
-                "desc-confounds_regressors.tsv"
-            ),
-            (
-                f"sub-01_{ses}_task-{task}_acq-mb4{phase}_run-{run}_"
-                "space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
-            ),
             "sub-01_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz",
             "sub-01_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz",
             "sub-01_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz",
@@ -127,16 +116,12 @@ def test_DMCC13Benchmark(
             data_file_names.extend(
                 [
                     "sub-01_desc-preproc_T1w.nii.gz",
-                    "sub-01_desc-brain_mask.nii.gz",
                     "sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5",
                 ]
             )
         else:
-            data_file_names.extend(
-                [
-                    "sub-01_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz",
-                    "sub-01_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz",
-                ]
+            data_file_names.append(
+                "sub-01_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz"
             )
 
         for data_type, data_file_name in zip(data_types, data_file_names):
@@ -151,6 +136,48 @@ def test_DMCC13Benchmark(
             # Assert metadata
             assert "meta" in out[data_type]
 
+        # Check BOLD nested data types
+        for type_, file_name in zip(
+            ("mask", "confounds"),
+            (
+                (
+                    f"sub-01_{ses}_task-{task}_acq-mb4{phase}_run-{run}_"
+                    "space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
+                ),
+                (
+                    f"sub-01_{ses}_task-{task}_acq-mb4{phase}_run-{run}_"
+                    "desc-confounds_regressors.tsv"
+                ),
+            ),
+        ):
+            # Assert data type
+            assert type_ in out["BOLD"]
+            # Assert data file path exists
+            assert out["BOLD"][type_]["path"].exists()
+            # Assert data file path is a file
+            assert out["BOLD"][type_]["path"].is_file()
+            # Assert data file name
+            assert out["BOLD"][type_]["path"].name == file_name
+
+        # Check T1w nested data types
+        # Assert data type
+        assert "mask" in out["T1w"]
+        # Assert data file path exists
+        assert out["T1w"]["mask"]["path"].exists()
+        # Assert data file path is a file
+        assert out["T1w"]["mask"]["path"].is_file()
+        # Assert data file name
+        if native_t1w:
+            assert (
+                out["T1w"]["mask"]["path"].name
+                == "sub-01_desc-brain_mask.nii.gz"
+            )
+        else:
+            assert (
+                out["T1w"]["mask"]["path"].name
+                == "sub-01_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz"
+            )
+
 
 @pytest.mark.parametrize(
     "types, native_t1w",
@@ -165,8 +192,8 @@ def test_DMCC13Benchmark(
         ("VBM_GM", False),
         ("VBM_WM", True),
         ("VBM_WM", False),
-        (["BOLD", "BOLD_confounds"], True),
-        (["BOLD", "BOLD_confounds"], False),
+        (["BOLD", "VBM_CSF"], True),
+        (["BOLD", "VBM_CSF"], False),
         (["T1w", "VBM_CSF"], True),
         (["T1w", "VBM_CSF"], False),
         (["VBM_GM", "VBM_WM"], True),

junifer/datagrabber/utils.py

@@ -13,51 +13,45 @@ from ..utils import logger, raise_error
 PATTERNS_SCHEMA = {
     "T1w": {
         "mandatory": ["pattern", "space"],
-        "optional": ["mask_item"],
-    },
-    "T1w_mask": {
-        "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {
+            "mask": {"mandatory": ["pattern", "space"], "optional": []},
+        },
     },
     "T2w": {
         "mandatory": ["pattern", "space"],
-        "optional": ["mask_item"],
-    },
-    "T2w_mask": {
-        "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {
+            "mask": {"mandatory": ["pattern", "space"], "optional": []},
+        },
     },
     "BOLD": {
         "mandatory": ["pattern", "space"],
-        "optional": ["mask_item"],
-    },
-    "BOLD_confounds": {
-        "mandatory": ["pattern", "format"],
-        "optional": [],
-    },
-    "BOLD_mask": {
-        "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {
+            "mask": {"mandatory": ["pattern", "space"], "optional": []},
+            "confounds": {
+                "mandatory": ["pattern", "format"],
+                "optional": ["mappings"],
+            },
+        },
     },
     "Warp": {
         "mandatory": ["pattern", "src", "dst"],
-        "optional": [],
+        "optional": {},
     },
     "VBM_GM": {
         "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {},
     },
     "VBM_WM": {
         "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {},
     },
     "VBM_CSF": {
         "mandatory": ["pattern", "space"],
-        "optional": [],
+        "optional": {},
     },
     "DWI": {
         "mandatory": ["pattern"],
-        "optional": [],
+        "optional": {},
     },
 }
 
@@ -129,6 +123,67 @@ def validate_replacements(
         raise_error(msg="At least one pattern must contain all replacements.")
 
 
+def _validate_mandatory_keys(
+    keys: List[str], schema: List[str], data_type: str
+) -> None:
+    """Validate mandatory keys.
+
+    Parameters
+    ----------
+    keys : list of str
+        The keys to validate.
+    schema : list of str
+        The schema to validate against.
+    data_type : str
+        The data type being validated.
+
+    Raises
+    ------
+    KeyError
+        If any mandatory key is missing for a data type.
+
+    """
+    for key in schema:
+        if key not in keys:
+            raise_error(
+                msg=f"Mandatory key: `{key}` missing for {data_type}",
+                klass=KeyError,
+            )
+        else:
+            logger.debug(f"Mandatory key: `{key}` found for {data_type}")
+
+
+def _identify_stray_keys(
+    keys: List[str], schema: List[str], data_type: str
+) -> None:
+    """Identify stray keys.
+
+    Parameters
+    ----------
+    keys : list of str
+        The keys to check.
+    schema : list of str
+        The schema to check against.
+    data_type : str
+        The data type being checked.
+
+    Raises
+    ------
+    RuntimeError
+        If an unknown key is found for a data type.
+
+    """
+    for key in keys:
+        if key not in schema:
+            raise_error(
+                msg=(
+                    f"Key: {key} not accepted for {data_type} "
+                    "pattern, remove it to proceed"
+                ),
+                klass=RuntimeError,
+            )
+
+
 def validate_patterns(
     types: List[str], patterns: Dict[str, Dict[str, str]]
 ) -> None:
@@ -143,10 +198,6 @@ def validate_patterns(
 
     Raises
     ------
-    KeyError
-        If any mandatory key is missing for a data type.
-    RuntimeError
-        If an unknown key is found for a data type.
     TypeError
         If ``patterns`` is not a dictionary.
     ValueError
@@ -180,22 +231,15 @@ def validate_patterns(
                 f"should be one of: {list(PATTERNS_SCHEMA.keys())}"
             )
         # Check mandatory keys for data type
-        for mandatory_key in PATTERNS_SCHEMA[data_type_key]["mandatory"]:
-            if mandatory_key not in data_type_val:
-                raise_error(
-                    msg=(
-                        f"Mandatory key: `{mandatory_key}` missing for "
-                        f"{data_type_key}"
-                    ),
-                    klass=KeyError,
-                )
-            else:
-                logger.debug(
-                    f"Mandatory key: `{mandatory_key}` found for "
-                    f"{data_type_key}"
-                )
+        _validate_mandatory_keys(
+            keys=list(data_type_val),
+            schema=PATTERNS_SCHEMA[data_type_key]["mandatory"],
+            data_type=data_type_key,
+        )
         # Check optional keys for data type
-        for optional_key in PATTERNS_SCHEMA[data_type_key]["optional"]:
+        for optional_key, optional_val in PATTERNS_SCHEMA[data_type_key][
+            "optional"
+        ].items():
             if optional_key not in data_type_val:
                 logger.debug(
                     f"Optional key: `{optional_key}` missing for "
@@ -206,19 +250,48 @@ def validate_patterns(
                     f"Optional key: `{optional_key}` found for "
                     f"{data_type_key}"
                 )
+                # Set nested type name for easier access
+                nested_data_type = f"{data_type_key}.{optional_key}"
+                nested_mandatory_keys_schema = PATTERNS_SCHEMA[data_type_key][
+                    "optional"
+                ][optional_key]["mandatory"]
+                nested_optional_keys_schema = PATTERNS_SCHEMA[data_type_key][
+                    "optional"
+                ][optional_key]["optional"]
+                # Check mandatory keys for nested type
+                _validate_mandatory_keys(
+                    keys=list(optional_val["mandatory"]),
+                    schema=nested_mandatory_keys_schema,
+                    data_type=nested_data_type,
+                )
+                # Check optional keys for nested type
+                for nested_optional_key in nested_optional_keys_schema:
+                    if nested_optional_key not in optional_val["optional"]:
+                        logger.debug(
+                            f"Optional key: `{nested_optional_key}` missing "
+                            f"for {nested_data_type}"
+                        )
+                    else:
+                        logger.debug(
+                            f"Optional key: `{nested_optional_key}` found for "
+                            f"{nested_data_type}"
+                        )
+                # Check stray key for nested data type
+                _identify_stray_keys(
+                    keys=optional_val["mandatory"] + optional_val["optional"],
+                    schema=nested_mandatory_keys_schema
+                    + nested_optional_keys_schema,
+                    data_type=nested_data_type,
+                )
         # Check stray key for data type
-        for key in data_type_val.keys():
-            if key not in (
+        _identify_stray_keys(
+            keys=list(data_type_val.keys()),
+            schema=(
                 PATTERNS_SCHEMA[data_type_key]["mandatory"]
-                + PATTERNS_SCHEMA[data_type_key]["optional"]
-            ):
-                raise_error(
-                    msg=(
-                        f"Key: {key} not accepted for {data_type_key} "
-                        "pattern, remove it to proceed"
-                    ),
-                    klass=RuntimeError,
-                )
+                + list(PATTERNS_SCHEMA[data_type_key]["optional"].keys())
+            ),
+            data_type=data_type_key,
+        )
         # Wildcard check in patterns
         if "}*" in data_type_val["pattern"]:
             raise_error(

junifer/datareader/default.py

@@ -5,7 +5,7 @@
 # License: AGPL
 
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Union
 
 import nibabel as nib
 import pandas as pd
@@ -102,57 +102,106 @@ class DefaultDataReader(PipelineStepMixin, UpdateMetaMixin):
         if params is None:
             params = {}
         # For each type of data, try to read it
-        for type_ in input.keys():
+        for type_key, type_val in input.items():
             # Skip Warp data type
-            if type_ == "Warp":
+            if type_key == "Warp":
                 continue
 
             # Check for malformed datagrabber specification
-            if "path" not in input[type_]:
+            if "path" not in type_val:
                 warn_with_log(
-                    f"Input type {type_} does not provide a path. Skipping."
+                    f"Input type {type_key} does not provide a path. Skipping."
                 )
                 continue
 
-            # Retrieve actual path
-            t_path = input[type_]["path"]
-            # Retrieve loading params for the data type
-            t_params = params.get(type_, {})
-
-            # Convert str to Path
-            if not isinstance(t_path, Path):
-                t_path = Path(t_path)
-                out[type_]["path"] = t_path
-
-            logger.info(f"Reading {type_} from {t_path.as_posix()}")
-            # Initialize variable for file data
-            fread = None
-            # Lowercase path
-            fname = t_path.name.lower()
-            # Loop through extensions to find the correct one
-            for ext, ftype in _extensions.items():
-                if fname.endswith(ext):
-                    logger.info(f"{type_} is type {ftype}")
-                    # Retrieve reader function
-                    reader_func = _readers[ftype]["func"]
-                    # Retrieve reader function params
-                    reader_params = _readers[ftype]["params"]
-                    # Update reader function params
-                    if reader_params is not None:
-                        t_params.update(reader_params)
-                    logger.debug(f"Calling {reader_func} with {t_params}")
+            # Iterate to check for nested "types" like mask;
+            # need to copy to avoid runtime error for changing dict size
+            for k, v in type_val.copy().items():
+                # Read data for base data type
+                if k == "path":
+                    # Convert str to Path
+                    if not isinstance(v, Path):
+                        v = Path(v)
+                    # Update path
+                    out[type_key]["path"] = v
+                    logger.info(f"Reading {type_key} from {v.absolute()!s}")
+                    # Retrieve loading params for the data type
+                    t_params = params.get(type_key, {})
                     # Read data
-                    fread = reader_func(t_path, **t_params)
-                    break
-            # If no file data is found due to unknown extension
-            if fread is None:
-                logger.info(
-                    f"Unknown file type {t_path.as_posix()}, skipping reading"
-                )
+                    out[type_key]["data"] = _read_data(
+                        data_type=type_key, path=v, read_params=t_params
+                    )
+                # Read data for nested data type
+                if isinstance(v, dict) and "path" in v:
+                    # Set path
+                    nested_path = v["path"]
+                    # Convert str to Path
+                    if not isinstance(nested_path, Path):
+                        nested_path = Path(nested_path)
+                    # Update path
+                    out[type_key][k]["path"] = nested_path
+                    # Set nested type key for easier access
+                    nested_type = f"{type_key}.{k}"
+                    logger.info(
+                        f"Reading {nested_type} from "
+                        f"{nested_path.absolute()!s}"
+                    )
+                    # Retrieve loading params for the nested data type
+                    nested_params = params.get(nested_type, {})
+                    # Read data
+                    out[type_key][k]["data"] = _read_data(
+                        data_type=nested_type,
+                        path=nested_path,
+                        read_params=nested_params,
+                    )
 
-            # Set file data for output
-            out[type_]["data"] = fread
             # Update metadata for step
-            self.update_meta(out[type_], "datareader")
+            self.update_meta(out[type_key], "datareader")
 
         return out
+
+
+def _read_data(
+    data_type: str, path: Path, read_params: Dict
+) -> Union[nib.Nifti1Image, pd.DataFrame, None]:
+    """Read data for data type.
+
+    Parameters
+    ----------
+    data_type : str
+        The data type being read.
+    path : pathlib.Path
+        The path to read data from.
+    read_params : dict
+        Parameters for reader function.
+
+    Returns
+    -------
+    nibabel.Nifti1Image or pandas.DataFrame or pandas.TextFileReader or None
+        The data loaded in memory if file type is known else None.
+
+    """
+    # Initialize variable for file data
+    fread = None
+    # Lowercase path
+    fname = path.name.lower()
+    # Loop through extensions to find the correct one
+    for ext, ftype in _extensions.items():
+        if fname.endswith(ext):
+            logger.info(f"{data_type} is of type {ftype}")
+            # Retrieve reader function
+            reader_func = _readers[ftype]["func"]
+            # Retrieve reader function params
+            reader_params = _readers[ftype]["params"]
+            # Update reader function params
+            if reader_params is not None:
+                read_params.update(reader_params)
+            logger.debug(f"Calling {reader_func!s} with {read_params}")
+            # Read data
+            fread = reader_func(path, **read_params)
+            break
+    # If no file data is found due to unknown extension
+    if fread is None:
+        logger.info(f"Unknown file type {path.absolute()!s}, skipping reading")
+
+    return fread

junifer/pipeline/utils.py

@@ -37,7 +37,7 @@ def check_ext_dependencies(
         If ``name`` is mandatory and is not found.
 
     """
-    valid_ext_dependencies = ("afni", "fsl", "ants")
+    valid_ext_dependencies = ("afni", "fsl", "ants", "freesurfer")
     if name not in valid_ext_dependencies:
         raise_error(
             "Invalid value for `name`, should be one of: "
@@ -52,6 +52,9 @@ def check_ext_dependencies(
     # Check for ants
     elif name == "ants":
         found = _check_ants(**kwargs)
+    # Check for freesurfer
+    elif name == "freesurfer":
+        found = _check_freesurfer(**kwargs)
 
     # Check if the dependency is mandatory in case it's not found
     if not found and not optional:
@@ -245,3 +248,63 @@ def _check_ants(commands: Optional[List[str]] = None) -> bool:
                 f"{commands_found_results}"
             )
     return ants_found
+
+
+def _check_freesurfer(commands: Optional[List[str]] = None) -> bool:
+    """Check if FreeSurfer is present in the system.
+
+    Parameters
+    ----------
+    commands : list of str, optional
+        The commands to specifically check for from FreeSurfer. If None, only
+        the basic FreeSurfer help would be looked up, else, would also
+        check for specific commands (default None).
+
+    Returns
+    -------
+    bool
+        Whether FreeSurfer is found or not.
+
+    """
+    completed_process = subprocess.run(
+        "recon-all -help",
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.STDOUT,
+        shell=True,  # is unsafe but kept for resolution via PATH
+        check=False,
+    )
+    fs_found = completed_process.returncode == 0
+
+    # Check for specific commands
+    if fs_found and commands is not None:
+        if not isinstance(commands, list):
+            commands = [commands]
+        # Store command found results
+        commands_found_results = {}
+        # Set all commands found flag to True
+        all_commands_found = True
+        # Check commands' existence
+        for command in commands:
+            command_process = subprocess.run(
+                [command],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
+                shell=True,  # is unsafe but kept for resolution via PATH
+                check=False,
+            )
+            command_found = command_process.returncode == 0
+            commands_found_results[command] = (
+                "found" if command_found else "not found"
+            )
+            # Set flag to trigger warning
+            all_commands_found = all_commands_found and command_found
+        # One or more commands were missing
+        if not all_commands_found:
+            warn_with_log(
+                "FreeSurfer is installed but some of the required commands "
+                "were not found. These are the results: "
+                f"{commands_found_results}"
+            )
+    return fs_found

junifer/preprocess/base.py

@@ -146,8 +146,8 @@ class BasePreprocessor(ABC, PipelineStepMixin, UpdateMetaMixin):
             The computed result as dictionary.
         dict or None
             Extra "helper" data types as dictionary to add to the Junifer Data
-            object. For example, computed BOLD mask can be passed via this.
-            If no new "helper" data types is created, None is to be passed.
+            object. If no new "helper" data type(s) is(are) created, None is to
+            be passed.
 
         """
         raise_error(