MGH

back to the main page

 

glossary of technical terms (unix and imaging) and links to other relevant technical information

 

search the CNL site

 

image analysis software info and links

 

image rotation, orientation, and translation

 

A basic "How to" for Bob Cox's Automated Functional NeuroImaging analysis program

 

How to do Event-Related Analyses in Afni

 

information about the Statistical Parametric Mapping image analysis program

This information is very old...most machines where this stuff were installed are gone...still, it is a lot of information, so I'd hate to just delete it when it might be useful to someone, somewhere.  Dianne Patterson 10/25/2006

At the CNL, there are two versions of the MGH program in use. The older version is used, together with afni to perform event related analyses. This technique has been our standby for years and more information can be found on the afni event page. The new MGH program (described here) is a massive undertaking that only runs on linux and still presents difficulties that prevent its general adoption.

The new MGH Software package includes several components: the fsfast tools, afni, fsl and freesurfer. It is freely available for download as several tar files. Portions of the MGH software require Matlab. The package is a work in progress and requires considerable perseverance to install and run.

For the sections on Preprocessing and Analysis, I have borrowed copiously, unabashedly and often verbatim from the MGH-NMR-StdProc-Handbook, the Fsfast tutorial (See Downloads), and the usage messages for the mgh programs. Those documents contain lots of information that will not be found here. Thanks to Scott Hayes for his patient explanations, great notes and assistance in creating this.

I would appreciate any comments or questions from users who encounter errors or find gaping holes in this tutorial. This is not meant to be comprehensive and is certainly not the only way to analyze the data, rather it is meant to provide a place to begin and an example of a set of steps that really works...so that, by analogy, you can create your own data analysis. If you have never processed image data before, or you are not familiar with unix, I recommend that you start with the unixintro and the afni pages. Thanks!

MGH Resources

Setup Instructions for Users (CNL)

  • Parent Subjects Directory: Logon to charlie. To use the MGH programs on Charlie, you will first need to decide where your parent subject directory will be. You may choose any of the RAID towers or Charlie's "data" directory (if there is enough room on the latter). Make the parent subject directory, (but make sure there is not already a directory by that name so you don't overwrite something) e.g.,
    >mkdir tutorial
  • Subject Directory Environment Variable: By default, MGH thinks that the parent subject dir is /data/freesurfer_alpha/subjects...so you will need to inform it otherwise. You must set the environment variable to your parent subject directory every time you run the tools. On Charlie this can be automated by adding the setenv SUBJECTS_DIR command to your .cshrc as part of the mgh alias (the basic mgh alias is already setup for all users on Charlie), eg.,:
    alias mgh 'source /data/freesurfer_alpha/mgh.csh'
    Could be changed to the following to set /buddy/data/tutorial as the parent subject directory:
    alias mgh 'source /data/freesurfer_alpha/mgh.csh; setenv SUBJECTS_DIR /buddy/data/tutorial; echo "SUBJECTS_DIR $SUBJECTS_DIR"'

    The above alias sources the files, sets the parent subject directory and echoes the new parent subject dir back to screen (actually, first it'll echo the default parent subject directory, then later it'll echo your parent subject directory). After you have set up the environment variable for the parent subject directory (as directed above), and you have sourced your .cshrc, type:
    >mgh
    If you need to move your directories and files, simply copy them to a new parent directory (e.g., on one of the raid towers) and reset the alias for the SUBJECTS_DIR to point to the new location. You will need to source your .cshrc again and rerun mgh for the changes to take effect. Do NOT try to use a link to point to your parent subject directory. The MGH tools have trouble with links.
    The environment should be completely set up. However, you still need to get your data and set up your directory structure and the correct configuration files (see mkmgh below).
  • Get the data: To do the tutorial, you'll need the two tarred gzipped files, e25996start.tgz and e26154start.tgz, from the MGH Tutorial Data directory on merlin (these are big, be patient). These tar files contain two directories, e25996 and e26154 respecitively, with the following raw data: renamed 3D structural image files in an Anatomy directory, and byte swapped bshorts in appropriate run directories (001 and 002), with their associated par.txt files. Untar each (e.g., tar zxvf e25996start.tgz) up above your parent directory (e.g., place the tar files on /buddy/data and untar them there).
  • Run mkmgh: On Charlie, use the mkmgh script (also available in Local Resources) to create the directory structure and files that mgh expects. Make sure you are in your parent subject directory when you run the mkmgh program. mkmgh will create the necessary talairach link, directory structures and files with appropriate values. Check the results. Simply type the following for the tutorial data:

    >mkmgh -nr 2 -ns 25 -ntr 349 -tr 2.5 -z 4.5 -v e25996 e26154
  • Explanation: What mkmgh does

