Friday, May 10, 2013

Parameter Extraction in AFNI: 3dmaskave and 3dmaskdump

Previously we showed how to extract parameters using Marsbar in SPM and featquery in FSL, and the concept is identical for AFNI. Once you have created a mask (e.g., using 3dUndump or 3dcalc), you can then extract parameter estimates from that ROI either using the tool 3dmaskave or 3dmaskdump.
3dmaskave is quicker and more efficient, and is probably what you will need most of the time. Simply supply a mask and the dataset you wish to extract from, and it will generate a single number of the average parameter estimate across all the voxels within that ROI. For example, let's say that I want to extract beta weights from an ROI centered on the left nucleus accumbens, and I have already created a 5mm sphere around that structure stored in a dataset called LeftNaccMask+tlrc. Furthermore, let's say that the beta weights I want to extract are in a beta map contained in the second sub-brik of my statistical output dataset. (Remember that in AFNI, sub-briks start at 0, so the "second" sub-brik would be sub-brik #1.) To do this, use a command like the following:

3dmaskave -mask LeftNaccMask+tlrc stats.202+tlrc'[1]'

This will generate a single number, which is the average beta value across all the voxels in your ROI.

The second approach is to use 3dmaskdump, which provides more information than 3dmaskave. This command will generate a text file that contains a single beta value at each voxel within the ROI. A couple of useful options are -noijk, to suppress the output of voxel coordinates in native space, and -xyz, to output voxel coordinates in the orientation of the master dataset (usually in RAI orientation). For example, to output a list of beta values into a text file called LeftNaccDumpMask.txt,

3dmaskdump -o LeftNaccDumpMask.txt -noijk -xyz -mask LeftNaccMask+tlrc stats.202+tlrc'[1]'

This will produce a text file that contains four columns: The first three columns are the x-, y-, and z-coordinates, and the fourth column is the beta value at that triplet of coordinates. You can take the average of this column by exporting the text file to a spreadsheet like Excel, or use a command like awk from the command line, e.g.

awk '{sum += $4} END {print "Average = ", sum/NR}' LeftNaccDumpMask.txt

Keep in mind that this is only for a single subject; when you perform a second-level analysis, usually what you will want to do is loop this over all of the subjects in your experiment, and perform a statistical test (e.g., t-test) on the resulting beta values.

Concluding Unscientific Postscript

I recently came across this recording of Schubert's Wanderer Fantasie, and I can't help but share it here; this guy's execution is damn near flawless, and, given both the time of the recording and some of the inevitable mistakes that come up, I have good reason to believe it was done in a single take. It's no secret that I do not listen to that much modern music, but it isn't that modern music is bad, necessarily; it's just that classical music is so good. Check out the melodic line around 16:30 to hear what I'm talking about.


  1. Hi Andy,

    Thanks so much for this blog and your videos (at least I think it was your videos that I watched). They are so helpful.

    I'm very new to this all, so forgive me if my question is extremely basic, but here goes:

    I am using visual localizers, drawing ROIs around the functionally-defined visual areas, then mapping these visual area ROIs onto functional data from our main experiment and drawing ROIs to include all activated voxels within the visual ROIs derived from the localizer data. I'm wondering if there is a way to automatically select all activated voxels within an ROI in afni as opposed to drawing this second set of ROIs by hand?

    1. Hi there,

      Thanks for writing! Just to make sure I have this right, you did a functional localizer, and then you're creating another ROI based on the activated voxels within the functional localizer, correct?

      My question is, what is this ROI going to be used for? If you're only going to extract parameter values from the activated voxels, then you could just use 3dmaskave, since that only collects data from non-zero voxels. And if you only wanted positive activation voxels, you could use the -mrange option to specify that (e.g., 3dmaksave -mask mask+tlrc -mrange 0.001 10



  2. or in SUMA, rather. I still get the two kind of mixed up


  3. hi, Andrew, I have a question regarding voxel labels. When I extract voxel time series (e.g from 3 ROI's) I get first 3 columns containing xyz coordinates for each voxel series but they are mixed. My question is there any command that gives me labels as well along with each coordinates.