-------------------------------------------
 The SessionsTools -> Combine 3D Phase Stats
 menu averages fourier-analyzed 3D stats
-------------------------------------------
This panel creates a new scan directory that will
contain averaged 3D fourier-based statistics.

Configure Buttons--Make CombineDir, Unset Dir

First carefully choose a name for the average
directory in the entry to the right of the Make
CombineDir button (you will be prompted to change
the default name, "phavg").  Then, click the Make
CombineDir button to create the directory.  If
the directory already exists, it will be re-used
rather than re-created.

To ignore an existing 3D phase average directory,
use Unset Dir.  The files in the unset directory
will not be altered and any saved parameters will
re-appear if you click Make CombineDir with that
directory name again.

The 3D stats files are combined voxel-by-voxel.
This ignores the funct=>struct transformation
matrix (register.dat) and relies on accurate 3D
cross scan alignment (typically via 3dvolreg run
in the Setup Align/Funct panel).

The transformation matrix for the combined file
is copied from the *first* scan in the scans to
combine list.  This transformation matrix gets
used when the combined file is PAINT'ed onto the
surface.  Be sure to re-COMBINE in order to redo
this copy register operation if you go back and
touch up the transformation matrix from the first
input scan (adjustments to later stat sets in the
list are ignored) and you want the that modified
transformation matrix to be used for PAINT in
this panel.

Choosing Stat Files to Average

A list of currently available fourier-analyzed
functional scans can be found in the "Select to
Add" dropdown combobox.  Selecting one of them
will add it to the "ScansToCombine" list.  To
delete (or re-order) a directory from that list,
select it in the list and then use the Delete or
Backspace key.

The input files for this panel are generated by
the "Calculate 3D Fourier Stats panel".  They can
either be:

  (1) a real/imaginary pair of bfloat slice
      series containing complex-valued
      significance calculations for each run
      (usu. sqrt-F)

  (2) the same data put into a real/imaginary
      AFNI BRIK pair aligned with the raw data
      (easier to manipulate and view)

  (3) a full Fourier transform of the time
      series data without any significance
      calculation, put into a real/imaginary pair
      of 4D AFNI BRIKs (relevant for operation:
      average full FT)

In the first two cases, the *output* files
will be the same format as the input (bfloat
or BRIK).  In the third, case, the output is
always a BRIK.

Reversing Phase of Stat Files

If scans to be combined do not have the same
phase direction (e.g., clockwise vs. counter-
clockwise direction of the moving sector in a
polar angle mapping experiment), the phase of one
or more scans can be reversed by selecting the
scan to be reversed, and then typing Return.
"Reversing the phase" means taking the negative
of the phase angle calculated for each voxel.
This is equivalent to reversing the direction of
time in the time domain.

Combine Operations

Next select a combine operation.  The operation
"vect avg complex sigs" (original default)
calculates the voxel-by-voxel vector average of
the the complex-valued significance calculation
(i.e., separately average real and imaginary
components).

The operation "phasecancel 2 cpx sigs" calculates
the voxel-by-voxel angular average of 2 opposite
phase-direction scans and then separately
averages the amplitudes (separately average phase
and amplitude components).

In the first case, if two vectors with large
amplitude have very different angles, the
amplitude of their vector average will be small;
in the second case, it will be large.  Thus, the
'phaseaverage' operation more strongly penalizes
voxels with inconsistent phase in the component
scans.  Currently, the 'phasecancel' operation
can only combine two scans.

The advantage of both of these methods is that
they can combine data from scans with different
numbers of timepoints and different stimulus
frequencies.

The third operation, "vect avg full FT's, do sig"
is a better method of combining scans with
identical numbers of data points and identical
stimulus frequencies.  It first averages the full
Fourier transforms of each individual time course
(this requires that the FOURIER button was run
with "full FT" clicked).  Then, in a second step,
the significance is calculated as before (F-ratio
computed from Fourier amplitude at the stimulus
frequency compared to fourier amplitude at
other/noise frequencies).  It uses the settings
(stim cycles, noise cutoffs) from the Fourier
panel from the first scan in the average.

It takes advantage of the fact that the noise
frequencies generally have different phases in
different runs, while the stimulus frequency will
have the same phase -- which increases the
contrast between signal and noise in the average.

This method is similar to averaging raw time
courses (with or without time reversal).  The
advantage is that a hemodynamic delay in the
stimulus frequency phase can be properly
introduced when combining scans with opposite
phases -- namely, *before* reversing the phase.
This is harder to do in the time domain.

Phase Offset

