For simplicity, let’s say that we have a 5×5 matrix of data (it’s really a 6×6 but we’ll just focus on the 25 numerical data values):

   X1 X2 X3 X4 X5
Y1 3000 5000 745 122 875
Y2 942 400 263 558 991
Y3 325 584 775 381 545
Y4 654 336 272 883 235
Y5 241 154 782 754 899

Notice that the column headers do not always line up with the rest of the columns; this is nothing to worry about. If you have a file like this (or are creating one), it is helpful to have a blank new line at the end (i.e., a blank extra row). This can help with the display and processing of text files.

Say you want to display the contents of the text file. Any easy way to do this is with cat {file}.txt. This will quickly display the contents on the screen. If it’s a long text file, you should use less {file}.txt instead of cat.

Here’s what this looks like with our sample file.

If you want to number the lines, you can run cat -n {file}.txt, which results in a display like this:

Or, you can use awk: awk 'FNR==1{print ""}1' {file}.txt

Now, let’s say that instead of the entire file, you just want a row of values or a single value. Here’s a way to display just one row: awk 'BEGIN { RS = "" ; FS = "\n" } ; { print $2 }' {file}.txt

The {print $2} specifies the second row in the file. This could be changed to $3, $5, $8, or whatever you want, if it’s a valid row number in the file.

You could also write that line to a new file with > or the pipe |.

Now, what if you want a column from the file?

awk '{ print $3 }' {file}.txt

Now, what if you want only a single value from the text file. I know there are shorter ways of doing this but one way is to do a two-step awk command by combining the column and row commands I already demonstrated:

awk 'BEGIN { RS = "" ; FS = "\n" } ; { print $2 }' {file}.txt | tee -a file_tmp.txt;
awk '{ print $3; exit }' file_tmp.txt | tee -a subject_volume.txt;
rm file_tmp.txt

This displays the second row in the file and writes it to a temporary file; then it reads and displays and saves the value from the 3rd column in the temp file. The “exit” part of the second command will limit the print command to a single value, should there be multiple values in the column (or row). Lastly, it deletes the temp file. In the screenshot above, I am showing the value in the second row, third column (this includes the row and coumn labels). You could also run this with the column command first, if that’s easier.

This can save you a lot of time if you have to pull out values from a lot of text files (e.g., aseg.stats) by using a for or while loop. I recently did this to pull values out of some text files. It would have taken hours to pull out the correct values from every participant by hand. With a script (series of “for” loops) it ran in seconds. Then, I had a file with all the values for all the participants, which was then imported into Excel.

I am a novice user of awk so specific questions about it are best directed elsewhere. This is just what I’ve figured out by reading various guides online.

Part of the difficulty with the flexibility of nonlinear registrations is that they can be too flexible. This is a problem when you are trying to align diffusion weighted scans to T1 scans, for example. Here are a couple images showing some distortion. This distortion is mostly due to proximity to the air filled sinuses.

A b0 image (no diffusion weighting applied) showing frontal distortion.

One direction from a 64 direction dwi sequence showing temporal distortion.

With very flexible nonlinear registration methods on a skull-stripped brain, the tools try to stretch brain regions to fit; if there is warping or other distortion, we do not get good results. Using a non-skull-stripped brain sometimes fixes the problem but in some cases (intra-individual inter-modal) nonlinear methods are likely overkill.

I’ve been doing trial runs with FreeSurfer’s bbregister in order to see how well it works. It’s relatively simple.

First, the T1(s) of a subject should be processed through the recon-all Freesurfer script. Next, if you want you can use FreeSurfer’s script dt_recon to do preliminary processing of diffusion data. That’s actually the easiest pathway because it will register your diffusion data to your structural data in the process. The matrix file you will need is called register.dat (see screenshot).

If you did not or do not want to run dt_recon (it uses a number of FSL’s diffusion tools), you can create that registration file by hand using bbregister. To do this type a command like this:

bbregister --s sub001 --mov /{path to b0 image}/lowb.nii.gz --reg /{path to where you will save the matrix file}/lowb2orig.dat --dti --init-fsl

What this does is create a .dat (matrix) file that tells an image how to get from diffusion space to FreeSurfer’s conformed space (i.e., the 256x256x256 1x1x1mm space that orig.mgz is in). You could set your --mov as the orig.mgz and add a --target with it set to your b0 (lowb or nodif or whatever the file is called) image. Without a --targ a conformed image (e.g., orig.mgz) is the implied target. I typically make the diffusion image the movable one and then apply the inverse matrix to files in conformed space that I want to be in diffusion space. It seems a little backward but it works well. [Note: I could be mistaken about this but I believe it is the case].

You’ll see something like this in your Terminal:

