#### extract 3D Timecourses ####
-------------------------------------------
funct: "Dump Time-Series from Label Vtxs (left-click-T)"
  set label <outfile>
  write_label_timecourses_stats 0            ;# rawdata
-------------------------------------------
funct: "Same As Above + Avg FT Percent (shift-left-clk-T)"
  set label <outfile>
  write_label_timecourses_stats 4            ;# rawdata + percent
-------------------------------------------
funct: "Dump Time-Series from Annot RGB (middle-click-T)"
  [single output auto-named w/region-name]
  write_annotcol_timecourses_stats r g b 0 ;# rawdata
-------------------------------------------
funct: "Dump Time-Series All Annots (shift-middle-click-T)"
  [multiple outputs auto-named w/region-names]
  write_annotcols_timecourses_stats 0      ;# rawdata
-------------------------------------------
N.B.: for single-voxel timecourse: ctrl-mid-click a vertex


Overview

The "T" button on the "label:" entry line reads a
label file or an MGH annotation file (which are
usually located in the "label" subdir of a
subject directory, but can be anywhere) using the
name in the "label:" entry to the left (variable:
$label, $anlabel).

Rawdata time series for the set of surface
vertices in the label or MGH annotation are
extracted using the current register.dat
transformation matrix in the current scandir.

The rawdata is sampled from the 3D file at one or
more points above the vertex along local surface
normal (see controls below).  Extracted
timecourses are then written to an ASCII file (or
files) in the current scan directory (see below).

Finally, the average timecourse for the entire
label is displayed at the top of the brain
surface window.

There are 4 different versions of this procedure:

 left-click-T:            all vertices in current label
 shift-left-click-T:     same + avg Fourier percent resp popup
 middle-click-T:       use annot vtxs from region w/curr color
 shift-middle-click-T:  all regions in current MGH annotation

See end below for details of file format,
documentation of the search-along-the-normal
parameters, and viewing average and single-vertex
time series.

-------------------------------------------
funct: "Dump Time-Series from Label Vtxs (left-click-T)"
  set label <outfile>
  write_label_timecourses_stats 0    ;# rawdata
-------------------------------------------

A default left-click on the "T" button dumps raw
data timecourses from current label in the
"label:" entry (see below for ASCII output
files -- listed on popup when proc finishes).

-------------------------------------------
funct: "Same As Above + Avg FT Percent (shift-left-clk-T)"
  set label <outfile>
  write_label_timecourses_stats 4    ;# rawdata/percent
-------------------------------------------

The second case (shift-left-click) is the same as
the first but also calculates precent response
across the label.  This only works with complex,
Fourier-analyzed data.  The average percent
peak-to-peak response amplitude returned in the
last pop-up (and the csurf log).

N.B.: this requires that complex raw fourier *3D
stats* (_x,_y) fourier have first been loaded
(i.e., not surface-sampled wfiles -- there will
be an error pop-up if 3D data not loaded).  Load
3D data as follows:

  (1) click "val:" to get "val3d:"
  (2) select _x or _y BRIK
  (3) click "R" (no visible effect)

