junifer 0.0.5.dev62__tar.gz → 0.0.5.dev86__tar.gz

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: junifer
-Version: 0.0.5.dev62
+Version: 0.0.5.dev86
 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>

junifer-0.0.5.dev86/docs/changes/newsfragments/341.enh

@@ -0,0 +1 @@
+Refactor DataGrabber ``patterns`` to make helper types like ``*_mask`` as "nested types" of the actual data type by `Synchon Mandal`_

junifer-0.0.5.dev86/docs/changes/newsfragments/342.misc

@@ -0,0 +1 @@
+Add support for accessing FreeSurfer via Docker wrapper along with ``mri_binarize``, ``mri_pretess``, ``mri_mc`` and ``mris_convert`` by `Synchon Mandal`_

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/docs/extending/datagrabber.rst

@@ -297,22 +297,22 @@ This approach can be used directly from the YAML, like so:
 .. code-block:: yaml
 
    datagrabber:
-     - kind: PatternDataladDataGrabber
-       types:
-         - BOLD
-         - T1w
-       patterns:
-         BOLD:
-           pattern: "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz"
-           space: MNI152NLin6Asym
-         T1w:
-           pattern: "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz"
-           space: native
-       replacements:
-         - subject
-         - session
-       uri: "https://gin.g-node.org/juaml/datalad-example-bids"
-       rootdir: example_bids_ses
+     kind: PatternDataladDataGrabber
+     types:
+       - BOLD
+       - T1w
+     patterns:
+       BOLD:
+         pattern: "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz"
+         space: MNI152NLin6Asym
+       T1w:
+         pattern: "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz"
+         space: native
+     replacements:
+       - subject
+       - session
+     uri: "https://gin.g-node.org/juaml/datalad-example-bids"
+     rootdir: example_bids_ses
 
 .. _extending_datagrabbers_base:
 
@@ -442,11 +442,11 @@ Step 4: Optional: Adding *BOLD confounds*
 -----------------------------------------
 
 For some analyses, it is useful to have the confounds associated with the BOLD
-data. This corresponds to the ``BOLD_confounds`` item in the
+data. This corresponds to the ``BOLD.confounds`` item in the
 :ref:`Data Object <data_object>` (see :ref:`data_types`). However, the
-``BOLD_confounds`` element does not only consists of a ``path``, but it requires
+``BOLD.confounds`` element does not only consists of a ``path``, but it requires
 more information about the format of the confounds file. Thus, the
