Resting State Analysis, Part III: Automating Your Analysis

Once you've set up a resting-state analysis script, either through or following example #9 in the documentation, I highly recommend that you set up some sort of higher-level script to automate running that script in each subject's directory. This is especially useful in the dataset we are using, since each individual analysis doesn't necessarily take that long, but we have a large number of subjects.

To begin, navigate to the downloaded KKI directory and use the following command to list each directory without trailing slashes:

ls -d */ | cut -f1 -d'/' > subjList.txt

You can then redirect this output to a text file, which can then be later edited at your leisure; in the above example, I used a redirect command to place all of the directories in a file called subjList.txt.

A for loop can then be used to do the analysis for each subject. (You can use any shell you want, but in this example I will use the t-shell.) Simply use the output of the text file as a variable, then use the for loop to execute the analysis for each subject, e.g.:

setenv subject `cat subjList.txt`
foreach subj ($subject)
cp $subj/session_1
cd $subj/session_1
tcsh $subj
cd ../..

The script, generated from the interface used in the last tutorial, can be found here. Note that I use a motion cutoff threshold of 0.3mm, which is slightly different from the standard 0.2mm cutoff; feel free to alter this if you like.

This should take care of all of your analyses while you go do something else, such as reading a book or shopping for tupperware and nosehair trimmers.* Of course, you will want to examine the output of your commands for any errors, but this menial task can usually be designated to one of your undergraduate RAs slated for resting-state data summoning immolation.

*Or maybe that's just me.

SPM Jobman

Now that we have created our own .mat files from the SPM GUI and seen how it can be written to the disk, altered, and reloaded back into SPM, the hour is at hand for using the command spm_jobman. This is a command for those eager to disenthrall themselves from the tyranny of graphical interfaces through batching SPM processes from the command line.

I first met spm_jobman - also known as Tim - a few weeks ago at a conference, when I was at the nadir of my sorrows, despairing over whether I would ever be able to run SPM commands without the GUI. Suddenly, like a judge divinely sent in answer to the lamentations of the oppressed, spm_jobman appeared by my side, trig and smartly dressed, and said he would be more than happy to help out; and from my first impression of his bearing and demeanor, I believed I was in the presence of an able and reliable ally. Anyone who has ever met spm_jobman, I believe, has felt the same thing. However, as I learned too late, far from being a delight, he is a charmless psychopath; and he continues to infect my dreams with nameless horrors and the unrelenting screams of the abattoir.

spm_jobman has three main options to choose from: Interactive, serial, and run. After choosing one of these options, for the second argument you enter your jobs structure, which is automatically populated after loading the .mat file from the command line. Interactive will load the traditional GUI with the options filled in from the jobs structure, which you can then modify and execute as you please; Serial will prompt the user to fill in each field, with the defaults set to the values in the jobs structure; and Run will execute the jobs structure without cuing the GUI. For most purposes, if you decide to run spm_jobman at all, you will want to use the Run command, as this allows you to loop processes over subjects without pause, allowing you to do more useful tasks, such as Googling the history of the lint roller.

Saving .mat files from SPM is immensely helpful in understanding the relationship between the .mat files created by SPM, and what exactly goes into them; and this will in turn reinforce your understanding of and ability to manipulate Matlab structures. The following tutorials show how the .mat file is generated from the SPM interface, which can then be used as a template for spm_jobman. I've been working with SPM for years now, but found out about this only recently; and I hope that it helps ease the burden of your SPM endeavors.

Unix for Neuroimagers: Shells and Variables

First, a few updates:

1) We just finished our first week of the semester here, and although things haven't been too busy, it may be a couple of weeks before I get back on a steady updating schedule. I'll do what I can to keep dropping that fatty knowledge on the regular, and educating your pale, soy-latte-white, Famous Dave's BBQ-stained faces on how to stay trill on that data and stack that cheddah to the ceiling like it's your job. And if you got one of those blogs dedicated to how you and your virgin-ass Rockband-playing frat brothers with names like Brady and Troy and Jason eating those cucumber salad sandwiches or whatever and you drop a link to this site, I'll know it. You show me that love, and I show it right the hell back.

2) While you're here, how about you donate a piece of that stack to the American Cancer Society. I mean, damn; I'm out there seven days a week on those roads, sweating and suffering, but you - you're at work procrastinating again, wringing your snow-bunny white hands over whether you should drop out of graduate school or just toughen it out and graduate in eight years, and while you're at it possibly take a swipe at that new Italian breezey who just entered the neuroscience program. Donate first, worry about those problems later.

