------------------------------------------------
 The CrossSessTools -> Cross Sess Spherical Avg
 menu creates cross-session cross-subject complex
 valued averages using spherical morph surfaces.
 Can also average real-only valued data.
------------------------------------------------
Before running this command, use File -> New
Spherical Avg to create a new empty cross-session
session.

This command samples complex-valued data
(e.g., response amplitude and phase) from
each individual subject's morphed sphere
($hemi.sphere.reg) to the canonical icosahedral
sphere (7th icosahedral sub-tessellation)
surface.  It then averages them in this common
coordinate system and calculates a dispersion
index.  Finally, it resamples the data back
onto an individual subject's morphed sphere
(which allows it to be displayed on any of that
subject's surfaces).

It can also average single-component real
valued data.

Create Average Scandir

Decide upon an informative scandir name, enter it
at the top of the panel, and click Make SphereAvg
Dir to create it.  There can only be one
cross-session scandir per cross-average session.

Select data to average

Click the ADD SESS button one or more times
to create blank session configuration lines.
The DEL LAST button deletes the most recently
added line, whether or not you have altered it.

Then on each line, select Session, Scandir, and
VtListPref in that order from the dropdowns to
select the files to average.  Complex-valued file
typically have _r and _i infixes, which won't be
visible in the dropdown, but which will be used.

To average single-component, real-valued data
instead, select phasetype "w" at the far right
(instead of the complex-valued ecc/pol/2cn
options).  In this case, only the .w suffix
will be stripped so that the _r and _i infixes
of each wfile will be visible.

If phasetype is changed to "w" or from "w" in the
middle of configuring the panel, re-select each
Scandir and VtxListPref dropdown to make sure
that valid file choices are shown (single and
double-component data can't be averaged within
one panel).

Normally, each scan should be the same kind of
scan (though they may all have different names).
There is currently no procedure for reversing the
phase (e.g., for counter-clockwise scans versus
clockwise scans), so the phase direction should
be the same for all subjects (any reversed phase
scans should be first averaged within subjects
using one of the following:

  SessionTools -> Combine 3D Phase Stats
  SessionTools -> Combine Surface Stats

Adjustable parameters -- Hemispheres

First select the hemisphere(s) on which to
operate (right, left or both).  This choice
is saved after the panel has been run.

Adjustable parameters -- Smoothing Steps

This is the number of smoothing steps during
the initial morphed-sphere to icosahedral-sphere
sampling.  The default is 1.  This is set to 0
on the way back to a single subject (that is,
no additional smoothing beyond that implied
by nearest neighbor resampling -- see next).
The data can be further smoothed after resampling
to an individual subject.

Adjustable parameters -- Sample Method: nnf[r]

To sample data onto the target surface, for each
target vertex the closest vertex in the source
surface is found (this is the forward map).
If the sample method is set to nnf (nearest
neighbor, forward), the sampling is now done.
This, however, can leave some source vertices
unrepresented in target (i.e., 'holes').

If nnfr (nearest neighbor, forward and reverse)
is chosen, then each hole is assigned to the
closest target vertex. If a target vertex has
multiple source vertices, then the source values
are averaged together.

The default sampling method is nnfr.  This
applies in both directions (individual subject
-> icosahedral, and icosadedral average ->
display subject).  This choice does not make
much difference for standard fMRI data.

Adjustable parameters -- Phasetype/Color Scale

Finally, select the phasetype (ecc/pol/2cn)
at the far right.  This presets the correct
color scale in the View SphereAvg Data panel
(2cn refers to two condition data analyzed by
fourier methods).

If the last option, "w" is selected, all *.w
files in the current scandir are shown in the
VtxListPref dropdowns (i.e., the _r and _i
infixes are not stripped).  Select this option
to average single-component real-valued data.

Run Sphere Average

Once every scan line is configured, click
SPHEREAVG at the top right to sample each
subject's data onto the spherical (7th
icosahedral sub-tessellation) surface, and
average it (complex valued vector average).

All the fields have to be filled in before this
SPHEREAVG will run.  The subject field can't
be edited (it is looked up from what is found
in each $session/image/name file).  The morphed
surface can't be edited either, so the surfaces
$hemi.sphere.reg must exist for every subject
(first run SubjectTools -> Register Surface for
each subject).

Since the per-subject parts of this command
take a long time, a progress window comes up,
noting when the processing for each input file
has been completed (there are potentially
4 files for each configured line: right and
left hemisphere, real and imaginary data).
The progress window resets itself during the
shorter final averaging process.  Clicking the
purple QuitSPHER button once will interrupt
the process.  This will take a moment, since
the processing (sampling or averaging) for the
current file will continue until it is complete.

A dispersion index is also calculated and saved
as left and right hemisphere paintfiles with
infix "_d".  This index

       average amplitude of indiv vectors
d  =   ----------------------------------
          amplitude of vector average

This index equals 1.0 in the limit of perfectly
aligned vectors, independent of their amplitude.
This will not be generated for real-only data.

This index will distinguish a particular-sized
vector average that was generated by a set of
large but inconsistent signals from a same-sized
vector average generated by a set of smaller
but more consistent signals.

Here is a schematic overview of the commands
that are run by SPHEREAVG:

  ## for each member of average
  foreach subj/sess {
    mri_surf2surf -- sample wfile to ico bfloat
    bresize       -- wrap 1D ico bfloat to '2D'
    to3d          -- convert pseudo 2D to BRIK
    3dcalc        -- calculate indiv amplitude
    3dcalc        -- trunc BRIK to short
  }
  ## average
  3dttest     -- cross-subj avg,ttest (real,imag)
  3dcalc      -- calculate dispersion index
  brik2bfloat -- conv avg,tstat to folded bfloat
  bresize     -- unfold bfloat (for display subj)

To see the exact detailed arguments to each of
these programs, click the SPHEREAVG button,
let if finish, quit csurf, and then look in
the csurf.log file (which is generated in the
current session scripts dir on quitting).

Sample to Single Subject

To sample the average and dispersion index
onto the surfaces of a single subject, click
SAMP2SUBJ. To change the display subject, select
a different subject from the "display subject"
dropdown.  This will edit the name file.

The view the average data and save bitmaps,
use CrossSessTools -> View SphereAvg Data,
which brings up a copy of the SessionTools ->
View Functional Data, and which has an identical
layout and function to it.