-``BOLD_confounds`` element is a dictionary with the following keys:
+``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
@@ -482,15 +482,15 @@ this:
          "BOLD": {
              "path": f"{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
              "space": "MNI152NLin6Asym",
-         },
-         "BOLD_confounds": {
-             "path": f"{subject}/{session}/func/{subject}_{session}_confounds.tsv",
-             "format": "adhoc",
-             "mappings": {
-                 "fmriprep": {
-                    "variable1": "rot_x",
-                    "variable2": "rot_z",
-                    "variable3": "rot_y",
+             "confounds": {
+                 "path": f"{subject}/{session}/func/{subject}_{session}_confounds.tsv",
+                 "format": "adhoc",
+                 "mappings": {
+                     "fmriprep": {
+                        "variable1": "rot_x",
+                        "variable2": "rot_z",
+                        "variable3": "rot_y",
+                     },
                  },
              },
          },

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/docs/extending/marker.rst

@@ -114,8 +114,7 @@ arguments:
   path to the data. The dictionary can also contain other keys, depending on the
   data type.
 * ``extra_input``: the rest of the :ref:`Data Object<data_object>`. This is
-  useful if you want to use other data to compute the Marker
-  (e.g.: ``BOLD_confounds`` can be used to de-confound the ``BOLD`` data).
+  useful if you want to use other data to compute the Marker.
 
 Following the example, we will compute the mean of the data in each parcel using
 :class:`nilearn.maskers.NiftiLabelsMasker`. Importantly, the output of the

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/docs/installation.rst

@@ -163,3 +163,36 @@ Or, alternatively, you can execute this command which will update the
 .. code-block:: bash
 
   junifer setup ants-docker | grep "PATH=" | xargs | >> ~/.bashrc
+
+FreeSurfer
+----------
+
+To install FreeSurfer, you can always follow the `FreeSurfer official instructions
+<https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall>`_. Additionally, you can
+also follow the following steps to install and configure the FreeSurfer Docker container
+in your local system.
+
+1. Install Docker. You can follow the
+   `Docker official instructions <https://docs.docker.com/get-docker/>`_.
+2. Pull the FreeSurfer Docker image from
+   `Docker Hub FreeSurfer <https://hub.docker.com/r/freesurfer/freesurfer>`_:
+
+.. code-block:: bash
+
+  docker pull freesurfer/freesurfer
+
+3. Add the Junifer FreeSurfer scripts to your PATH environment variable. Run the
+   following command:
+
+.. code-block:: bash
+
+  junifer setup freesurfer-docker
+
+Take the last line and copy it to your ``.bashrc`` or ``.zshrc`` file.
+
+Or, alternatively, you can execute this command which will update the
+``~/.bashrc`` for you:
+
+.. code-block:: bash
+
+  junifer setup freesurfer-docker | grep "PATH=" | xargs | >> ~/.bashrc

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/docs/understanding/data.rst

@@ -109,9 +109,6 @@ Data Types
    * - ``BOLD``
      - BOLD image (4D)
      - Preprocessed or Denoised BOLD image (fMRIPrep output)
-   * - ``BOLD_confounds``
-     - BOLD image confounds (CSV/TSV file)
-     - Confounds that can be applied to the BOLD image.
    * - ``VBM_GM``
      - VBM Gray Matter segmentation (3D)
      - CAT output (`m0wp1` images)

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/docs/understanding/preprocess.rst

@@ -23,7 +23,7 @@ Confound Removal
 ----------------
 
 This step is meant to remove *confounds* from the ``BOLD`` data. The confounds
-are extracted from the ``BOLD_confounds`` data (must be provided by the
+are extracted from the ``BOLD.confounds`` data (must be provided by the
 :ref:`Data Grabber <datagrabber>`). The confounds are then regressed out from
 the ``BOLD`` data using :func:`nilearn.image.clean_img`.
 
@@ -36,7 +36,7 @@ Strategy
 
 This confound remover uses the `nilearn`_ API from
 :func:`nilearn.interfaces.fmriprep.load_confounds`. That is, define a *strategy*
-to extract the confounds from the ``BOLD_confounds`` data. The *strategy* is
+to extract the confounds from the ``BOLD.confounds`` data. The *strategy* is
 defined by choosing the *noise components* to be used and the *confounds* to be
 extracted from each noise components. The *noise components* currently supported
 are:

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.5.dev62'
-__version_tuple__ = version_tuple = (0, 0, 5, 'dev62')
+__version__ = version = '0.0.5.dev86'
+__version_tuple__ = version_tuple = (0, 0, 5, 'dev86')

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/api/cli.py

@@ -588,3 +588,29 @@ def ants_docker() -> None:  # pragma: no cover
     export PATH="$PATH:{ants_wrappers_path}"
     """
     click.secho(msg, fg="blue")
+
+
+@setup.command("freesurfer-docker")
+def freesurfer_docker() -> None:  # pragma: no cover
+    """Configure FreeSurfer-Docker wrappers."""
+    import junifer
+
+    pkg_path = Path(junifer.__path__[0])  # type: ignore
+    fs_wrappers_path = pkg_path / "api" / "res" / "freesurfer"
+    msg = f"""
+    Installation instructions for FreeSurfer-Docker wrappers:
+
+    1. Install Docker: https://docs.docker.com/get-docker/
+
+    2. Get the FreeSurfer-Docker image by running this on the command line:
+
+        docker pull freesurfer/freesurfer
+
+    3. Get license from: https://surfer.nmr.mgh.harvard.edu/registration.html .
+       You can skip this step if you already have one.
+
+    4. Add this line to the ~/.bashrc or ~/.zshrc file:
+
+    export PATH="$PATH:{fs_wrappers_path}"
+    """
+    click.secho(msg, fg="blue")

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/api/functions.py

@@ -362,7 +362,7 @@ def reset(config: Dict) -> None:
             shutil.rmtree(job_dir)
             # Remove parent directory (if empty)
             if not next(os.scandir(job_dir.parent), None):
-                job_dir.parent.rmdir()        
+                job_dir.parent.rmdir()
 
 
 def list_elements(

junifer-0.0.5.dev86/junifer/api/res/freesurfer/mri_binarize

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+run_freesurfer_docker.sh mri_binarize "$@"

junifer-0.0.5.dev86/junifer/api/res/freesurfer/mri_mc

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+run_freesurfer_docker.sh mri_mc "$@"

junifer-0.0.5.dev86/junifer/api/res/freesurfer/mri_pretess

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+run_freesurfer_docker.sh mri_pretess "$@"

junifer-0.0.5.dev86/junifer/api/res/freesurfer/mris_convert

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+run_freesurfer_docker.sh mris_convert "$@"

junifer-0.0.5.dev86/junifer/api/res/freesurfer/run_freesurfer_docker.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+corrected_args=()
+docker_args=()
+mounts=0
+
+FS_LICENSE="${FS_LICENSE:=$HOME/freesurfer_license.txt}"
+
+if [ -f "${FS_LICENSE}" ]; then
+    >&2 echo "Using freesurfer license from ${FS_LICENSE}"
+else
+    >&2 echo "Freesurfer license not found at ${FS_LICENSE}. You can either set FS_LICENSE to the path of the license file or place the license file at
+${FS_LICENSE}"
+    exit 1
+fi
+
+# Map the license path to the container by binding
+license_path=$(realpath "${FS_LICENSE}")
+license_path_fname=$(basename "${FS_LICENSE}")
+host_dir=$(dirname "${license_path}")
+((mounts+=1))
+container_dir="/data/mount_${mounts}"
+docker_args+=("-v ${host_dir}:${container_dir}")
+export DOCKERENV_FS_LICENSE=${container_dir}/${license_path_fname}
+
+for var in "$@"
+do
+if [ -d "${var}" ]; then
+        echo "$var is a directory" >&2
+        var=$(realpath "${var}")
+        host_dir=$(dirname "${var}")
+        ((mounts+=1))
+        container_dir="/data/mount_${mounts}"
+        docker_args+=("-v ${host_dir}:${container_dir}")
+        var=${container_dir}
+    elif [ -f "${var}" ] || [[ "${var}" == /* ]]; then
+        if [ -f "${var}" ]; then
+            echo "$var is a file" >&2
+            var=$(realpath "${var}")
+        else
+            echo "$var is a prefix" >&2
+        fi
+        fname=$(basename "${var}")
+        host_dir=$(dirname "${var}")
+        ((mounts+=1))
+        container_dir="/data/mount_${mounts}"
+        docker_args+=("-v ${host_dir}:${container_dir}")
+        var=${container_dir}/${fname}
+    fi
+    corrected_args+=("${var}")
+done
+
+echo "Docker args: ${docker_args[*]}" >&2
+echo "Corrected args for FreeSurfer: ${corrected_args[*]}" >&2
+
+cwd=$(pwd)
+cmd="docker run --rm ${docker_args[*]} -v ${cwd}:${cwd} -w ${cwd} freesurfer/freesurfer ${corrected_args[*]}"
+echo "Running command: ${cmd}" >&2
+${cmd}
+
+unset DOCKERENV_FS_LICENSE

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/configs/juseless/datagrabbers/tests/test_ucla.py

@@ -27,7 +27,6 @@ def test_JuselessUCLA() -> None:
 
         types = [
             "BOLD",
-            "BOLD_confounds",
             "T1w",
             "VBM_CSF",
             "VBM_GM",
@@ -43,12 +42,11 @@ def test_JuselessUCLA() -> None:
     "types",
     [
         "BOLD",
-        "BOLD_confounds",
         "T1w",
         "VBM_CSF",
         "VBM_GM",
         "VBM_WM",
-        ["BOLD", "BOLD_confounds"],
+        ["BOLD", "VBM_CSF"],
         ["T1w", "VBM_CSF"],
         ["VBM_GM", "VBM_WM"],
         ["BOLD", "T1w"],

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/configs/juseless/datagrabbers/ucla.py

@@ -23,8 +23,8 @@ class JuselessUCLA(PatternDataGrabber):
     datadir : str or Path, optional
         The directory where the dataset is stored.
         (default "/data/project/psychosis_thalamus/data/fmriprep").
-    types: {"BOLD", "BOLD_confounds", "T1w", "VBM_CSF", "VBM_GM", \
-           "VBM_WM"} or a list of the options, optional
+    types: {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM"} or \
+           list of the options, optional
         UCLA data types. If None, all available data types are selected.
         (default None).
     tasks : {"rest", "bart", "bht", "pamenc", "pamret", \
@@ -76,13 +76,13 @@ class JuselessUCLA(PatternDataGrabber):
                     "MNI152NLin2009cAsym_preproc.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-            },
-            "BOLD_confounds": {
-                "pattern": (
-                    "{subject}/func/{subject}_"
-                    "task-{task}_bold_confounds.tsv"
-                ),
-                "space": "fmriprep",
+                "confounds": {
+                    "pattern": (
+                        "{subject}/func/{subject}_"
+                        "task-{task}_bold_confounds.tsv"
+                    ),
+                    "space": "fmriprep",
+                },
             },
             "T1w": {
                 "pattern": (

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/data/masks.py

@@ -250,8 +250,8 @@ def get_mask(  # noqa: C901
     ValueError
         If extra key is provided in addition to mask name in ``masks`` or
         if no mask is provided or
-        if ``masks = "inherit"`` but ``extra_input`` is None or ``mask_item``
-        is None or ``mask_items``'s value is not in ``extra_input`` or
+        if ``masks = "inherit"`` and ``mask`` key for the ``target_data`` is
+        not found or
         if callable parameters are passed to non-callable mask or
         if parameters are passed to :func:`nilearn.masking.intersect_masks`
         when there is only one mask or
@@ -310,8 +310,8 @@ def get_mask(  # noqa: C901
     if len(true_masks) == 0:
         raise_error("No mask was passed. At least one mask is required.")
 
-    # Get the data type for the input data type's mask
-    inherited_mask_item = target_data.get("mask_item", None)
+    # Get the nested mask data type for the input data type
+    inherited_mask_item = target_data.get("mask", None)
 
     # Create component-scoped tempdir
     tempdir = WorkDirManager().get_tempdir(prefix="masks")
@@ -330,28 +330,16 @@ def get_mask(  # noqa: C901
             mask_name = t_mask
             mask_params = None
 
-        # If mask is being inherited from previous steps like preprocessing
+        # If mask is being inherited from the datagrabber or a preprocessor,
+        # check that it's accessible
         if mask_name == "inherit":
-            # Requires extra input to be passed
-            if extra_input is None:
-                raise_error(
-                    "Cannot inherit mask from another data item "
-                    "because no extra data was passed."
-                )
-            # Missing inherited mask item
             if inherited_mask_item is None:
                 raise_error(
-                    "Cannot inherit mask from another data item "
-                    "because no mask item was specified "
-                    "(missing `mask_item` key in the data object)."
-                )
-            # Missing inherited mask item in extra input
-            if inherited_mask_item not in extra_input:
-                raise_error(
-                    "Cannot inherit mask from another data item "
-                    f"because the item ({inherited_mask_item}) does not exist."
+                    "Cannot inherit mask from the target data. Either the "
+                    "DataGrabber or a Preprocessor does not provide `mask` "
+                    "for the target data type."
                 )
-            mask_img = extra_input[inherited_mask_item]["data"]
+            mask_img = inherited_mask_item["data"]
         # Starting with new mask
         else:
             # Load mask

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/data/parcellations.py

@@ -889,7 +889,7 @@ def _retrieve_tian(
         )
         with open(parcellation_lname, "w") as filehandle:
             for listitem in labels:
-                filehandle.write("%s\n" % listitem)
+                filehandle.write(f"{listitem}\n")
         logger.info(
             "Currently there are no labels provided for the 7T Tian "
             "parcellation. A simple numbering scheme for distinction was "

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/data/tests/test_masks.py

@@ -365,27 +365,10 @@ def test_get_mask_errors() -> None:
                 target_data=vbm_gm,
             )
 
-        # Test "inherited" masks errors
-
-        # 1) No extra_data parameter
-        with pytest.raises(ValueError, match=r"no extra data was passed"):
+        # Test "inherited" masks error
+        with pytest.raises(ValueError, match=r"provide `mask`"):
             get_mask(masks="inherit", target_data=vbm_gm)
 
-        extra_input = {"VBM_MASK": {}}
-
-        # 2) No mask_item key in target_data
-        with pytest.raises(ValueError, match=r"no mask item was specified"):
-            get_mask(
-                masks="inherit", target_data=vbm_gm, extra_input=extra_input
-            )
-
-        # 3) mask_item not in extra data
-        with pytest.raises(ValueError, match=r"does not exist"):
-            vbm_gm["mask_item"] = "wrong"
-            get_mask(
-                masks="inherit", target_data=vbm_gm, extra_input=extra_input
-            )
-
 
 @pytest.mark.parametrize(
     "mask_name,function,params,resample",
@@ -457,18 +440,15 @@ def test_get_mask_inherit() -> None:
         )
 
         # Now get the mask using the inherit functionality, passing the
-        # computed mask as extra data
-        extra_input = {
-            "BOLD_MASK": {
-                "data": gm_mask,
-                "space": element_data["BOLD"]["space"],
-            }
+        # computed mask as the data
+        bold_dict = element_data["BOLD"]
+        bold_dict["mask"] = {
+            "data": gm_mask,
+            "space": element_data["BOLD"]["space"],
         }
-        element_data["BOLD"]["mask_item"] = "BOLD_MASK"
         mask2 = get_mask(
             masks="inherit",
-            target_data=element_data["BOLD"],
-            extra_input=extra_input,
+            target_data=bold_dict,
         )
 
         # Both masks should be equal

{junifer-0.0.5.dev62 → junifer-0.0.5.dev86}/junifer/datagrabber/aomic/id1000.py

@@ -24,9 +24,8 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
         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", "BOLD_confounds", "BOLD_mask", "T1w", "T1w_mask", \
-           "VBM_CSF", "VBM_GM", "VBM_WM", "DWI"} or \
-           a list of the options, optional
+    types: {"BOLD", "T1w", "VBM_CSF", "VBM_GM", "VBM_WM", "DWI"} or \
+           list of the options, optional
         AOMIC data types. If None, all available data types are selected.
         (default None).
     native_t1w : bool, optional
@@ -49,24 +48,23 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "mask_item": "BOLD_mask",
-            },
-            "BOLD_confounds": {
-                "pattern": (
-                    "derivatives/fmriprep/{subject}/func/"
-                    "{subject}_task-moviewatching_"
-                    "desc-confounds_regressors.tsv"
-                ),
-                "format": "fmriprep",
-            },
-            "BOLD_mask": {
-                "pattern": (
-                    "derivatives/fmriprep/{subject}/func/"
-                    "{subject}_task-moviewatching_"
-                    "space-MNI152NLin2009cAsym_"
-                    "desc-brain_mask.nii.gz"
-                ),
-                "space": "MNI152NLin2009cAsym",
+                "mask": {
+                    "pattern": (
+                        "derivatives/fmriprep/{subject}/func/"
+                        "{subject}_task-moviewatching_"
+                        "space-MNI152NLin2009cAsym_"
+                        "desc-brain_mask.nii.gz"
+                    ),
+                    "space": "MNI152NLin2009cAsym",
+                },
+                "confounds": {
+                    "pattern": (
+                        "derivatives/fmriprep/{subject}/func/"
+                        "{subject}_task-moviewatching_"
+                        "desc-confounds_regressors.tsv"
+                    ),
+                    "format": "fmriprep",
+                },
             },
             "T1w": {
                 "pattern": (
@@ -75,15 +73,14 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                     "desc-preproc_T1w.nii.gz"
                 ),
                 "space": "MNI152NLin2009cAsym",
-                "mask_item": "T1w_mask",
-            },
-            "T1w_mask": {
-                "pattern": (
-                    "derivatives/fmriprep/{subject}/anat/"
-                    "{subject}_space-MNI152NLin2009cAsym_"
-                    "desc-brain_mask.nii.gz"
-                ),
-                "space": "MNI152NLin2009cAsym",
+                "mask": {
+                    "pattern": (
+                        "derivatives/fmriprep/{subject}/anat/"
+                        "{subject}_space-MNI152NLin2009cAsym_"
+                        "desc-brain_mask.nii.gz"
+                    ),
+                    "space": "MNI152NLin2009cAsym",
+                },
             },
             "VBM_CSF": {
                 "pattern": (
@@ -128,14 +125,13 @@ class DataladAOMICID1000(PatternDataladDataGrabber):
                             "{subject}_desc-preproc_T1w.nii.gz"
                         ),
                         "space": "native",
-                        "mask_item": "T1w_mask",
-                    },
-                    "T1w_mask": {
-                        "pattern": (
-                            "derivatives/fmriprep/{subject}/anat/"
-                            "{subject}_desc-brain_mask.nii.gz"
-                        ),
-                        "space": "native",
+                        "mask": {
+                            "pattern": (
+                                "derivatives/fmriprep/{subject}/anat/"
+                                "{subject}_desc-brain_mask.nii.gz"
+                            ),
+                            "space": "native",
+                        },
                     },
                     "Warp": {
                         "pattern": (