Consolidate slice timing and func preprocessing.

Author: jpellman

docs/user/_sources/files.txt

@@ -2,9 +2,9 @@
 -------------------
 Working With Preconfigured Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-We provide preconfigured versions of two files, :file:`data_config.yml` (used to define file structure templates when generating subject lists) and :file:`scan_parameters.csv` (used when running :doc:`Slice Timing Correction </slice>`) for use with key `INDI <http://fcon_1000.projects.nitrc.org/>`_ data releases. While the preconfigured :file:`scan_parameters.csv` files can be used unmodified, it is necessary to slightly edit the file structure templates in :file:`data_config.yml` before they can be used.
+We provide preconfigured versions of two files, :file:`data_config.yml` (used to define file structure templates when generating subject lists) and :file:`scan_parameters.csv` (used when running :doc:`Slice Timing Correction </func>`) for use with key `INDI <http://fcon_1000.projects.nitrc.org/>`_ data releases. While the preconfigured :file:`scan_parameters.csv` files can be used unmodified, it is necessary to slightly edit the file structure templates in :file:`data_config.yml` before they can be used.
 
-For multiscan sites like the Enhanced NKI-Rockland Sample dataset, the multiscan parameters template is used. These must be modified with a path to the slice timing parameters which also available below. See :doc:`Slice Timing Correction </slice>` for further detail.
+For multiscan sites like the Enhanced NKI-Rockland Sample dataset, the multiscan parameters template is used. These must be modified with a path to the slice timing parameters which also available below. See :doc:`Slice Timing Correction </func>` for further detail.
 
 File structure templates in preconfigured copies of :file:`data_config.yml` will be prefixed with the text :file:`/path/to/data`. This is because though we are able to pre-define the folder structure of INDI releases, there is no way for us to know where exactly the data will be located on your specific system. Users must replace :file:`/path/to/data` with the path to the data files downloaded from INDI. For example, if you have downloaded the `ABIDE <http://fcon_1000.projects.nitrc.org/indi/abide/>`_ data set and placed the files in an :file:`/ABIDE` directory loaded in your :file:`/home/science/` folder, you would replace :file:`/path/to/data` with :file:`/home/science/ABIDE`.
 

docs/user/_sources/func.txt

@@ -1,8 +1,13 @@
 Functional Preprocessing
 -------------------------
 
-Timeseries Options
-^^^^^^^^^^^^^^^^^^
+Slice Timing Correction 
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most fMRI images are created by combining multiple 2D slices into a single 3D volume. Slices are acquired one after another, either sequentially in ascending or descending order, or in an interleaved manner, such that every other slice is acquired in a first pass, and the remaining slices are acquired in a second pass. The time between the acquisition of the first and last slice depends on the TR used (e.g. 2.5 seconds for a TR of 2500ms). Slice timing correction acts to adjust the timecourse of voxels in each slice to account for these differences. This is done by interpolating the data in each slice to match the timing of a reference slice. Slice timing correction is necessary because many statistical models used for fMRI analysis assume that all voxels are measured simultaneously. As such, differences in acquisition time between slices can cause confounds.
+
+You can configure your slice time correction settings through the C-PAC pipeline configuration editor, under the *Time Series Options* tab in the *Functional Preprocessing* section. Here you can select whether or not to run Slice Time Correction, as well as which slice acquisition pattern to enter.
+
 .. figure:: /_images/ts_options.png
 
 #. **First Timepoint - [integer]:** The starting volume of the scan.  If you need to censor the first volumes of a scan to facilitate stable magnetization, you can do so here.
@@ -43,6 +48,52 @@ The box below contains an example of what these parameters might look like when
     slice_timing_correction : [0]
     slice_timing_pattern : ['Use NIFTI Header']
 
