Updated group analysis documentation. Added example files and clarified that categorical variable levels can be strings.

Author: jpellman

docs/user/_images/ga_contrast_csv.png

@@ -14,6 +14,11 @@ The following presentation also gives a good overview of the group analysis user
 
 * https://docs.google.com/presentation/d/1cJVNeNSK8Uy8UTzN6mMG4YR5YLqnpV4HopqsKZbma5k/pub?start=false&loop=false&delayms=10000#slide=id.p
 
+The example files used in the presentation above are also available below for your perusal:
+
+* `A Subject List <_static/subject_list_group_analysis.txt>`_
+* `A Phenotype File <_static/example_phenotypic_file.csv>`_
+
 Configuring CPAC to Run FSL Group Analysis
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -28,9 +33,9 @@ Specifying Models to Run
 
 .. figure:: /_images/ga_model_setup.png
 
-#. **Subject List - [path]:** Full path to a list of subjects to be included in the model. This should be a text file with one subject per line.  A list in this format containing all subjects run through CPAC was generated along with the main CPAC subject list (see subject_list_group_analysis.txt). Another easy way to manually create this file is to copy the subjects column from your Regressor/EV spreadsheet.
+#. **Subject List - [path]:** Full path to a list of subjects to be included in the model. This should be a text file with one subject per line.  A list in this format containing all subjects run through CPAC was generated along with the main CPAC subject list (see the subject list in `Overview`). Another easy way to manually create this file is to copy the subjects column from your Regressor/EV spreadsheet.
 
-#. **Phenotype/EV File -[path]:** Full path to a .csv file containing EV information for each subject. Tip: A file in this format (containing a single column listing all subjects run through CPAC) was generated along with the main CPAC subject list (see template_phenotypic.csv).
+#. **Phenotype/EV File -[path]:** Full path to a .csv file containing EV information for each subject. A file in this format (containing a single column listing all subjects run through CPAC) was generated along with the main CPAC subject list (see the phenotype file in `Overview`).  Levels for categorical variables in this file can be expressed as words ('ADHD'/'TD') or numerical values (0/1) depending on your preferences.
 
 #. **Subjects Column Name [text]:** Name of the subjects column in your EV file.
 
@@ -73,7 +78,7 @@ Specifying Contrasts
     * **>** Greater than
     * **+** Positive
     * **-** Negative
-    For categorical contrasts, use the + and - operators.  Using a phenotype file with two groups coded as 1 or 2 will produce an EV for 'group2'.  'group2+' will perform the contrast 'group 2 > group 1' and 'group2-' will perform the contrast 'group 1 > group 2'.  Using these two operators avoids issues of multicollinearity introduced by dummy coding.
+    For categorical contrasts, use the + and - operators.  Using a phenotype file with two groups coded as 'ADHD' or 'TD' will produce an EV for 'TD'.  'diagnosisTD+' will perform the contrast 'TD > ADHD' and 'diagnosisTD-' will perform the contrast 'ADHD > TD'.  Using these two operators avoids issues of multicollinearity introduced by dummy coding.
 
 #. **f-Tests - [checkboxes]:** Define an f-test by selecting two or more contrasts to include.  When you are done, select the f-tests that you wish to run.  
 

docs/user/_images/ga_contrast_ftest.png

@@ -0,0 +1,9 @@
+subject_id,sex,diagnosis,age
+1019436,1,ADHD,12.98
+2014113,1,ADHD,10.3452054795
+3154996,1,ADHD,11.65
+3699991,1,TD,12.7726027397
+3884955,1,TD,11.84
+3902469,1,TD,10.6356164384
+4275075,0,ADHD,10.5
+7774305,0,TD,11.22

docs/user/_images/ga_contrasts.png

@@ -0,0 +1,8 @@
+1019436
+2014113
+3154996
+3699991
+3884955
+3902469
+4275075
+7774305

docs/user/_images/ga_contrasts_populated.png

@@ -56,6 +56,11 @@ <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this head
 <ul class="simple">
 <li><a class="reference external" href="https://docs.google.com/presentation/d/1cJVNeNSK8Uy8UTzN6mMG4YR5YLqnpV4HopqsKZbma5k/pub?start=false&amp;loop=false&amp;delayms=10000#slide=id.p">https://docs.google.com/presentation/d/1cJVNeNSK8Uy8UTzN6mMG4YR5YLqnpV4HopqsKZbma5k/pub?start=false&amp;loop=false&amp;delayms=10000#slide=id.p</a></li>
 </ul>
