docs: final details (file trees, confounds tsv files, etc.)

Author: oesteban

docs/outputs.rst

@@ -21,7 +21,7 @@ Outputs of *fMRIPrep*
      the same-subject's T1w space or into MNI space.
 
   3. **Additional data for subsequent analysis**, for instance the transformations
-     between different spaces or the estimated confounds.
+     between different spaces or the estimated confounds_.
 
 
 *fMRIPrep* outputs conform to the :abbr:`BIDS (brain imaging data structure)`
@@ -34,106 +34,151 @@ These reports provide a quick way to make visual inspection of the results easy.
 Each report is self contained and thus can be easily shared with collaborators (for example via email).
 `View a sample report. <_static/sample_report.html>`_
 
-
 Derivatives of *fMRIPrep* (preprocessed data)
 ---------------------------------------------
 Preprocessed, or derivative, data are written to
 ``<output dir>/fmriprep/sub-<subject_label>/``.
 The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions we follow.
 
 Anatomical derivatives are placed in each subject's ``anat`` subfolder:
+::
 
-- ``anat/sub-<subject_label>_[space-<space_label>_]desc-preproc_T1w.nii.gz``
-- ``anat/sub-<subject_label>_[space-<space_label>_]desc-brain_mask.nii.gz``
-- ``anat/sub-<subject_label>_[space-<space_label>_]dseg.nii.gz``
-- ``anat/sub-<subject_label>_[space-<space_label>_]label-CSF_probseg.nii.gz``
-- ``anat/sub-<subject_label>_[space-<space_label>_]label-GM_probseg.nii.gz``
-- ``anat/sub-<subject_label>_[space-<space_label>_]label-WM_probseg.nii.gz``
-
-Template-normalized derivatives use the space label ``MNI152NLin2009cAsym``, while derivatives in
+  sub-<subject_label>/
+    anat/
+      sub-<subject_label>[_space-<space_label>]_desc-preproc_T1w.nii.gz
+      sub-<subject_label>[_space-<space_label>]_desc-brain_mask.nii.gz
+      sub-<subject_label>[_space-<space_label>]_dseg.nii.gz
+      sub-<subject_label>[_space-<space_label>]_label-CSF_probseg.nii.gz
+      sub-<subject_label>[_space-<space_label>]_label-GM_probseg.nii.gz
+      sub-<subject_label>[_space-<space_label>]_label-WM_probseg.nii.gz
+
+Spatially-standardized derivatives are denoted with a space label,
+such as ``MNI152NLin2009cAsym``, while derivatives in
 the original ``T1w`` space omit the ``space-`` keyword.
 
 Additionally, the following transforms are saved:
+::
 
-- ``anat/sub-<subject_label>_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5`` 
-- ``anat/sub-<subject_label>_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5`` 
+  sub-<subject_label>/
+    anat/
+      sub-<subject_label>_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
+      sub-<subject_label>_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
 
 If FreeSurfer reconstructions are used, the following surface files are generated:
+::
 
-- ``anat/sub-<subject_label>_hemi-[LR]_smoothwm.surf.gii``
-- ``anat/sub-<subject_label>_hemi-[LR]_pial.surf.gii``
-- ``anat/sub-<subject_label>_hemi-[LR]_midthickness.surf.gii``
-- ``anat/sub-<subject_label>_hemi-[LR]_inflated.surf.gii``
+  sub-<subject_label>/
+    anat/
+      sub-<subject_label>_hemi-[LR]_smoothwm.surf.gii
+      sub-<subject_label>_hemi-[LR]_pial.surf.gii
+      sub-<subject_label>_hemi-[LR]_midthickness.surf.gii
+      sub-<subject_label>_hemi-[LR]_inflated.surf.gii
 
-And the affine translation between ``T1w`` space and FreeSurfer's reconstruction (``fsnative``) is
-stored in:
+And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's
+conformed space for surface reconstruction (``fsnative``) is stored in:
+::
 
