AFNI program: waver

Output of -help


Usage: waver [options] > output_filename
Creates an ideal waveform timeseries file.
The output goes to stdout, and normally would be redirected to a file.

---------
Note Well
---------
You should consider instead using program 3dDeconvolve to generate
an ideal FMRI timeseries file.  For example:

  3dDeconvolve -polort -1 -nodata 100 1.0 -num_stimts 1     \
               -stim_times 1 '1D: 10 30 50 70' 'BLOCK(5,1)' \
               -x1D Ideal -x1D_stop

will produce the file Ideal.xmat.1D, with 100 time points spaced
at TR=1.0 seconds, with stimuli at 10, 30, 50, and 70 seconds,
using the 'BLOCK' model with 5 seconds stimulus duration.

The waver program is no longer being updated, since almost everything
it does (and more) can be done in 3dDeconvolve -- RW Cox -- October 2010.

--------
Options: (# refers to a number; [xx] is the default value)
--------
  -WAV = Sets waveform to Cox special                    [default]
           cf. AFNI FAQ list for formulas:
           https://afni.nimh.nih.gov/afni/doc/faq/17
  -GAM = Sets waveform to form t^b * exp(-t/c)
           (cf. Mark Cohen)

  -EXPR "expression" = Sets waveform to the expression given,
                         which should depend on the variable 't'.
     e.g.: -EXPR "step(t-2)*step(12-t)*(t-2)*(12-t)"
     N.B.: The peak value of the expression on the '-dt' grid will
           be scaled to the value given by '-peak'; if this is not
           desired, set '-peak 0', and the 'natural' peak value of
           the expression will be used.

  -FILE dt wname = Sets waveform to the values read from the file
                   'wname', which should be a single column .1D file
                   (i.e., 1 ASCII number per line).  The 'dt value
                   is the time step (in seconds) between lines
                   in 'wname'; the first value will be at t=0, the
                   second at t='dt', etc.  Intermediate time values
                   will be linearly interpolated.  Times past the
                   the end of the 'wname' file length will have
                   the waveform value set to zero.
               *** N.B.: If the -peak option is used AFTER -FILE,
                         its value will be multiplied into the result.

These options set parameters for the -WAV waveform.
  -delaytime #   = Sets delay time to # seconds                [2]
  -risetime #    = Sets rise time to # seconds                 [4]
  -falltime #    = Sets fall time to # seconds                 [6]
  -undershoot #  = Sets undershoot to # times the peak         [0.2]
                     (this should be a nonnegative factor)
  -restoretime # = Sets time to restore from undershoot        [2]

These options set parameters for the -GAM waveform:
  -gamb #        = Sets the parameter 'b' to #                 [8.6]
  -gamc #        = Sets the parameter 'c' to #                 [0.547]
  -gamd #        = Sets the delay time to # seconds            [0.0]

These options apply to all waveform types:
  -peak #        = Sets peak value to #                        [100]
  -dt #          = Sets time step of output AND input          [0.1]
  -TR #          = '-TR' is equivalent to '-dt'

The default is just to output the waveform defined by the parameters
above.  If an input file is specified by one the options below, then
the timeseries defined by that file will be convolved with the ideal
waveform defined above -- that is, each nonzero point in the input
timeseries will generate a copy of the waveform starting at that point
in time, with the amplitude scaled by the input timeseries value.

  -xyout         = Output data in 2 columns:
                     1=time 2=waveform (useful for graphing)
                     [default is 1 column=waveform]

  -input infile  = Read timeseries from *.1D formatted 'infile';
                     convolve with waveform to produce output
              N.B.: you can use a sub-vector selector to choose
                    a particular column of infile, as in
                      -input 'fred.1D[3]'

  -inline DATA   = Read timeseries from command line DATA;
                     convolve with waveform to produce output
                     DATA is in the form of numbers and
                     count@value, as in
                     -inline 20@0.0 5@1.0 30@0.0 1.0 20@0.0 2.0
     which means a timeseries with 20 zeros, then 5 ones, then 30 zeros,
     a single 1, 20 more zeros, and a final 2.
     [The '@' character may actually be any of: '@', '*', 'x', 'X'.
      Note that * must be typed as \* to prevent the shell from
      trying to interpret it as a filename wildcard.]

  -tstim DATA    = Read discrete stimulation times from the command line
                     and convolve the waveform with delta-functions at
                     those times.  In this input format, the times do
                     NOT have to be at intervals of '-dt'.  For example
                       -dt 2.0 -tstim 5.6 9.3 13.7 16.4
                     specifies a TR of 2 s and stimuli at 4 times
                     (5.6 s, etc.) that do not correspond to integer
                     multiples of TR.  DATA values cannot be negative.
                   If the DATA is stored in a file, you can read it
                     onto the command line using something like
                       -tstim `cat filename`
                     where using the backward-single-quote operator
                     of the usual Unix shells.
   ** 12 May 2003: The times after '-tstim' can now also be specified
                     in the format 'a:b', indicating a continuous ON
                     period from time 'a' to time 'b'.  For example,
                       -dt 2.0 -tstim 13.2:15.7 20.3:25.3
                     The amplitude of a response of duration equal to
                     'dt' is equal to the amplitude of a single impulse
                     response (which is the special case a=b).  N.B.: This
                     means that something like '5:5.01' is very different
                     from '5' (='5:5').  The former will have a small amplitude
                     because of the small duration, but the latter will have
                     a large amplitude because the case of an instantaneous
                     input is special.  It is probably best NOT to mix the
                     two types of input to '-tstim' for this reason.
                     Compare the graphs from the 2 commands below:
                       waver -dt 1.0 -tstim 5:5.1 | 1dplot -stdin
                       waver -dt 1.0 -tstim 5     | 1dplot -stdin
                     If you prefer, you can use the form 'a%c' to indicate
                     an ON interval from time=a to time=a+c.
   ** 13 May 2005: You can now add an amplitude to each response individually.
                     For example
                       waver -dt 1.0 -peak 1.0 -tstim 3.2 17.9x2.0 23.1x-0.5
                     puts the default response amplitude at time 3.2,
                     2.0 times the default at time 17.9, and -0.5 times
                     the default at time 23.1.

  -when DATA     = Read time blocks when stimulus is 'on' (=1) from the
                     command line and convolve the waveform with with
                     a zero-one input.  For example:
                       -when 20..40 60..80
                     means that the stimulus function is 1.0 for time
                     steps number 20 to 40, and 60 to 80 (inclusive),
                     and zero otherwise.  (The first time step is
                     numbered 0.)

  -numout NN     = Output a timeseries with NN points; if this option
                     is not given, then enough points are output to
                     let the result tail back down to zero.

  -ver           = Output version information and exit.

* Only one of the 3 timeseries input options above can be used at a time.
* Using the AFNI program 1dplot, you can do something like the following,
  to check if the results make sense:
    waver -GAM -tstim 0 7.7 | 1dplot -stdin
* Note that program 3dDeconvolve can now generate many different
  waveforms internally, markedly reducing the need for this program.
* If a square wave is desired, see the 'sqwave' program.

++ Compile date = Mar 24 2024 {AFNI_24.0.17:linux_ubuntu_16_64}


This page auto-generated on Sun Mar 24 22:22:50 EDT 2024