+<p>The example files used in the presentation above are also available below for your perusal:</p>
+<ul class="simple">
+<li><a class="reference external" href="_static/subject_list_group_analysis.txt">A Subject List</a></li>
+<li><a class="reference external" href="_static/example_phenotypic_file.csv">A Phenotype File</a></li>
+</ul>
 </div>
 <div class="section" id="configuring-cpac-to-run-fsl-group-analysis">
 <h2>Configuring CPAC to Run FSL Group Analysis<a class="headerlink" href="#configuring-cpac-to-run-fsl-group-analysis" title="Permalink to this headline">¶</a></h2>
@@ -72,8 +77,8 @@ <h3>Specifying Models to Run<a class="headerlink" href="#specifying-models-to-ru
 <img alt="_images/ga_model_setup.png" src="_images/ga_model_setup.png" />
 </div>
 <ol class="arabic simple">
-<li><strong>Subject List - [path]:</strong> Full path to a list of subjects to be included in the model. This should be a text file with one subject per line.  A list in this format containing all subjects run through CPAC was generated along with the main CPAC subject list (see subject_list_group_analysis.txt). Another easy way to manually create this file is to copy the subjects column from your Regressor/EV spreadsheet.</li>
-<li><strong>Phenotype/EV File -[path]:</strong> Full path to a .csv file containing EV information for each subject. Tip: A file in this format (containing a single column listing all subjects run through CPAC) was generated along with the main CPAC subject list (see template_phenotypic.csv).</li>
+<li><strong>Subject List - [path]:</strong> Full path to a list of subjects to be included in the model. This should be a text file with one subject per line.  A list in this format containing all subjects run through CPAC was generated along with the main CPAC subject list (see the subject list in <cite>Overview</cite>). Another easy way to manually create this file is to copy the subjects column from your Regressor/EV spreadsheet.</li>
+<li><strong>Phenotype/EV File -[path]:</strong> Full path to a .csv file containing EV information for each subject. A file in this format (containing a single column listing all subjects run through CPAC) was generated along with the main CPAC subject list (see the phenotype file in <cite>Overview</cite>).  Levels for categorical variables in this file can be expressed as words (&#8216;ADHD&#8217;/&#8217;TD&#8217;) or numerical values (0/1) depending on your preferences.</li>
 <li><strong>Subjects Column Name [text]:</strong> Name of the subjects column in your EV file.</li>
 <li><strong>Model Setup - [checkboxes]:</strong> A list of EVs from your phenotype file will populate in this window. From here, you can select whether the EVs should be treated as categorical or if they should be demeaned (continuous/non-categorical EVs only). &#8216;MeanFD&#8217; and &#8216;Measure Mean&#8217; will also appear in this window automatically as options to be used as regressors that can be included in your model design. Note that the MeanFD and mean of measure values are automatically calculated and supplied by C-PAC via individual-level analysis.  Also, MeanFD and mean of measure values are automatically demeaned prior to being inserted into the group analysis model.</li>
 <li><strong>Design Matrix Formula - [Patsy formula]:</strong> Specify the formula to describe your model design. Essentially, including EVs in this formula inserts them into the model. The most basic format to include each EV you select would be &#8216;EV + EV + EV + ..&#8217;, etc. You can also select to include MeanFD and Measure_Mean here. Note that this design formula is pre-generated for the user depending on the EVs in the phenotype file, but can be edited at any time. C-PAC uses the Python library Patsy to generate the design matrices, so more information on how to format your design formula for specific designs can be found here- <a class="reference external" href="https://patsy.readthedocs.org/en/latest/formulas.html">Patsy formula documentation</a>.  If you have used R in the past, Patsy&#8217;s formula syntax should be familiar.</li>
@@ -107,7 +112,7 @@ <h3>Specifying Contrasts<a class="headerlink" href="#specifying-contrasts" title
 <li><strong>+</strong> Positive</li>
 <li><strong>-</strong> Negative</li>
 </ul>
-<p class="last">For categorical contrasts, use the + and - operators.  Using a phenotype file with two groups coded as 1 or 2 will produce an EV for &#8216;group2&#8217;.  &#8216;group2+&#8217; will perform the contrast &#8216;group 2 &gt; group 1&#8217; and &#8216;group2-&#8216; will perform the contrast &#8216;group 1 &gt; group 2&#8217;.  Using these two operators avoids issues of multicollinearity introduced by dummy coding.</p>
+<p class="last">For categorical contrasts, use the + and - operators.  Using a phenotype file with two groups coded as &#8216;ADHD&#8217; or &#8216;TD&#8217; will produce an EV for &#8216;TD&#8217;.  &#8216;diagnosisTD+&#8217; will perform the contrast &#8216;TD &gt; ADHD&#8217; and &#8216;diagnosisTD-&#8216; will perform the contrast &#8216;ADHD &gt; TD&#8217;.  Using these two operators avoids issues of multicollinearity introduced by dummy coding.</p>
 </dd>
 </dl>
 </li>