Improve documentation.

docs/outputs.rst

@@ -239,11 +239,13 @@ Functional timeseries and connectivity matrices
 This includes the atlases used to extract the timeseries.
 
 .. important::
+
    If ``abcd`` or ``hbcd`` mode is used, the time series will be interpolated.
    If ``linc`` mode is used, the time series will be censored.
    In both cases, the correlation matrices will be calculated using the censored time series.
 
 .. important::
+
    Correlation matrices with the ``desc-<INT>volumes`` entity are produced if the
    ``--create-matrices`` parameter is used with integer values.
 
@@ -331,17 +333,37 @@ The "framewise_displacement" column contains zeros for low-motion volumes, and o
 high-motion outliers.
 This file includes the high-motion volumes that are removed in most other derivatives.
 
-``design.tsv`` is a tab-delimited file with one column for each nuisance regressor,
-including one-hot encoded regressors indicating each of the high-motion outlier volumes.
-This file includes the high-motion volumes that are removed in most other derivatives.
+``design.tsv`` is a tab-delimited file with one column for each nuisance regressor.
+This file includes rows for the high-motion volumes that are removed in most other derivatives.
+It does not indicate which volumes are removed (please see the ``outliers.tsv`` for that)
+and also does not include the intercept or linear trend terms that are separately applied before
+the GLM regression.
+
+``_desc-linc_qc.tsv`` is a tab-delimited file with one row and one column for each of several QC
+metrics. The QC metrics are described in detail in the ``desc-linc_qc.json`` file.
+This file includes metrics indicating the number of volumes removed due to high motion,
+the number of confounds used in the denoising step
+(including two for the linear trend and intercept),
+and the number of degrees of freedom lost by temporal filtering.
+
+In order to determine the degrees of freedom for the resulting correlations,
+you should do the following calculation:
+``num_retained_volumes - (num_dof_used_by_denoising + num_dof_used_by_filter + 2)``.
 
 .. important::
-   Please note that the outlier columns are somewhat misleading,
-   as volumes are removed by censoring, rather than regression.
+
+   This formula ignores autocorrelation.
+   In order to calculate the effective degrees of freedom for your correlation coefficients,
+   consider using a tool like xDF.
+
+.. warning::
+
+   This formula must be adjusted for correlations computed from random subsets of the time series
+   (i.e., by using the ``--create-matrices`` parameter with integer values).
 
 
-DCAN style scrubbing file (if ``--skip-dcan-qc`` is not used)
-=============================================================
+DCAN style scrubbing file (if ``--abcc-qc`` is not used)
+========================================================
 
 This file is in hdf5 format (readable by h5py), and contains binary scrubbing masks from 0.0
 to 1mm FD in 0.01 steps.

docs/workflows.rst

@@ -773,9 +773,6 @@ to satisfy DCAN-specific tools.
    regressors, this could lead to the imperfect removal of noise from your BOLD data.
 
 The residuals from the second step are referred to as the ``denoised, interpolated BOLD``.
-The ``denoised, interpolated BOLD`` will only be written out to the output
-directory if the ``--skip-dcan-qc`` flag is not used,
-as users **should not** use interpolated data directly.
 
 
 Re-censoring
@@ -791,6 +788,8 @@ After bandpass filtering, high motion volumes are removed from the
    In the ``abcd`` and ``hbcd`` modes,
    the denoised, **interpolated** BOLD data are the primary output.
 
+   This behavior is specifically controlled with the ``--output-type`` flag.
+
 
 Resting-state derivative generation
 ===================================

xcp_d/cli/parser.py

@@ -434,6 +434,7 @@ def _build_parser():
     )
     g_censor.add_argument(
         "--output-type",
+        "--output_type",
         dest="output_type",
         default="auto",
         action="store",

xcp_d/data/reports-spec-func.yml

@@ -16,7 +16,12 @@ sections:
               and outlier volumes are identified.
     subtitle: Framewise Displacement and Censored Volumes
   - bids: {datatype: figures, suffix: design}
-    caption:  The "design matrix" represents the confounds that are used to denoise the BOLD data.
+    caption: |
+      The "design matrix" represents the confounds that are used to denoise the BOLD data.
+
+      Please note that the outlier columns are somewhat misleading,
+      as volumes are removed by censoring, rather than regression.
+      This figure does not include the intercept or linear trend that are removed in the denoising step.
     subtitle: Design Matrix for Confound Regression
     style:
       height: 100px

xcp_d/data/reports-spec.yml

@@ -24,7 +24,12 @@ sections:
               and outlier volumes are identified.
     subtitle: Framewise Displacement and Censored Volumes
   - bids: {datatype: figures, suffix: design}
-    caption:  The "design matrix" represents the confounds that are used to denoise the BOLD data.
+    caption: |
+      The "design matrix" represents the confounds that are used to denoise the BOLD data.
+
+      Please note that the outlier columns are somewhat misleading,
+      as volumes are removed by censoring, rather than regression.
+      This figure does not include the intercept or linear trend that are removed in the denoising step.
     subtitle: Design Matrix for Confound Regression
     style:
       height: 500px