= Testing Loss and Gain of Statistical Power =

Surface quality can be tested by tracking change in statistical power between groupstats results of the ADNI60 subjects. The test {{{diff_power}}}, currently located in {{{utils/test/diff_power}}}, locates surfaces regions with the largest change in power. Given a source and reference groupstats test (i.e. thickness of controls vs ADs in dev and stable6), diff_power does the following:
  1.  Subtracts the ''stable6'' sig.mgh from the ''dev'' sig.mgh (producing sigdiff.mgh) and masks any vertices that did not gain or lose significance (default threshold: p=0.05)
  2.  Computes clusters from the masked sigdiff.mgh and locates the vertex of peak change (in either direction) for each cluster
  3.  For the largest ''n,,c,,'' clusters, finds the difference in thickness (between the ''dev'' and ''stable6'') for each individual subject at the peak vertex
  4.  For the top ''n,,s,,'' subjects with the greatest thickness difference, maps the peak vertex from fsaverage to the ''dev'' and ''stable6'' white and pial surfaces and computes the distance between the two
  5.  The results are stored in a {{{summary.log}}} file (in a diffpower output dir underneath the contrast directory), and a script called {{{inspect.sh}}} is created to automatically point the user to the offending surface regions

Here is an example of the cluster information saved in:<<BR>>
{{{/autofs/space/freesurfer/subjects/test/adni60/dev/groupstats_2017-06-25/maps/glm.thickness.lh.sm00/control-ad/diffpower_stable6_0_0/summary.log}}}
{{{
================================================================================
fsaverage cluster:    1
avg change in power:  -1.7761
peak change in power: -4.6965
peak vertex ID:       6560

         peak diff    avg diff        peak        peak       white        pial
subj     thickness   thickness     src-vtx     ref-vtx    vtx-dist    vtx-dist
--------------------------------------------------------------------------------
0657       -2.4819     -2.5324       94065      101722      8.9340      9.5627
0934       -0.4215     -0.1048       94278       93622      0.8505      0.9646
1251        0.3980      0.1895      102093      102358      0.5470      0.6754
}}}
The ''average diff thickness'' column represents the average difference within the cluster.

To view each surface region detailed in the report, run the {{{inspect.sh}}} saved to the diffpower output directory, which will walk through each vertex of interest in freeview.

'''note:''' inspect.sh just links to the most recent recons stored in the freesurfer subject tree; diff power doesn't save any subject data. So visually inspecting the results of diff_power on anything but the most recent groupstats test will be misleading.

=== running diff power ===

diff_power will be added to the ADNI60 testing cronjob that runs weekly on launchpad, but if it needs to be run manually, here is the usage:

{{{
required:
    --src <dir>        source groupstats directory
    --ref <dir>        reference groupstats directory
    --contrast <name>  contrast name as listed in group.fsgd (e.g. control-ad)
    --test <var>       test variable (e.g. thickness)

optional:
    --thresh <float>   -log(P) significance threshold (default: 1.301)
    --smooth <int>     specify smoothing (default: 00)
}}}