-- ``anat/sub-<subject_label>_from-T1w_to-fsnative_mode-image_xfm.txt``
+  sub-<subject_label>/
+    anat/
+      sub-<subject_label>_from-fsnative_to-T1w_mode-image_xfm.txt
+      sub-<subject_label>_from-T1w_to-fsnative_mode-image_xfm.txt
 
-Functional derivatives are stored in the ``func`` subfolder.
+Functional derivatives are stored in the ``func/`` subfolder.
 All derivatives contain ``task-<task_label>`` (mandatory) and ``run-<run_index>`` (optional), and
 these will be indicated with ``[specifiers]``.
+::
 
-- ``func/sub-<subject_label>_[specifiers]_space-<space_label>_boldref.nii.gz``
-- ``func/sub-<subject_label>_[specifiers]_space-<space_label>_desc-brain_mask.nii.gz``
-- ``func/sub-<subject_label>_[specifiers]_space-<space_label>_desc-preproc_bold.nii.gz``
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_space-<space_label>_boldref.nii.gz
+      sub-<subject_label>_[specifiers]_space-<space_label>_desc-brain_mask.nii.gz
+      sub-<subject_label>_[specifiers]_space-<space_label>_desc-preproc_bold.nii.gz
 
 Volumetric output spaces include ``T1w`` and ``MNI152NLin2009cAsym`` (default).
 
-Confounds are saved as a :abbr:`TSV (tab-separated value)` file:
+For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an
+accompanying *confounds* file will be generated.
+Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file:
+::
 
-- ``func/sub-<subject_label>_[specifiers]_desc-confounds_regressors.nii.gz``
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_desc-confounds_regressors.tsv
+      sub-<subject_label>_[specifiers]_desc-confounds_regressors.json
+
+These :abbr:`TSV (tab-separated values)` tables look like the example below,
+where each row of the file corresponds to one time point found in the
+corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series.
+::
+
+  csf white_matter  global_signal std_dvars dvars framewise_displacement  t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00  trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04
+  682.75275 0.0 491.64752000000004  n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0  0.0 0.0 0.0
+  669.14166 0.0 489.4421  1.168398  17.575331 0.07211929999999998 -0.4506846719 0.1191909139  -0.0945884724 0.1542023065  -0.2302324641 0.0838194238  -0.032426848599999995 0.4284323184  -0.5809158299 0.1382414008  -0.1203486637 0.3783661265  0.0 0.0 0.0207752 0.0463124 -0.000270924  -0.0  0.0 -2.402958171  -0.7574011893
+  665.3969  0.0 488.03  1.085204  16.323903999999995  0.0348966 0.010819676200000001  0.0651895837  -0.09556632150000001  -0.033148835  -0.4768871111 0.20641088559999998 0.2818768463  0.4303863764  0.41323714850000004 -0.2115232212 -0.0037154909000000004  0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0  0.0 -1.341359143  0.1636017242
+  662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893  -0.2220965269 -0.0912891436 0.2326688125  0.279138129 -0.111878887  0.16901660629999998 0.0550480212  0.1798747037  -0.25383302620000003  0.1646403629  0.3953613889  0.0 0.010164  -0.0103568  0.0424513 0.0 -0.0  0.00019174  -0.1554834655 0.6451987913
 
 If FreeSurfer reconstructions are used, the ``(aparc+)aseg`` segmentations are aligned to the
 subject's T1w space and resampled to the BOLD grid, and the BOLD series are resampled to the
 midthickness surface mesh:
+::
 
-- ``func/sub-<subject_label>_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz``
-- ``func/sub-<subject_label>_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz``
-- ``func/sub-<subject_label>_[specifiers]_space-<space_label>_hemi-[LR].func.gii``
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz
+      sub-<subject_label>_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz
+      sub-<subject_label>_[specifiers]_space-<space_label>_hemi-[LR].func.gii
 
 Surface output spaces include ``fsnative`` (full density subject-specific mesh),
 ``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and
 ``fsaverage5`` (10k vertices, default).
 
