-------------------------------------------
 The SessionsTools -> Setup Align/Funct Scans
 menu sets up the basic image parameters for
 functional and alignement scans in preparation
 for statistical analysis and rendering.
-------------------------------------------
On the left of this panel is a list of the
subdirectories in the current scan session.  On
the right are a set of pages of buttons and
entries -- a separate set for each alignment or
functional scan directory.

The first time you bring up this panel, all the
pages on the right of the panel will be blank
(regardless of which scan directory is selected,
no parameters appear on the right).

To configure a particular directory, select it
from the list on the left (it should be marked
green) and then click one of the buttons at the
top center of the panel to declare it to be
either a "Funct Scan Dir" or an "Align Scan Dir".

A "Funct Scan Dir" should contain one functional
scan, with multiple images/timepoints for each
slice.  An "Align Scan Dir" should contain a
T1-weighted scan that is (1) taken in the same
plane as the functional scans, and (2) also has
the same slice block center as the functional
scans.  It will usually have a higher resolution
that the functional scans (e.g., 1x1x2 mm for a
3x3x3 mm functional scans).

To save the current configuration of all of the
scan directories in the current session, hit Save
or Save/Close at the bottom of the panel.  You
can move between directories without losing any
configuration information as long as you do not
exit the panel.  Hitting Cancel will exit the
panel and leave the configuration in whatever
state it was when you first opened the panel.

The bottom buttons only affect the configuration
metadata for the the scan directories.  This
information is stored in an ASCII file:

  csurf.dat

which is located in the funct scripts directory:

  $FUNCTIONALS_DIR/$session/image/scripts

The Save/Close and Save buttons do not affect any
of the data files in the scan directories.

Ignored directories

The following directories are ignored by
Setup Align/Funct scan:

  scripts  (and scripts~)
  rgb  (and rgb~)
  tmp  (and tmp~)
  mpg
  irp
  shim
  raw

-------------------------------------------
(1) Configure the Alignment Scan
-------------------------------------------

Once a directory has been declared to be an
"Align Scan Dir", the first step is to read the
header of a file (or an example file if
slice-based).  All the files within the current
scan directory will be present in the "Image
File:" dropdown combo box.  Select one of the
files (e.g., alignscan+orig.BRIK).  Then click
"READ HEADER" to attempt to read the parameters
for this file.  Verify that all the fields have
been filled in correctly.  Any fields that say
"-unset-" need to be set manually.

Now click the INIT button near the bottom of the
panel to create an initial default transformation
matrix (the identity matrix).  This is equivalent
to assuming that the Align scan and the Subject
scan used to make the surface are already aligned
(they often are *not* aligned).  A panel will say
this was done automatically if you forget to do
this before hitting the "Align=>Subj" button.
You can also use the INIT button to start over.

The adjacent INIT/FLIP button does the particular
3D transpose needed for a typical (e.g., Siemens)
transverse EPI scan (or an alignment scan with
slice orientation and block center copied from a
functional scan).  If you use INIT/FLIP, verify
that the L/R flip done is correct (you can tell
it is wrong if it is impossible to accurately
register to the target).

tkregister Sampling Policy

The original tkregister *truncated* the
transformed floating point coordinates before
doing a nearest neighbor sampling of the moveable
volume.  MGH tkregister2 and bbregister *round*
before sampling (better, b/c invertible).  The
tkregister in csurf can do either kind of
sampling (as can paint, tkmedit, and tksurfer).

To the right of the INIT and INIT/FLIP buttons is
a checkbutton, "init round".  If no register.dat
yet exists, the default is for it to be selected.
If register.dat already exists, the button state
will be determined by reading the file.  INIT or
INIT/FLIP will create either type of register.dat
depending on the state of the "init round"
checkbutton.  All later programs will read the
register.dat to determine what to do.

The sampling policy is specified in register.dat
by an optional line following the transformation
matrix.  If the line is empty or contains
"tkregister", this means truncate.  If the line
contains "round", this means round.  Use "round"
for new data.