+Through the Subject List
+""""""""""""""""""""""""
+
+You can also specify slice timing parameters within the subject list.  If you wish to specify slice timing correction parameters in this way, scan parameters must be supplied to C-PAC in a ``.csv`` file, and the path to this file provided when :doc:`setting up a new subject list </subject_list_config>`.
+
+.. line-block::
+  **If all subjects within a site have the same acquisition order:** 
+  Use the template :file:`scan_parameters.csv` file available for download `here <https://raw.github.com/FCP-INDI/C-PAC/master/configs/scan_parameters.csv>`_. 
+
+  **If subjects within a site have different acquisition orders:**
+  Use the template :file:`scan_parameters_multiscan.csv` file available for download `here <https://raw.github.com/FCP-INDI/C-PAC/master/configs/scan_parameters_multiscan.csv>`_. 
+
+Slice Timing information should be entered into these files as follows:
+
+* **Site** - Site name corresponding to a site-level folder in your directory structure (e.g. :file:`site_1`).
+* **Scan** - Only for :file:`scan_parameters_multiscan.csv`. Scan name corresponding to a scan-level folder in your directory structure (e.g. :file:`anat`, :file:`rest`)
+* **TR** - TR in seconds.
+* **Reference** - Desired reference slice (usually the middle slice).
+* **Acquisition** - Acquisition order.
+
+    * **altplus** - Alternating in the +z direction
+    * **alt+z** - Alternating in the +z direction
+    * **alt+z2** - Alternating, but beginning at slice #1 
+    * **altminus** - Alternating in the -z direction
+    * **alt-z** - Alternating in the -z direction
+    * **alt-z2** - Alternating, starting at slice #nz-2 instead of #nz-1
+    * **seqplus** - Sequential in the plus direction
+    * **seqminus** - Sequential in the minus direction
+
+* **FirstTR** - First volume to include in analysis. (Reminder, volumes start at 0)
+* **LastTR** - Last volume to include in analysis.
+
+If your data does not conform to one of the 6 acquisition orders in the list above (as would be the case for multiband and multi-echo sequences), you must generate acquisition order files before running slice timing correction. This is done using the AFNI command ``dicom_hdr`` and specifying the first DICOM file in an image sequence, as well as the name of an output :file:`.txt` file.::
+
+    dicom_hdr -slice_times /path/to/file.dcm > output_name.txt
+
+This will output a text file with the name you specified. Each number in this file corresponds to a slice and the time when it was acquired (relative to the beginning of the TR). The following is an example of an acquisition order file for a a multiband fMRI scan with 40 slices and TR=645ms::
+
+    0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0 0.0 452.5 257.5 65.0 517.5 322.5 130.0 582.5 387.5 195.0
+
+The path to the acquisition order file for each scan should be specified in the "Acquisition" column of your :file:`scan_parameters.csv` or :file:`scan_parameters_multiscan.csv` file.
+
+**Note:** alt+z2 is the order most commonly used on Siemens scanners for interleaved scans with an even number of slices.
+
+**Note:** Scan parameter information specified for slice timing correction will override the settings specified in the pipeline configuration YAML.
+
 Functional to Anatomical Registration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. figure:: /_images/func_to_anat_reg.png

docs/user/_sources/pipeline_config.txt

@@ -64,7 +64,6 @@ Preprocessing
 
     Anatomical Preprocessing <anat>
     Functional Preprocessing <func>
-    Slice Timing Correction <slice>
     Nuisance Corrections <nuisance>
     Temporal Filtering <nuisance>
     Motion Correction <motion>
@@ -81,6 +80,11 @@ Derivatives
 * :doc:`Regional Homogeneity (ReHo) </reho>` - Measure the similarity of activity patterns across neighboring voxels.
 * :doc:`Network Centrality </centrality>` - Analyze the structure of functional networks.
 
+-Derivatives that will be computable in the future, and for which there are currently non-functioning interfaces in the alpha version, will include:
+-
+-* :doc:`Bootstrap Analysis of Stable Clusters (BASC) </basc>` - Quantify the stable characteristics of networks.
+-* :doc:`Connectome-wide Association Studies (CWAS) </cwas>` - Explore the relationship between patterns of functional connectivity and phenotypes.
+
 Running Preprocessing and Individual-Level Analysis
 ---------------------------------------------------
 When you are ready to run C-PAC, select the subject lists and pipelines you would like to run and click the *Run Individual Level Analysis* button.

docs/user/_sources/preproc.txt

@@ -72,7 +72,7 @@ First, open the CPAC GUI by entering the command ``cpac_gui`` in a terminal wind
 
 .. figure:: /_images/main_gui.png
 
-In order to run CPAC, you must specify a list of subjects and data files to process. This is done by generating or loading a subject list file that contains information about each subject to be run, their associated image files, and (optionally) scan parameter information for use during :doc:`Slice Timing Correction </slice>`.
+In order to run CPAC, you must specify a list of subjects and data files to process. This is done by generating or loading a subject list file that contains information about each subject to be run, their associated image files, and (optionally) scan parameter information for use during :doc:`Slice Timing Correction </func>`.
 
 If you would like to use a previously generated subject list, click the *Load* button and select the appropriate ``.yml`` subject list file. If you have loaded multiple subject lists, use the checkboxes to select which subject lists you would like to run with the pipelines that have been checked in the adjacent *Pipelines* box.
 
@@ -131,6 +131,6 @@ By default, C-PAC will process data for all subjects matching the file templates
 
 Set Up Slice Timing Correction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you wish to run :doc:`Slice Timing Correction </slice>`, you must specify the path to a spreadsheet file containing scan acquisition parameters and slice timing information. Instructions for creating this file can be :doc:`found here </slice>`, and we provide preconfigured versions for INDI data releases on the :doc:`Preconfigured Files </files>` page. If you do not wish to run Slice Timing Correction, set :file:`scanParametersCSV = None`.
+If you wish to run :doc:`Slice Timing Correction </func>`, you must specify the path to a spreadsheet file containing scan acquisition parameters and slice timing information. Instructions for creating this file can be :doc:`found here </func>`, and we provide preconfigured versions for INDI data releases on the :doc:`Preconfigured Files </files>` page. If you do not wish to run Slice Timing Correction, set :file:`scanParametersCSV = None`.