-If CIFTI outputs are requested, the BOLD series is also saved as ``dtseries.nii`` CIFTI2 files:
+If CIFTI outputs are requested (with the ``--cifti-outputs`` argument),
+the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files:
+::
 
-- ``func/sub-<subject_label>_[specifiers]_bold.dtseries.nii``
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_bold.dtseries.nii
 
+CIFTI is a container format that holds both volumetric (regularly sampled in a grid)
+and surface (sampled on a triangular mesh) samples.
 Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym``), while cortical
-time series are sampled to surface (supported spaces: ``fsaverage5``, ``fsaverage6``)
+time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``)
 
 Finally, if ICA-AROMA is used, the MELODIC mixing matrix and the components classified as noise
 are saved:
+::
 
-- ``func/sub-<subject_label>_[specifiers]_AROMAnoiseICs.csv``
-- ``func/sub-<subject_label>_[specifiers]_desc-MELODIC_mixing.tsv``
-
+  sub-<subject_label>/
+    func/
+      sub-<subject_label>_[specifiers]_AROMAnoiseICs.csv
+      sub-<subject_label>_[specifiers]_desc-MELODIC_mixing.tsv
 
 .. _fsderivs:
 
 FreeSurfer Derivatives
 ----------------------
-A FreeSurfer subjects directory is created in ``<output dir>/freesurfer``.
-
+A FreeSurfer subjects directory is created in ``<output_dir>/freesurfer``.
 ::
 
-    freesurfer/
-        fsaverage{,5,6}/
-            mri/
-            surf/
+    <output_dir>/
+        fmriprep/
             ...
-        sub-<subject_label>/
-            mri/
-            surf/
+        freesurfer/
+            fsaverage{,5,6}/
+                mri/
+                surf/
+                ...
+            sub-<subject_label>/
+                mri/
+                surf/
+                ...
             ...
-        ...
 
 Copies of the ``fsaverage`` subjects distributed with the running version of
 FreeSurfer are copied into this subjects directory, if any functional data are
 sampled to those subject spaces.
 
-
 Confounds
 ---------
 The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a mixture of fluctuations
@@ -174,23 +219,7 @@ Such tabular files may include over 100 columns of potential confound regressors
    The choice of confounding variables may depend on the analysis you want to perform,
    and may be not straightforward as no gold standard procedure exists.
    For detailed description of various denoising strategies and their performance,
-   see Parkes et al. ([Parkes2018]_) and Ciric et al. ([Ciric2017]_).
-
-
-For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, a
-``<output_folder>/fmriprep/sub-<sub_id>/func/sub-<sub_id>_task-<task_id>_run-<run_id>_desc-confounds_regressors.tsv``
-file will be generated.
-These are :abbr:`TSV (tab-separated values)` tables, which look like the example below: ::
-
-  csf white_matter  global_signal std_dvars dvars framewise_displacement  t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00  trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04
-  682.75275 0.0 491.64752000000004  n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0  0.0 0.0 0.0
-  669.14166 0.0 489.4421  1.168398  17.575331 0.07211929999999998 -0.4506846719 0.1191909139  -0.0945884724 0.1542023065  -0.2302324641 0.0838194238  -0.032426848599999995 0.4284323184  -0.5809158299 0.1382414008  -0.1203486637 0.3783661265  0.0 0.0 0.0207752 0.0463124 -0.000270924  -0.0  0.0 -2.402958171  -0.7574011893
-  665.3969  0.0 488.03  1.085204  16.323903999999995  0.0348966 0.010819676200000001  0.0651895837  -0.09556632150000001  -0.033148835  -0.4768871111 0.20641088559999998 0.2818768463  0.4303863764  0.41323714850000004 -0.2115232212 -0.0037154909000000004  0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0  0.0 -1.341359143  0.1636017242
-  662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893  -0.2220965269 -0.0912891436 0.2326688125  0.279138129 -0.111878887  0.16901660629999998 0.0550480212  0.1798747037  -0.25383302620000003  0.1646403629  0.3953613889  0.0 0.010164  -0.0103568  0.0424513 0.0 -0.0  0.00019174  -0.1554834655 0.6451987913
-
-Each row of the file corresponds to one time point found in the
-corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series
-(stored in ``<output_folder>/fmriprep/sub-<sub_id>/func/sub-<sub_id>_task-<task_id>_run-<run_id>_desc-preproc_bold.nii.gz``).
+   see [Parkes2018]_ and [Ciric2017]_.
 
 Confound regressors description
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -208,19 +237,19 @@ Basic confouds
 
 Parameter expansion of basic confounds
 ======================================