-------------------------------------------
(2) Register the Alignment Scan to the original Struct
-------------------------------------------

Now use the "Align=>Subj" button starts up the
registration program (tkregister) with the scans
used to make the surface for this subject as the
TARGET scan, and the alignment scans in the
currently selected directory as the MOVEABLE
scan.

The sole purpose of the tkregister application is
to generate a transformation matrix that maps the
alignment scan onto the scans used to make the
subject's surface.  The only file that tkregister
affects is:

  register.dat

one of which will be located in each scan dir:

  $FUNCTIONALS_DIR/$session/image/$scan

This file contains a 1mm => 1mm linear
transformation matrix (4x4 including rotation,
scaling, and in the fourth column, translation)
and an optional sampling policy line (see above).
During PAINT operations, the register.dat matrix
is used to map the x,y,z location of each surface
vertex into functional voxel coordinates.

See the "Register" Help menu item for tips on
how to register data sets.

Once the data sets have been aligned to your
satisfaction, hit the SAVEREG button on the
tkregister application to save it (it will backup
the previous registration matrix to the file
register.dat~).  Then quit the tkregister
application (using same now-purple button you
started it with).

-------------------------------------------
(2) Configure the Functional Scans
-------------------------------------------

Now select each functional scan in the listbox at
the left and configure each one as a "Funct Scan
Dir" (top left button).  Click READ HEADER and
check for missing or "-unset-" parameters.