3) We got another performance for you all this November, including Schumann's Adagio and Allegro for cello and piano, Resphigi's Adagio con Variazioni, and the Debussy cello sonata. Time and location TBA. Also, more music videos will be uploaded soon, but while you're waiting, you can listen to the latest Mozart Fantasie in D Minor, which has proved one of my most popular videos to date; last I checked, it had 57 views, which I think qualifies for viral status. We goin' worldwide, baby! World-WIDE!!

4) AFNI tutorials are next on the docket, after wrapping up the intro Unix tutorials for neuroimagers, and possibly doing a couple more FSL tutorials on featquery, FSL's ROI analysis tool. Beyond that, there isn't much else I have to say about it; now that you've mastered the basics, you should be able to get the program to jump through whatever hoops you set up for it and to do whatever else you need. There are more complex and sophisticated tools in FSL, to be sure, but that isn't my focus; I will, on the other hand, be going into quite a lot of details with AFNI, including how to run functional connectivity and MVPA analyses. It will take time, but we will get there; as with the FSL tutorials, I'll start from the bottom up.

Anyway, the latest Unix tutorial covers the basics on shells and variables. Shells are just ways of interfacing with the Unix OS; different shells, such as the t-shell (tcsh) and bash shell, do the same thing, but have different syntax and different nomenclature for how they execute commands. So, for example, an if/else statement in the t-shell looks different from a similar statement in the bash shell.

Overall, there's no need to worry too much about which shell you use, although AFNI's default is tcsh, so you may want to get yourself used to that before doing too much with AFNI. I myself use tcsh virtually all of the time, except for a few instances where bash is the only tool that works for the job (running processes on IU's supercomputer, Quarry, comes to mind). There are lots of tcsh haters out there for reasons that are beyond me, but for everything that I do, it works just fine.

As for variables, this is one of the first things you get taught in any intro computer science class, and those of you who have used other software packages, such as R or Matlab, already know what a variable is. In a nutshell, a variable is a thing that has a value. The value can be a string, or a letter, or a number, or pretty much anything. So, for example, when I type in the command
set x=10
in the t-shell, the variable is x, and the value is now 10. If I wish to extract the value from x at any time, I prepend a dollar sign ('$') to it, in order to tell Unix that what follows is a variable. You can also use the 'echo' command to dump the value of the variable to the standard output (i.e., your terminal). So, typing
echo $x
returns the following:
which is the value that I assigned to x.

From there, you can build up more complicated scripts and, by having the variable as a placeholder in various locations in your script, only have to change the value assigned to it in order to change the value in each of those locations. It makes your programming more flexible and easier to read and understand, and is critical to know if you wish to make sense of the example scripts generated by AFNI's "uber" scripts.

With all of the tutorials so far, you have essentially all of the fundamentals you need to operate FSL. Really, you only need to understand how to open up a terminal and make sure your path is pointing to the FSL binaries, but after that, all you need to do is understand the interface, and you can get by with pointing and clicking. However, a more sophisticated understanding is needed for AFNI, which will be covered soon. Very soon. Patience, my pretties.

FSL Tutorials 4-5: Group-Level Analysis

It has well been said that analyzing an fMRI dataset is like using a roll of toilet paper; the closer you get to the end, the faster it goes. Now that you know how to analyze a single run, applying this concept to the rest of the dataset is straightforward; simply apply the same steps to each run, and then use the "Higher-Level Analysis" option within FEAT to select your output directories. You might want to label them for ease of reference, with the run number appended to each directory (e.g., output_run01, output_run02, etc).

Also uploaded is a walkthrough for how to locate and look at your results. The main directory of interest is the stats folder, which contains z-maps for each contrast; simply open up fslview and underlay an anatomical image (or a standard template, such as the MNI 152 brain, if it is a higher-level analysis that has been normalized), and then overlay a z-map to visualize your results. The sliders at the top of fslview allow you to set the threshold for the lower and upper bounds of your z-scores, so that, for example, you only see z-scores with a value of 3.0 or greater.

After that, the same logic applies to collapsing parameter estimates across subjects, except that in this case, instead of feeding in single-run FEAT directories into your analysis, you use the GFEAT directories output from collapsing across runs for a single subject. With the use of shell scripting to automate your FEAT analyses, as we will discuss in the next tutorial, you can carry out any analysis quickly and uniformly; not only is scripting an excellent way to reduce the amount of drudge work, but it also ensures that human error is out of the equation once you hit the go button.

Make sure to stay tuned for how to use this amazing feature, therewith achieving the coveted title of Nerd Baller and Creator of the Universe.