Segementation-FSL-Pipeline

From VISTA LAB WIKI

Revision as of 10:12, 30 October 2015 by Michael (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page describes steps for doing automated preprocessing on a 3D reference anatomy, using FSL, to help set up a gray/white matter segmentation.

Contents

[edit] Pre-Processing

Once you have run niftiFromDicom and mrAnatAverageAcpcNifti to get an averaged t1 in nifti format you can follow the five steps below. These steps assume that you can use FSL tools via the command line. If you're unsure if you can run FSL from the command line, go to your X11 shell and type fsl, you should get the FSL gui to pop up. If the gui does not pop up go here for help with editing your .bashrc file.

[edit] Segmentation Pipeline: FSL v4.1.4 and later

1. Run FIRST: (~10-20min)

  • FIRST is run from the command line. The only file that you need to provide as input is your averaged/aligned anatomical image (e.g, t1.nii.gz).
  • From the command line use: run_first_all -i [input file name] -o [output file prefix]
Example:> run_first_all -i t1.nii.gz -o t1_scSeg
  • FIRST generates many files. It may help to move these files into a separate folder once the process is done.
  • The output file we will use later (in step 4) is t1_scSeg_all_fast_firstseg.nii.gz

2. Run BET: (~1min)

  • BET is also run from the command line. The input file, again, will be the averaged and aligned t1.nii.gz file.
  • This step is somewhat interactive: You must adjust the threshold for the extraction (-f) to assure that the skull is removed while the cortical surface is left in tact. This will require running BET multiple times to assure that it is satisfactory.
  • From the command line use: bet [input file name] [output file name] -m -f .4
Example:> bet t1.nii.gz t1_bet.nii.gz -m -f .4
  • Once the process is complete use fslview to view the resulting extraction (see image below).
Example:> fslview t1_bet.nii.gz
  • This will open the FSL Viewer. You can also open the averaged t1 in the same viewer to use as a reference to judge the quality of the extraction (File > Add > nameOfYourAveragedT1). Adjust the overlay settings to adjust the opacity (slider).
  • Values anywhere from .02 to 0.1 have been used so far. You just have to play with the f value to get it where you want it.
-f = .2, .4, and .7. Note skull remaining at left (.2) and gray matter cut off at far right (.7).
  • The output file used in the next step is t1_bet.nii.gz


3. Run FAST: (~7min)

  • FAST is run via the command line and uses the t1_bet.nii.gz file generated in step 2 as input.
  • From the command line: fast [inputFileName]
Example:> fast t1_bet.nii.gz
  • The output of this function will be the inputFileName with _seg added to the file name (ex: t1_bet_seg.nii.gz)
  • The output file we will use later (in step 4) is t1_bet_seg.nii.gz


4. Convert First/Fast Files to Class File: (~2min)

Example:>> mrGrayConvertFirstToClass('t1_scSeg_all_fast_firstseg.nii.gz','t1_bet_seg.nii.gz','t1_class.nii.gz')
  • This function has been written such that if you just type the name of the function, it will prompt you to direct it to each file, as well as ask you to provide a output file name (we suggest t1_class).
  • Be sure to use t1_scSeg_all_fast_firstseg.nii.gz (step 1) for the FIRST file and t1_bet_seg.nii.gz (step 3) for the FAST file.
  • The resulting files will be t1_class.nii.gz and t1_class.lbl which can be loaded into ITKGray. Once loaded into ITKGray it should look something like the image below.
t1_class.nii.gz and t1_class.lbl loaded into ITKGray. In this example the white matter is labeled blue for the left and yellow for the right. The CSF is red and the subcortical gray matter is green.

[edit] Vistasoft Wrapper Function and Batch Scripting

If you have the FSL package (v1.4 or greater) installed and in your unix path you can take advantage of a function written in Matlab that will allow you to easily script the FSL auto-segmentation pipeline.

[edit] Wrapper Function: mrAnatFslAutoSegment.m

You can see the help file for mrAnatFslAutoSegment.m in your Matlab command window. Pertinent information is below. Usage Notes:

 mrAnatFslAutoSegment(segToRun,[t1File],[outDir],[betFile],[betThresh],[betOpt],[convert],[smooth],[fName])
  • This function will run a subject's t1 anatomical image through FSL's automatic segmentation pipleline. The user can choose if they want to run FIRST, FAST, or BOTH. BET will be automatically run if a betFile does not exist in the directory and the user does not provide one.
  • Soft links to the files used for segmentation will be placed in the outDir to remind the user later which images were used.
  • You will need to:
  1. Have FSL installed and in your unix path. VISTA Lab: See the FSL page for help with this.
  2. Have a t1 file
  3. Set the input arguments
  • segToRun:
- 'first' = Run FIRST (only)
- 'fast' = Run FAST (only)
- 'all' = Run FIRST and FAST
  • t1File
- Full path to t1 nifti file (if not provided the user will be prompted to select at t1 file)
  • outDir
- Full path to where you want the files placed (defaults to fullfile((mrvDirup(t1File)), 'seg','fsl');
  • betFile
- Full path to brain extracted image (if you have one). If you don't provide a brain extracted image BET will be run for you at the specified threshold.
  • betThresh
- Defaults to .04 if not provided.
  • betOpt
- String of options allows you to set other options for use with BET (e.g., -m).
  • convert
- 1 or 0 - if 1 (true) mrGrayConvertFirstToClass will be run to convert the resulting segmentation to a "class" file that has left and right labels etc. Default = 1. If you don't want it to run set to 0. If you segToRun = 'all' convert == 1 will combine the segmentations into one file.
  • smooth
- Scalar (e.g, 3) that specifies a kernel size to smooth the resulting segmentation when passed into mrGrayConvertFirstToClass. Defaults to 0.
  • fname
- fname allows the user to set a uniqe file name root for the files that are created.
Wait... it takes a while. ~5 min for FAST and ~30 for FIRST

IMPORTANT NOTE: As of 8/12/10 - May need to use the older version of FIRST - there seems to be some kind of strange flip/displacement of the sub-cortical segmentation images that renders the FIRST segmentation completely useless. UPDATE: This does not seem to be helping at all. Not sure what to do about it.

[edit] Batch Scripting

The function above, or another version of it (dtiAutoSegmentaionFSL) can easily be placed within a for loop to process multiple subjects in one go. A relatively good example of this process can be found in the Vistasoft repository - dti_Longitude_FSLAutoSegment.m, where the funciton dtiAutoSegmentFsl.m was used in a simple looping structure to create automatic FSL segmentations for 55 subjects in a longitudinal study.. Comments are copied below.


dti_Longitude_FSLAutoSegment.m
This script takes a group of subjects and runs dtiAutoSegmentationFsl to create a segmentation of gray/white matter using FSLs tools (BET,FIRST and FAST). This script just loops over each subject and feeds the function the correct inputs: dtiAutoSegmentationFSL(segToRun,[t1File],[outDir],[betFile],[betThresh],[betOpt]).

The novel aspect of this particular script is that it recursively searches through each year in reverse order looking for a subject's T1.nii.gz. The reason for this is that each year the subject's t1 was aligned to and averaged with the previous year, thus yeilding a "cleaner" image. We would like to feed FSL the best image we have available, thus we search recursively in reverse order. We also have previously generated, and inspected, bet images which we feed in here. If these files don't exist the function creates one using standard parameters.

A log file is also generated and saved within the specified logDir. This file contains the subjects names as well as the files used for segmentation and the path to the saved data.

[edit] Segmentation Pipeline: Older FSL Versions (< 4.1.4)

Once you have run niftiFromDicom and mrAnatAverageAcpcNifti to get an averaged t1 in nifti format you can follow the five steps below. These steps assume that you can use FSL tools via the command line. If you're unsure if you can run FSL from the command line, go to your X11 shell and type fsl, you should get the FSL gui to pop up. If the gui does not pop up go here for help with editing your .bashrc file.


1. Run FIRST: (~2hrs)

  • FIRST is run from the command line. The only file that you need to provide as input is your averaged t1.nii.gz.
  • From the command line use: run_first_all [input file name] 4 [output file prefix] (The second input (4) is the z-value used to threshold the boundary voxels)
Example:> run_first_all t1.nii.gz 4 t1_sgm
  • FIRST generates many files. It helps to move these files into a separate folder once the process is done.
  • The output file we will use later (in step 5) is t1_sgm_all_th4_first.nii.gz
  • Due to a bug in run_first_all you may receive an error message when you use -m 4 instead of the default. If you run into error you need to edit [fslroot]/bin/run_first_all. Make sure line 278 reads if [ $bmeth = thresh ] ; then.


2. Run BET: (~3min)

  • BET is also run from the command line. The input file, again, will be the averaged t1.nii.gz
  • This step is interactive: You must adjust the threshold for the extraction (-f) to assure that the skull is removed while the cortical surface is left in tact. This will require running BET multiple times to assure that it is satisfactory.
  • From the command line use: bet [input file name] [output file name] -m -f .4
Example:> bet t1.nii.gz t1_bet.nii.gz -m -f .4
  • Once the process is complete use fslview to view the resulting extraction (see image below).
Example:> fslview t1_bet.nii.gz
  • This will open the FSL Viewer. You can also open the averaged t1 in the same viewer to use as a reference to judge the quality of the extraction (File > Add > nameOfYourAveragedT1). Adjust the overlay settings to adjust the opacity (slider).
  • Values anywhere from .02 to 0.1 have been used so far. You just have to play with the f value to get it where you want it.
-f = .2, .4, and .7. Note skull remaining at left (.2) and gray matter cut off at far right (.7).
  • The output file used in the next step is t1_bet.nii.gz


3. Run FAST: (~5min)

  • FAST is run via the command line and uses the t1_bet.nii.gz file generated in step 2 as input.
  • From the command line: fast [inputFileName]
Example:> fast t1_bet.nii.gz
  • The output of this function will be the inputFileName with _seg added to the file name (ex: t1_bet_seg.nii.gz)


4. Swap Coordinates: (~30sec)

  • Because the conventions for acquired data differ we must swap the X coordinate in order for the images to match.
  • This is done from the command line using the function fslswapdim [inputFileName] -x y z [outputFileName]
Example:> fslswapdim t1_bet_seg.nii.gz -x y z t1_bet_seg_swap.nii.gz
  • The file we will use in the next step is the resulting swapped FAST file: t1_bet_seg_swap.nii.gz


5. Convert First/Fast Files to Class File: (~5min)

  • Finally, in matlab, via the commant line (matlabr2008a -nodesktop) run mrGrayConvertFirstToClass.
  • Usage: mrGrayConvertFirstToClass(firstNifti,fastNifti,outFileName)
Example:>> mrGrayConvertFirstToClass('t1_sgm_all_th4_first.nii.gz','t1_bet_seg_swap.nii.gz','t1_class.nii.gz')
  • Bob has written this function to include a GUI that will pop up, if you just type the name of the function, and ask you to direct it to each file as well as ask you to provide a output file name (we suggest t1_class).
  • Be sure to use t1_sgm_all_th4_first.nii.gz (step 1) for the FIRST file and t1_bet_swap.nii.gz (step 4) for the FAST file.
  • The resulting files will be t1_class.nii.gz and t1_class.lbl which can be loaded into ITKGray. Once loaded into ITKGray it should look something like the image below.
t1_class.nii.gz and t1_class.lbl loaded into ITKGray. In this example the white matter is labeled blue for the left and yellow for the right. The CSF is red and the subcortical gray matter is green.
Personal tools