Repository: nilearn/nilearn

Issue:
[ENH] the compcor option for `load_confound_strategy` should allow overall global signal regressor
### Is there an existing issue for this?

- [X] I have searched the existing issues

### Describe your proposed enhancement in detail.

This is change will be more inline with the fmriprep recommendation: 
![image](https://github.com/nilearn/nilearn/assets/13743617/1f108821-e299-4462-9fdb-63987b2a11de)


### Benefits to the change

allow user to use the gsr option when using the default. 
This will not effect people who wish to use the bare bone `load_confounds`.

### Pseudocode for the new behavior, if applicable

Change from
```python
"compcor": {
    "strategy": ("high_pass", "motion", "compcor"),
    "motion": "full",
    "n_compcor": "all",
    "compcor": "anat_combined",
    "demean": True,
},
```
to
```python
"compcor": {
    "strategy": ("high_pass", "motion", "compcor"),
    "motion": "full",
    "n_compcor": "all",
    "compcor": "anat_combined",
    "global_signal": None,
    "demean": True,
},
```



Discussion:
I can address this with #4222 in one PR
Good with me. Note that we cut a release versy soon.

Resolving patch:
diff --git a/examples/03_connectivity/plot_signal_extraction.py b/examples/03_connectivity/plot_signal_extraction.py
--- a/examples/03_connectivity/plot_signal_extraction.py
+++ b/examples/03_connectivity/plot_signal_extraction.py
@@ -187,8 +187,8 @@
     motion="basic",
     wm_csf="basic",
     scrub=5,
-    fd_threshold=0.2,
-    std_dvars_threshold=3,
+    fd_threshold=0.5,
+    std_dvars_threshold=1.5,
 )
 
 print(
diff --git a/nilearn/interfaces/fmriprep/load_confounds.py b/nilearn/interfaces/fmriprep/load_confounds.py
--- a/nilearn/interfaces/fmriprep/load_confounds.py
+++ b/nilearn/interfaces/fmriprep/load_confounds.py
@@ -206,10 +206,19 @@ def load_confounds(
         DVARS only.
 
     fd_threshold : :obj:`float`, default=0.2
+
+        .. deprecated:: 0.11.0
+           The default value will be changed to 0.5 in 0.13.0
+
         Framewise displacement threshold for scrub in mm.
 
     std_dvars_threshold : :obj:`float`, default=3
+
+        .. deprecated:: 0.11.0
+           The default value will be changed to 1.5 in 0.13.0
+
         Standardized DVARS threshold for scrub.
+        The default threshold matching :term:`fMRIPrep`.
         DVARs is defined as root mean squared intensity difference of volume N
         to volume N+1 :footcite:t:`Power2012`.
         D referring to temporal derivative of timecourses,
@@ -295,7 +304,30 @@ def load_confounds(
 
     """
     _check_strategy(strategy)
-
+    if "scrub" in strategy and fd_threshold == 0.2:
+        fd_threshold_default = (
+            "The default parameter for fd_threshold is currently 0.2 "
+            "which is inconsistent with the fMRIPrep default of 0.5. "
+            "In release 0.13.0, "
+            "the default strategy will be replaced by 0.5."
+        )
+        warnings.warn(
+            category=DeprecationWarning,
+            message=fd_threshold_default,
+            stacklevel=2,
+        )
+    if "scrub" in strategy and std_dvars_threshold == 3:
+        std_dvars_threshold_default = (
+            "The default parameter for std_dvars_threshold is currently 3 "
+            "which is inconsistent with the fMRIPrep default of 1.5. "
+            "In release 0.13.0, "
+            "the default strategy will be replaced by 1.5."
+        )
+        warnings.warn(
+            category=DeprecationWarning,
+            message=std_dvars_threshold_default,
+            stacklevel=2,
+        )
     # load confounds per image provided
     img_files, flag_single = sanitize_confounds(img_files)
     confounds_out = []
diff --git a/nilearn/interfaces/fmriprep/load_confounds_strategy.py b/nilearn/interfaces/fmriprep/load_confounds_strategy.py
--- a/nilearn/interfaces/fmriprep/load_confounds_strategy.py
+++ b/nilearn/interfaces/fmriprep/load_confounds_strategy.py
@@ -27,8 +27,8 @@
         "motion": "full",
         "wm_csf": "full",
         "scrub": 5,
-        "fd_threshold": 0.2,
-        "std_dvars_threshold": 3,
+        "fd_threshold": 0.2,  # updated here and doc to 0.5 in v0.13
+        "std_dvars_threshold": 3,  # updated here and doc to 1.5 in v0.13
         "global_signal": None,
         "demean": True,
     },
@@ -37,6 +37,7 @@
         "motion": "full",
         "n_compcor": "all",
         "compcor": "anat_combined",
+        "global_signal": None,
         "demean": True,
     },
     "ica_aroma": {
@@ -101,6 +102,10 @@ def load_confounds_strategy(img_files, denoise_strategy="simple", **kwargs):
           variance as the noise component estimation as the number of compcor
           component can be really high. Please refer to :term:`fMRIPrep`
           documentation for more details.
+
+          .. versionadded:: 0.11.0
+            `golobal_signal` is now a tunable parameter for compcor.
+
         - 'ica_aroma': Load confounds for non-aggresive ICA-AROMA strategy
           described in :footcite:t:`Pruim2015`. The strategy requires
           :term:`fMRIPrep` outputs generated with `--use-aroma` suffixed with
@@ -152,7 +157,7 @@ def load_confounds_strategy(img_files, denoise_strategy="simple", **kwargs):
         N/A                 N/A            N/A       N/A       True*
         scrubbing True      full*  full   None*         5*    0.2*         \
         3*                  N/A            N/A       N/A       True*
-        compcor   True      full*  N/A    N/A           N/A   N/A          \
+        compcor   True      full*  N/A    None*         N/A   N/A          \
         N/A                 anat_combined* all*      N/A       True*
         ica_aroma True      N/A    basic* None*         N/A   N/A          \
         N/A                 N/A            N/A       full      True*


Test patch:
diff --git a/nilearn/interfaces/fmriprep/tests/test_load_confounds_strategy.py b/nilearn/interfaces/fmriprep/tests/test_load_confounds_strategy.py
--- a/nilearn/interfaces/fmriprep/tests/test_load_confounds_strategy.py
+++ b/nilearn/interfaces/fmriprep/tests/test_load_confounds_strategy.py
@@ -166,6 +166,14 @@ def test_strategy_compcor(tmp_path, fmriprep_version):
         "a_comp_cor_57" if fmriprep_version == "1.4.x" else "w_comp_cor_00"
     )
     assert expected not in compcor_col_str_anat
+    assert "global_signal" not in compcor_col_str_anat
+
+    # test the global signal option
+    confounds, _ = load_confounds_strategy(
+        file_nii, denoise_strategy="compcor", global_signal="basic"
+    )
+    compcor_col_str_anat = "".join(confounds.columns)
+    assert "global_signal" in compcor_col_str_anat
 
 
 @pytest.mark.parametrize("fmriprep_version", ["1.4.x", "21.x.x"])