-------------------------------------------
 The SessionsTools -> Calc 3D Rand Block Stats
 sets up and runs deconvolution on 3D volume
 data set using AFNI 3dDeconvolve (by Doug Ward)
-------------------------------------------
This panel configures files and runs Doug Ward's
3dDeconvolve on functional time-series BRIKs.
Normally, you then use SessionTools -> Import 3D
Stats to extract the output files and PAINT them.
It requires that single-column 1D paradigm files
have been previously generated and placed within
each paradigm dir, which typically a directory
named "stim1Ds" within each scandir (see below).

The full 3dDeconvolve command line passed to
sh/bash is saved in the current scandir as:

  deconv.sh

The Image Name Format

This will typically be a concatenated,
motion-corrected time-series BRIK.  This is
automatically entered from the Setup Functional
panel.

Paradigm Dir

The standard subdirectory name is "stim1Ds".
This is the directory containing single-condition
1D files that together specify the columns of the
paradigm (design matrix) for a single scan.
Since these files are small, and since a central
paradigm file store may get out of sync with an
already-performed expt, make a "stim1Ds"
subdirectory in each scandir, and then copy the
paradigm files used for each scan into each
subdirectory (the only kind of files in there
should be paradigm files).  The directory tree
should look like this:

session
    image
        scan1
            stim1Ds
                face1.1D
                house1.1D
        scan2
            stim1Ds
                face2.1D
                house2.1D
        . . .

You must use a relative path for the Paradigm Dir
(i.e., the path *cannot* start with a "/").

Paradigm Files

These are single-column (n x 1) files, one for
each condition.  The filename should be a short
lower-case word followed by a .1D suffix (e.g.,
face.1D, house.1D, scramb.1D).  See below on
naming rules for files that are going to be
auto-concatentated by Combine 3D Raw Images.

The short names for the condition 1D files should
be 7 chars or less before the ".1D" suffix (incl.
the concatenation number -- see below).  For
example, use "animal2.1D" rather than a verbose
filename like Animal_Pictures_2.1D").  This makes
the auto-generated contrast names (esp. when a
contrast includes multiple conditions) easier to
read.  It also allows tabs in the Random Block
Statistics panel to space out the conditions
properly.  Finally, it is the only way to silence
a nagging pop-up :-}

Each line in the text files should end in
unix-style newline character, '\n'.  Some
programs may insert different or multiple
end-of-line characters.  For example, the Excel
output "export to space-separated" has DOS
carriage returns, '\r', not unix newlines, '\n'.
Fix them by using, for example, tr (translate):

  tr '\r' '\n' < condfiles.prn > condfiles.txt

That command line converts DOS carriage returns
to unix newlines.  If you have *two* invisible
end-of-line characters -- e.g., both DOS carriage
returns (\r) *and* unix newlines (\n) -- use this
tr command instead to strip the \r's:

  tr '\r' < condfiles.prn > condfiles.txt

Be sure to use a different file name for the
output file because a unix command line ending in
"> filename" will first create an empty output
file, destroying the input file (unix gotcha).

To see explicitly what is in a text
file, use

  od -cv textfile