Don't run the FUNCT=>SUBJ register button yet.
Check that the combox box labeled "SamePlane
AlignDir:" has auto-selected the alignment scan
(select it from the dropdown if it wasn't).

Slice time correction

There are two alternate methods for doing this,
which may be optionally used in the later
"Calculate 3D Fourier Stats" panel for correcting
the calculated response phase.  The default is no
correction (assume slices all within a TR were
collected at same time).  No correction is a safe
choice.

Slice time: explicit order specification

The first method is to explicitly specify the
order of slice acquisition using the row of
"Slice Ord:" buttons in the middle of the panel:

  simul  odev  evod  odevr  evodr  asc  desc

which mean:

  simul -- no correction (default: assume simultaneous)
  odev  -- interleaved, odd then even, start lownum slice
  odevr -- interleaved, odd then even, start highnum slice
  evod  -- interleaved, even then odd, start lownum slice
  evodr -- interleaved, even then odd, start highnum slice
  asc   -- ascending, start lowest num slice
  desc  -- descending, start highest num slice

For Siemens product EPI (NON-multiband)
transverse slices, the correct settings are:

  odd number of slices:  odev
  even number of slices:  evod

N.B.: this method does NOT (yet) work for
multiband (SMS) acceleration > 1.

Slice time: read TAXIS_OFFSETS

The second, alternate, method is to read the
within-TR slice time offsets for each slice out
of the AFNI HEAD file for a data BRIK
(TAXIS_OFFSETS field) and put the results into
the "Slice Time Offsets List:" field.  The
"Multiband Accel Factor:" if set by looking for
the number of repeat times in that list.

These will only be correct if the BRIK has been
generated from the IMA (DICOM) file by AFNI to3d
using tpattern equals "FROM_IMAGE".  Using, e.g.,
tpattern "seq+z", "alt+z", etc., will NOT
generate correct TAXIS_OFFSETS.  Versions of
ima2brik >= 0.4b work correctly.

The slice onset times can also be manually pasted
into "Slice Time Offsets List:" as a list of
space-separated times (in sec) beginning from the
start of the TR with slice 1.

If TAXIS_OFFSETS is absent in the AFNI HEAD file,
these fields will be blank (OK to leave them
blank).  Note that some versions of AFNI programs
(e.g., 3dvolreg) do not propagate this field from
input to output.

Slice time: how information is used

Slice time correction information can optionally
be used in the later "Calculate 3D Fourier Stats"
panel for correcting the calculated response
phase.  The ON/OFF buttons for each method are
there -- the default is no correction.  If one or
the other method is selected, the appropriate
option (-slicetiming or -taxisoffsets) will
passed to the "fourier" program when it runs in
the Fourier panel.

Volreg: 3D Motion Correct/CrossScanReg w/AFNI

The AFNI tool, 3dvolreg, should be used for
within scan motion correction and cross-scan
registration using the buttons in the line
labeled "Volreg:".  The combo box labeled "Targ:"
picks the target scan.  It can be the current
scan (default) or any other scan currently
configured as a functional scan.  The field "TR:"
picks the target TR (default 10).

Clicking "CURR" aligns all the other TR's in the
current functional scan with the target TR.

Clicking "ALL" aligns all the TR's in every
currently configured functional scan to the
target TR, which is the typical use if all the
functional prescriptions are the same.

The volume-registered BRIK's are then written
back into the respective scan directories with a
"-vreg" infix.  For example:

 infile:  scandir1/scanname1+orig.BRIK
 outfile: scandir1/scanname1-vreg+orig.BRIK

 infile:  scandir2/scanname2+orig.BRIK
 outfile: scandir2/scanname2-vreg+orig.BRIK

The original BRIK's will be untouched.  The name
of the new volume-register BRIK's will be
inserted into the "Image Name Format" field in
the Setup Align/Funct scans panels.  Note that
this operation doubles the size of the functional
data in each affected scandir.

This program will only run on a bona fide *.BRIK
as an input.  To go back to the original
non-motion corrected data (or to re-run the
3dvolreg program with a different target),
re-select a non-vreg'd "Image File:" and redo
READ HEADER.

Viewing Functional Scans (check motion/register)

If the functional scan is a bona fide *.BRIK
file, you can view it with AFNI by using the AFNI
button (or typing Alt-f in the panel).  This will
start AFNI in the currently selected functional
scan directory.

-------------------------------------------
(4) Copy Alignment Registration to Functionals
-------------------------------------------

Go back to the previously configured Alignment
directory and use the "Copy Align To All Functs"
button to copy the alignscan-to-subjectscan
transformation matrix into each configured
functional scan directory.  This copies the
transformation, taking into account the fact that
the slice thickness and inplane resolution
typically differs between the alignment and
functional scans (specifically: the thickness and
inplane parameters in register.dat are updated;
the transformation matrix is copied unchanged
since it is always 1x1x1mm -> 1x1x1mm).

(4) Verify/Touch-up Functional Scan Registration

Select the first functional scan at the left.
Now register the functional scan directly to the
surface reconstruction scan using the FUNCT=>SUBJ
register button, which starts tkregister again.
Since the functional and alignment scans were
collected in the same plane, the rotation of the
functional scan will be correct.

Alignment/Functional Offset

Any offset between the block centers of the
functional and alignment scans will not be
accounted for.  To correct this, use only the
TRANSLATE buttons from tkregister.  Since the
scan has already been rotated, there will be an
x, y, and z component to the translation.  Change
planes and translate until the functional scan is
aligned.

SubjectsDir Target ImageSet

This is normally the "orig" data set (a COR dir
or an mgz file) used to make the surface:

   $subject/mri/orig
   $subject/mri/orig.mgz

To use a different target data set (path relative
to $subject/mri), change this entry.

Non-Rigid Transformations

Lower-bandwidth, higher signal-to-noise scans may
have additional shearing (e.g., rhomboidal)
distortion.  To correct for a shear, you have to
use a combination of a rotation and a scaling --
a rotation alone won't work.  For example, to
correct a shear in which the left side of the
image is too high and right side too low, do
something like this:

  1) choose a rotation point near the center
  2) rotate 30 degrees to the right
  3) scale 95% in the vertical direction
  4) rotate 30 degrees to the left
  5) scale 105% in the vertical direction

Apply shear or scaling with discretion, only
after completely exhausting attempts to align the
images using rigid body translation and rotation.