-Only accounting for the standard six motion parameters may not be sufficient to remove all variance related to 
+Only accounting for the standard six motion parameters may not be sufficient to remove all variance related to
 head motion from the fMRI signal.
-Thus, Friston et al. ([Friston1996]_) and Satterthwaite et al. ([Satterthwaite2013]_)
+Thus, Friston et al. [Friston1996]_ and Satterthwaite et al. [Satterthwaite2013]_
 proposed *24-motion-parameter* expansion, with a goal of removing from fMRI signal as much of the motion-related
 variance as possible.
 To make this technique more accessible, *fMRIPrep* automaticaly calculates motion parameter
-expansion ([Satterthwaite2013]_), providing timeseries corresponding to first *temporal derivatives* of six motion
+expansion [Satterthwaite2013]_, providing timeseries corresponding to first *temporal derivatives* of six motion
 parameters, together with their *quadratic terms*, resulting in the total 24 head motion parameters
 (6 standard motion parameters + 6 temporal derivatives of six motion parameters + 12 quadratic terms of 6 motion
 parameters and their 6 temporal derivatives).
 Additionally, *fMRIPrep* returns temporal derivatives and quadratic terms for the ``csf``, ``white_matter``
 and ``global_signal`` to enable applying 36-parameter denoising strategy
-proposed by Satterthwaite et al. ([Satterthwaite2013]_).
+proposed by Satterthwaite et al. [Satterthwaite2013]_.
 
 Derivatives and quadratic terms are stored under column names with suffixes: ``_derivative1`` and powers ``_power2``.
 These were calculated for head motion estimates (``trans_`` and ``rot_``) and compartment signals
@@ -230,19 +259,20 @@ Confounds for outlier detection
 ===============================
 
 - ``framewise_displacement`` - is a quantification of the estimated bulk-head motion calculated using
-  formula proposed by Power et al. ([Power2012]_);
-- ``dvars`` - the derivative of RMS variance over voxels (or :abbr:`DVARS`)([Power2012]_)
-- ``std_dvars`` - standardized DVARS;
+  formula proposed by [Power2012]_;
+- ``dvars`` - the derivative of RMS variance over voxels (or :abbr:`DVARS (derivative of
+  RMS variance over voxels)`) [Power2012]_;
+- ``std_dvars`` - standardized :abbr:`DVARS (derivative of RMS variance over voxels)`;
 - ``non_steady_state_outlier_XX`` - columns indicate non-steady state volumes with a single
   ``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per
   outlier/volume).
 
 All these confounds can be used to detect potential outlier time points - frames with high motion or spikes.
 Detected outliers can be further removed from time series using methods such as: volume *censoring* - entirely
-discarding problematic time points ([Power2012]_), regressing signal from outlier points in denoising procedure,
+discarding problematic time points [Power2012]_, regressing signal from outlier points in denoising procedure,
 or including outlier points in the subsequent first-level analysis when building the design matrix.
 Averaged value of confound (for example, mean ``framewise_displacement``)