The measured response phase consists of a
stimulus phase plus a hemodynamic delay phase.
If scans are combined with opposite directions of
phase, the hemodynamic delay phase can be
subtracted out.  However, if the operation
'phaseaverage' is used, this will reduce the
amplitude of the vector average (there is no
effect of a hemodynamic delay on the
'phasecancel' operation and no effect of a
non-zero offset in this panel).  To avoid this
reduction in amplitude, an estimated average
hemodynamic delay (in units 0.0 to 1.0, where 1.0
equals one full stimulus cycle) can be applied
prior to the 'phaseaverage' operation.

Action Button--COMBINE

This button performs the 3D phase average of the
fourier-analyzed data sets that you have selected
using the operation selected, and writes the
result into the current sig average directory as
a new set of 3D files.

Action Button--PAINT

This button samples the combined data onto the
surface specified in "Surface for Sampling 3D
Data" in the Fourier panel.  The result is four
new files, two for each hemisphere, which consist
of the real and imaginary components of the
combined Fourier statistics (*.w files) which can
be directly displayed on the surface with View
Functional Data panel.  Note that this button
generates files for both hemispheres, regardless
of which hemisphere is currently selected.

##############################
Input File Formats -- 3D/Volume
##############################

 (1) Fourier-analyzed complex sig (bfloat):
     [o riginal slice-based format]
   ---------------------------------------
   sess/scan1/<stem>_r_000.bfloat 
   sess/scan1/<stem>_i_000.bfloat 
   sess/scan1/<stem>_r_001.bfloat 
   sess/scan1/<stem>_i_001.bfloat 
   ...
   sess/scan1/<stem>_r_029.bfloat 
   sess/scan1/<stem>_i_029.bfloat 
   ---------------------------------------
   sess/scan2/<stem>_r_000.bfloat 
   sess/scan2/<stem>_i_000.bfloat 
   sess/scan2/<stem>_r_001.bfloat 
   sess/scan2/<stem>_i_001.bfloat 
   ...
   sess/scan2/<stem>_r_029.bfloat 
   sess/scan2/<stem>_i_029.bfloat 
   ---------------------------------------
   ...

 (2) Fourier-analyzed complex sig (BRIK):
     [new style: volume, easier to view]
     [these BRIK's contain floats]
   ---------------------------------------
   sess/scan1/<stem>_r+orig.BRIK
   sess/scan1/<stem>_r+orig.HEAD
   sess/scan1/<stem>_i+orig.BRIK
   sess/scan1/<stem>_i+orig.HEAD
   ---------------------------------------
   sess/scan2/<stem>_r+orig.BRIK
   sess/scan2/<stem>_r+orig.HEAD
   sess/scan2/<stem>_i+orig.BRIK
   sess/scan2/<stem>_i+orig.HEAD
   ---------------------------------------
   ...

 (3) Full complex Fourier transform (BRIK)
     [N.B.: sig/F-ratio calc not yet done]
     [these BRIK's contain floats, 4x raw]
   ---------------------------------------
   sess/scan1/<stem>_xf+orig.BRIK
   sess/scan1/<stem>_xf+orig.HEAD
   sess/scan1/<stem>_yf+orig.BRIK
   sess/scan1/<stem>_yf+orig.HEAD
   ---------------------------------------
   sess/scan2/<stem>_xf+orig.BRIK
   sess/scan2/<stem>_xf+orig.HEAD
   sess/scan2/<stem>_yf+orig.BRIK
   sess/scan2/<stem>_yf+orig.HEAD
   ---------------------------------------
   ...

##############################
Output File Formats -- 3D/Volume
##############################

 (1) Average complex sig (bfloat):
     [original slice-wise format]
   ---------------------------------------
   sess/phavg/<stem>_r_000.bfloat 
   sess/phavg/<stem>_i_000.bfloat 
   sess/phavg/<stem>_r_001.bfloat 
   sess/phavg/<stem>_i_001.bfloat 
   ...
   sess/phavg/<stem>_r_029.bfloat 
   sess/phavg/<stem>_i_029.bfloat 
   ---------------------------------------

 (2) Average complex sig (BRIK):
     [new style: volume, easier to view]
     [these BRIK's contain floats]
   ---------------------------------------
   sess/scan1/<stem>_r+orig.BRIK
   sess/scan1/<stem>_r+orig.HEAD
   sess/scan1/<stem>_i+orig.BRIK
   sess/scan1/<stem>_i+orig.HEAD
   ---------------------------------------

##############################
Output File Formats -- 2D/vertexlist
##############################

  (1) output of PAINT (avg complex sig):
   ---------------------------------------
   sess/phavg/<stem>_r-rh.w
   sess/phavg/<stem>_i-rh.w
   ---------------------------------------