This will print out the actual bytes in the
file 16 to a line, with spaces between each byte
(N.B.: space characters also show up as spaces
[separated by spaces]).  There should only be
numbers (0 and 1) and newlines (\n) (and possibly
spaces or tabs (\t) in the paradigm file.  Spaces
and tabs will be ignored.  Any other characters
will cause csurf or 3dDeconvolve errors.

The filename stem (e.g., face, house, scramb)
will be used in the interface and the resulting
saved bitmaps as the condition name.  Inside
the file, there should be a 1 when its named
condition is present and a 0 when it is not
(an error panel will come up if something other
than 0 or 1 is found).

The baseline condition is defined by the presence
of a 0 in all of the condition files.  Thus,
there is no 1D file for the OFF-condition.
Except for the off-condition case, for a given
TR, there should be a 1 in exactly one paradigm
file.  Here is an example of a portion of a
paradigm file:

====== cut here ==========================
0
0
1
1
1
...
====== cut here ==========================

If the scandir was generated by concatenating
raw data files from separate runs (COMBINE
on the SessionTools -> Combine 3D Raw Images
panel) prior to opening this panel, the COMBINE
concatentation process should already have
automatically generated the following files:

 concat'd BRIK/HEAD raw data timeseries file
 concat'd motion.1D file (if runs volreg'd)
 boundsfile: run1.1D (so HDRs don't cross runs)
 a stim1Ds subdirectory
 concat'd paradigm files put in stim1Ds/

N.B.: for the automatic concatenation of paradigm
1D files by Combine 3D Raw Images 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'.

TR (sec)

Repetition time between successive images of
the same slice in seconds.

Maximum Lag (-maxlag)

The maximum lag (in TRs) to allow when solving
for the hemodynamic response function for a
each trial type.

Polynomial Fit Order (-polort)

This specifies the order of the polynomial used
to fit the low frequency drift in the signal.
The default is 2.

Motion Params File (-dfile)

This should contain a 6-parameters-per-timestep
estimate of motion artifact.  This is typically
generated by 3dvolreg after motion correction is
run in the Setup Functional panel.

Scans, Total TRs

The number of scans that were concatenated to
generate the input file named at the top, and the
total number of TRs that it contains.

Paradigm Panel

When "READ 1Ds" is clicked, the individual
condition paradigm files are each read and
assembled into a paradigm matrix, where each
column comes from one 1D file.  The stems of the
paradigm filenames are substituted for 1's and
"----" is substituted the 0's in the 1D file.
This step verifies that the 1D files all have
the same length.

Automatically-Included Contrasts (cond vs. OFF)

A comparison of each condition to the OFF
condition (a '0' for that TR in every 1D file) is
automatically computed and given a label based on
the stem of the corresponding 1D file.

Pairwise Contrasts (old subpanel)

N.B.: this subpanel is only visible if
Preferences -> Simple Rand Block Diffs is ticked
*before* opening SessionTools -> Calculate 3D
Random Block Stats.  The default is not ticked.

To add a subtraction, select a block type from
the "Condition A:" and  "Condition B:" dropdown
menus and then click "ADD SUBTRACTION" which
should add it to the Subtractions list below.  To
omit a subtraction, use Backspace.  This panel
can only generate contrasts between pairs of
single conditions.

User-defined GLT Contrasts (new subpanel)

Use "ADD CONTRAST" to add a line of entries, one
for each condition.  All entries will initially
be defaulted to 0.  Use 1, -1 and sometimes 2,
-2, to arrange a comparison between any two
groups of conditions.  If there are positive and
negative numbers, they should add to 0.  The
"DELETE LAST" button removes the last contrast
line.  The configuration is saved on Save or
Save/Close.

After the contrasts have been setup, click "AUTO
NAMES" to generate names for them.  The
auto-generated names will look like this:

  {cnd1,cnd2}-VS-{cnd3,cnd4} => contrast
  {cnd1,cnd2}                 => add 2 conds
  VS-{cnd3,cnd4}           => opposite sign above

where cnd1, cnd2, etc are the stems of the 1D
filenames.

These names will serve as stems for files for
later Import and Render steps.  Note that AFNI
3Ddeconvolve has a 32-char limit on the length of
any individual label name.  With a large number
of conditions, the automatically generated names
can breach the 32-char limit.  In that case, a
warning will come up, and then the name in the
"GLT name" field can be manually trimmed.  It
will be tested again on clicking DECONVOLVE.

General linear test matrices

The generated GLT matrices (single-row files for
each condition vs. OFF plus single-row files for
each optional subtraction/contrast) are saved in
a subdirectory in each scandir (both old and new
subpanels):

  $scandir/gltmats/*.mat

The first set of 0's in each file corresponds to
the number of baseline parameters (polorts+1).
If the run has been concatenated, the total
number of entries here will be number of runs
times number of polorts+1.

The second set of 0's, 1's, -1's (and maybe 2's
and -2's) correspond to a series of conditions,
arranged in same order (alphabetical) as in the
panel.  Each condition contains maxlags+1
entries.  In this section, contrasts between
conditions may be specified.

The last set of values are the 6 motion
parameters from running 3dvolreg.  If the run
been concatenated, a concatenated motion.1D file
will be used.

Action Button--DECONVOLVE

When DECONVOLVE is clicked, 3dDeconvolve will be
run according to the mode radio buttons just
above the paradigm window (test/F/t-stats).  The
output stats file will be written into the
current scan directory.  If Test is selected, the
parameters are checked for completeness and the
design matrix is tested for singularity.

Stats Output File

The output stats BRIK name appears here after
DECONVOLVE has been run.  This takes a while
for a concatenated scan.  Correct settings for
rendering will depend on the paradigm.  For the
blue/red scale, try starting with:

  smooth:   10
  thresh:   0.0
  contrast: 0.15
  midpoint: 7