-can be added as a regressor in group level analysis ([Yan2013]_).
+can be added as a regressor in group level analysis [Yan2013]_.
 
 *Spike regressors* for outlier censoring can also be generated from within *fMRIPrep* using
 the command line options ``--fd-spike-threshold`` and ``--dvars-spike-threshold``
@@ -259,19 +289,18 @@ ICA-AROMA confounds
     If you are already using ICA-AROMA cleaned data (``~desc-smoothAROMAnonaggr_bold.nii.gz``),
     do not include ICA-AROMA confounds during your design specification or denoising procedure.
 
-
 CompCor confounds
 =================
 :abbr:`CompCor (Component Based Noise Correction)` is a component-based noise correlation method.
-In the method, principal components are derived from :abbr:`ROI (Region of Interest)` which is unlikely
-to include signal related to neuronal activity, such as :abbr:`CSF (cerebro-spinal fluid)`
-and abbr:`WM (white matter)` masks.
-Signals extracted from CompCor components can be further regressed out from the fMRI data during
-denoising procedure ([Behzadi2007]_).
+In the method, principal components are calculated within an :abbr:`ROI (Region of Interest)`
+that is unlikely to include signal related to neuronal activity, such as :abbr:`CSF (cerebro-spinal fluid)`
+and :abbr:`WM (white matter)` masks.
+Signals extracted from CompCor components can be further regressed out from the fMRI data with a
+denoising procedure [Behzadi2007]_.
 
 - ``a_comp_cor_XX`` - additional noise components are calculated using anatomical :abbr:`CompCor
   (Component Based Noise Correction)`;
-- ``t_comp_cor_XX``) - additional noise components are calculated using anatomical :abbr:`CompCor
+- ``t_comp_cor_XX`` - additional noise components are calculated using temporal :abbr:`CompCor
   (Component Based Noise Correction)`.
 
 Four separate CompCor decompositions are performed to compute noise components: one temporal
@@ -281,9 +310,9 @@ from the union of these.
 
 .. warning::
     Only a subset of these CompCor decompositions should be used for further denoising.
-    The original Behzadi aCompCor implementation ([Behzadi2007]_) can be applied using
+    The original Behzadi aCompCor implementation [Behzadi2007]_ can be applied using
     components from the combined masks, while the more recent Muschelli implementation
-    ([Muschelli2014]_) can be applied using
+    [Muschelli2014]_ can be applied using
     the :abbr:`WM (white matter)` and :abbr:`CSF (cerebro-spinal fluid)` masks. To determine the provenance
     of each component, consult the metadata file (see below).
 
@@ -311,12 +340,11 @@ Metadata files contain additional information about columns in the confounds TSV
       }
     }
 
-
 For CompCor decompositions, entries include:
 
   - ``Method``: anatomical or temporal CompCor.
-  - ``Mask``: denotes the ROI where the decomposition that generated the component
-    was performed: ``CSF``, ``WM``, or ``combined`` for anatomical CompCor.
+  - ``Mask``: denotes the :abbr:`ROI (region of interest)` where the decomposition that generated
+    the component was performed: ``CSF``, ``WM``, or ``combined`` for anatomical CompCor.
   - ``SingularValue``: singular value of the component.
   - ``VarianceExplained``: the fraction of variance explained by the component across the decomposition ROI mask.
   - ``CumulativeVarianceExplained``: the total fraction of variance explained by this particular component
@@ -329,7 +357,7 @@ For CompCor decompositions, entries include:
 Confounds and "carpet"-plot on the visual reports
 -------------------------------------------------
 Some of the estimated confounds, as well as a "carpet" visualization of the
-:abbr:`BOLD (blood-oxygen level-dependent)` time-series (see [Power2016]_).
+:abbr:`BOLD (blood-oxygen level-dependent)` time series [Power2016]_.
 This plot is included for each run within the corresponding visual report.
 An example of these plots follows: