AFNI program: 3dTshift

Usage: 3dTshift [options] dataset
Shifts voxel time series from the input dataset so that the separate
slices are aligned to the same temporal origin.  By default, uses the
slicewise shifting information in the dataset header (from the 'tpattern'
input to program to3d).

Method:  detrend -> interpolate -> retrend (optionally)

The input dataset can have a sub-brick selector attached, as documented
in '3dcalc -help'.

The output dataset time series will be interpolated from the input to
the new temporal grid.  This may not be the best way to analyze your
data, but it can be convenient.

Warnings:
* Please recall the phenomenon of 'aliasing': frequencies above 1/(2*TR) can't
  be properly interpolated.  For most 3D FMRI data, this means that cardiac
  and respiratory effects will not be treated properly by this program.

* The images at the beginning of a high-speed FMRI imaging run are usually
  of a different quality than the later images, due to transient effects
  before the longitudinal magnetization settles into a steady-state value.
  These images should not be included in the interpolation!  For example,
  if you wish to exclude the first 4 images, then the input dataset should
  be specified in the form 'prefix+orig[4..$]'.  Alternatively, you can
  use the '-ignore ii' option.

* It seems to be best to use 3dTshift before using 3dvolreg.

Options:
  -verbose      = print lots of messages while program runs

  -TR ddd       = use 'ddd' as the TR, rather than the value
                  stored in the dataset header using to3d.
                  You may attach the suffix 's' for seconds,
                  or 'ms' for milliseconds.

  -tzero zzz    = align each slice to time offset 'zzz';
                  the value of 'zzz' must be between the
                  minimum and maximum slice temporal offsets.
            N.B.: The default alignment time is the average
                  of the 'tpattern' values (either from the
                  dataset header or from the -tpattern option)

  -slice nnn    = align each slice to the time offset of slice
                  number 'nnn' - only one of the -tzero and
                  -slice options can be used.

  -prefix ppp   = use 'ppp' for the prefix of the output file;
                  the default is 'tshift'.

  -ignore ii    = Ignore the first 'ii' points. (Default is ii=0.)
                  The first ii values will be unchanged in the output
                  (regardless of the -rlt option).  They also will
                  not be used in the detrending or time shifting.

  -rlt          = Before shifting, the mean and linear trend
  -rlt+         = of each time series is removed.  The default
                  action is to add these back in after shifting.
                  -rlt  means to leave both of these out of the output
                  -rlt+ means to add only the mean back into the output
                  (cf. '3dTcat -help')

  -Fourier = Use a Fourier method (the default: most accurate; slowest).
  -linear  = Use linear (1st order polynomial) interpolation (least accurate).
  -cubic   = Use the cubic (3rd order) Lagrange polynomial interpolation.
  -quintic = Use the quintic (5th order) Lagrange polynomial interpolation.
  -heptic  = Use the heptic (7th order) Lagrange polynomial interpolation.

  -tpattern ttt = use 'ttt' as the slice time pattern, rather
                  than the pattern in the input dataset header;
                  'ttt' can have any of the values that would
                  go in the 'tpattern' input to to3d, described below:

   alt+z = altplus   = alternating in the plus direction
   alt-z = altminus  = alternating in the minus direction
   seq+z = seqplus   = sequential in the plus direction
   seq-z = seqminus  = sequential in the minus direction
   @filename         = read temporal offsets from 'filename'

  For example if nz = 5 and TR = 1000, then the inter-slice
  time is taken to be dt = TR/nz = 200.  In this case, the
  slices are offset in time by the following amounts:

             S L I C E   N U M B E R
   tpattern    0   1   2   3   4   Comment
   --------- --- --- --- --- ---   -------------------------------
   altplus     0 600 200 800 400   Alternating in the +z direction
   altminus  400 800 200 600   0   Alternating in the -z direction
   seqplus     0 200 400 600 800   Sequential  in the -z direction
   seqplus   800 600 400 200   0   Sequential  in the -z direction

  If @filename is used for tpattern, then nz ASCII-formatted numbers
  are read from the file.  These indicate the time offsets for each
  slice. For example, if 'filename' contains
     0 600 200 800 400
  then this is equivalent to 'altplus' in the above example.
  (nz = number of slices in the input dataset)

N.B.: if you are using -tpattern, make sure that the units supplied
      match the units of TR in the dataset header, or provide a
      new TR using the -TR option.

As a test of how well 3dTshift interpolates, you can take a dataset
that was created with '-tpattern alt+z', run 3dTshift on it, and
then run 3dTshift on the new dataset with '-tpattern alt-z' -- the
effect will be to reshift the dataset back to the original time
grid.  Comparing the original dataset to the shifted-then-reshifted
output will show where 3dTshift does a good job and where it does
a bad job.

-- RWCox - 31 October 1999

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100.200>'                                 {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.