You can check your results with tkregister2: tkregister2 --mov /{path to b0 image}/lowb.nii.gz --reg /{path to where you will save the matrix file}/lowb2orig.dat --surf

You’ll see something like this in tkregister2:

I’ve yet to get a bad result but we have good MRI data.

Now you can use this registration matrix to get ROIs from FreeSurfer’s conformed space (this example was made up with an occipital ROI that could have been created in ITK-SNAP; you could also change all of aseg.mgz into diffusion space this way) into diffusion space with mri_vol2vol:

mri_vol2vol --mov /Users/Shared/DWI_MAS/sub001/DATA/nodif.nii.gz --targ /Users/Shared/DWI_MAS/sub001/ROIS/sub001_r_occipital_roi.nii.gz --o /Users/Shared/DWI_MAS/sub001/ROIS/sub001_r_occipital_roi2dwi.nii.gz --reg /Users/Shared/DWI_MAS/sub001/DATA/orig2nodif.dat --inv –-nearest

Note the --inv that specifies to apply the inverse of the matrix (conformed –> diffusion rather than diffusion –> conformed).

It also works for getting FreeSurfer cortical labels into diffusion space with mri_label2vol (note: you’ll want to play around with the --proj option to see what works for you):

mri_label2vol --label /Applications/freesurfer/subjects/sub001/label/lh.entorhinal_exvivo.label --reg /Users/Shared/DWI_MAS/sub001/DATA/nodif2orig.dat --fillthresh .3 --hemi lh --subject sub001 --o /Users/Shared/DWI_MAS/sub001/rois/sub001_l_exvivo_erc.nii.gz --temp /Users/Shared/DWI_MAS/sub001/data/nodif.nii.gz --proj frac 0 1 .1

There you go! Using bbregister, you can end up with good intra-individual, inter-modal registrations. I went beyond a simple registration but registrations are only really useful as one very important step in a broader imaging process.

The repository includes a number of neuroscience packages (programs) for easy installation and update (e.g., FSL, MRIcron, AFNI, 3d Slicer, ITK-SNAP). You can add the repositories to your existing Linux installation (Debian or Ubuntu) or you can download a Debian virtual machine, which allows you to try out Debian and the repository without altering your current system. To use this virtual machine you need to install VirtualBox (a free download for Windows, Linux, Mac, or Solaris). The setup is easy and explained on the neurodebian website.

Here’s what it looks like running on my Mac (or you can visit this link for a full-size screenshot):

I haven’t had an opportunity to use it much yet but I wanted to spread the word about this service. I’ll post more about it once I have an opportunity to use it more. It makes the installation and management of many popular neuroscience programs easy (for example, it can be as easy as: sudo apt-get install ants). Unless you are doing very graphics heavy 3D imaging work, virtualizing many neurodebian will have plenty of performance on modern computer systems.

Here is a great, in-depth introduction to Bash scripting. That link takes you to a directory where you can select the format of the guide: HTML, PDF, or a few others. I did not create that guide or have any role in its creation. It was created by people affiliated with The Linux Documentation Project.

The guide might be more in-depth than you might need for your neuroimaging scripting needs but it is a great resource if you want to brush up on your scripting. Then, if you branch out to a language like Perl, it will likely be easier to learn.

RAM

If you want to stick with a Mac environment, a Mac Pro would be ideal (although we use iMacs, which work wonderfully). If you plan on running a lot of processes in parallel or doing some intensive visualizations, put as much RAM in the computer as possible. The current generation of Mac Pros can accept 64 GB of RAM; the current iMacs accept 16 GB of RAM. However, if you are not going to do a lot of intensive visualization (if you are not going to use TrackVis, for example), 8 GB of RAM should be the minimum. Again, get as much RAM as possible but get at least 8 GB. I like at least 2 GB per processor/core.

As far as the quality of RAM is concerned, most RAM is pretty good quality now; you do not necessarily have to use really expensive RAM unless your system calls for it. It is a good idea to run a memory test though to check for any problems.

CPU

The rule with the CPU is the same as with RAM – get as much as you can. Not all processes are parallelized but some are. Additionally, for something like FreeSurfer, if you have multiple processors (or just multiple cores), you can run multiple instances of the program concurrently. This is another reason why you want as much RAM as you can have – each process uses RAM so the more you run, the more RAM you need. As far as processors go, it doesn’t matter if you use Intel or AMD (or something else); I prefer Intel but I just built an AMD box and in the end, it doesn’t matter too much which company you choose. For imaging, I recommend at least 4 cores/processors but get as many as you can. In our lab we have iMacs with i7 hyperthreaded cores (4 real cores plus 4 virtual cores). You can get a Mac Pro with 12 cores (2 six core processors), which would be great for imaging work. Of course, you could build a Linux machine with similar specifications for cheaper than the Mac Pro but there are good reasons for choosing either path. If money is not an option (and you don’t need really high-end stuff), I’d recommend Macs. You could, alternatively, chain a number of Mac Minis together and build your own little processing farm. Mac Minis don’t have the best processors but if you can parallelize tasks, a stack of Mac Minis might do the trick. Of course, if you have access to a supercomputer, that can be even better (although, there are plenty of reasons to avoid supercomputers too).

