Merge pull request #240 from FCP-INDI/dev-1.7.1

Merge v1.7.1 updates to Source

Author: sgiavasis

docs/_sources/_images/acpc_gui.png

@@ -8,10 +8,11 @@
 Initial Preprocessing
 ^^^^^^^^^^^^^^^^^^^^^
 
-Initial preprocessing offers methods like `non-local means filtering <https://www.iro.umontreal.ca/~mignotte/IFT6150/Articles/Buades-NonLocal.pdf>`_ and `N4 bias field correction <https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3071855/>`_ to preprocess anatomical images.
+Initial preprocessing offers methods like `ACPC Alignment <https://doi.org/10.1016/j.neuroimage.2013.04.127>`_ , `non-local means filtering <https://www.iro.umontreal.ca/~mignotte/IFT6150/Articles/Buades-NonLocal.pdf>`_ and `N4 bias field correction <https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3071855/>`_ to preprocess anatomical images.
 
 C-PAC provides options for configuring initial preprocessing - users can select:
 
+* `ACPC Alignment <https://github.com/Washington-University/HCPpipelines/blob/master/PreFreeSurfer/scripts/ACPCAlignment.sh>`_
 * `ANT's DenoiseImage <https://manpages.debian.org/experimental/ants/DenoiseImage.1.en.html>`_
 * `ANT's N4BiasFieldCorrection <http://manpages.ubuntu.com/manpages/trusty/man1/N4BiasFieldCorrection.1.html>`_
 
@@ -21,10 +22,22 @@ Configuring CPAC to run initial preprocessing:
 
 .. figure:: /_images/anat_init_options.png
 
+#. **ACPC Alignment - [On,Off]:** Anterior Commissure - Posterior Comissure (ACPC) alignment. Default is Off. If choose 'on', clicking on the setting icon will bring up a dialog where you can set ACPC alignment parameters.
+
 #. **Non-Local Means Filtering - [On,Off]:** ANTs DenoiseImage. Default is Off.
 
 #. **N4 Bias Field Correction - [On,Off]:** ANTs N4BiasFieldCorrection - a variant of the popular N3 (nonparametric nonuniform normalization) retrospective bias correction algorithm. Default is Off.
 
+Configuring ACPC Alignment options:
+""""""""""""""""""""""""""""""""""""""
+**Note:** These options are pre-set for ACPC Alignment's default values. These do not need to be modified unless you are looking to optimize the results of ACPC alignment for your particular dataset.
+
+.. figure:: /_images/acpc_gui.png
+
+#. **ACPC Brain Size - [150]:** ACPC size of brain in z-dimension in mm. Default: 150mm for human data, 70mm for macaque data.
+#. **ACPC Aligned Skull Template - [path]:** Skull template to be used for ACPC alignment. It is not necessary to change this path unless you intend to use a non-standard template.
+#. **ACPC Aligned Brain Template - [path]:** Brain template to be used for ACPC alignment. For human data, it can be 'None'. It is not necessary to change this path unless you intend to use a non-standard template.
+
 
 Skull-Stripping
 ^^^^^^^^^^^^^^^

docs/_sources/_images/anat_init_options.png

@@ -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' multiplied by 'Number of Cores for Anatomical Registration (ANTS)' must not be greater than the total number of cores.
+#. **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/_static/flowcharts/anatomical.svg

@@ -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/_static/flowcharts/pipeline-individual.svg

@@ -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.