consolidating my setup notes for inclusion in a repo

setupNeuroimagingEnvironment.md

setupNeuroimagingEnvironment.md

All of my scripts and documentation assume that these neuroimaging resources have been installed. For each package I cover the three computing environments I currently use:

• OS X Mountain Lion + MacPorts
• Neurodebian on Ubuntu 12.04 on 64-bit processors
• Neurodebian VM, running Debian 7.0 wheezy 32-bit on VirtualBox

Software covered:

• neurodebian virtual machine
• itksnap
• mricron
• mricrogl
• imagej/fiji
• fsl
• afni
• BXH/XCEDE tools (from FBIRN)
• freesurfer
• spm

[email protected] updated: 20130523

Neurodebian Virtual Machine (VM)

1. Download the neurodebian VM .ova/.ovf:

• click "Get Neurodebian"
• Select operating system: Mac or Windows
• Download the Debian 7.0 .ova or zip/ovf file (I prefer the 32-bit version. Easier to distribute to heterogeneous hardware).

2. Download and install the latest VirtualBox binaries.

3. Follow the neurodebian install instructions, which they support with a youtube video.

4. Boot up the new virtual machine. Don't bother to select any new packages from the point-and-click wizard that autoruns.

ITK-SNAP

Installing the ITK-SNAP binary on OS X Mountain/Lion:

Download latest version from the ITK-SNAP Downloads page.

• Choose "MacOS Binary (Intel, 64 bit, OSX 10.5+)"
• Drag the resulting ITK-SNAP.app to /Applications folder

Install the ITK-SNAP binary on Ubuntu 12.04:

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install itksnap

###########################

MRIcron

###########################

#-----------------------------------------------------------------

Installing MRIcron on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

Download latest from http://www.nitrc.org/projects/mricron

( probably called "MRIcron [month]/[year] osx.zip")

Unzip the downloaded file (which currrentlyproduces a folder called osx).

Install:

cd ~/Downloads/osx/ mv mricron.app dcm2niigui.app npm.app /Applications/

Move dcm2nii to a folder in the $PATH, e.g., /usr/local/bin :

echo ${PATH} # does this contain /usr/local/bin ? ls /usr/local # is there a folder called bin inside of /usr/local ? If not: sudo mkdir /usr/local/bin sudo mv ~/Downloads/osx/dcm2nii /usr/local/bin/

#-----------------------------------------------------------------

Installing MRIcron on Ubuntu 12.04:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install mricron mricron-data mricron-doc

remember that preferences are stored here if you would like to edit them:

~/.dcm2niigui/dcm2niigui.ini

~/.dcm2nii/dcm2nii.ini

###########################

MRIcroGL

###########################

#-----------------------------------------------------------------

Installing MRIcroGL on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

Download from http://www.mccauslandcenter.sc.edu/mricrogl/

pay attention to downloaded filename: if you already had osx.zip

in your Downloads folder from mricrON, this may get called "osx(1).zip" etc.

cd ~/Downloads mkdir mricrogl cd mricrogl unzip ~/Downloads/osx.zip sudo mv mricrogl.app /Applications/ mv *.nii.gz /Users/Shared/sampleBrainVolumes/mricrogl # or other parent of sample data

save the pdf manual somewhere

###########################

ImageJ / FIJI

###########################

#-----------------------------------------------------------------

Installing FIJI on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

download dmg file from http://fiji.sc/Downloads, then do this:

cd ~/Downloads open fiji-macosx.dmg cp -R /Volumes/Fiji/Fiji.app /Applications/ hdiutil unmount /Volumes/Fiji open /Applications/Fiji.app

then install imagej plugins (instructions below)

#-----------------------------------------------------------------

Installing ImageJ/FIJI on Ubuntu 12.04:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install fiji

then install imagej plugins (instructions below)

#-----------------------------------------------------------------

Installing ImageJ plugins:

#-----------------------------------------------------------------

Even in 2013 imagej/fiji can't open .nii.gz files without a plugin (though .nii's work).

Download and install the plugin from http://rsb.info.nih.gov/ij/plugins/nifti.html :

