-------------------------------------------
funct (left-click): ASCII rawdata timecourses for ROI
  write_roi_timecourses
-------------------------------------------
funct (mid-click): ASCII rawdata timecourses for segid
  write_segid_timecourses <idum>
-------------------------------------------


Detailed Description "T" button

The "T" button reads a 3D ROI/label file (which
is usually located in the current scandir, but
can be anywhere) using the name in the "roi:"
entry to the left (variable: $label).  The
rawdata time series for each voxel in the ROI
file is extracted using the register.dat
transformation matrix in the current scandir.

Since the ROI file is at the same resolution as
the statistical overlay, which wll have been
upsampled to the higher resolution of the
anatomical underlay (1x1x1mm), multiple ROI
voxels will typically sample a single rawdata
voxel (typically 3x3x3mm).  Duplicate timecourses
are removed and a tally of the number of times
each rawdata voxel timeseries has been sampled by
the ROI file is noted in the output file (on
average, this will be the function/structural
volume ratio).  The ASCII output file is written
in the current scan directory (see below).

Output files

One ASCII output files has a name constructed
from the name of ROI label file.  For example:

  MT+orig.BRIK -> MT.raw

This file has a one-line header (format, data
size, sources) followed by a series of lines, one
for each voxel.  Each line contains the raw data
xyz indices, the number of times this voxel has
been upsampled by the ROI file, and finally the
rawdata voxel brightness values for each time
point.  For example:

 #!ascii , fmt: rawx rawy rawz upsampvotes \
      t1 t2 ... t256 \
      (subj=marty, lab=/tmp/MT+orig.BRIK, n=22)
 19 48 39 4 1531 1498 1569 1616 1563 1593 ...
 19 47 39 15 1269 1280 1368 1421 1390 1388 ...
 ...
 [foreach sampled voxel in rawdata file]

The rawx,rawy,rawz coordinates are in raw BRIK
order, ignoring any orientation information in
the HEAD (so BRIK can be read by itself using
the following code):

  for (t=0; t<rawdata_tdim; t++)
    for (z=0; z<rawdata_zdim; z++)
      for (y=0; y<rawdata_ydim; y++)
        for (x=0; x<rawdata_xdim; x++)
          rawdata[t][z][y][x] = one_time_point;

If the surface vertex location is off the edge of
the rawdata block, the integer x,y,z indices are
all set to -1, and the rawdata voxel values are
all set to 0.

Args for tkmedit

  -real <format>          [stats at rawdata res]
  -complex <cformat_r> <cformat_i>    [ditto]
  -scandir <dir_usu_in_image>
  -regdat <registerdatfile>
  -rawdata <rawdata>+orig.BRIK
  -label <some-area>+orig.BRIK
  -statmask <cformat_s>

The procedure can also be performed from the
tkmedit tcl prompt (or a tcl script) where
$scandir is name of scan directory inside "image"
subdir inside the current session.  The current
scandir can be abbreviated with a '*' and the
current subject dir with a '~' using setfile (a
globbing 'set').  For example:

  setfile regdat */$scandir/register.dat
  setfile rawdata */$scandir/<rawdata>+orig.BRIK
  read_rawdata
  setfile label */$scandir/MT+orig.BRIK
  write_roi_timecourses

    => output files: */$scandir/MT.raw

-------------------------------------------
Alt funct (mid-click): ASCII rawdata timecourses for segid
  write_segid_timecourses <idnum>
-------------------------------------------

Same as above, except, get ROI for extracting
timecourses from the idnum of a 3D segmentation
region.

An MGH segmentation must first be loaded using
"R" on the "im2:" line.  Look in dropdown for
files like:

  aparc.a2009s+aseg

To find the idnum of a segmentation region,
double-middle-click one of the colored regions in
the image window in the F2 interface.

A table of all the idnums and corresponding names
is written into the csurf log, written when the
segmentation is read.

Finally, type the idnum into the "roiup:" entry
(N.B.: at startup, this field will contain a
default name for an roi RRIK).

The ASCII output file in the current scandir will
have a name like:

  segid-12120.raw

and will have the same format as described above.
