Initial creation of separate page discussing running analyses after preparing config file/subject list

jpellman · jpellman · commit 3bd7bf53199f · 2016-04-29T18:15:18.000-04:00
diff --git a/docs/user/_sources/group_analysis.txt b/docs/user/_sources/group_analysis.txt
@@ -183,6 +183,3 @@ If you would like to add f-tests, add each f-test as a column to the csv and the
 
 .. figure:: /_images/ga_contrast_ftest.png
 
-Running Group-Level Analysis
-""""""""""""""""""""""""""""
-When you are finished configuring the pipeline for group-level analysis, click save. When you are ready to run group-level analysis, select the subject lists and pipelines you would like to run and click the Run Group Level Analysis button. You will be presented with a dialog and asked to select which strategies you would like to include.
diff --git a/docs/user/_sources/index.txt b/docs/user/_sources/index.txt
@@ -74,6 +74,7 @@ User Guide Index
    Setting Up A Subject List <subject_list_config>
    Setting Up A Pipeline <pipeline_config>
    Setting Up Group Analysis <group_analysis>
+   Running C-PAC Locally <running>
    Running C-PAC in the Cloud <cloud>
    Preconfigured Files <files>
    C-PAC Benchmark <benchmark>
diff --git a/docs/user/_sources/pipeline_config.txt b/docs/user/_sources/pipeline_config.txt
@@ -5,8 +5,8 @@ Overview
 
 There are two ways of setting up a pipeline configuration for C-PAC:
 
-* Using a text editor (useful for remote servers where using the GUI is not possible or impractical)
-* Using the pipeline configuration interface in the GUI
+* Using a text editor (useful for remote servers where using the C-PAC GUI is not possible or impractical)
+* Using the pipeline configuration interface in the C-PAC GUI
 
 Definitions
 '''''''''''
@@ -43,8 +43,6 @@ If the C-PAC GUI is not open already, type the command ``cpac_gui`` in a termina
 
 When you have finished configuring your pipeline, click *Save*. You will be asked to specify a location to save a configuration file containing information about the pipeline, and to specify a name for the pipeline.
 
-To modify an existing pipeline, select it and click *Edit*. To use a previously configured pipeline, click *Load* and select the appropriate pipeline configuration file. If you have loaded multiple pipelines, use the checkboxes to select which pipelines you would like to run. 
-
 Configurable Settings
 ---------------------
 
@@ -81,62 +79,8 @@ 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:
+-Derivatives that will be computable in the future, and for which there are currently non-functioning interfaces in the alpha version, 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.
-
-The following schematic illustrates the order in which C-PAC executes.
-
-.. figure:: /_images/processing_workflow.png
-
-
-Output Structure
-^^^^^^^^^^^^^^^^
-
-Symbolic Links
-""""""""""""""
-C-PAC gives you the option of creating an output directory containing `symbolic links <http://en.wikipedia.org/wiki/Symbolic_link>`_ to processed files. We strongly recommend this setting be enabled, as it makes it much easier to navigate output files. The following schematic shows the structure of the resulting :file:`sym_links` directory:
-
-.. figure:: /_images/symlink_structure.png
-
-Pipeline and strategy folders are named as described above. 
-
-File Descriptions
-"""""""""""""""""
-Preprocessed anatomical data from the Anatomical Preprocessing, Registration, and Segmentation workflows can be found in :file:`../scan/anat/` directory for each subject. The following diagram shows processing steps and standard output files for these workflows.
-
-.. figure:: /_images/anat_prepro_schematic.png
-
-Preprocessed functional data from the Functional Preprocessing workflow can be found in the :file:`../scan_<name>/func` directory for each subject. The following diagram shows processing steps and standard output files for this workflow.
-
-.. figure:: /_images/functional_preprocessing.png
-
-Derivative Outputs
-""""""""""""""""""
-Derivatives for each subject can be found in the :file:`../scan_<name>` directory of each subject. This folder also contains the outputs of the registration and segmentation workflows.
-
-.. figure:: /_images/derivs_outputs.png
-
-Within each derivative folder will be sub-folders for each set of frequency filters set in :file:`config.yml`, as well as a folder containing smoothed outputs.
-
-Derivatives are output in both native space (:file:`*_img.nii.gz` and :file:`*_map.nii.gz` files), with values transformed to z-scores (:file:`*_Z_*.nii.gz`) and in standard space (:file:`*_to_standard.nii.gz`).
-
-QC Interface
--------------
-**Note:** QC pages are currently under development, and their look and functionality will change in future releases.
-
-If you have enabled it in your pipeline configuration, the CPAC Quality Control (QC) interface is an efficient way to rapidly view the outputs of a CPAC run. For each subject, CPAC generates an HTML file containing images of each output and additional information such as motion parameters and signal-to-noise ratios.
-
-.. figure:: /_images/qc_main.png
-
-Though it is possible to view the QC page for each subject individually, we recommend generating a combined QC page that lets you easily navigate between subjects. To do this, open a python terminal and run the following command::
-
-  import CPAC
-  CPAC.utils.create_all_qc.run('/path/to/output_directory')
-
-Alternately, it is of course possible to simply view CPAC outputs using the application of your choice. 
diff --git a/docs/user/_sources/running.txt b/docs/user/_sources/running.txt
@@ -0,0 +1,96 @@
+Running C-PAC
+==============
+Overview
+--------
+
+As with configuring the subject list, pipeline configuration, and group analysis files, there are two ways of executing a C-PAC run:
+
+* Using C-PAC's command line interface
+* Using the main dialog in the C-PAC GUI
+
+This page will also discuss how to navigate C-PAC's output structure once a run is finished.
+
+Using the Command Line Interface
+---------------------------------
+Running Preprocessing and Individual-Level Analysis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To start a C-PAC run from the command line or a shell script you can use the `cpac_run.py` utility (which is added to your path automatically upon installing C-PAC).  An example of this tool's syntax is as follows:
+
+.. code-block:: bash
+
+    cpac_run.py /path/to/pipeline_config.yml /path/to/CPAC_subject_list.yml
+
+Using the GUI
+-------------
+
+Running Preprocessing and Individual-Level Analysis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You have already interacted with the *Subject Lists* and *Pipelines* panes in the main dialog in order to create new subject lists and pipeline configurations.  There is, however, more to the main dialog than making new files!  Both panes have a *Load* option that will load in any previously created YAML files.  Additionally, there is a *View* button that allows you to inspect the text of the YAML files for the currently selected subject list or pipeline configuration.  
+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.
+
+The following schematic illustrates the order in which C-PAC executes.
+
+.. figure:: /_images/processing_workflow.png
+
+Subject List
+
+If you would like to use a previously generated subject list, click the *Load* button and select the appropriate YAML 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.
+
+**Note: Do not confuse the *Load* button on the main window of the GUI with the *Load Settings* button on the Subject List Setup window shown above.  The latter button is intended to load data configuration files that the subject list setup dialogue can use to create subject lists and will not work with other YAML files.  The former button is for already generated subject list files.**
+
+Pipeline
+
+To modify an existing pipeline, select it and click *Edit*. 
+To use a previously configured pipeline, click *Load* and select the appropriate pipeline configuration file. If you have loaded multiple pipelines, use the checkboxes to select which pipelines you would like to run. 
+
+Running Group-Level Analysis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When you are finished configuring the pipeline for group-level analysis, click save. When you are ready to run group-level analysis, select the subject lists and pipelines you would like to run and click the Run Group Level Analysis button. You will be presented with a dialog and asked to select which strategies you would like to include.
+
+Output Structure
+----------------
+
+Symbolic Links
+^^^^^^^^^^^^^^
+C-PAC gives you the option of creating an output directory containing `symbolic links <http://en.wikipedia.org/wiki/Symbolic_link>`_ to processed files. We strongly recommend this setting be enabled, as it makes it much easier to navigate output files. The following schematic shows the structure of the resulting :file:`sym_links` directory:
+
+.. figure:: /_images/symlink_structure.png
+
+Pipeline and strategy folders are named as described above. 
+
+File Descriptions
+^^^^^^^^^^^^^^^^^
+Preprocessed anatomical data from the Anatomical Preprocessing, Registration, and Segmentation workflows can be found in :file:`../scan/anat/` directory for each subject. The following diagram shows processing steps and standard output files for these workflows.
+
+.. figure:: /_images/anat_prepro_schematic.png
+
+Preprocessed functional data from the Functional Preprocessing workflow can be found in the :file:`../scan_<name>/func` directory for each subject. The following diagram shows processing steps and standard output files for this workflow.
+
+.. figure:: /_images/functional_preprocessing.png
+
+Derivative Outputs
+^^^^^^^^^^^^^^^^^^
+Derivatives for each subject can be found in the :file:`../scan_<name>` directory of each subject. This folder also contains the outputs of the registration and segmentation workflows.
+
+.. figure:: /_images/derivs_outputs.png
+
+Within each derivative folder will be sub-folders for each set of frequency filters set in :file:`config.yml`, as well as a folder containing smoothed outputs.
+
+Derivatives are output in both native space (:file:`*_img.nii.gz` and :file:`*_map.nii.gz` files), with values transformed to z-scores (:file:`*_Z_*.nii.gz`) and in standard space (:file:`*_to_standard.nii.gz`).
+
+QC Interface
+-------------
+**Note:** QC pages are currently under development, and their look and functionality will change in future releases.
+
+If you have enabled it in your pipeline configuration, the C-PAC Quality Control (QC) interface is an efficient way to rapidly view the outputs of a C-PAC run. For each subject, C-PAC generates an HTML file containing images of each output and additional information such as motion parameters and signal-to-noise ratios.
+
+.. figure:: /_images/qc_main.png
+
+Though it is possible to view the QC page for each subject individually, we recommend generating a combined QC page that lets you easily navigate between subjects. To do this, open a python terminal and run the following command::
+
+  import CPAC
+  CPAC.utils.create_all_qc.run('/path/to/output_directory')
+
+Alternately, it is of course possible to simply view C-PAC outputs using the application of your choice. 
diff --git a/docs/user/_sources/subject_list_config.txt b/docs/user/_sources/subject_list_config.txt
@@ -4,6 +4,8 @@ Overview
 --------
 For C-PAC to run an analysis, it must have at least one pipeline configuration file and one subject list.  The creation of a pipeline configuration file is treated in the next section.  This section will deal with how to create a C-PAC subject list.  There are two ways to set up such a list:
 