Data Preparation

Prepare 3D Structurals

  • Purpose: Prepare the 3D structural images by converting them to the correct format and putting them into the expected directories. This is accomplished in two steps. In the first step you make an afni brik. In the second step, you convert the brik to COR files and dump those COR files into the expected directory for each subject.
  • Commands to make a BRIK:
    • The following commands assume you have renamed the *.MR files so that the operating system orders them correctly. The tutorial files have this done.
    • >cd e25996
      >to3d -anat -prefix 3dvol ’Anatomy/E25996S4*’
    • Explanation: to3d is the command. -anat is a flag telling afni that this is an anatomical file. -prefix is a flag that is followed with the prefix that you want to be assigned to the output file. seqplus="sequential in the plus direction". Finally, list the path to the files to be used in the BRIK.
    • GUI: In the to3d window, choose square pixels, slice thickness, z: 1.5 (use square or irregular radio buttons to set). Field of view: 220 (All of this should be okay by default, but check the values).
      Assume a sagittal view, set
      x orientation: Anterior to Posterior
      y orientation: Superior to Inferior
      z orientation: Right to Left (This is not the normal for building a 3D afni BRIK, but seems to work correctly for BRIKs that will be converted to COR files)
    • Byte swap the image (Take a look, you can toggle the byte swapping with the Byte Swap button and see that the swapped version is cleaner).
    • You will be asked to specify a directory where the output will be written. "." (without the "") for "here" will work okay.
    • Repeat the procedure for each subject
  • Command to convert BRIK to COR files and Move Them
    • Usage: mri_average [options] <volume> ... <output volume>
      -a rigid alignment of input volumes before averaging       (what is the conform flag? Not a clue)
    • Command Example
      >mri_average -conform 3dvol+orig.BRIK /buddy/data/tutorial/e25996_anat/mri/orig (for this command, like the ones to follow, you must substitute the approapriate paths)
    • Repeat conversion for each subject. In the case of the tutorial, the 3D structurals in e26154 are S5 rather than S4.

