-------------------------------------------
 The SessionsTools -> Combine Surface Stats
 menu averages already-painted surface stats
-------------------------------------------
This panel creates a new scan directory that
will contain averaged surface-based statistics
(possibly cross-session).

Configure Buttons--Make SurfAvg Dir, Unset Dir

First carefully choose a name for the average
directory in the entry to the right of the Make
Avg Dir button.  Clicking Make SurfAvg Dir
creates that directory.  If the directory already
exists, it will be re-used rather than
re-created.

To ignore an existing surface 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 SurfAvg Dir with that
directory name again.

Choosing Stat Files to Average

Choosing the pre-painted stats to average is a
three-part process.

First select a session from which a scan will be
chosen, by selecting a session using the
"Functional Sessions to Choose From" dropdown
combo box at the top.  This allows you to average
scans across different sessions, as long as they
are in the current Functional Sessions directory
($FUNCTIONALS_DIR).  The statistics to average
must have been painted using a single subject's
surface (the same version of it!).  If you want
to select a scan from the currently open session,
you have to hit 'Enter' in the combo box.

Second, once you have selected a session, the
dropdown combo box on the next line at the left
("Select Both", meaning both hemispheres) will
now contain the individual scan directories in
that session.  Select one scan directory.  If the
scan directory contains pre-painted data, the
dropdown combo box immediately to the right
("Vertex List Prefix") will be updated.

Finally, select one of the pre-painted vertex
list prefixes in the "Vertex List Prefix"
dropdown combo box to the right.  If the paint
file is from a retinotopy session, the real and
imaginary infixes will be automatically stripped
(you only need to select either the real or
imaginary file).

Once you have selected one of the paint files,
the full path to it will be added to the central
"Fullpath Vertex Lists to Combine" panel.  To
delete (or re-order) directories from that list,
select one in the list and use the Delete or
Backspace key.

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 (or
double-clicking).  "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

Now select a combine operation.  The operation
'realaverage' simply averages two real-valued
data sets (e.g., F-stats).  The other three
operations average complex data sets and differ
only in how they setup the default color scale
options in the View Functional Data panel.  For
complex data sets, you can introduce a phase
offset for each data set that differs from zero
(see below).

Use Script, New Script checkbox

If the "Use Script" checkbox is selected, a
editable combine script will be created (IRIX
only, using binary: surfcombine).  Checking "New
Script" overwrites/re-generates a fresh version
of this file if it already exists.

Action Button--SURFCOMBINE

This button performs a surface-based average of
the pre-painted stats data sets that you have
selected and writes the result into the current
surf average directory as a new set of painted
files (*.w files) which can be directly displayed
on the surface with View Functional Data panel.
Note that this button operates on the files for
both hemispheres, regardless of which hemisphere
is currently selected.

When you click the SURFCOMBINE button with "Use
Script" *un*-checked, the selected paintfiles are
combined (using binary: rcxcombine).

When you click the SURFCOMBINE button with "Use
Script" checked, a small text file with a *.scom
suffix is created and opened using the default
text editor.  This file will be used by the
surfcombine program to do the averaging after you
click "OK" on the alert panel.

You can edit the file in the editor before it
is used.  For example, you can use non-zero
angle_offsets for each file (OK to have a
different angle offset for each file) or the
phase can be reversed for one or more input
files.  Do this by changing the default arguments
of the transform_angles command:

  transform_angles <revphaseflag> <angle_offset>
                     default=0     default=0.0

The commands that can be placed in the *.scom
file and their arguments are:
-----------------------------------------
[set data source directory]

  setdir <directory_path>

[read data onto top of stack, multiple reads push]

  read_real    <stem-hemi.w>
  read_complex <stem_r-hemi.w> <stem_i-hemi.w>

[operate on data on top of stack, in place]

  smooth_real    <steps>
  smooth_complex <steps>
  transform_angles <revphaseflag:0,1> <angle_offset:0-1>
  thresh_real <thresh>
  sigmoid_real <fmid> <fslope>  [f=(1+tanh(fslope*(f-fmid)))/2]
  sigmoid_complex <fmid> <fslope>  [operate on, scale amp]
  abs_real
  abs_complex

[operate on data across stack, output pushed onto top]

  average_real    <numfiles>
  average_complex <numfiles>
  max_real    <numfiles>
  max_complex <numfiles>

[write data, top of stack -- orig format wfiles]

  write_real <stem-hemi.w>
  write_complex <stem_r-hemi.w> <stem_i-hemi.w>

[write data, top of stack -- curv format wfiles]

  write_real_cv <stem-hemi.w>
  write_complex_cv <stem_r-hemi.w> <stem_i-hemi.w>
-----------------------------------------

Input and Output Files

 infiles (paint files--complex data example):

   ----------------------------------
   session1/scandir1/scanname1_r-rh.w
   session1/scandir1/scanname1_i-rh.w
   session1/scandir1/scanname1_r-lh.w
   session1/scandir1/scanname1_i-lh.w
   ----------------------------------
   session2/scandir1/scanname1_r-rh.w
   session2/scandir1/scanname1_i-rh.w
   session2/scandir1/scanname1_r-lh.w
   session2/scandir1/scanname1_i-lh.w
   ----------------------------------

 outfiles (paint files--complex data example):

   ----------------------------------------
   currentsession/surfavg/scanname1_r-rh.w
   currentsession/surfavg/scanname1_i-lh.w
   ----------------------------------------
   currentsession/surfavg/scanname1_r-lh.w
   currentsession/surfavg/scanname1_i-lh.w
   ----------------------------------------