+In order to run C-PAC, 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>`.
+
 * Using a text editor (useful for servers where using the C-PAC GUI is not possible or impractical)
 * Using the subject list builder interface in the C-PAC GUI
 
@@ -72,21 +74,16 @@ First, open the C-PAC GUI by entering the command ``cpac_gui`` in a terminal win
 
 .. figure:: /_images/main_gui.png
 
-In order to run C-PAC, 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 YAML 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.
-
-If you do not already have a subject list file prepared, click on the *New* button next to the *Subject Lists* box.  This will bring up the following dialog window:
+Now, to generate a subject list file, click on the *New* button next to the *Subject Lists* box.  This will bring up the following dialog window:
 
 .. figure:: /_images/subject_list_gui.png
 
 Each of the options in this window will now be described in the sections below.
 
-**Note: Do not confuse the *Load* button on the main window of the GUI with the *Load Settings* button on the Subject List Setup window shown above.  The latter button is intended to load data configuration files that the subject list setup dialogue can use to create subject lists and will not work with other YAML files.  The former button is for already generated subject list files.**
 
 Defining Anatomical and Functional File Path Templates
 -------------------------------------------------------
-CPAC has been designed to process large, complex data sets, and supports processing of multiple scans per subject, multiple scan sessions, and multiple data acquisition sites with differing scan acquisition parameters. Because the file directory structures resulting from such data sets can be complex, it is necessary to manually define the location of the image files to be processed for each subject.
+C-PAC has been designed to process large, complex data sets, and supports processing of multiple scans per subject, multiple scan sessions, and multiple data acquisition sites with differing scan acquisition parameters. Because the file directory structures resulting from such data sets can be complex, it is necessary to manually define the location of the image files to be processed for each subject.
 
 File path templates are defined by adding wildcard characters (``%s``) to the file path of each type of image file to be processed (anatomical and functional). For each file path, you will need to add two of these wildcard characters, one in the place of the acquisition site directory, and one in the place of the subject directory. For example, if the full paths to the image files for :file:`subject_01` were:: 
 
@@ -127,7 +124,7 @@ If you experience difficulties defining file path templates, you may want to re-
 
 Selectively Include or Exclude Subjects
 ---------------------------------------
-By default, C-PAC will process data for all subjects matching the file templates defined above. In many cases however, a user may want to run only a subset of the subjects within a particular data set. In others, a user may want to exclude particular subjects from analysis. This can be done by specifying a list of subjects through the :file:`subjectList` or :file:`exclusionSubjectList` options. Lists can be specified either as a text file or directly in :file:`data_config.yml`. Text files should contain one subject ID per line, with each subject ID matching the name of a subject folder. The same steps can used with the :file:`siteList` option to selectively process data from specific acquisition sites.
+By default, C-PAC will process data for all subjects matching the file templates defined above. In many cases however, you may want to run only a subset of the subjects within a particular data set. In others, you may want to exclude particular subjects from analysis. This can be done by specifying a list of subjects through the :file:`subjectList` or :file:`exclusionSubjectList` options. Lists can be specified either as a text file or directly in :file:`data_config.yml`. Text files should contain one subject ID per line, with each subject ID matching the name of a subject folder. The same steps can used with the :file:`siteList` option to selectively process data from specific acquisition sites.
 
 Set Up Slice Timing Correction
 ------------------------------
