Add motion estimate filter docs, and updated the output directory lists.

Author: sgiavasis

docs/_sources/user/compute_config.rst

@@ -8,7 +8,7 @@ Computer Settings
 
 #. **Maximum Memory Per Participant (GB) - [number]:**  The maximum amount of memory each participant's workflow can allocate. Use this to place an upper bound of memory usage. **Warning: 'Memory Per Participant' multiplied by 'Number of Participants to Run Simultaneously' must not be more than the total amount of RAM. Conversely, using too little RAM can impede the speed of a pipeline run. It is recommended that you set this to a value that when multiplied by 'Number of Participants to Run Simultaneously' is as much RAM you can safely allocate.**
 
-#. **Maximum Cores Per Participant - [integer]:** Number of cores (on a single machine) or slots on a node (cluster/grid) per subject. Slots are cores on a cluster/grid node. 'Number of Cores Per Subject' multiplied by 'Number of Subjects to Run Simultaneously' must not be greater than the total number of cores. Dedicating more than one core/CPU per participant will direct C-PAC to parallelize the motion correction and time series registration transform application steps, for a speed increase.
+#. **Maximum Cores Per Participant - [integer]:** Number of cores (on a single machine) or slots on a node (cluster/grid) per subject. Slots are cores on a cluster/grid node. 'Number of Cores Per Participant' multiplied by 'Number of Participants to Run Simultaneously' must not be greater than the total number of cores. Dedicating more than one core/CPU per participant will direct C-PAC to parallelize the motion correction and time series registration transform application steps, for a speed increase.
 
 #. **Number of Participants to Run Simultaneously - [integer]:** This number depends on computing resources.
 

docs/_sources/user/func.rst

@@ -18,7 +18,16 @@ Initial Preprocessing
 #. **Motion Correction Tool - [3dvolreg, mcflirt]:** Choose motion correction method. Options: AFNI volreg, FSL mcflirt. Default is AFNI volreg.
 #. **Motion Correction Reference - [mean, median, selected volume]:** Choose motion correction reference. Options: mean, median, selected volume. Default is mean.
 #. **Motion Correction Reference Volume - [integer]:** Choose an integer as the motion correction reference volume if choosing "selected volume" as motion correction reference.