The peak-to-peak stimulus frequency amplitude is
computed by dividing the raw discrete FT
amplitude at the stimulus frequence (hypot(_x,_y)
by the number of time points, comparing it to the
average voxel amplitude, then converting to
peak-to-peak percent:

               hypot(_x,_y)
 %resp  =  --------------   /   rawavg * 2 * 2 * 100
                timepoints

The first factor of 2 is for pos/neg freqs, and
the second is for peak-to-peak amplitude.

See R-click help for the "val:" line "W" button
for how to get percent response directly from
surface-painted _x,_y data without a timecourse
(requires entering timepoints and average rawdata
timecourse amplitude).

-------------------------------------------
funct: "Dump Time-Series from Annot RGB (middle-click-T)"
  [single output auto-named w/region-name]
  write_annotcol_timecourses_stats r g b 0    ;# rawdata
-------------------------------------------

For the third alternate case, first load an MGH
annotation file by selecting one from the
dropdown followed by "R" on the "label:" line.

Then load a single RGB color from a region in
that MGH annotation by clicking the region
(colors load to the entries to the right of the
"MESH" button; region names will be visible in
the csurf log).

The extracted timecourses will come from that
single region in the MGH annotation.

-------------------------------------------
funct: "Dump Time-Series All Annots (shift-middle-click-T)"
  [multiple outputs auto-named w/region-names]
  write_annotcols_timecourses_stats 0    ;# rawdata
-------------------------------------------

The final fourth case is like the third, except
that data from every one of the different regions
in the annotation will be dumped (takes a while).


ASCII Output files (3)

For a default left click of "T", three ASCII
output files will have names constructed from the
name of label file (same format for both MGH
'dot' style or UCSD/UCL 'dash' style label
files).  For example:

  rh.MT.label ->

     rh.MT.raw
     rh.MT.xyz
     rh.MT.avg

or:

  rh-MT.label ->

     rh.MT.raw
     rh.MT.xyz
     rh.MT.avg

For a middle-click or shift-middle click used to
extract MGH annotation file rawdata, the file
names will all contain an infix "region" followed
by the structure name in the annotation file.
For example:

  rh.region_S_central.raw
  rh.region_S_central.xyz
  rh.region_S_central.avg

The first output file is the timecourses file
(*.raw), which has a one-line header (format,
data size, sources) followed by a series of
lines, one for each vertex.  Each line contains
the vertex number, the original-surface floating
point surface coordinates used for sampling
(surfx, surfy, surfz), the integer indices of the
(non-unique) sampled rawdata (rawx, rawy, rawz)
voxel, the MNI Talairach coordinates (talx, taly,
talz) of the surface points, and finally the
rawdata voxel brightness values for each time
point.  For example:

#!ascii , fmt (justtime): vtx surfx surfy surfz \
  rawx rawy rawz talx taly talz t1 t2 ... t512 \
  (lab=lh-MY_AREA.label, raw=pol+orig.BRIK, \
   n=201, normdfracsamp=0.00, uniqvfl=0)
 21465 -9.50 -66.50 -9.50 14 26 19 602 615 601 ...
 21483 -11.50 -66.50 -11.50 15 23 9 562 556 554 ..
 ...
 [foreach vertex in label file]


Norm search parameters

The rawdata timecourse is extracted at one or
more points along the vertex normal.  This
operation is controlled by 7 settings at the
bottom of the SessionTools -> Setup Funct Scan
panel.  These setting also control the PAINT
operation:

  "NormSrch:" (units: "mm" or "frac" of thick)
  "mn/mx:" (limits along normal)
  "dx:" (step size along normal)
  [PAINT operation] "mx" or "av" or "nm"
  "NormSrch" (point or search)
  "Same" (freesurfer vs. same-vtx thickness)
  "UniqVox" (first vtx to sample a voxel gets it)
  "UniqVtx" (vtx nearest avg of set sampling vox wins)
  "Alldx" (write out tseries for each depth)
  "AllVtxs" (don't omit vtxs off edge of funct scan)

See Help -> Setup Align/Funct Scans for more
details.  The default is to sample a point midway
between min and max using the fractional distance
between the white and pial surfaces.

These parameters can also be adjusted
interactively in tksurfer by left-clicking
"label:", which brings up a pop-up panel.
Currently, normdop (0=max, 1=avg, 2=min) only
affects the tksurfer paint button, "PAINT"
(left-click "val:" to make the PAINT button
visible).

The surfx,surfy,surfz coordinates are from the
$origcoords surface, typically $hemi.orig or
$hemi.white (not the current surface).  Surface
coordinates read out of label file are ignored.

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

  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 rawx,rawy,rawz
indices are all set to -1, and the rawdata voxel
values are all set to 0.

By default the timecourses in the first output
file are not unique; for typical fMRI data, more
than one vertex will sample the same rawdata
timecourse voxel since surface vertices are
closer together than typical fMRI voxels (see
details in Help -> Setup Align/Funct Scans).

The second output file (*.xyz) contains unique
rawdata voxel indices intersected by label
vertices for indexing into the rawdata BRIK.

The third output file (*.avg) contains the
average timecourse.


Norm search args for tksurfer

  -regdat <registerdatfile>
  -rawdata <rawdata>+orig.BRIK
  -normdfracflag <0=mm,1=frac>
  -normdfracsamp <float:def=0.4>
  -normdfracmax <float> [used if search]
  -normdsamp <float:def=1.0(mm)>
  -normdmax <float> [used if search]
  -normdsampsearchflag <0,1>
  -normdsampuniqvoxflag <0,1>
  -normdsampuniqvtxflag <0,1>
  -normddstep <float:mm=0.25, frac=0.1>
  -samevtxthickflag <0,1>
  -stimcycles <int:def=8>
  -showavgcycflag <0,1:def=1>
  -rawdatarange <float:def=0.0=auto>

The procedure can also be performed from the
tksurfer 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
  read_regdat
  setfile rawdata */$scandir/<rawdata>+orig.BRIK
  read_rawdata
  setfile label ~/label/rh-MT.label
  ## use next for mm
  set normdsamp 1.0
  ## use next for fraction of thickness
  set normdfracsamp 0.4
  ## arg is: 0=timecourses,1=stats,2=both
  write_label_timecourses_stats 0

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

If the current hemisphere thickness file is
present (tksurfer will automatically read it if
it is found) and -normdfracflag is set, the
rawdata will be sampled at the requested fraction
of cortical thickness along normal above each
vertex (option: tksurfer ...  -normdfracsamp
<frac>, or tcl: set normdfracsamp <dfrac>).  If
no thickness file is present, absolute distance
above vertex in mm will be used instead (option:
tksurfer ... -normdsamp <mm>, or tcl: set
normdsamp <mm>).

A search along the normal will be performed if
-normdsampsearchflag is set with limits set by
normd{frac}samp and normd{frac}max.

The first time that timecourses are extracted for
a label file (or for ctrl-middle-clicking a
vertex -- see below), there will be a short delay
to read the entire raw data file into memory.  To
re-read a different rawdata file with the same
surface displayed, use tcl commands, or restart
tksurfer with new args (e.g., from csurf).  The
tiny register.dat file is re-read every time.


Average timecourse display across label/annotation

A simple average of the timecourses from the
label is computed and displayed (N.B.: for
phase-encoded data, label should approximately
follow an isopolar or isoeccentricity line
to keep phases from cancelling each other).

The average timecourse line will be colored
according to the current color scale after
averaging the .val (real data) or both
.val and .val2 (complex data) from the
data currently present on the surface (which is
normally derived from the avg raw data timecourse
being displayed).

If stats read in are complex, average cycle is
drawn under the timecourse by default, using a
thicker, slightly dimmer line (to turn off avg
cycle underlay: tcl: set showavgcycflag 0).

By default, the rawdata range is autoscaled for
each new timecourse plot (to see directly
comparable de-meaned data values: tcl: e.g., set
rawdatarange 100).


Display single vertex timecourse

To simply display the rawdata timecourse for a
single vertex in the tksurfer window, do
ctrl-middle-click on a vertex (no need to first
select it).  This will also write out (append)
that vertex to an ASCII file in the current
scandir:

    */$scandir/rh.selected.raw

This file has the same format as the timecourses
files above.  To clear timecourse(s) from the
tksurfer window, click "REDRAW" (or R-click,
which clears marked vertices and also does an
auto "REDRAW").

For Fourier-analyzed data, the timecourse will be
colored using the current (e.g., phase-sensitive)
color scale.  In addition, the number of
stimcycles will be used to collapse the time
course to a single cycle, which will then be
repeated stimcycles times in a thicker line
underneath the timecourse.  Finally, the precent
response for this voxel will be printed in the
csurf log.

By default, the previous single voxel timecourse
is cleared.  To cause prevent clearing in order
to overlay multiple single-voxel timecourses, set
the C/tcl variable multitimecourseflag to 1.

N.B.: If you "W" (write) an rgb file, the window
will be raised and redrawn first, which will
erase the graph(s).  If you want to save the
onscreen timecourse(s) and cyan cursors, use the
"WN" (write, no raise/redraw) button to the right
of "W" button instead (be sure no windows are
obscuring the tksurfer window before displaying
timecourses since the "WN" button does not raise
window).
