[NF] migrate package load_confounds main function load_confounds

examples/03_connectivity/plot_signal_extraction.py

@@ -79,7 +79,7 @@
 
 ##############################################################################
 # Extract signals and compute a connectivity matrix without confounds removal
-# -------------------------------------------------------------------
+# ---------------------------------------------------------------------------
 # After covering the basic of signal extraction and functional connectivity
 # matrix presentation, let's look into the impact of confounds to :term:`fMRI`
 # signal and functional connectivity. Firstly let's find out what a functional

nilearn/_utils/fmriprep_confounds.py

@@ -1,6 +1,6 @@
-""" Misc utilities for the library.
+""" Misc utilities for function nilearn.input_data.fmriprep_confounds.
 
-Authors: load_confounds team
+Author: Hao-Ting Wang
 """
 
 

nilearn/input_data/fmriprep_confounds.py

@@ -1,6 +1,7 @@
 """Flexible method to load confounds generated by fMRIprep.
 
-Authors: load_confounds team
+Authors: Pierre Bellec, François Paugam, Hanad Sharmarke, Hao-Ting Wang,
+Michael W. Weiss, Steven Meisler, Thibault Piront.
 """
 import pandas as pd
 from .fmriprep_confounds_utils import (_sanitize_confounds, _confounds_to_df,
@@ -62,7 +63,7 @@ def _check_error(missing):
 def fmriprep_confounds(img_files,
                        strategy=["motion", "high_pass", "wm_csf"],
                        motion="full",
-                       scrub="full", fd_thresh=0.2, std_dvars_thresh=3,
+                       scrub=5, fd_thresh=0.2, std_dvars_thresh=3,
                        wm_csf="basic",
                        global_signal="basic",
                        compcor="anat_combined", n_compcor="all",
@@ -149,16 +150,13 @@ def fmriprep_confounds(img_files,
         - "full" global signal + derivatives + quadratic terms + power2d
           derivatives (4 parameters)
 
-    scrub : {'full', 'basic'}
-        Type of scrub of frames with excessive motion :footcite:`Power2014`
-
-        - "basic" remove time frames based on excessive framewise displacement
-          and DVARS.
-        - "full" also remove continuous segments containing fewer than 5
-          volumes.
-
-        One-hot encoding vectors are added as regressors for each scrubbed
-        frame.
+    scrub : int, default 5
+        After accounting for time frames with excessive motion, further remove
+        segments shorter than the given number. The default value is 5
+        (referred as full scrubbing in :footcite:`Power2014`). When the value
+        is 0, temove time frames based on excessive framewise displacement and
+        DVARS only. One-hot encoding vectors are added as regressors for each
+        scrubbed frame.
 
     compcor : {'anat_combined', 'anat_separated', 'temporal',\
     'temporal_anat_combined', 'temporal_anat_separated'}

nilearn/input_data/fmriprep_confounds_components.py

@@ -75,9 +75,11 @@ def _load_scrub(confounds_raw, scrub, fd_thresh, std_dvars_thresh):
     motion_outliers_index = np.sort(
         np.unique(np.concatenate((fd_outliers_index, dvars_outliers_index)))
     )
-    # Do full scrubbing if desired, and motion outliers were detected
-    if scrub == "full" and len(motion_outliers_index) > 0:
-        motion_outliers_index = _optimize_scrub(motion_outliers_index, n_scans)
+    # when motion outliers were detected, remove segments with too few
+    # timeframes if desired
+    if scrub > 0 and len(motion_outliers_index) > 0:
+        motion_outliers_index = _optimize_scrub(motion_outliers_index, n_scans,
+                                                scrub)
     # Make one-hot encoded motion outlier regressors
     motion_outlier_regressors = pd.DataFrame(
         np.transpose(np.eye(n_scans)[motion_outliers_index]).astype(int)

nilearn/input_data/fmriprep_confounds_scrub.py

@@ -3,25 +3,25 @@
 import pandas as pd
 
 
-def _optimize_scrub(motion_outliers_index, n_scans):
-    """Remove continuous segments containing fewer than 5 volumes."""
+def _optimize_scrub(motion_outliers_index, n_scans, scrub=5):
+    """Remove continuous segments with fewer than a minimal segment length."""
     # Start by checking if the beginning continuous segment is fewer than
-    # 5 volumes
-    if motion_outliers_index[0] < 5:
+    # a minimal segment length (default to 5)
+    if motion_outliers_index[0] < scrub:
         motion_outliers_index = np.asarray(
             list(range(motion_outliers_index[0])) + list(motion_outliers_index)
         )
     # Do the same for the ending segment of scans
-    if n_scans - (motion_outliers_index[-1] + 1) < 5:
+    if n_scans - (motion_outliers_index[-1] + 1) < scrub:
         motion_outliers_index = np.asarray(
             list(motion_outliers_index)
             + list(range(motion_outliers_index[-1], n_scans))
         )
     # Now do everything in between
     fd_outlier_ind_diffs = np.diff(motion_outliers_index)
     short_segments_inds = np.where(
-        np.logical_and(fd_outlier_ind_diffs > 1, fd_outlier_ind_diffs < 6)
-    )[0]
+        np.logical_and(fd_outlier_ind_diffs > 1,
+                       fd_outlier_ind_diffs < (scrub + 1)))[0]
     for ind in short_segments_inds:
         motion_outliers_index = np.asarray(
             list(motion_outliers_index)

nilearn/input_data/fmriprep_confounds_utils.py

@@ -1,7 +1,4 @@
-"""Helper functions for the manipulation of fmriprep output confounds.
-
-Authors: load_confounds team
-"""
+"""Helper functions for the manipulation of fmriprep output confounds."""
 import numpy as np
 import pandas as pd
 from sklearn.preprocessing import scale

nilearn/input_data/tests/test_fmriprep_confounds.py

@@ -483,11 +483,12 @@ def test_sample_mask(tmp_path):
     )
 
     reg, mask = fmriprep_confounds(
-        regular_nii, strategy=["motion", "scrub"], scrub="full", fd_thresh=0.15
+        regular_nii, strategy=["motion", "scrub"], scrub=5, fd_thresh=0.15
     )
     # the current test data has 6 time points marked as motion outliers,
     # and one nonsteady state (overlap with the first motion outlier)
-    # 2 time points removed due to the "full" srubbing strategy
+    # 2 time points removed due to the "full" srubbing strategy (remove segment
+    # shorter than 5 volumes)
     assert reg.shape[0] - len(mask) == 8
     # nilearn requires unmasked confound regressors
     assert reg.shape[0] == 30
@@ -504,7 +505,7 @@ def test_sample_mask(tmp_path):
 
     # When no volumes needs removing (very liberal motion threshould)
     reg, mask = fmriprep_confounds(
-        regular_nii, strategy=["motion", "scrub"], scrub="basic", fd_thresh=4
+        regular_nii, strategy=["motion", "scrub"], scrub=0, fd_thresh=4
     )
     assert mask is None