3dROIstats: Promises and Pitfalls

Just as a follow-up to the previous post, with AFNI's 3dROIstats, it usually makes sense to assign different values to different ROIs; that way, when data is extracted from those ROIs, each one is labeled individually. Since every one of you you reads everything I write and watches everything I film, you probably noticed that I used a couple of different commands for combining ROIs, such as:

3dcalc -a roi1 -b roi2 -c roi3 -expr '(a+b+c)' -prefix outputfile

and, in the video,

3dcalc -a roi1 -b roi2 -c roi3 -expr 'step(a) + 2*step(b) + 4*step(c)' -prefix outputfile


The reason for assigning values increasing exponentially (1, 2, 4, 8, 16, etc) is to identify which voxels belong to a single ROI, and which voxels belong to overlaps of ROIs. For example, let's say that we have three ROIs, A, B, and C. Using weights of 1, 2, and 4 would result in the following table of values:

1: A only
2: B only
3: overlap of A & B
4: C only
5: overlap of A & C
6: overlap of B & C
7: overlap of A & B & C

By contrast, if you used weights of 1, 2, and 3, then the intersection of A and B would be indistinguishable from region C. (Of course, if do not think that any of your ROIs will overlap, then using discrete consecutive digits, such as 1, 2, 3, etc, is also fine.)

Once you have created your combined mask and are happy with the locations of your ROIs, the command 3dROIstats can be used to dump out data extracted from each ROI from one or more sub-briks (e.g., beta-maps) of a statistical dataset. The command is pretty straightforward, and this template command should be pretty much all you need:

3dROIstats -mask combinedMask+tlrc 'stats+tlrc[1,2,5,...etc]'

For each sub-brik specified in the dataset, 3dROIstats will dump out the average data value within each ROI. So, for example, if you have three ROIs in your mask and two sub-briks, 3dROIstats will output a 2x3 table with three values for each sub-brik, one for each ROI.

I hope that is as clear as a glaucous sky, which I think is a word that means unclear, or something. I just read it in a Cormac McCarthy novel and he uses a lot of words that I don't know. Whatever. I was trying to be ironic.

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.

FSL Tutorial: Featquery_gui

Now that we've created our masks, we can go ahead and extract data using FSL's featquery tool. You may want to run it from the command line when batching large numbers of subjects, but this tutorial will focus on Featquery_gui, a graphical interface for loading subjects and ROIs, and then performing data extraction from that ROI. The procedure is similar to Marsbar, and I hope that the video is clear on how to do this.

Also, I've attached a Black Dynamite video for your enjoyment. Nothing to do with ROIs, really, but we all need a break now and then.

A Note about FMRI Masks

Now that we have covered how to create masks using three separate software packages - FSL, SPM, and AFNI - I should probably take a step back and talk about what masks are all about. When I first read about masks, all I heard was a bunch of mumbo jumbo about zeros and ones, and unhelpful saran wrap metaphors. While this did remind me to purchase valuable kitchen supplies, it was unhelpful in understanding what a mask was, exactly, and how it was used.

Simply put, a mask is a subset of voxels you wish to analyze. Let's say I'm only interested in the right hemisphere of the brain; to create a mask of the right hemisphere, imagine using a papercutter to split the brain in half, and only taking the right hemisphere for further analysis, while discarding the left hemisphere into the trash can. The generation of masks follows this same logic - only focus on a specific part of the brain, and discard the rest.

Fortunately, we have come a long way since using office supplies to create masks, and now we have computers to do it for us. In order to create a mask using any of the listed software packages, usually you will use a tool to insert "1's" into the voxels that you wish to analyze, and "0's" everywhere else. Then, say that you want to do an ROI analysis only on those voxels that contain "1's". If you are trying to extract contrast estimates for a subject, the contrast estimate at each voxel will be multiplied by the mask, and you will be left with the contrast estimates in the "1's" voxels (since each estimate is being multiplied by 1), and zeros everywhere else.

Furthermore, ROI extraction within a mask often averages the contrast (or parameter) estimates across all of the voxels inside the mask. It is also possible to extract estimates from single voxels or a single triplet of coordinates - just think of this as ROI analysis of a very small mask.

I hope that this clarifies things a bit; I know that it took me a couple of years to wrap my head around the whole concept of masks and ROIs and severing hemispheres from each other. However, once you understand this, the whole process of ROI interrogation becomes much simpler and more intuitive, and analyses become easier to carry out. ROI analysis is the foundation for carrying out more complex analyses, such as double dissociations and connectivity analyses, and it is well to become familiar with this before tackling larger game.

Parameter Extraction with MarsBar

Marsbar, a region of interest (ROI) tool interfacing with SPM, is a swiss-army knife of programs for ROI manipulation and data extraction. The most commonly used features of Marsbar are 1) The creation of ROIs from spheres or boxes centered on specified coordinates, and 2) The extraction of parameter or contrast estimates from ROIs. The following video tutorial focuses on the latter, in which parameter estimates for each subject are dumped out from a defined ROI.

For example, say you have two ROIs placed in distinct locations, and you wish to extract parameter estimates from the contrast A-B from each of those ROIs. Marsbar can do this easily, even flippantly, such a saucy and irreverent child it is. After your ROIs have been created, simply specify the SPM design you wish to extract parameter estimates from. In the case of second-level analyses, the SPM.mat files generated by these analyses will contain a number of time points equal to the number of subjects that went into that analysis; where Marsbar comes in is taking all of the parameter estimates for each subject and averages them over the entire ROI, generating a list of averaged parameter values for each subject.

Once this is done, save the results to a .mat file, load the file into memory, and check the output of SPM.marsY.Y (as in, "Why, Black Dynamite? Why?").


More deets can be found in the following tutorial; for a text-based walkthrough, complete with pictures, check out this link. I believe that both of these approaches are valid with both SPM5 and SPM8 distributions; if not, I apologize.

Unlike when Black Dynamite was denied the chance to apologize for the life he took so needlessly.