---

Q27. What are "-time:zt" and "-time:tz" in to3d?
When you input data to to3d, you give a list of filenames on the command line. to3d reads images from these files, 1 slice at a time. The order in which these slices are presented to the program determines if you want "-time:zt" or "-time:tz". Let's take an example where you have 8 slices and 99 repetitions. If you named your slice files im.[slice num].[time num] (im.1.01 .. im.8.01 all being gathered at the 1st repetition, then im.1.02 .. im.8.02 at the next repetition, etc.), then when you did an ls im.*.* on these files, they would appear in the order

  im.1.01 im.1.02 im.1.03 ... im.1.99 im.2.01 im.2.02 ...

This order is "-time:tz", since if you type "im.*.*" on the command line, they will appear in this order to the program. It is important to realize that this order is determined by Unix, not by the program. Wildcard characters (such as "*" and "?") are expanded into lists of filenames before the program is run, and the program only sees the resulting filename list, not the wildcards. (An exception is if you put the entire wildcarded filename inside forward single quotes, as in 'im.*.*'. Then Unix does not expand the wildcards on the command line. Instead, to3d will do the expansion internally, but the filename order will be the same as if Unix did it externally. This ability is provided to let to3d get around limitations on some Unix systems that restrict the length of an expanded command line.)

In this example, you would run to3d with a command like

  to3d -time:tz 99 8 3s alt+z [other options] im.*.*

where I've assumed your repetition time (TR) is 3 seconds. The "alt+z" tells AFNI that the images are spread out in acquisition evenly across the TR=3s, in alternating order (1 3 5 7 2 4 6 8), which is usual (but not universal) in MRI.

If instead, you named your files im.[time num].[slice num], then you would have to use

  to3d -time:zt 8 99 3s alt+z [other options] im.*.*

This is because the order in which the files would be listed when you type "im.*.*" would be z varying first, then t, since the slice index now appears after the time index in the filename.

If your files are 3D blocks, one at each time, then you will usually be inputting data in the "-time:zt" order, since each file will contain a bunch of z values at a fixed time. But some sites (e.g., MGH) gather all the data from one slice, all times, into one such 3D block. In this case, they would have to use "-time:tz".

For more explanations, see the to3d chapter of the auxiliary programs manual (afni_aux.ps), and the output of to3d -help. In particular, you will need to read these sections if your slices are gathered in some other time order than the one implied by "alt+z".

Filename Ordering
In the above example, I used filenames like im.A.B, where A was a 1 digit number from 1-8 specifying the slice, and B was a 2 digit number from 1-99 specifying the time order. If you had more than 9 slices, you would want A to be a 2 digit number; if you had more than 99 repetitions, you would want B to be a 3 (or 4) digit number.

Let's take a simple example: suppose you have just one slice and 99 repetitions, but the time points are labeled with a single digit when possible:

  im.1 im.2  im.3  ... im.9  im.10 im.11 im.12 ... im.97 im.98 im.99

When you use the wildcard im.* to input these files, you will find that the order in which they are read is

  im.1 im.10 im.11 ... im.19 im.2  im.20 im.21 ... im.29  im.3 im.31 ...

which is not useful at all. There are two solutions. The first is to use the "?" wildcard character, which matches just one character. In this case, you would use im.? im.?? on the command line, which would read all the 1 digit files first, followed by all the 2 digit files. The second solution is to rename all the files to use the same number of digits. The following C shell script will rename im.1 to be im.001, etc.:

  foreach fred ( `count -dig 3 1 99` )
    @ k = $fred
    mv im.$k im.$fred
  end

You can execute this by typing it in at the command line, or by putting it into a file (renum, say), and running it by typing source renum. If you have it in a file, then you can edit and re-use it later.

Ordering Files with Weird Names
Let's say you have files with names like this (from a real DICOM example):

  MR.1.2.840.113619.2.1.6637.3053478798.3.27.920368684
  MR.1.2.840.113619.2.1.6637.3053544334.3.26.920368684
  MR.1.2.840.113619.2.1.6637.3053609870.3.25.920368684
                                          **