Register: Copy Registration Between Functionals

After finishing with one functional, you can copy
the final functional alignment transformation
matrix between functional scans using the CP PREV
button.  Select one scan, then a second, then
click the button.  It will ask you to verify that
you are copying the registration matrix from the
first to the second scan.  To copy the current
directory functional registration to all the
other functionals, use the CP TO OTHERS button.

Same Plane Struct Dir

The drop down chooses the alignment scan
directory.  This is automatically set because
currently there can only be one alignment scan
per session.

BlkCentOff (avoid)

The value (in mm) in "BlkCentOff" is added to the
register.dat file when it is copied between the
alignment scan and the functional scans.  Try to
avoid having to reset this from 0.0 by collecting
alignment scans whose block center is the same as
functional scans.

Sample-to-Surface and Extract Timecourses Options

During the PAINT process (in several different
later panels) and the time course extraction
process (the "label:" line "T" button, see
below), a 3D statistic or rawdata timecourse is
associated with each vertex on the surface by
finding which voxel the vertex lies within.

NormSearch: Vertex Normal Search Op (PAINT, t-course)

First select the normal search type: "mm"
(absolute distance) or "frac" (fraction of
cortical thickness).  Then by entering different
values into the "mn/mx:" field (minumum, maxium)
fields, a search will be performed between those
limits in increments of "dx:" size.

