-------------------------------------------
 The SessionsTools -> Import 3D Stats sets up
 to import statistical data set that have already
 been analyzed with AFNI (or SPM)
-------------------------------------------
This panel imports externally calculated native
resolution statistics (usu. calculated with AFNI
3dDeconvolve) and paints them onto the surface
using the register.dat file.

For BRIKs with multiple conditions generated by
3dDeconvolve, there are options for running a
cluster exclusion mask (3dmerge) and using the
resulting clustered t- or F-stat files to mask
the coefficient files (3dcalc) to a selected
(corrected) significance threshold (entered as t-
or F-values).

Select Input Data Set

First select the input data set to extract and
convert from the "External Stats Image Set"
dropdown.  The interface will guess at the
StatType using the input file suffix:

  <stem>.BRIK/HEAD   => AFNI-SINGLE
  <stem>.BRIK/HEAD   => AFNI-MULTI
  <stem>_%03d.bfloat => BFLOAT

This will be a single-frame bfloat or AFNI BRIK,
or a multi-frame AFNI BRIK (bucket) containing,
for example, amplitude coefficient estimates
(area under the estimated hemodynamic response
functions) and corresponding F- or t-stats for
each condition and optional contrasts.

The output BRIK from 3dDeconvolve run via csurf
will contain a "-stats" infix in the filename.
If pre-smoothing has been done, there will also
be an infix indicating this (e.g., "-sm4.0-").

AFNI BRIK Format

First read the HEAD file by pressing READ HEADER