Prepare Functionals

  • Purpose: You need the correctly formatted functional files and their associated parameter files in each run directory. The tutorial data provides a set of bshorts and an appropriate par.txt file for each run. Simply copy these into the appropriate directories in your Subject Directory.
  • Command Examples:
    >cp e25996/001/* /buddy/data/tutorial/e25996/bold/001/
    >cp e25996/002/* /buddy/data/tutorial/e25996/bold/002/
    >cp e26154/001/* /buddy/data/tutorial/e26154/bold/001/
    >cp e26154/002/* /buddy/data/tutorial/e26154/bold/002/
  • Explanation: the tutorial data bshorts were constructed on the sgis, using grecons5x, rename_spiral, to3d (to construct the brik, z=4.5, FOV=220), from3d, afnireg2bshort). grecons5x does not work on our linux machines, so this is currently the best approach. See the afni preprocessing page for examples of these commands if you want to start with raw data.
  • ByteSwap Warning: We have had some trouble with the issue of byte swapping the functional images. Logic dictates they need to be swapped to be read correctly on linux after being reconstructed on an SGI. The tutorial data, however, is not byteswapped and works fine. Other data we've tried did need byte swapping.
  • Once you have created bshort files, you can start mgh and view them with yakview:
    >yakview -i fmc -r fmc -slice 10
    will bring up a window allowing you to view your bshort file (fmc_010.bshort in this example). If it looks clean on linux, then it will likely work fine. Please keep careful track of your data's processing history so we can identify the issue.
  • You should now remove the untarred directories (e.g., >rm -fr e25996 e26154); and the *.tgz files.

Preprocessing

Motion Correction

  • Purpose: The motion correction program uses the afni motion correction algorithm to align all the images in a session to the first image in the first run. (Motion correction is not necessary if you have completed it in afni beforehand. See Afni Preprocessing.)
  • Usage: mc-sess
    Optional Arguments:
    -method mcmethod : afni
    -targnthrun n : use nth run as target (default=1)
    -toff m : target image offset (0)
    -fstem stem : stem of output motion-corrected volume (fmc)
    -fmcstem stem : stem of output motion-corrected volume (fmc)
    -umask umask : set unix file permission mask
    -version : print version and exit
    Session Arguments
    -sf sessidfile
    -df srchdirfile
    -s sessid
    -d srchdir
    -fsd dir (optional - default = bold)
  • Command Example: From inside your Parent Subject Directory, run:
    >mc-sess -sf sessidfile -d .
  • Explanation:
    • -sf sessidfile supplies the name of the sessionidfile, so the program will know where to find the subject data.
    • -d . supplies the path to the current subject directory. If you are operating from some other directory, or running a batch file and you want to be careful, then the absolute path (e.g., -d /buddy/data/tutorial) should be foolproof.
  • Output:
    • This takes quite a while to run (1 hour 23 minutes for the tutorial set) especially the Matlab steps (one for each run) which are resource hogs
    • It generates an additional set of bshort and hdr files with the prefix fmc_ in each run directory.
    • It also creates these two files: fmc.bhdr and fmc.mcdat, which contain text records of parameters used.
    • It creates an mctmp directory in each subject's bold directory containing several BRIK and HEAD files
    • It creates a log directory with a file mc-bold-sess.log

Spatial Smoothing

  • Purpose: This step is optional. It applies a gaussian smoothing function similar to that used in SPM. Smoothing increases the signal to noise ratio, but if spatialsmooth-sess (this one) overdoes it because it smooths between planes as well as within planes, then try smoothing in the mkanalysis step later (In the tutorial, you'll try both).
  • Usage: spatialsmooth-sess
    Required Arguments
    -i instem : input functional volume stem
    -o outstem : output functional volume stem
    -fwhm : gaussian fwhm (sigma = fwhm/2.36)
    Session Arguments
    -sf sessidfile
    -df srchdirfile
    -s sessid
    -d srchdir
    -fsd fsdir (optional)
    Other Arguments
    -umask umask : set unix file permission mask
    -version : print version and exit
    -help : print help and exit
  • Command Example:
    >spatialsmooth-sess -i fmc -o fss -fwhm 5.5 -sf sessidfile -d .
  • Explanation:
    • -i fmc supplies an input stem (fmc for functional-motion corrected).
    • -o fss supplies an output stem that clarifies spatial smoothing has been completed on the output files (fss for functional-spatial-smoothed).
    • -fwhm 5.5 A gaussian function specifies the size in mm of the smoothing, here 1.5 x 3.44 [inplane voxel size]=~5.5).
    • -sf sessidfile the sessidfile is identified so that the smoothing function will know which subject directories to work on.
    • -d . the search directory is supplied.
  • Output:
    • This runs very quickly, about 11 seconds for the entire tutorial dataset
    • This creates an additional set of bshort and hdr files with the prefix fss_ in each run directory.
    • It also creates a file called fss.bhdr, containing textual information about parameters used (like fmc.bhdr).
    • spatiallysmooth-sess-bold.log is added to the log directory

Intensity Normalization

  • Purpose: This produces a file with mean intensity data for the entire functional volume for each raw and motion corrected run. This step is optional but highly recommended when data are to be averaged across subjects.
  • Usage: inorm-sess
    Optional Arguments
    -thresh threshold : fraction of global mean to separate brain and air
    -motioncor : inorm the motion corrected volumes
    -funcstem stem : stem of functional volume (default: f or fmc)
    -umask umask : set unix file permission mask
    -version : print version and exit
    Session Arguments
    -sf sessidfile
    -df srchdirfile
    -s sessid
    -d srchdir
    -fsd fsdir (optional)
  • Command Examples:
    >inorm-sess -funcstem fss -sf sessidfile -d .
    >inorm-sess -funcstem fmc -sf sessidfile -d .
  • Explanation: Here we run inorm-sess two times, once to normalize the spatially smoothed data ( -funcstem fss) and once to normalize the unsmoothed data (-funcstem fmc). Several files will be generated that hold information about the normalization process. See previous commands for a description of the other flags.
  • Output:
    • These commands run fast, ~6 seconds for the fss data (which gets a bunch of divide by 0 errors) and 3 minutes for the fmc data.
    • It generates a file in the log directory: inorm-sess-bold.log, which is overwritten each time inorm is run)
    • It generates a script directory in each bold directory and put a file, run-inorm, in each.
    • In each run directory, the inorm-sess command creates a set of report files for the input set, e.g., for the fss data, it created the following: fss.meanval, fss.report, fss.twf-over, fss.twf-under, and inorm.log.

Go to the MGH Analysis Page