Possible operations (radio buttons at far right)
on the set of statistics recovered in the search
are: "mx" (find largest absolute-valued statistic
along the vertex normal), "av" (find average
statistic), or "mn" (find minimum absolute-valued
statistic).  If the data is complex-valued, the
comparisons are based on the complex magnitude.
There is an identical set of controls on the
Import 3D Stats panel (imported stats typically
won't have functional scans to setup).

NormSrch,Same,UniqVox,UniqVtx,Alldx (Paint/t-course)

The NormalSearch operations are used for:

(1) standard PAINT operations

(2) interactive PAINT of 3D data
     sets (click "val:" to toggle to "val3d:")

(3) generating vertex-wise ASCII output files
     during surface label based timecourse
     extraction -- the "T" button on the "label:"
     line in tksurfer

Csurf passes these along with the parameters
described above to tksurfer using command line
parameters (see log).  The timecourses are
written to ASCII output files:

  $hemi.LABEL_NAME.raw  (vertices and raw t-courses)
  $hemi.LABEL_NAME.xyx  (uniq rawdata vox coords)

The state of the first three "NormSrch", "Same",
and "UniqVox" checkbuttons allows for different
behaviors during the generation of the *.raw,
*.raw,stat, and *.stat files.  The main four
types are:

  NormSearch = OFF
  UniqVox = OFF

    1 sample point halfway between min/max
    1 vox timecourse appears on multiple vtx lines
    each surf vertex appears 1 time in *.raw file
    no holes in surface vtx coverage

  NormSearch = OFF
  UniqVox = ON

    1 sample point halfway between min/max
    1 vox timecourse appears at most on 1 vtx line
    each surf vertex appears 1 time in *.raw file
    holes in surface vtx coverage

  NormSearch = ON
  UniqVox = OFF

    multiple samples along norm between min/max
        i.e., same *vtx* may appear on multiple lines
    1 vox timecourse appears 1 time *along norm*
    1 vox timecourse can appear on diff vtx lines
    no holes in surface vtx coverage

  NormSearch = ON
  UniqVox = ON

    multiple samples along norm between min/max
        i.e., same *vtx* may appear on multiple lines
    1 vox timecourse appears at most on 1 vtx line
    holes in surface vtx coverage

UniqVtx

If "UniqVtx" is ticked (N.B.: requires
"UniqVox"), then the vertex that 'owns' the
unique voxel in the timecourses output file will
be the one closest to the average location of all
the vertices that sampled it.  This contrasts
with "UniqVox" only, where the first vertex to
sample/hit the voxel 'owns' it.

Ticking this box will also pass -uniqsampvtxs to
paint.c, causing the Fourier and ExtStats PAINT
button to also write out a uniq sample label in
the current scandir named:

  ?h-UniqSampVtxs.label

This label will contain the single vertices that
were closest to the average location of each set
of vertices that sampled one voxel during the
paint operation.  This file can be used when an
offline statistic needs to be calculated on the
same number of vertices as there are sampled
voxels.

The same uniqsamp vertex operation can be done
interactively in tksurfer using the three
operations on the "val3d:" line (if not visible,
click "val:" to toggle to it):

 (1) load at least one 3D native stats file "R"
 (2) sample 3D file to surf w/"PAINT" (finds uniq vox)
 (3) run "UQ" to find uniqsamp vertices

The result (stored live in memory) can be used
for sampling timecourses, for constraining the
cross-correlation spotlight ("label:" line "X"
button), and can be interactively saved
(middle-click UQ instead of left-click).

The advantage of the interactive version from the
tksurfer NormSearch/PAINT pop-up is that it can
be used to quickly visualize the effects of
different sampling regimes and settings, which
can then finally be saved in the Setup Funct
panel.

Same

The above 4 NormSearch/UniqVox possibilities
above can also be modified by the "Same" tickbox.
With "Same" OFF, distance (mm) or fraction of
cortical thickness is measured along the local
surface perpendicular.  If "Same" is ticked, the
local surface normal is replaced by a unit 1
vector along the line between same-numbered
vertices (e.g., white and pial), and the fraction
of thickness is replaced by the fraction of the
distance to the same-numbered vertex.

Alldx

Finally, the third "Alldx" checkbutton removes
the unique-ing operation during normal search so
that a time course will be written for each
"dx"-sized search step.  This can be used for
offline weighted averaging of normal samples.
Note that this option is overridden if "UniqVox"
is checked.

The state of the mx/av/mn radio button is ignored
during timecourse extraction.  To obtain a
linearly-weighted average of the timecourse along
a surface normal, set:

  NormSearch = ON
  UniqVox = OFF
  Alldx = ON

and then average (offline) the timecourses for
each dx step.

All the NormSearch options can also be adjusted
interactively from the tksurfer popup available
by left-clicking "label:" (text to the left of
the label entry) in tksurfer (N.B.: changes there
won't affect saved csurf values here).

The full names of the tksurfer tcl
variables/options are:

  NormSrch		$normdsampsearchflag
  Same		$samevtxthickflag
  UniqVox		$normdsampuniqvoxflag
  UniqVtx		$normdsampuniqvtxflag
  Alldx		$normdsampallflag

AllVtxs

Normally, the *.w files generated by PAINT only
contain surface vertices intersecting functional
data/stats (vertices not painted are by default
set to 0.0 upon read).  To obtain a full-rank
wfile that contains every surface vertex, click
this box (tksurfer tcl variable/option:
$allverticesflag).

Clone Funct Dir

The CLONE FUNCT button creates a complete copy of
the currently-selected functional dir and appends
the specified suffix to it (so inheritance is
clear).  It copies everything in the directory
(N.B.: it used to just make links to the big
files -- now everything is copied, including raw
data and motion-corrected data).

This is to make it possible to run and save
alternate analyses on the same data, or merely to
save alternate rendering parameters in the Render
panel for the same data set.


-------------------------------------------
Common Layout of SessionTools Panels
-------------------------------------------

Most of the rest of the SessionTools panels are
arranged in a similar way.

 (1) center-top buttons that configure the
     current directory as a directory of a
     certain kind or tell the program to ignore a
     directory by Unset-ing it (a previously
     configured, then Unset directory, recovers
     its sets when re-configured)

 (2) settable parameters in the main part
     of the panel

 (3) action buttons at the top right with bold
     lettering that read the parameters you have
     set and actually perform computations that
     affect data files.  Those buttons turn
     purple during computations.

Some panels have smaller bold-font actions button
in the main body of the panels, mostly for
(re-)reading headers.
