Restructure XCP-D to better match fMRIPrep (PennLINC#1225)

docs/workflows.rst

@@ -245,7 +245,7 @@ See :ref:`usage_inputs` for information on input dataset structures.
 
 Anatomical processing
 =====================
-:func:`~xcp_d.workflows.anatomical.init_postprocess_anat_wf`
+:func:`~xcp_d.workflows.anatomical.volume.init_postprocess_anat_wf`
 
 XCP-D performs minimal postprocessing on anatomical derivatives from the preprocessing pipeline.
 This includes applying existing transforms to preprocessed T1w and T2w volumes,
@@ -255,7 +255,7 @@ while retaining the original resolution.
 
 Surface normalization
 ---------------------
-:func:`~xcp_d.workflows.anatomical.init_warp_surfaces_to_template_wf`
+:func:`~xcp_d.workflows.anatomical.surface.init_warp_surfaces_to_template_wf`
 
 If the ``--warp-surfaces-native2std`` flag is used,
 then fsnative surface files from the preprocessing derivatives will be warped to fsLR-32k space.
@@ -267,7 +267,7 @@ then fsnative surface files from the preprocessing derivatives will be warped to
 
 Identification of high-motion outlier volumes
 =============================================
-:func:`~xcp_d.workflows.postprocessing.init_prepare_confounds_wf`,
+:func:`~xcp_d.workflows.bold.postprocessing.init_prepare_confounds_wf`,
 :class:`~xcp_d.interfaces.censoring.GenerateConfounds`
 
 XCP-D uses framewise displacement to identify high-motion outlier volumes.
@@ -282,7 +282,7 @@ The threshold used to identify outlier volumes can be set with the ``--fd-thresh
 
 Motion parameter filtering [OPTIONAL]
 -------------------------------------
-:func:`~xcp_d.workflows.postprocessing.init_prepare_confounds_wf`,
+:func:`~xcp_d.workflows.bold.postprocessing.init_prepare_confounds_wf`,
 :class:`~xcp_d.interfaces.censoring.GenerateConfounds`,
 :func:`~xcp_d.utils.confounds.load_motion`
 
@@ -336,7 +336,7 @@ per :footcite:t:`gratton2020removal`.
 
 Framewise displacement calculation and thresholding
 ---------------------------------------------------
-:func:`~xcp_d.workflows.postprocessing.init_prepare_confounds_wf`,
+:func:`~xcp_d.workflows.bold.postprocessing.init_prepare_confounds_wf`,
 :class:`~xcp_d.interfaces.censoring.GenerateConfounds`,
 :func:`~xcp_d.utils.modified_data.compute_fd`
 
@@ -357,7 +357,7 @@ These volumes will later be removed from the denoised data.
 
 Confound regressor selection
 ============================
-:func:`~xcp_d.workflows.postprocessing.init_prepare_confounds_wf`,
+:func:`~xcp_d.workflows.bold.postprocessing.init_prepare_confounds_wf`,
 :func:`~xcp_d.interfaces.censoring.GenerateConfounds`
 
 The confound regressor configurations in the table below are implemented in XCP-D,
@@ -533,7 +533,7 @@ For more information about confound regressor selection, please refer to :footci
 
 Dummy scan removal [OPTIONAL]
 =============================
-:func:`~xcp_d.workflows.postprocessing.init_prepare_confounds_wf`,
+:func:`~xcp_d.workflows.bold.postprocessing.init_prepare_confounds_wf`,
 :class:`~xcp_d.interfaces.censoring.RemoveDummyVolumes`
 
 XCP-D allows the first *N* volumes to be removed before processing.
@@ -548,7 +548,7 @@ or they may rely on the preprocessing pipeline's estimated non-steady-state volu
 
 Despiking [OPTIONAL]
 ====================
-:func:`~xcp_d.workflows.postprocessing.init_despike_wf`
+:func:`~xcp_d.workflows.bold.postprocessing.init_despike_wf`
 
 Despiking is a process in which large spikes in the BOLD times series are truncated.
 Despiking reduces/limits the amplitude or magnitude of the large spikes but preserves those
@@ -697,7 +697,7 @@ These include regional homogeneity (ReHo) and amplitude of low-frequency fluctua
 
 ALFF
 ----
-:func:`~xcp_d.workflows.restingstate.init_alff_wf`
+:func:`~xcp_d.workflows.bold.metrics.init_alff_wf`
 
 Amplitude of low-frequency fluctuation (ALFF) is a measure that ostensibly localizes
 spontaneous neural activity in resting-state BOLD data.
@@ -730,8 +730,8 @@ Smoothed ALFF derivatives will also be generated if the ``--smoothing`` flag is
 
 ReHo
 ----
-:func:`~xcp_d.workflows.restingstate.init_reho_nifti_wf`,
-:func:`~xcp_d.workflows.restingstate.init_reho_cifti_wf`
+:func:`~xcp_d.workflows.bold.metrics.init_reho_nifti_wf`,
+:func:`~xcp_d.workflows.bold.metrics.init_reho_cifti_wf`
 
 Regional Homogeneity (ReHo) is a measure of local temporal uniformity in the BOLD signal computed at each voxel of the processed image.
 Greater ReHo values correspond to greater synchrony among BOLD activity patterns measured in a local neighborhood of voxels, with neighborhood size determined by a user-specified radius of voxels.
@@ -744,8 +744,8 @@ For subcortical voxels in the CIFTIs, 3dReho is used with the same parameters th
 
 Parcellation and functional connectivity estimation [OPTIONAL]
 ==============================================================
-:func:`~xcp_d.workflows.connectivity.init_functional_connectivity_nifti_wf`,
-:func:`~xcp_d.workflows.connectivity.init_functional_connectivity_cifti_wf`
+:func:`~xcp_d.workflows.bold.connectivity.init_functional_connectivity_nifti_wf`,
+:func:`~xcp_d.workflows.bold.connectivity.init_functional_connectivity_cifti_wf`
 
 If the user chooses,
 the ``denoised BOLD`` is fed into a functional connectivity workflow,
@@ -790,15 +790,15 @@ which improves reproducibility.
 
 Smoothing [OPTIONAL]
 ====================
-:func:`~xcp_d.workflows.postprocessing.init_resd_smoothing_wf`
+:func:`~xcp_d.workflows.bold.postprocessing.init_resd_smoothing_wf`
 
 The ``denoised BOLD`` may optionally be smoothed with a Gaussian kernel.
 This smoothing kernel is set with the ``--smoothing`` parameter.
 
 
 Concatenation of functional derivatives [OPTIONAL]
 ==================================================
-:func:`~xcp_d.workflows.concatenation.init_concatenate_data_wf`
+:func:`~xcp_d.workflows.bold.concatenation.init_concatenate_data_wf`
 
 If the ``--combine-runs`` flag is included, then BOLD runs will be grouped by task and concatenated.
 Several concatenated derivatives will be generated, including the ``denoised BOLD``,
@@ -816,7 +816,7 @@ the ``denoised, interpolated BOLD``, the temporal mask, and the filtered motion
 
 Quality control
 ===============
-:func:`~xcp_d.workflows.plotting.init_qc_report_wf`
+:func:`~xcp_d.workflows.bold.plotting.init_qc_report_wf`
 
 The quality control (QC) in ``XCP-D`` estimates the quality of BOLD data before and after
 regression and also estimates BOLD-T1w coregistration and BOLD-Template normalization

xcp_d/tests/test_workflows_anatomical.py

@@ -1,4 +1,4 @@
-"""Tests for the xcp_d.workflows.anatomical module."""
+"""Tests for the xcp_d.workflows.anatomical.surface module."""
 
 import os
 import shutil
@@ -66,7 +66,7 @@ def test_warp_surfaces_to_template_wf(
     """
     tmpdir = tmp_path_factory.mktemp("test_warp_surfaces_to_template_wf")
 
-    wf = anatomical.init_warp_surfaces_to_template_wf(
+    wf = anatomical.surface.init_warp_surfaces_to_template_wf(
         output_dir=tmpdir,
         software="FreeSurfer",
         omp_nthreads=1,
@@ -95,7 +95,7 @@ def test_warp_surfaces_to_template_wf(
 
 
 def test_postprocess_anat_wf(ds001419_data, tmp_path_factory):
-    """Test xcp_d.workflows.anatomical.init_postprocess_anat_wf."""
+    """Test xcp_d.workflows.anatomical.volume.init_postprocess_anat_wf."""
     tmpdir = tmp_path_factory.mktemp("test_postprocess_anat_wf")
 
     anat_to_template_xfm = ds001419_data["anat_to_template_xfm"]
@@ -110,7 +110,7 @@ def test_postprocess_anat_wf(ds001419_data, tmp_path_factory):
         config.nipype.omp_nthreads = 1
         config.nipype.mem_gb = 0.1
 
-        wf = anatomical.init_postprocess_anat_wf(
+        wf = anatomical.volume.init_postprocess_anat_wf(
             t1w_available=True,
             t2w_available=True,
             target_space="MNI152NLin2009cAsym",

xcp_d/tests/test_workflows_connectivity.py

@@ -17,11 +17,11 @@
 from xcp_d.utils.bids import _get_tr
 from xcp_d.utils.utils import _create_mem_gb, get_std2bold_xfms
 from xcp_d.utils.write_save import read_ndata, write_ndata
-from xcp_d.workflows.connectivity import (
+from xcp_d.workflows.bold.connectivity import (
     init_functional_connectivity_cifti_wf,
     init_functional_connectivity_nifti_wf,
-    init_load_atlases_wf,
 )
+from xcp_d.workflows.parcellation import init_load_atlases_wf
 
 np.set_printoptions(threshold=sys.maxsize)
 

xcp_d/tests/test_workflows_restingstate.py → xcp_d/tests/test_workflows_metrics.py

@@ -12,7 +12,7 @@
 from xcp_d.utils.bids import _get_tr
 from xcp_d.utils.utils import _create_mem_gb
 from xcp_d.utils.write_save import read_ndata, write_ndata
-from xcp_d.workflows import restingstate
+from xcp_d.workflows.bold import metrics
 
 
 def test_nifti_alff(ds001419_data, tmp_path_factory):
@@ -41,7 +41,7 @@ def test_nifti_alff(ds001419_data, tmp_path_factory):
         config.workflow.smoothing = 6
         config.nipype.omp_nthreads = 2
 
-        alff_wf = restingstate.init_alff_wf(
+        alff_wf = metrics.init_alff_wf(
             name_source=bold_file,
             TR=TR,
             mem_gb=mem_gbx,
@@ -84,7 +84,7 @@ def test_nifti_alff(ds001419_data, tmp_path_factory):
         # the amplitude in low frequencies for a voxel
         tempdir = tmp_path_factory.mktemp("test_nifti_alff_02")
 
-        alff_wf = restingstate.init_alff_wf(
+        alff_wf = metrics.init_alff_wf(
             name_source=bold_file,
             TR=TR,
             mem_gb=mem_gbx,
@@ -128,7 +128,7 @@ def test_cifti_alff(ds001419_data, tmp_path_factory):
         config.workflow.smoothing = 6
         config.nipype.omp_nthreads = 2
 
-        alff_wf = restingstate.init_alff_wf(
+        alff_wf = metrics.init_alff_wf(
             name_source=bold_file,
             TR=TR,
             mem_gb=mem_gbx,
@@ -216,7 +216,7 @@ def test_nifti_reho(ds001419_data, tmp_path_factory):
         config.execution.xcp_d_dir = tempdir
         config.nipype.omp_nthreads = 2
 
-        reho_wf = restingstate.init_reho_nifti_wf(name_source=bold_file, mem_gb=mem_gbx)
+        reho_wf = metrics.init_reho_nifti_wf(name_source=bold_file, mem_gb=mem_gbx)
         reho_wf.inputs.inputnode.bold_mask = bold_mask
         reho_wf.base_dir = tempdir
         reho_wf.inputs.inputnode.denoised_bold = bold_file
@@ -272,7 +272,7 @@ def test_cifti_reho(ds001419_data, tmp_path_factory):
         config.execution.xcp_d_dir = tempdir
         config.nipype.omp_nthreads = 2
 
-        reho_wf = restingstate.init_reho_cifti_wf(
+        reho_wf = metrics.init_reho_cifti_wf(
             name_source=source_file,
             mem_gb=mem_gbx,
             name="orig_reho_wf",
@@ -296,7 +296,7 @@ def test_cifti_reho(ds001419_data, tmp_path_factory):
         # Run ReHo again
         assert os.path.isfile(noisy_bold_file)
 
-        reho_wf = restingstate.init_reho_cifti_wf(
+        reho_wf = metrics.init_reho_cifti_wf(
             name_source=source_file,
             mem_gb=mem_gbx,
             name="noisy_reho_wf",

xcp_d/tests/test_workflows_execsummary.py → xcp_d/tests/test_workflows_plotting.py

@@ -1,11 +1,11 @@
-"""Test xcp_d.workflows.execsummary."""
+"""Test xcp_d.workflows.plotting."""
 
 import os
 
 from nilearn import image
 
 from xcp_d.tests.utils import get_nodes
-from xcp_d.workflows import execsummary
+from xcp_d.workflows import plotting
 
 
 def test_init_plot_custom_slices_wf(ds001419_data, tmp_path_factory):
@@ -17,7 +17,7 @@ def test_init_plot_custom_slices_wf(ds001419_data, tmp_path_factory):
     img_3d = image.index_img(nifti_file, 5)
     img_3d.to_filename(nifti_3d)
 
-    wf = execsummary.init_plot_custom_slices_wf(
+    wf = plotting.init_plot_custom_slices_wf(
         output_dir=tmpdir,
         desc="SubcorticalOnAtlas",
         name="plot_custom_slices_wf",

xcp_d/workflows/__init__.py

@@ -2,28 +2,12 @@
 # vi: set ft=python sts=4 ts=4 sw=4 et
 """Nipype workflows for xcp_d."""
 
-from xcp_d.workflows import (
-    anatomical,
-    base,
-    bold,
-    cifti,
-    connectivity,
-    execsummary,
-    outputs,
-    plotting,
-    postprocessing,
-    restingstate,
-)
+from xcp_d.workflows import anatomical, base, bold, parcellation, plotting
 
 __all__ = [
     "anatomical",
     "base",
     "bold",
-    "cifti",
-    "connectivity",
-    "execsummary",
-    "outputs",
+    "parcellation",
     "plotting",
-    "postprocessing",
-    "restingstate",
 ]

xcp_d/workflows/anatomical/__init__.py

@@ -0,0 +1,11 @@
+"""Workflow for anatomical postprocessing."""
+
+from xcp_d.workflows.anatomical import outputs, parcellation, plotting, surface, volume
+
+__all__ = [
+    "outputs",
+    "parcellation",
+    "plotting",
+    "surface",
+    "volume",
+]