AFNI's uber_subject.py

Back in the good old days, we would create our scripts ex nihilo; out of nothingness would we construct gigantic, Babel-esque scripts that nobody - to be honest, not even we - could understand. We would pore over FMRI textbooks and fumble around with commands and tools we thought were germane, only to have everything collapse all around us when it came time for execution. I remember with painful clarity the moment when I finally hit upon the idea of looping over subjects for each iteration of the script; I thought I was a creative genius.

Lawless, ruthless, and terrifying; those days were like the wild west. Nobody knew what the hell was going on; you might come across a block of analysis script posted by some group in Singapore, compare it to your own, and wonder how your two labs could ever come to the same conclusion about anything, given how radically different your scripts were. Your script would call for slice timing correction, followed by coregistration and normalization, while their script would call for a cup of chopped onions and a clove of chopped garlic. Then, slowly, you would realize that what you were looking at was a recipe for chicken cacciatore or something, and you would feel like an idiot. Overall, those days were not good.

Fortunately for us, these days we now have a script called uber_subject.py, which takes care of generating analysis scripts quickly and easily. AFNI script ex machina, as it were. If you have programs and binaries from the past couple of years or so (and there's no reason you shouldn't; if you haven't updated in a while, a quick '@update.afni.binaries -d', without the quotes, should do the trick), you will have uber_subject.py. If you type it from the command line - and your python libraries are current and functional (see here for a message board thread if you have trouble with this) - then a graphical user interface will pop up, prompting you to input parameters such as smoothing kernel size, number of regressors, relationship status, and so forth, until you have a completely idiosyncratic script to fit your needs. Overall it has worked very well for me so far, and word is that it will be integrated with an even higher level script called uber_script.py. I've had some issues getting it to work, so instead of trying to fix it, I have taken the path of least resistance and settled for uber_subject.py. You will be glad that you did as well.

AFNI Part 1: Introduction

As promised, we now begin our series of AFNI tutorials. These walkthroughs will be more in-depth than the FSL series, as I am more familiar with AFNI and use it for a greater number of tasks; accordingly, more advanced tools and concepts will be covered.

Using AFNI requires a solid understanding of Unix; the user should know how to write and read conditional statements and for loops, as well as know how to interpret scripts written by others. Furthermore, when confronted with a new or unfamiliar script or command, the user should be able to make an educated guess about what it does. AFNI also demands a sophisticated knowledge of fMRI preprocessing steps and statistical analysis, as AFNI allows the user more opportunity to customize his script.

A few other points about AFNI:

1) There is no release schedule. This means that there is no fixed date for the release of new versions or patches; rather, AFNI responds to user demands on an ad hoc basis. In a sense, all users are beta testers for life. The advantage is that requests are addressed quickly; I once made a feature request at an AFNI bootcamp, and the developers updated the software before I returned home the following week.

2) AFNI is almost entirely run from the command line. In order to make the process less painful, the developers have created "uber" scripts which allow the user to input experiment information through a graphical user interface and generate a preprocessing script. However, these should be treated as templates subject to further alteration.

3) AFNI has a quirky, strange, and, at times, shocking sense of humor. Through clicking on a random hotspot on the AFNI interface, one can choose their favorite Shakespeare sonnet; read through the Declaration of Independence; generate an inspirational quote or receive kind and thoughtful parting words. Do not let this deter you. As you become more proficient with AFNI, and as you gain greater life experience and maturity, the style of the software will become more comprehensible, even enjoyable. It is said that one knows he going insane when what used to be nonsensical gibberish starts to take on profound meaning. So too with AFNI.

The next video will cover the to3d command and the conversion of raw volumetric data into AFNI's BRIK/HEAD format; study this alongside data conversion through mricron, as both produce a similar result and can be used to complement each other. As we progress, we will methodically work through the preprocessing stream and how to visualize the output with AFNI, with an emphasis on detecting artifacts and understanding what is being done at each step. Along the way different AFNI tools and scripts will be broken down and discussed.

At long last my children, we shall take that which is rightfully ours. We shall become as gods among fMRI researchers - wise as serpents, harmless as doves. Seek to understand AFNI with an open heart, and I will gather you unto my terrible and innumerable flesh and hasten your annihilation.

Ye Good Olde Days

I've uploaded my powerpoint presentation about what I learned at the AFNI bootcamp; for the slides titled "AFNI Demo", "SUMA Demo", and so on, you will have to use your imagination.

The point of the presentation is that staying close to your data - analyzing it, looking at it, and making decision about what to do with it - are what we are trained to do as cognitive neuroscientists (really, any scientific discipline). The reason I find AFNI to be superior is that it allows the user to do this in a relatively easy way. The only roadblocks are getting acquainted with Unix and shell programming, and also taking the time to get a feel for what looks normal, and what looks potentially troublesome.

Back in the good old days (ca. 2007-2008) we would simply make our scripts from scratch, looking through fMRI textbooks and making judgments about what processing step should go where, and then looking up the relevant commands and options to make that step work. Something would inevitably break, and if you were like me you would spend days or weeks trying to fix it. To make matters worse, if you asked for help from an outside source (such as the message boards), nobody had any idea what you were doing.

The recent scripts containing the "uber" prefix - such as "uber_subject.py", "uber_ttest.py", and so on - have mitigated this problem considerably, generating streamlined scripts that are more or less uniform across users, and therefore easier to compare and troubleshoot. Of course, you still need to go into the generated script and make some modifications here and there, but everything is pretty much in place. It will still suggest that you check each intermediate step, but that becomes easier to ignore once you have a higher-level interface that takes care of all the minor details for you. Like everything else, there are tradeoffs.