Conclusion

In summary, you can never have too much RAM and too much processing power when it comes to neuroimaging. If you think that the costs up front are high, wait until you have to do work over and have to wait for your computers. The less time you spend processing, the more time you have to analyze and write. Generally time that you spend waiting for processes to finish is wasted time. That’s why you want the fastest computer with as much RAM as you can afford. I have to reiterate though that you only need buckets of RAM (>8 GB or so) if you are doing a lot of visualization, otherwise, you don’t have to get too much RAM (>16 GB).

I’ll address graphics cards in a future post, especially as they apply to imaging (e.g., CUDA and FreeSurfer).

Obtaining reliable data and drawing meaningful and robust inferences from diffusion MRI can be challenging and is subject to many pitfalls. The process of quantifying diffusion indices and eventually comparing them between groups of subjects and/or correlating them with other parameters starts at the acquisition of the raw data, followed by a long pipeline of image processing steps. Each one of these steps is susceptible to sources of bias, which may not only limit the accuracy and precision, but can lead to substantial errors. This article provides a detailed review of the steps along the analysis pipeline and their associated pitfalls. These are grouped into 1 pre-processing of data; 2 estimation of the tensor; 3 derivation of voxelwise quantitative parameters; 4 strategies for extracting quantitative parameters; and finally 5 intra-subject and inter-subject comparison, including region of interest, histogram, tract-specific and voxel-based analyses. The article covers important aspects of diffusion MRI analysis, such as motion correction, susceptibility and eddy current distortion correction, model fitting, region of interest placement, histogram and voxel-based analysis. We have assembled 25 pitfalls (several previously unreported) into a single article, which should serve as a useful reference for those embarking on new diffusion MRI-based studies, and as a check for those who may already be running studies but may have overlooked some important confounds. While some of these problems are well known to diffusion experts, they might not be to other researchers wishing to undertake a clinical study based on diffusion MRI.

I think this is a must-read article for anyone working with diffusion imaging. There are a lot of wonderful things that we can do with diffusion weighted images but we have to be conscious of the limitations and sources of bias in this type of imaging. The day we stop questioning and challenging our methods and results – thinking critically about our methods and personal biases – is the day our science really suffers. We as scientists have an obligation to do the best work possible because our research can have broad, applied implications that might affect a lot of people for good or ill. At the very least, scientists add to the general pool of knowledge and we want that pool as free from contaminants as possible. It is critical thinkers like Jones and Cercignani who help keep scientists honest with their (our) methods, even if we sometimes act out of innocence by using methods we do not really understand.

Here’s the reference: Jones and Cercignani. Twenty-five pitfalls in the analysis of diffusion MRI data. NMR in biomedicine (2010) vol. 23 (7) pp. 803-820.

I want to be able to work with the FreeSurfer created files in other programs so I’ll convert to nii.gz.

mri_convert /Applications/freesurfer/subjects/{subjectID}/mri/orig.mgz /Applications/freesurfer/subjects/{subjectID}/mri/orig.nii.gz

Now I want to convert the aseg.mgz file over. I’ll use a different method than mri_convert or mri_binarize (although both could work).

mri_label2vol –subject {subjectID} –seg /Applications/freesurfer/subjects/{subjectID}/mri/aseg.mgz –fillthresh .8 –identity –temp /Applications/freesurfer/subjects/{subjectID}/mri/orig.mgz –o /Applications/freesurfer/subjects/{subjectID}/mri/aseg2vol.nii.gz

Technically, I didn’t need the –subject on there but I like to include it just as a redundancy.

Here’s the output in ITK-SNAP:

But I don’t need all of the brain structures, I just want the left caudate (label 11).

mri_binarize –i /Applications/freesurfer/subjects/{subjectID}/mri/aseg2vol.nii.gz –match 11 –o /Applications/freesurfer/subjects/{subjectID}/mri/left_caudate.nii.gz

You actually can run that command with the basic aseg.mgz (and thus skip the mri_label2vol step above) but I wanted to show both. I’d recommend using mri_label2vol for binary mask creation but for subcortical structures it shouldn’t matter. Running this conversion both ways (mri_label2vol and mri_binarize) results in a perfect mask overlap (the blue and red caudates – one from each method – appear purple in this screenshot).