cd ~/Downloads curl -O http://rsb.info.nih.gov/ij/plugins/download/jars/nifti_io.jar cp nifti_io.jar /Applications/Fiji.app/plugins/ # ...for OS X . Adapt for linux.

Re-open imagej/fiji. Opening nii.gz files should now work (drag & drop, or File->Open).

Also should now see five new commands in imagej/fiji:

File/Import/NIfTI-Analyze,

File/Save As/Analyze (NIfTI-1),

File/Save As/NIfTI-1,

File/Save As/Analyze 7.5 and

Analyze/Tools/Coordinate Viewer.

###########################

FSL

###########################

#-----------------------------------------------------------------

Installing FSL on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

Before installing FSL, freesurfer, or AFNI on Mountain/Lion be sure to install XQuartz,

and logout and then back in: (http://xquartz.macosforge.org)

Google "FSL install" and follow instructions. Currently here:

http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/MacOsX#Downloading_the_install_file_without_installing_the_software

There are multiple ways to install (as of May 2013). I get mixed results with the recommended fslinstaller.py, but I typically use it and then just fix whatever didn't work.

Run FSL's installer script in "download only" mode (about 1-hr):

cd ~/Downloads python fslinstaller.py -o

Calculate the md5 sum of the downloaded file and use it to launch installation:

fslDownload=fsl-5.0.2.2-macosx.tar.gz fslDestDir="/usr/local" fslMD5=md5 ${fslDownload} | awk '{ print $NF}' python fslinstaller.py -d ${fslDestDir} -f ${fslDownload} -C ${fslMD5}

After the install completes, confirm that the file /etc/bashrc received a block of FSL environmental variables (below).

If not, the install program may have added it to your personal ~/.profile or ~/.bash_profile instead.

For system-wide installation, remove from those files and append to /etc/bashrc:

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some FSL setup:

FSLDIR=/usr/local/fsl PATH=${FSLDIR}/bin:${PATH} export FSLDIR PATH . ${FSLDIR}/etc/fslconf/fsl.sh #------------------------------------------ EOF

cat /etc/bashrc

Either log out and back in again, or issue this terminal command:

. /etc/bashrc

TEST: did $FSLDIR get exported correctly? This should return "/usr/local/fsl" (no quotes) :

echo $FSLDIR

TEST: Does fslview exist in /Applications?

ls /Applications

...if not create a shortcut like this:

sudo ln -s /usr/local/fsl/bin/fslview.app /Applications/fslview.app

TEST: we should be able to open /Applications/fslview.app :

open /Applications/fslview.app

TEST: we should be able to open fslview.app from the commandline :

fslview ${FSLDIR}/data/standard/MNI152_T1_2mm_LR-masked.nii.gz

#-----------------------------------------------------------------

Installing FSL on Ubuntu 12.04:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install fsl-complete fsl-feeds

...but previous to fsl-completed, you needed to apt-get instal fsl-atlases fsl-feeds fsl-first-data fslview and fsl-feeds?

then get instructions for environmental variables (e.g., may need to source AFNI/FSL script from /etc/bash.bashrc)

man fsl

#-----------------------------------------------------------------

Installing FSL on Debian 7.0 Wheezy Neurodebian VM:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install fsl-complete fsl-feeds

...but previous to fsl-completed, you needed to apt-get instal fsl-atlases fsl-feeds fsl-first-data fslview and fsl-feeds?

then get instructions for environmental variables (e.g., may need to source AFNI/FSL script from /etc/bash.bashrc)

man fsl

After the install completes, confirm that the file /etc/bash.bashrc received a block of FSL environmental variables (below).

If not, the install program may have added it to your personal ~/.profile or ~/.bash_profile instead.

For system-wide installation, remove from those files and append to /etc/bash.bashrc:

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bash.bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some FSL setup:

. /etc/fsl/5.0/fsl.sh #------------------------------------------ EOF

cat /etc/bashrc

#-----------------------------------------------------------------

Install and run FSL test suite ("FEEDS"):

#-----------------------------------------------------------------

Download FEEDS from FSL (> 270 MB): http://fsl.fmrib.ox.ac.uk/fsldownloads/

(on neurodebian download via command "sudo apt-get install fsl-feeds")

Run FEEDS (http://fsl.fmrib.ox.ac.uk/fsl/feeds/doc/):

(on neurodebian, this is all replaced by command fsl-selftest or /usr/bin/time fsl-selftest)

2013 i7 imac: 971.77 real 951.78 user 22.83 sys

cd ~/Downloads (or where ever you saved your download) tar -zxvf fsl-*-feeds.tar.gz cd feeds /usr/bin/time ./RUN all

###########################

AFNI

###########################

#-----------------------------------------------------------------

Installing AFNI on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

Before installing FSL, freesurfer, or AFNI on Mountain/Lion be sure to install XQuartz,

and logout and then back in: (http://xquartz.macosforge.org)

…then download latest AFNI for Mac, unzip, and move to a reasonable location:

cd ~/Downloads curl -O http://afni.nimh.nih.gov/pub/dist/tgz/macosx_10.7_Intel_64.tgz tar -zxvf macosx_10.7_Intel_64.tgz sudo mv macosx_10.7_Intel_64 /usr/local/abin

Add AFNI's new location to the path in /etc/bashrc :

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some AFNI environmental variables:

export PATH=/usr/local/abin:${PATH} export AFNI_ENFORCE_ASPECT=YES #------------------------------------------ EOF

cat /etc/bashrc

Either log out and back in again, or issue this terminal command:

. /etc/bashrc

TEST: Open a new terminal window and test your afni install by issuing the command "afni" (no quotes) to open GUI

make sure AFNI_ENFORCE_ASPECT is working effectively (see below)

#-----------------------------------------------------------------

Installing AFNI on Ubuntu 12.04:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install afni afni-atlases

...then "man afni" to get instructions for environmental variables

(e.g., may need to source AFNI/FSL script from /etc/bash.bashrc)

In the event that the neurodebian version of AFNI is broken/old/whatever

you may want to substitute a binary version from outside of neurodebian.

Two steps to do that:

1) Download, unzip, and move to a reasonable destination (not overwriting

neurodebian's afni in the process):

curl -O http://afni.nimh.nih.gov/pub/dist/tgz/linux_xorg7_64.tgz # (> 600 MB) tar -zxvf linux_xorg7_64.tgz mv linux_xorg7_64 ~/abin

2) Kill neurodebian's AFNI environmental variables and add

this new directory (~/abin in my example) to $PATH (see below)

#-----------------------------------------------------------------

Installing AFNI on Debian 7.0 Wheezy Neurodebian VM:

#-----------------------------------------------------------------

I'm currently happy with the version in the neurodebian repos:

sudo apt-get install afni afni-atlases

...then "man afni" to get instructions for environmental variables

(e.g., may need to source AFNI/FSL script from /etc/bash.bashrc)

For system-wide install, source the AFNI config file from /etc/afni/afni.sh :

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bash.bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some AFNI environmental variables:

. /etc/afni/afni.sh #------------------------------------------ EOF

cat /etc/bashrc

#-----------------------------------------------------------------

Checking and Setting env variable AFNI_ENFORCE_ASPECT :

#-----------------------------------------------------------------

In some environments the AFNI GUI allows you to accidentally distort image

aspect ratio by resizing an image window. Not good, but avoidable:

First here's a reminder of how to read and set AFNI environmental variables:

afni -help | grep Vname afni -help | grep Dname

If the following command returns no output, the variable AFNI_ENFORCE_ASPECT isn't set

[sic: yes, this command should end with "=" as written here:]

afni -VAFNI_ENFORCE_ASPECT=

To set AFNI_ENFORCE_ASPECT on a per-execution basis, can launch the afni GUI with:

afni -DAFNI_ENFORCE_ASPECT=YES

#-----------------------------------------------------------------

Unsetting AFNI environmental variables:

#-----------------------------------------------------------------

Sometimes you need to clear AFNI-related environmental variables, for example

if Neurodebian is installed but you need to temporarily use AFNI installed in a user-space directory:

unset env | awk -F= '/AFNI/ ${print $1}' | xargs

...this would probably be followed by listing your local user-space afni directory

earlier in the path than the system-wide afni directory, for example:

export PATH=~/abin:${PATH}

...and then check that the "right" AFNI will run:

which afni which 3dinfo

###########################

BXH/XCEDE FBIRN TOOLS

###########################

#-----------------------------------------------------------------

Installing BXH/XCEDE tools on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

As of May 2013, the shipping binaries of BXH/XCEDE tools includes broken imagemagick.

Here's a script describing the problem and my work-around:

http://goo.gl/9Rd6V

...after executing the steps in that script do this to confirm

the changes to /etc/bashrc :

cat /etc/bashrc

Either log out and back in again, or issue this terminal command:

. /etc/bashrc

TEST: did $BXHDIR get exported correctly? This should return a listing of bxh programs :

ls $BXHDIR

#-----------------------------------------------------------------

Installing BXH/XCEDE tools on Debian Linux 7.0 Wheezy Neurodebian VM

#-----------------------------------------------------------------

manualy download most recent bxh/xcede release from nitrc: http://www.nitrc.org/projects/bxh_xcede_tools

ls -l ~/Downloads/bxh_xcede_tools-*.tgz

bxh_xcede_tools-1.10.7-lsb31.i386.tgz

unpack and install bxh/xcede:

...first declare the bxh version as it appears in the download filename:

bxhVersion=1.10.7

...then unpack and install

cd ~/Downloads tar -zxvf bxh_xcede_tools-${bxhVersion}-lsb31.i386.tgz sudo mv bxh_xcede_tools-${bxhVersion}-lsb31.i386 /opt/ sudo ln -s /opt/bxh_xcede_tools-${bxhVersion}-lsb31.i386 /opt/bxh

for system-wide access, configure the environment via /etc/bashrc :

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bash.bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some BXH/XCEDE environment statements:

BXHDIR=/opt/bxh PATH=${BXHDIR}/bin:${PATH} export BXHDIR PATH #------------------------------------------ EOF

###########################

FreeSurfer

WARNINING: Stable 5.2 release WITHDRAWN awaiting upcoming version 5.3

###########################

If you haven't done so already, obtain a license, and copy the .license file to your

$FREESURFER_HOME directory per https://surfer.nmr.mgh.harvard.edu/registration.html

#-----------------------------------------------------------------

Installing FreeSurfer on Mac OS X Mountain/Lion:

#-----------------------------------------------------------------

Before installing freesurfer on Mountain/Lion be sure to install XQuartz (http://xquartz.macosforge.org)

and FSL (b/c FS's install will detect location of FSL).

Download latest .dmg from the Freesurfer Wiki:

http://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall

This can be done from the commandline instead of the webpage:

fsFtpDir="ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.2.0" fsFtpFilename="freesurfer-Darwin-lion-stable-pub-v5.2.0.dmg" cd ~/Downloads curl -O ${fsFtpDir}/${fsFtpFilename}

…and to resume a failed download:

curl -C - -o ${fsFtpFilename} ${fsFtpDir}/${fsFtpFilename}

confirm that the download is valid:

sh <<EOF curl -s -o freesurfer_md5sums.txt http://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/md5sum.txt echo "" echo "expected md5 sum:" grep ${fsFtpFilename} freesurfer_md5sums.txt echo "" echo "md5sum of downloaded ${fsFtpFilename}:" md5 ${fsFtpFilename} echo "" echo "(re-download if they don't match)" echo "" EOF

Doubleclick on the .dmg and run the .pkg installation file found inside of it.

Detailed instructions at http://surfer.nmr.mgh.harvard.edu/fswiki/Installation

(Note the folder that this installs to, likely /Applications/freesurfer, which you will assign to $FREESURFER_HOME below.)

add post-install config to /etc/bashrc per the bash section of

http://surfer.nmr.mgh.harvard.edu/fswiki/SetupConfiguration) :

WARNING: note the ${escapedVariables} below, which

are escaped for heredoc (http://goo.gl/j3HMJ).

Un-escape them if manually typing into a text editor.

Otherwise, just paste these lines to your bash prompt

(up to and including "EOF" line):

editDate=/bin/date +%Y%m%d editTime=$(date +%k%M) sudo tee -a /etc/bashrc >/dev/null <<EOF #------------------------------------------

on ${editDate} at ${editTime}, $USER

added some freesurfer environmental variables:

export FREESURFER_HOME=/Applications/freesurfer . ${FREESURFER_HOME}/SetUpFreeSurfer.sh #------------------------------------------ EOF

cat /etc/bashrc

copy the sample data to a place where users can write to it:

cp -a $SUBJECTS_DIR /Users/Shared/fs_sampleSubjects

edit ${FREESURFER_HOME}/SetUpFreeSurfer.sh to reflect the change in $SUBJECTS_DIR, then

either log out and back in again, or issue this terminal command:

. /etc/bashrc

TEST: open a new terminal windows. You should see a number of freesurfer-related

lines at the top of the new terminal window, and all the terminal windows you open after that.

TESTS: Test your installation by issuing the test commands detailed on the Testing Freesurfer webpage

(as of January 2013: http://surfer.nmr.mgh.harvard.edu/fswiki/TestingFreeSurfer )

TEST freeview:

freeview
-v $SUBJECTS_DIR/bert/mri/norm.mgz
-v $SUBJECTS_DIR/bert/mri/aseg.mgz:colormap=lut:opacity=0.2
-f $SUBJECTS_DIR/bert/surf/lh.white:edgecolor=yellow
-f $SUBJECTS_DIR/bert/surf/rh.white:edgecolor=yellow
-f $SUBJECTS_DIR/bert/surf/lh.pial:annot=aparc:edgecolor=red
-f $SUBJECTS_DIR/bert/surf/rh.pial:annot=aparc:edgecolor=red

TEST tkmedit (volume viewer):

tkmedit bert orig.mgz tkmedit bert norm.mgz -segmentation aseg.mgz $FREESURFER_HOME/FreeSurferColorLUT.txt

TEST tksurfer (surface viewer):

tksurfer bert rh pial

TEST short reconstruction segment (< 30 minutes)

recon-all -s bert -autorecon1

TEST full reconstruction (~ 24 hours)

2013 i7 iMac:

recon-all -s bert finished without error at Mon May 6 00:52:13 EDT 2013

22032.75 real 21947.85 user 60.84 sys

recon-all -s bert -all

#-----------------------------------------------------------------

Installing FreeSurfer on Ubuntu 12.04 :

#-----------------------------------------------------------------

download latest .tar.gz from the Freesurfer Wiki:

http://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall

This can also be done from the commandline instead of the webpage:

fsFtpDir="ftp://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/5.2.0" fsFtpFilename="freesurfer-Linux-centos4_x86_64-stable-pub-v5.2.0.tar.gz" cd ~/Downloads wget ${fsFtpDir}/${fsFtpFilename}

…and to resume a failed download:

curl -C - -o ${fsFtpFilename} ${fsFtpDir}/${fsFtpFilename}

confirm that the download is valid:

sh <<EOF curl -s -o freesurfer_md5sums.txt http://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/md5sum.txt echo "" echo "expected md5 sum:" grep ${fsFtpFilename} freesurfer_md5sums.txt echo "" echo "md5sum of downloaded ${fsFtpFilename}:" md5 ${fsFtpFilename} echo "" echo "(re-download if they don't match)" echo "" EOF

###########################

SPM (Mountain Lion)

###########################

Download the latest SPM 8 package.

(currently from http://www.fil.ion.ucl.ac.uk/spm/software/spm8/ )

Unzip the downloaded SPM package and move the resulting SPM folder to /usr/local ,

so that SPM's program files are not in /usr/local/spm.

Open matlab and issue the command "userpath;" (no quotes). This will tell you what

folder Matlab is going to look in for certain files. You care about this folder because

in the next step you're going to create a special file that gets placed there.

In the Matlab window issue the command "pathtool;" (no quotes). This opens a new window.

In this window, add /usr/local/spm to # the list of folders that Matlab searches for files.

Upon clicking "save", this window may complain about problems creating a file called pathdef.m, and ask you where you would like to put this file. Put it on the folder that was returned by the userpath # command you entered earlier.

Test your installation by closing and then reopening Matlab. Type "spm;" (no quotes) at the Matlab prompt, and the SPM graphical user interface should open.