If a BRIK contains no labels (BRICK_LABS field in
*.HEAD file) or only a single default label
('#0~), it will be treated as an AFNI-SINGLE
import, which allows the extraction of a single
subbrik ("Briks to Skip" selects which subbrik to
extract, if there are more than one).

AFNI 3dDeconvolve labels (BRICK_LABS)

The label numbers auto-generated by AFNI
3dDeconvolve have changed over the years
including at least these:

  Version 1: label delimited by "'" and "~" with
  subbrik number enclosed in brackets (e.g.,
  [0]), and using spaces (" ") to separate stem from
  LC[0] and LC[0] from "coef" or "F-stat" suffix

  Version 2: label delimted by "'" and "~" with
  number preceded by "#" and using underscores
  (_) to separate stem (e.g., up-VS-down) from
  GLT#0 infix and from "Coef" and "Fstat" suffix

Csurf changes both brackets and the "#" to "@" in
the csurf label display and in the stems of the
output BRIK (or bfloat) filenames.  Avoiding
brackets avoids shell problems, and the "#" is
avoided because MGH nmovie won't display a
filename containing that character.

Multi-frame BRIK Subpanel

An extra sub-panel appears when a BRIK containing
multiple labels is selected.  After pressing the
READ HEADER button in the sub-panel, you should
then be able to choose which sub-briks to extract
(typically all), and which sub-briks to use as
maskfiles (typically, all again).

Coef files masked by cluster-filtered t- or
F-stats will be dumped out from line with a Coef
"ValueFile" and a t- or F-stat "MaskFile".
Cluster-filtered t- or F-stat files will be
dumped out from lines with a t- or F-stat in both
"ValueFile" and "MaskFile" (i.e., mask stat file
with cluster exclusion derived from same file).
These files are written so that thresholds can be
interactively set at display time.

Finally, the mask thresh can be set.  The mask
threshold is entered as a t- or F-value.  For
AFNI stats, use the AFNI viewer with the "Define
Overlay ->" side panel open to map t- or F-values
to p values (AFNI will automatically consider the
degrees of freedom).  To interactively mask data
in tksurfer, set a low threshold (0.01), which
can conveniently be done by using "Gobal
MaskThresh <Ret>" at the top of the MaskThresh
column.

If "cluster" is ticked, t- or F-stats will first
be run through a cluster exclusion filter using
3dmerge (to correct for multiple comparisons)
with two requested cluster parameters set in the
interface.  These parameters are passed as:

 3dmerge ... -dxyz=1 -1clust_order <connected> <minvol> ...

The first parameter, "connected=", parameter
means the minimum Euclidean distance between
voxels for them to be considered to be in the
same cluster during region growing (N.B.: units
are voxel width, *not* mm).  To filter using
clusters with no gaps, use 1.  To allow one-voxel
holes in clusters, use 2, and so on.

The second "minvol=" parameter clips off clusters
that are below this volume (N.B.: units are voxel
volume, *not* mm^3). For example, using the
default of 40 with 3x3x3 mm voxels results in a
minimum cluster volume of 1080 mm^3 (about 1
cm^3).

Default values are entered here, but can be
recalculated using AlphaSim or 3dClustSim.  To
view the resulting cluster filter itself, open
AFNI and examine the files with a "-clustmask"
infix.  The values in the file are the numerical
order of size of the clusters found.

Extracted file names

The extracted and masked coeff/amplitude files
have names like:

---------------------------
 older 3dDeconvolve
---------------------------
  [old bfloat slice format]
    <cond1>_LC@0@_coef-clust+orig_%03d.bfloat
    <cond2>_LC@0@_coef-clust+orig_%03d.bfloat
    ...
  [BRIK format]
    <cond1>_LC@0@_coef-clust+orig.BRIK
    <cond2>_LC@0@_coef-clust+orig.BRIK
    ...

---------------------------
 newer 3dDeconvolve
---------------------------
  [old bfloat slice format]
    <cond1>_GLT@0_Coef-clust+orig_%03d.bfloat
    <cond2>_GLT@0_Coef-clust+orig_%03d.bfloat
    ...
  [BRIK format]
    <cond1>_GLT@0_Coef-clust+orig_%03d.bfloat
    <cond2>_GLT@0_Coef-clust+orig_%03d.bfloat
    ...
---------------------------

The corresponding extracted and clustered
statistics look like:

---------------------------
 older 3dDeconvolve
---------------------------
  [old bfloat slice format]
    <cond1>_F-stat-clust+orig_%03d.bfloat
    <cond2>_F-stat-clust+orig_%03d.bfloat
    ...
  [BRIK format]
    <cond1>_F-stat-clust+orig.BRIK
    <cond2>_F-stat-clust+orig.BRIK
    ...

---------------------------
 newer 3dDeconvolve
---------------------------
  [old bfloat slice format]
    <cond1>_GLT_Fstat-clust+orig_%03d.bfloat
    <cond2>_GLT_Fstat-clust+orig_%03d.bfloat
    ...
  [BRIK format]
    <cond1>_GLT_Fstat-clust+orig.BRIK
    <cond2>_GLT_Fstat-clust+orig.BRIK
    ...
---------------------------

After checking the configuration, then press
EXTRACT/CONVERT.  Check for errors in the log.

Extracting stats *without* cluster filter

If "Cluster" is unticked, stats files can be
extracted and thresholded directly.  In this
case, the infixes will be "-thresh" instead of
"-clust".  Thus, there are 6 possible
extract/mask operations:

Coef operations

 1. coef/nocluster/nothresh -> dump coef
 2. coef/nocluster/thresh -> thresh coef
 3. coef/cluster/thresh ->
     a. cluster stat for given thresh
     b. mask coef with it

Stat operations

 4. stat/nocluster/nothresh -> dump stat
 5. stat/nocluster/thresh -> thresh stat
 6. stat/cluster/thresh ->
     a. dump unclustered stat (-thresh)
     b. cluster stat for given thresh
     c. mask stat with it

Minimum Required HEAD Parameters

Here are the absolute minimal required parameters
for import of a *single* frame of external
statistics.  This example is for a 64x64x24
3.2mm^3 dataset with 256 time points:

  type  = float-attribute
  name  = DELTA
  count = 3
    3.203125 3.203125 3.2

  type = integer-attribute
  name = DATASET_RANK
  count = 8
    3 1 0 0 0
    0 0 0

  type = integer-attribute
  name = DATASET_DIMENSIONS
  count = 3
    64 64 24 0 0
  
  type  = float-attribute
  name = BRICK_FLOAT_FACS
  count = 1
    0.03051851

Note that additional fields (e.g., label names)
are read out of the HEAD file for mulitple frame
statistics BRIK.

PAINT

Pressing PAINT, paints all the extracted 3D files
onto the chosen cortical surface, using the
current vertex normal operation (same operations
as on Setup Align/Funct Scans panel, for
explanation, see Help for that panel).  You can
then view all of the painted files later on in
the rendering panel:

  SessionTools -> View Functional Data

where there is a set of radiobuttons near the top
of the panel that allow the rendering of multiple
extracted sub-briks from a single scan directory.
The options are:

 one  -- render selected (single) vertex file
 last -- render all vertexfiles from last extract
 all  -- render all vertexfiles (except complex)

When the multiple-render options are clicked, the
selected vertex file changes to "-multiple-".
The stems of the output rgb files in that case
are the same as the stems of the sub-briks.

The .bfloat format

The old .bfloat format -- now deprecated in favor
of AFNI BRIK's which are easier to view and less
clutter -- is a slice-based format (headerless
data with a matching minimal ASCII header file)
that can be used internally by FreeSurfer
programs, and is easily generated by an external
C program.  The filename format for each slice
file and header file is:

  <stem>_%03d.bfloat
  <stem>_%03d.hdr

The slice numbering is zero-based.  The first
slice is therefore:

  <stem>_000.bfloat
  <stem>_000.hdr

The bfloat file is a headerless string of floats
with x as the inner loop (x is the R->L direction
in tkregister when a default (identity matrix)
register.dat is loaded).  The hdr file is an
ASCII file that contains 4 strings:

  <ysize> <xsize> <numtimepoints> <other>

For example:

  64 64 1 0

Note that for binary compatibility across all
platforms, the BRIK and bfloat files are stored
in MSB byte order (SGI/Sun/PPC-Mac) byte order.
All the FreeSurfer programs automatically swap
bytes on read and write on Linux.  For this
reason, if bfloat files are generated by a simple
C program in Linux using fwrite(), you should
swap the bytes as the last step.  For example,
you could run AFNI 4swap on each bfloat after
generating it.  The oldstyle *.hdr files are
ASCII and therefore don't need to be swapped.