Now say you wanted to make a mask a little bit bigger or a little bit smaller (to either pick up surrounding voxels or to exclude part of a mask). You can use mri_binarize to do that (you could even do this with the step above, I’m separating it out for simplicity):

mri_binarize –i /Applications/freesurfer/subjects/{subjectID}/mri/left_caudate2.nii.gz –erode 1 –match 2 –o /Applications/freesurfer/subjects/{subjectID}/mri/left_caudate3.nii.gz

In that command I input (–i), erode 1 voxel in 3D (–erode 1) from the left caudate (–match 2; that is a 2 because I created this binary mask earlier and gave the left caudate a value of 2), and then specify an output (–o).

Here you can see the results (visualization in FSLView, which I’m not overly fond of but it makes viewing mask overlap very easy):

As you can see, the eroded caudate is one voxel smaller in 3D than the original caudate.

You can created a summed overlap file (or combine any mask files in the same space together) by using fslmaths (you can also do this with the mri_binarize –merge option but I’m just introducing a range of tools):

fslmaths {input file} -add {adding file} {output}

First I will start with a more complicated example before I get to the for loop. This one requires a little bash scripting. You have a problem, you want to create 400 subject directories (don’t ask me why, I’m just providing an example) but don’t want to create them one by one. A simple script could save a lot of time:

#!/bin/sh

t=0 #this specifies a starting value

read -p “How many subject directories would you like to create? ” SUBS ;

let SUBS1=${SUBS}+1 #creates a new variable (SUBS1) that is one value greater than the input

condition ()

{

((t++))

if [ $t -lt ${SUBS1} ]

then

return 0  # true

else

return 1  # false

fi

}

read -p “Enter the full path (no trailing /) to the directory where you would like to create the directories: ” SUBSDIR

while condition

#     ^^^^^^^^^

#     Function call — ${SUBS1} loop iterations.

do

mkdir ${SUBSDIR}/sub${t} ; #The “sub” could be changed to whatever you want the prefix to be (e.g., blind, subject, con, exp).

done

This script was modified from one on this site (about bash loops) with input from this site (about bash mathematics). I created that script even though you (or I) probably will not use it very much or at all; it is useful for showing a quick way to create a lot of consecutively numbered directories somewhere on your computer. This script also can be modified as needed in order to do similar functions. I actually only wrote the script so I would have a list of directories to use for this example. Here is the result of the script:

Now I will move on to the real purpose of this post: not scripting but for loops.

Let’s say that you want to create a labels directory within a series of subjects’ FreeSurfer directories (or anywhere else). We can pretend that those subjects directories I created above are my FreeSurfer subjects. For this we do not need to write a whole script; a simple for loop will suffice.

First cd to your FreeSurfer subjects directory – e.g., cd /Applications/freesurfer/subjects

Then create a text file with the list of subject directories you want to deal with: ls >> blinds.txt

Next, open that file to remove any unwanted items: open -a TextEdit blinds.txt

After it only contains a list of the subjects you are ready to save it, close it, and proceed.

Now we are ready to use a for loop to create a bunch of directories called labels (one within each FreeSurfer subjects directory):

for blind in `cat blinds.txt`; do mkdir /Applications/freesurfer/subjects/${blind}/labels; done

That’s it. Pretty simple! A for loop requires a for, a do, and a done. The semi-colons ( ; ) are required when running a multi-step command like this on a single line.

Here is a screenshot of what my subjects directory (pretend this is my FreeSurfer subjects directory) now looks like:

Also notice the blinds.txt file that I created by listing the subjects directory and saving that output to a text file (which I then edited).

That is one example of a simple for loop. Any repetitive task that we can use bash for can be put in a simple loop like that. Here is another example using a FreeSurfer command (all the dashes are double dashes): for blind in `cat blinds.txt`; do mri_annotation2label --subject ${blind} --hemi lh --outdir labels; done

Or, you could copy a number of files from one location to another: for blind in `cat blinds.txt` ; do mkdir /my_new_imaging_directory/${blind} ; cp ./${blind}/${blind}_T1.nii.gz /my_new_imaging_directory/${blind}/${blind}_T1.nii.gz ; done

That loop is slightly more complicated, it has a couple commands in the do part. First, I make a series of new target directories (you wouldn’t need to include that if the target directories exist already): mkdir… ; then, I copy images from one location to another: cp …. A command like this is useful in a script if you want to create temporary files to process further and then remove. I like to create copies of files so I do not accidentally and permanently alter the original images. Just make sure you remove the temp files when you are done or you will end up with a lot of redundant files.

Looping is one reason why it is important to be consistent in labeling files and directories. Name directories that make sense; keep all your images and files organized. If you are consistent, you can throw a simple for loop together and save a lot of time without having to write a script. I use loops at least weekly but I create or use scripts less often.