-------------------------------------------
 The SessionsTools -> Combine 3D Raw Images
 menu averages/concatenates raw funct data
-------------------------------------------
The basic layout of this panel (scan directories
to the left, common action button at the top,
pages of parameters to the right) is similar to
the other SessionTools panels.  For more details,
see Help -> Setup Align/Funct.

This panel creates a new scan directory that
will contain averaged scans.

Configuration Buttons--Make Avg Dir, Unset Dir

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

To ignore an existing raw avg/concat directory,
use Unset Dir.  The files the unset directory
will not be altered and any saved parameters will
re-appear if you Make Avg Dir with that directory
name again.

Operation

Selected scans can either be averaged, time point
by time point, or concatenated.

Choosing Scans to Combine

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

Reversing time

For the 'Average' operation (but not for the
'Concatenate' operation), the direction of time
can be reversed on a scan-by-scan basis (e.g., to
obtain average time courses for reversed
phase-encoded scans) by ticking the checkboxes
(by selecting a ScanToCombine and hitting
<Return>).

Time Offset of Reversed Scans

Time-reversed scans can also be time-shifted to
compensate for hemodynamic delay before
averaging.  The units are TR's (default is 0, no
time shift).  All reversed scans are time-shifted
by the same amount.  The number entered must be
an integer.

Since only the reversed scans are time-shifted,
twice the estimated hemodynamic delay (in integer
units of TRs) should be entered.

A positive number -- e.g. 4 -- means that the
reversed time series will be shifted by 4 TR's
(moved back in time before averaging) to
compensate for hemodynamic delay.  Un-reversed
scans are never altered.  A negative number of
TR's is accepted (e.g., for an asymmetrical
reversed paradigm).

Empty values in the reversed scans after
time-shifting are padded with the average of the
two end values (versus wrapping time, which can
introduce an artifactual step, since there will
in general be an uncorrected ramp in the raw
data).

Note that the resulting average will still
contain a hemodynamic delay equivalent to that of
a single unreversed run.  This can be compensated
for at display time by incrementing the value of
$angle_cycles.  Since the units of angle_cycles
are 0.0 to 1.0, where 1.0 equals the time of 1
cycle, if the cycle time was 64 secs/cycle, then
a 4 sec hemodynamic delay equals 1/64 cycles/sec
* 4 sec equals an angle_offset of 0.0625 (this
offset should be added onto the default
angle_cycles, which is 0.0 or 0.5 depending on
hemisphere).

The hemodynamic delay may not be the same at
every voxel.  By reversing time, fixed per-voxel
*differences* in hemodynamic delay are cancelled.
However, the bulk hemodynamic delay itself must
still be estimated (or measured).

Action Button--COMBINE

This button performs averages or concatenates the
3D time series data sets and writes the result
into the current raw average directory as a set
of BRIK's.  Also works on old-style
<stem>_%03d.bshort files, each of which contains
all the timepoints for a single slice (first
slice is 000).  Each *.bshort must have a
matching single-line ASCII *.hdr file:

  <y> <x> <t> 0

The registration matrix from the first scan is
copied into the raw avg/concat directory and by
convention, the first scan in the average is used
as the output file stem:

 infiles (several x-y-z-t images):

   scandir1/scanname1[-vreg]+orig.BRIK
   scandir2/scanname2[-vreg]+orig.BRIK

 outfile (one x-y-z-t image):

   avgdir/scanname1[-vreg]+orig.BRIK

If the scans have been volume-registered with
3dvolreg ("vreg" infix), those will automatically
be used.  Otherwise, the original raw scans are
used.  The averaging is done in 3D without any
additional registration.  Note that register.dat
files are ignored.

Other Files Generated by "Concatenate"

If the COMBINE operation is concatenate, an AFNI
boundary file, runs.1D, is automatically created
(units are TRs).  If the time series is analyzed
using deconvolution, this file is consulted to
prevent stimulus events at the end of one run
from accounting for variance at the beginning
of the next run.

If motion correction has been run on the
individual scans, a concatenated motion.1D file
will also automatically be generated.

Finally, if paradigm files are present in a
paradigm subdirectories (default: stim1Ds/) of
each scan to be concatenated, the paradigm files
for each condition will be separately
concatentated and placed in a paradigm directory
in the new concatenated scandir.  For the
automatic concatenation of paradigm 1D files to
work correctly, the paradigm files in the stim1Ds
subdir in each of the scan dirs to be
concantentated *must* be named as follows:

  scan1
    face1.1D
    house1.1D
  scan2
    face2.1D
    house2.1D
  ...

That is, the condition name stem (up to the
number before the .1D suffix) much be exactly
the same across all scans to be concatentated.
The stem must be immediately followed by a single
numeral before the .1D suffix.

The list of conditions (1D files) to concatenate
is taken from the first directory in the list.
That is, each successive scan should have
the same set of conditions in it.  It's OK if
numerals are the same across scans (e.g., same
randomization in those scans).  The concatenated
paradigm file will be given a name that has the
numeral position replaced by a 'C'.

Touch up

If you averaged the data, at this point you
may want to go back to SessionTools -> Setup
Align/Funct Scans to touch up the FUNCT=>SUBJ
registration for the averaged scan.