The ** asterisks mark the location of the acquisition sequence number (in the example above, 27, 26, then 25 -- the 11th 'field' separated by periods). However, Unix will list them in order based mostly on the characters that precede this location. To get these files into order, the simplest This can be done with a C shell script like this:

  ls MR.1.2.* > q1
  sort -n -k11 -t. q1 > q2
  set ii = 1
  foreach fred ( `cat q2` )
    set jj = `count -digits 4 $ii $ii`
    mv $fred im.${jj}
    @ ii = $ii + 1
  end
  /bin/rm -f q1 q2

The first line of this script creates file q1 as a listing of the files to be renamed. The second line of the script sorts the file q1 numerically (not alphabetically) using the 11-th "field" (that's what the -k11 on the sort command line means), where the fields are separated by the "." character (which is what the -t. means). sort is a Unix system command - see man sort for its details. Then the foreach loop reads the sorted filenames from the q2 file and renames them to im.0001, etc. Finally, the temporary files q1 and q2 are removed.

It would also be possible to use the sorted list directly in a command like to3d `cat q2`, where the backquotes would place the sorted file list onto the command line. However, these filenames are so long that this procedure will likely overflow your computer's limits on command line length (at least, it does on our SGIs).

[Later] The "-@" option to to3d now will let you read file q2 onto the command line, without the limits of the shell or operating system. In this example, you would use the command to3d -@ < q2, and so would only need the first two commands above to create the q2 file. Or, if you have a great deal of confidence, you can do it all in one command with
ls MR.1.2.* | sort -n -k11 -t. | to3d [options] -@
thus eliding both the need to create a temporary file to hold the filenames, and the need to rename the input files. For more details, see Q32.

3D+time Functional Datasets?
You will find that the graphical interface in to3d does not allow you to create a time-dependent functional dataset. This is because I (and therefore AFNI) view the raw EPI time series as "anatomical" data, and "functional" datasets are those that directly reveal something about functional activity. Thus, functional datasets are computed from anatomical 3D+time datasets.

The principal difference between functional and anatomical datasets in AFNI is that anatomical datasets are used as the grayscale underlay images and functional datasets are used to create the color overlays. This was a design decision made back in the old days (summer 1994). If I were doing it over again, I would probably not make this distinction, but it's there.

Anyhow, you can create a 3D+time functional dataset of the "fim" type using to3d. This can be done by using the -fim switch on the to3d command line. If you forget this, you can use 3drefit to change the dataset type afterwards, as in

  3drefit -fim zork+orig

Such a dataset can be used as a functional overlay, and you can scroll through it with the Time Index control (but note that the time index of the anatomical and functional dataset will be linked). However, for many purposes, it would be better to create a multi-brick functional dataset as a "bucket" dataset ("fbuc" type, switch -fbuc in 3drefit).

If you want the same data to be both anatomical and functional, you must create 2 datasets. You can avoid the disk overhead of this by using the 3ddup program. After creating an anatomical dataset (say bob+orig), then you can create a "warp-on-demand" fim copy of this with just a .HEAD file with the command

  3ddup -fim -prefix bobfunc bob+orig

When AFNI needs to display images from bobfunc+orig, it will take the data out of bob+orig. Such warp-on-demand datasets can only be used for 2D image display purposes. If you want to process them in other ways, they must be written to disk - there must be a .BRIK file created using one of the AFNI Write buttons.

Note that is is not possible or legal to create a functional 3D+time dataset of any other type than "fim". This is because there is no support in any AFNI code for time-dependent data that has more than one value per voxel per time step; for example, you can't have a 3D+time "fico" dataset. I can certainly visualize situations in which such multiple-valued 3D+time data would be useful (e.g., combined gradient-echo and spin-echo EPI). Someday, maybe this capability will be put into AFNI. Then again, maybe not.

[Answer last changed 24 May 2001]