Afni: Making Waver Files

All voxels in the functional brain image are followed through time. Each voxel displays a pattern (of intensity variation) through time that corresponds to the blood oxygen level in that particular location at a particular time. These patterns can be compared to the predicted hemodynamic response associated with a task. Afni 1-D files are files that contain predicted hemodynamic responses to be correlated to actual hemodynamic patterns displayed by our functional analyses. Correlations between the predicted pattern and the pattern in each voxel can then identify locations/voxels in the brain that appear to be activated during the task.

Waver is the program used to make these 1-D files. Ultimately, you want waver to generate a file with a column of 80 numbers if you have 80 TRs (for example). Waver typically generates extra TRs at the end of the output file that you don't you'll need to examine and edit the file in nedit (or another text editor) to make sure that you have one value for each TR.

>waver will provide information about how to use the program (see Appendix A)

1 = Active
0 =Inactive
99999 = missing values

Here is a sample command to create a base 1D file (the values you enter here will be convolved with the ideal waveform):

>waver -WAV -delaytime 0.0 -risetime 2.0 -dt 1.0 -inline 2@0 3@1 2@0 > fred.1D

The above line tells waver to create a text file with the following characteristics:

-WAV tells waver to use the Cox special waveform as the hemodynamic default.
-delaytime 0.0 = Sets delay time, before the start of the hemodynamic (HD) response, to 0 seconds.
-risetime 2.0 = Sets rise time (of the HD response) to 2 seconds
-dt 1.0 = Sets time step (TR) of output AND input to 1.0 second
-inline DATA = Read timeseries from command line DATA; convolve with waveform to produce output DATA in the form of numbers and count@value, as in "-inline 2@0 3@1 2@0" which means a timeseries with 2 TRs at zero, then 3 TRs at one, then a final 2 TRs at zero to be convolved with the HD waveform.

The output of the waver command is normally sent to standard output (it scrolls by you on the screen), but can be redirected with the > to a file (in this case, fred.1D) that will be created in the area you are currently working in.

Following is the file generated with the above command (the numbers represent a standard hemodynamic response given the input parameters):

0 0
1 50
2 150
3 238.462
4 253.647
5 193.647
6 120
7 46.3532
8 -13.6468
9 -38.462
10 -30
11 -10
12 0
13 0

Such files will need to be edited, eg,

>nedit fred.1D

Note that in editing, you must keep track of the row number very accurately. Many editors, including nedit, have an option to turn on a counter to keep track of your row and column position….turn it on: Go to "preferences" in the nedit menu and select "statistics line" or "show statistics". Cursor row and column number will appear in the status line at the bottom of the nedit window.

In our example, we requested 7 timepoints and waver generated 13. So you will want to remove the last 6 values from the file:

0 0
1 50
2 150
3 238.462
4 253.647
5 193.647
6 120
7 46.3532

Editing may also involve dropping certain time periods from consideration by inserting the number 99999 (make SURE you get all 5 9's in there) in place of rows that will be dropped out. Usually you will 9999 out time blocks that encompass a particular stimulus. You can 99999 out rows after creating the file, or you can tell the waver command to 99999 them out for you later. This is difficult to illustrate with our hypothetical 7 second experiment, so lets image something else.

Suppose an experiment has 3 conditions: rest, control and hum. Imagine you have 100 TRs: Each condition takes a certain number of TRs. Let's say, for simplicity's sake, that TRs 1-10 occur during a rest, 11-20 occur during a control, 21-30 occur during hum and then the pattern repeats twice more, followed by a final rest:

  • Rest: 1-10
  • Control 11-20
  • Hum 21-30
  • Rest: 31-40
  • Control 41-50
  • Hum 51-60
  • Rest: 61-70
  • Control 71-80
  • Hum 81-90
  • Rest: 91-100

You are, of course, not obligated by waver to make each condition last for the same period of time (10 TRs in this example) or to put the conditions into the same repetitive pattern, though you'll probably choose a very regular pattern for the sake of good experimental design.

Here are some sample waver files for our imagined 100 TR experiment:

>waver -WAV -delaytime 0.0 -risetime 2.0 -dt 1.0 -inline 10@0 10@1 10@1 10@0 10@1 10@1 10@0 10@1 10@1 10@0 > ContHum_Rest.1D

In the above example, we are creating a file that compares rest (0) to the active condition ('control' and 'hum' conditions are both 'active'). You'll need to remove extra TRs from the end.

Suppose we want to compare 'rest' to 'hum' and ignore the 'control' condition? We could manually edit ContHum_Rest.1D so that control rows (11-20, 41-50, 71-80) were set to 99999 (and we might want to give the edited version a new name). We could also use waver to create an alternative file (and we'd need to remove extra TRs from the end):

>waver -WAV -delaytime 0.0 -risetime 2.0 -dt 1.0 -inline 10@0 10@99999 10@1 10@0 10@99999 10@1 10@0 10@9999 10@1 10@0 > Hum_Rest.1D

At this point, you should be able to figure out how to compare 'hum' to 'control' (and ignore 'rest'); or, how to treat 'rest' and 'control' as active conditions that you wish to compare to 'hum' as an inactive condition, etc. Good luck.

Appendix A

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

Options: (# refers to a number; [xx] is the default value)
-WAV = Sets waveform to Cox special [default] (cf. AFNI FAQ list for formulas)
-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.

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]

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

The default is just to output the waveform defined by the parameters above. If an input file is specified by one of the options below, then the time series 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 = Outputs data in 2 columns, where the first column is time and the second is the waveform. Without the -xyout option, waver produces 1 column, the waveform. The two column option is useful for graphing.

-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 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.

At least one option is required, or the program will just print this message to stdout. Only one of the 3 timeseries input options above can be used.

If you have the 'xmgr' graphing program, then a useful way to preview the results of this program is through a command pipe like
>waver -dt 0.25 -xyout -inline 16@1 40@0 16@1 40@0 | xmgr -source stdin
Using the cruder AFNI package program 1dplot, you can do something like:
>waver -GAM -tstim 0 7.7 | 1dplot -stdin

If a square wave is desired, see the 'sqwave' program.