-
+#. **Motion Estimate Filter:** Adapted from the motion estimate filter by `DCAN Labs <https://github.com/DCAN-Labs>`__. Based on the filter described `in this publication <https://www.biorxiv.org/content/10.1101/337360v1.full.pdf>`__.
+
+    #. **run - [False, True]:** Toggle the filter.
+    #. **filter_type - ['notch', 'lowpass']:** Use either a notch/bandstop or low-pass filter.
+    #. **filter_order - [integer]:** Specify the filter order. Default is 4.
+    #. **breathing_rate_min - [integer]:** Lowest breaths-per-minute value in the entire dataset (across all participants). Required for both notch and lowpass filters. Mutually exclusive with `center_frequency`, `filter_bandwidth`, and `lowpass_cutoff`. Using this parameter will guide the automatic design of the filter.
+    #. **breathing_rate_max - [integer]:** Highest breaths-per-minute value in the entire dataset (across all participants). Required for the notch filter. Mutually exclusive with `center_frequency`, `filter_bandwidth`, and `lowpass_cutoff`. Using this parameter will guide the automatic design of the filter.
+    #. **center_frequency - [float]:** Notch filter only. Manually select the center frequency for the notch filter. Mutually exclusive with `breathing_rate_min` and `breathing_rate_max`. Use this to manually design the filter.
+    #. **filter_bandwidth - [float]:** Notch filter only. Manually select the bandwidth for the notch filter. Mutually exclusive with `breathing_rate_min` and `breathing_rate_max`. Use this to manually design the filter.
+    #. **lowpass_cutoff - [float]:** Lowpass filter only. Manually select the cutoff frequency for the lowpass filter. Mutually exclusive with `breathing_rate_min` and `breathing_rate_max`. Use this to manually design the filter.
 
 Configuration Without the GUI
 """""""""""""""""""""""""""""

docs/_sources/user/output_dir.rst

@@ -38,13 +38,15 @@ The output directory folders below are produced during a default run. If you ena
 * **frame_wise_displacement_power**: 1-D file containing the vector of framewise displacement values between volumes, as calculated via Power.
 * **functional_brain_mask**: Binary mask of the brain in functional space.
 * **functional_brain_mask_to_standard**: Binary mask of the functional-space brain warped to standard template.
-* **functional_freq_filtered**: Preprocessed functional timeseries file all the way up to temporal filtering.
+* **functional_freq_filtered**: Preprocessed functional timeseries file all the way up to temporal filtering. 4D time series.
 * **functional_nuisance_regressors**: .mat file containing the data corresponding to each nuisance that was regressed out during nuisance regression.
 * **functional_to_anat_linear_xfm**: Functional-to-anatomical space linear transform. FSL-FLIRT format.
-* **functional_to_standard**: Preprocessed functional timeseries warped to standard template space.
+* **functional_to_standard**: Preprocessed functional timeseries warped to standard template space. 4D time series.
+* **functional_to_standard_smooth**: Smoothed version of functional_to-standard. 4D time series.
+* **functional_to_standard_xfm**: Composite transform (as a NIfTI .nii.gz file) bringing data from native functional (BOLD) space to template space.
 * **mean_functional_to_standard**: Mean functional (one-volume 3D file of functional scan) warped to standard template space.
 * **mni_to_anatomical_nonlinear_xfm**: Same as the anatomical_to_mni_nonlinear_xfm described above, except the inverse warp.
-* **motion_correct**: Motion-corrected functional timeseries in functional space, before the rest of functional preprocessing.
+* **motion_correct**: Motion-corrected functional timeseries in functional space, before the rest of functional preprocessing. 4D time series.
 * **motion_params**: Text file containing the single-value max or mean numbers of each head motion parameter/measure.
 * **output_means**: Text files containing the mean intensity values of each output or derivative. Used later in group-level analysis.
 * **path_files_here**: Text files containing full file paths to all of the C-PAC outputs in the output directory. Can be used for convenient file path parsing.
@@ -104,14 +106,15 @@ In addition to the output directories described above under "Descriptions", the
 
 **Extra Functional Outputs** - Set 'Write Extra Functional Outputs' to 'On' to produce these outputs.
 
-* **functional_nuisance_residuals**: A NIfTI (.nii) file of the pre-processed functional time series produced directly after nuisance regression is performed.
-* **functional_preprocessed**: The functional time series produced directly after initial functional pre-processing (de-obliquing, re-orienting, motion correction, functional skull-stripping, and image intensity normalization). In native space.
+* **functional_nuisance_residuals**: A NIfTI (.nii) file of the pre-processed functional time series produced directly after nuisance regression is performed. 4D time series.
+* **functional_nuisance_residuals_smooth**: Smoothed version of functional_nuisance_residuals. 4D time series.
+* **functional_preprocessed**: The functional time series produced directly after initial functional pre-processing (de-obliquing, re-orienting, motion correction, functional skull-stripping, and image intensity normalization). In native space. 4D time series.
 * **functional_preprocessed_mask**: A binary mask of the functional_preprocessed output. In native space.
 * **mean_functional**: The mean of the functional time-series taken over the time course. Presented as a single-volume NifTI file.
 * **mean_functional_in_anat**: The mean of the functional time-series, registered/warped to anatomical (T1) space.
-* **motion_correct_to_standard**: Motion-corrected functional timeseries in template space, before the rest of functional preprocessing.
-* **motion_correct_to_standard_smooth**: Motion-corrected functional timeseries in template space, before the rest of functional preprocessing, but smoothed.
-* **slice_time_corrected**: The functional time-series after slice-time correction.
+* **motion_correct_to_standard**: Motion-corrected functional timeseries in template space, before the rest of functional preprocessing. 4D time series.
+* **motion_correct_to_standard_smooth**: Motion-corrected functional timeseries in template space, before the rest of functional preprocessing, but smoothed. 4D time series.
+* **slice_time_corrected**: The functional time-series after slice-time correction. 4D time series.
 
 **Non-smoothed** - Set 'Run Smoothing' to either 'Off' or 'On/Off' to produce these outputs.