FreeSurfer

From VISTA LAB WIKI

Jump to: navigation, search

We use FreeSurfer from MGH for registration, including applications in DTI. Some general instructions for installation and use are here. See an MGH test and tutorial here.


Contents

[edit] FreeSurfer installation on Vista Ubuntu Linux

Edit your ~/.bashrc file to include

 # For FreeSurfer
 export FREESURFER_HOME=/white/local/freesurfer/v5.3.0
 source $FREESURFER_HOME/SetUpFreeSurfer.sh

This is for bash, if you use tcsh, look up instructions here.

You need to set up your SUBJECTS_DIR environment variable. E.g.,

 export SUBJECTS_DIR=/some-internal-path/to-data/freesurfer

This variable should point to a location on the disk where FreeSurfer will be creating FreeSurfer-specific folders containing intermediate stage processing results for every subject. The folder's structure will be as follows:

SUBJECTS_DIR
|
-- subjectID1
| ---some FS-specific folders
| -- mri (FS created this folder, an your parcellation results will be in here)
| --- other FS-specific folders
-- subjectID2
-- subjectID3
...

If you do not set up SUBJECTS_DIR, FreeSurfer will be confused and will not know where to output results.

[edit] FreeSurfer in Matlab

In order for Matlab to have access to Freesurfer executables you must do two things:

  1. Start matlab through a terminal.
  2. Add the following lines to your matlab startup.m file.
 fshome = getenv('FREESURFER_HOME');
 fsmatlab = sprintf('%s/matlab',fshome);
 if (exist(fsmatlab) == 7)
   path(path,fsmatlab);
 end
 clear fshome fsmatlab;
 fsfasthome = getenv('FSFAST_HOME');
 fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);
 if (exist(fsfasttoolbox) == 7)
   path(path,fsfasttoolbox);
 end
 clear fsfasthome fsfasttoolbox;

[edit] Freesurfer Routines in Vistasoft

We have written several routines for working with Freesurfer data in Vistasoft. You can browse those functions on the Vistalab/Vistasoft GitHub page:

[edit] Running FreeSurfer

[edit] Full cortical reconstruction, parcellation and labeling

Full FreeSurfer parcellation involves a hundred steps. These steps have been conveniently batched in a script called recon-all which you can run with the following parameters:

 recon-all -i <PATH_TO_YOUR_T1_NIFTI_FILE> -subjid <SUBJECT_ID> -all

E.g.,

recon-all -i /pathToData/t1/t1.nii.gz -subjid subject001 -all

The resulting images you want are here:

SUBJECTS_DIR
|
-- subjectID
| -- mri
| -- aseg.mgz (This solution contains L/R gray matter, subcortical structures, white matter (L/R) cerebellum, etc -- someone edit please)
| -- aparc+aseg.mgz (This solution contains all of the above + a fine parcellation of cortex into ~2000 anatomical patches -- someone edit please to provide more details)
| -- other files

[edit] Running specific pipelines

Running full recon-all FreeSurfer pipeline is very time consuming, may take more than a day. You can choose to control which processing routines you want performed. Here is the list of steps performed by default. This list can be obtained by typing "recon-all" and reading the regurgitated voluminous bits of wisdom.

Autorecon Processing Stages:

1. Motion Correction and Conform
2. NU (Non-Uniform intensity normalization)
3. Talairach transform computation
4. Intensity Normalization 1
5. Skull Strip
6. EM Register (linear volumetric registration)
7. CA Intensity Normalization
8. CA Non-linear Volumetric Registration
9. Remove neck
10. EM Register, with skull
11. CA Label (Aseg: Volumetric Labeling) and Statistics
12. Intensity Normalization 2 (start here for control points)
13. White matter segmentation
14. Edit WM With ASeg
15. Fill (start here for wm edits)
16. Tessellation (begins per-hemisphere operations)
17. Smooth1
18. Inflate1
19. QSphere
20. Automatic Topology Fixer
21. Final Surfs (start here for brain edits for pial surf)
22. Smooth2
23. Inflate2
24. Spherical Mapping
25. Spherical Registration
26. Spherical Registration, Contralater hemisphere
27. Map average curvature to subject
28. Cortical Parcellation (Labeling)
29. Cortical Parcellation Statistics
30. Cortical Ribbon Mask
31. Cortical Parcellation mapped to ASeg


They offer a variety of pipelines that perform sequences of steps you might be interested in, tailored to your particular use case. For example, to perform WM/GM segmentation try running recon-all with the following step-wise process directives (both, in the same order):

 recon-all -i <PATH_TO_YOUR_T1_NIFTI_FILE> -subjid <subjectID> -autorecon1
 recon-all -subjid <subjectID> -autorecon2-inflate1

The two commands above will take your data through stages 1-18.

If you want more technical details/control of the processing stages, a good reference is the table ReconAllDevTable.

[edit] Viewing segmentation/parcellation results

To view mgz files you are interested in, try the following command:

 tkmedit <subjectID> <yourfile.mgz>

(Make sure your SUBJECTS_DIR is set to point to a directory that contains subjectID FreeSurfer data).

Alternatively you can just use the -f flag and provide the location of the file:

 tkmedit -f /path/to/your/file.mgz
 Example Usage:
 tkmedit -f ./mri/T1.mgz

[edit] Converting FreeSurfer result files (*.mgz) to NIFTI

We use mri_convert utility. You may need to change --out_orientation parameter if your nifti files come up in a wrong orientation. You may want to use "-rt nearest" if you are converting maps of labels, not continuous intensity values. By default your data are in __?_ space. Typically we want our segmented data to be in the same space as the original T1. Parameter "--reslice_like" takes care of that.

The following command does a great job of converting our data to an nii image.

 mri_convert --out_orientation RAS  -rt nearest --reslice_like <reference.nii or reference.nii.gz> <input.mgz> <output.nii>

E.g.,

 mri_convert --out_orientation RAS  -rt nearest --reslice_like /some-path-to-data/js040726/t1/t1.nii.gz <path-to-freesurfer-data>/js040726/mri/aseg.mgz <path-to-freesurfer-data>/mri/aseg.nii

Warning: The above code changes the header information but not the data. This can cause problems. What we should do is ask Justin Ales.

[edit] Extracting a white matter segmentation to use with itkGray

To extract a white matter segmentation for use with itkGray and vistasoft tools, convert the freesurfer file called ribbon.mgz (step 30 above) to an itkClass file in nifti format.

The file ribbon.mgz is similar to the class files we create when we segment brains in itkGray. It is aligned to the freesurfer anatomical t1, and it contains integer values representing left and right gray and white matter. These values are different from those we use in itkGray and vistasoft, so we need to convert:

  • LW: 2 => 3
  • LG: 3 => 5
  • RW: 41 => 4
  • RG: 42 => 6

To do the conversion, call the matlab vistasoft function, fs_ribbon2itk:

fs_ribbon2itk(<subjID>, <PATH_TO_YOUR_NIFTI_CLASS_OUTFILE>, fillWithCSF[= 1 or 0], <PATH_TO_YOUR_T1_NIFTI_FILE>)

[edit] Additional information

  • An awesome simple tutorial for testing your FreeSurfer installation (getting started) can be obtained here.
Personal tools