📚 Add text to document how to use custom regressors (#230)

Author: shnizzedy

.vscode/launch.json

@@ -24,7 +24,7 @@
             "debugStdLib": true,
             "args": [
                 "-m", "sphinx",
-                "docs/user/_sources", "docs/user"
+                "docs/_sources/user", "docs/user"
             ]
         }
     ]

docs/_sources/_static/params/nuisance_config.csv

@@ -1,3 +1,3 @@
 runNuisance,Run Nuisance Signal Correction,"A list where ‘1’ represents ‘yes’ and ‘0’ represents ‘no’ (e.g., ‘[1]’)."
 lateral_ventricles_mask,Standard Lateral Ventricles Binary Mask.,"A path (e.g., $FSLDIR/data/atlases/HarvardOxford/ HarvardOxford-lateral-ventricles-thr25-2mm.nii.gz)."
-Regressors,"The nuisance corrections you wish to apply. Corrections include aCompCor, tCompCor, White Matter, Cerebrospinal Fluid, Grey Matter, Global Signal, Motion, Polynomial regression, Bandpass, Censoring.","See below for a full specification of regressors."
+Regressors,"The nuisance corrections you wish to apply. Corrections include aCompCor, tCompCor, White Matter, Cerebrospinal Fluid, Grey Matter, Global Signal, Motion, Polynomial regression, Bandpass, Censoring, Custom.","See below for a full specification of regressors."

docs/_sources/user/nuisance.rst

@@ -98,6 +98,16 @@ Median angle correction is another global signal correction approach. It is assu
 
 Principal component analysis (PCA) is used to decompose the resting-state data. Median angle is computed by taking the inverse cosine of each voxel’s time series vector's projection onto the first principal component (i.e. the global mean signal) and then calculating the median over the angles from all the vectors. If an inverse relation is found between the median angle and the mean BOLD signal amplitude, then an additive signal confound is present. As resting-state data sets with high median angles and low mean BOLD magnitudes are likely to be the least contaminated by an additive global confound (He and Liu, 2011), the inverse relation between median angle and mean BOLD magnitude is used to correct for differences in the additive confound. Specifically, the angular distributions of datasets with small median angles can be shifted to attain a larger target median angle to effectively minimize the effects of the global signal confound. The calculation of target angle for median angle correction is described in He and Liu (2011).
 
+Custom Regressors
+^^^^^^^^^^^^^^^^^
+You can provide your own custom regressor signals beyond those provided by C-PAC (e.g., task encodings or quasi-periodic pattern waveforms).
+
+Each custom regressor must be either a CSV or NIFTI file that contains a single column of the same length as the functional signal with ``1``\s indicating volumes to keep and ``0``\s indicating volumes to censor.
+
+The custom regressor specification also takes a boolean ``convolve`` (default = ``false``).
+
+An example with one custom regressor is included in :ref:`nuisance-no-gui`, below.
+
 Configuring Nuisance Signal Regression Options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. figure:: /_images/nuisance.png
@@ -108,6 +118,8 @@ Configuring Nuisance Signal Regression Options
 
 #. **Select Regressors: - [checkbox: compcor, wm, csf, global, pc1, motion, linear, quadratic]:**  Clicking on the *+* icon to the right of the box here will bring up a dialog where you can check off which nuisance variables you would like to include.  You may generate multiple sets of nuisance regression strategies in this way.  When you are done defining nuisance regression strategies, check the box next to each strategy you would like to run.
 
+.. _nuisance-no-gui:
+
 Configuration Without the GUI
 """""""""""""""""""""""""""""
 
@@ -120,7 +132,7 @@ The following key/value pairs must be defined in your :doc:`pipeline configurati
 
 The following box contains the full specification for regressors:
 
-.. program-output:: python /build/docs/user/_sources/nuisance_regressors_docstring.py
+.. program-output:: python /build/docs/_sources/user/nuisance_regressors_docstring.py
 
 The box below contains an example of what these parameters might look like when defined in the YAML.
 

docs/_sources/nuisance_regressors_docstring.py renamed to docs/_sources/user/nuisance_regressors_docstring.py

@@ -1,9 +1,9 @@
 from CPAC import nuisance
 
-nstring = nuisance.create_nuisance_workflow.__doc__[
-    nuisance.create_nuisance_workflow.__doc__.find(
+nstring = nuisance.create_regressor_workflow.__doc__[
+    nuisance.create_regressor_workflow.__doc__.find(
         "selector = "
-    ) + len("selector = ") + 1:nuisance.create_nuisance_workflow.__doc__.find(
+    ) + len("selector = ") + 1:nuisance.create_regressor_workflow.__doc__.find(
         "Workflow Outputs"
     )
 ].rstrip()[:-1].lstrip('\n')