AFNI Command of the Week: 3dZcutup and 3dZcat

When I used to work at OSU, on the lab wiki I would put up a new AFNI command every week, detailing a program that isn't necessarily used all that often, but has some interesting applications for the user looking for more ways to manipulate their data. I plan to do the same on this blog, in the hopes that someone might find them useful.

One such tool that came to my attention a couple of weeks ago was 3dZcutup, a program for taking apart individual slice or groups of slices, in order to rearrange them or, more commonly, to perform statistical analyses on only one slice at a time, if computer memory becomes an issue. The usage is simple: Supply an input dataset, a prefix for your output dataset, and specify the range of slices you want to dump into the output dataset. For example, say you have a functional dataset r01+orig with 35 slices in the z-direction; if you wish to output only the first half of the slices into one dataset and the second half of the slices into another dataset, you could do something like the following:

3dZcutup -prefix bottomHalf -keep 0 16 r01+orig
3dZcutup -prefix topHalf -keep 17 34 r01+orig


Recall that the slices start at slice 0, which is why the last slice in this dataset is labeled 34. The output datasets for these commands would look something like this:

TopHalf

BottomHalf

In order to rearrange these slices, either to recreate the original dataset or to inverse the slices, you can collate the slices with the complement to 3dZcutup, 3dZcat:

3dZcat -prefix rightDirection bottomHalf topHalf
3dZcat -prefix wrong Direction topHalf bottomHalf

RightDirection

WrongDirection

A more useful application of 3dZcutup and 3dZcutup is during the stage of 3dDeconvolve, where each slice (or group of slices) can be run through 3dDeconvolve, and then stacked together to create the complete statistical dataset (the following is copied from the help file of 3dZcutup, since it is the better than any example I could come up with):

  foreach sl ( `count -dig 2 0 20` )
    3dZcutup -prefix zcut${sl} -keep $sl $sl epi07+orig

    # Analyze this slice with 3dDeconvolve separately

    3dDeconvolve -input zcut${sl}+orig.HEAD            \
                 -num_stimts 3                         \
                 -stim_file 1 ann_response_07.1D       \
                 -stim_file 2 antiann_response_07.1D   \
                 -stim_file 3 righthand_response_07.1D \
                 -stim_label 1 annulus                 \
                 -stim_label 2 antiann                 \
                 -stim_label 3 motor                   \
                 -stim_minlag 1 0  -stim_maxlag 1 0    \
                 -stim_minlag 2 0  -stim_maxlag 2 0    \
                 -stim_minlag 3 0  -stim_maxlag 3 0    \
                 -fitts zcut${sl}_fitts                \
                 -fout -bucket zcut${sl}_stats
  end

  # Assemble slicewise outputs into final datasets

  time 3dZcat -verb -prefix zc07a_fitts zcut??_fitts+orig.HEAD
  time 3dZcat -verb -prefix zc07a_stats zcut??_stats+orig.HEAD

What this will do is loop over twenty slices and perform 3dDeconvolve on each slice separately, and then reassemble both the fitts and stats datasets from all of the individual slices after they have been analyzed. This can help when the dataset is either extremely large, or your computer has relatively little memory.


Thanks to alert reader Landoska, who once cut his FMRI data into four slices instead of eight, because he wasn't hungry enough for eight slices. (rimshot)