MRTrix examples


Revision as of 13:41, 18 July 2015 by Rjpatruno (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page describes how to run MRtrix on a data set on our computers (SNI-VCS). If you need to install MRtrix on your own platform, see this page.


[edit] Introduction

We are shifting a lot of our compute to SNI-VCS. That virtual machine (hosted at the SLAC facility) has the mrtrix executables installed in the directory


Make sure that directory is on your path by placing in .bash_profile


If you would like an updated version or some change, speak to Michael Perry.

[edit] Vistasoft and MRtrix

In general, you can use the Vistasoft tools to run MrTrix. These matlab scripts were mostly written by Ariel Rokem, Bob Dougherty and Franco Pestilli.

[edit] Command line MRtrix

[edit] Converting segmentation files into .mif format

White matter mask is useful to use in MrTrix analysis. Right now, we convert the white matter segmentation files into .mif format in order to use it in mrTrix.

In a first step, recommended method is use FreeSurfer for first-stage segmentation, and then use itkGray for manually correcting segmentation errors. See Anatomical_Methods for detail.

Hereafter, I will describe the method for converting itkGray segmentation file into mrTrix format.

In itkGray format, white matter is defined as

3: left white matter 4: right white matter

whereas we must define

1: white matter 0: other voxels

in mrTrix white matter mask.

mrtrix_itkclass_wmmask.m is a MATLAB function converting the segmentation file in itkGray (mrVista) format into this format.

You could simply run

classfile = 't1_class.nii.gz'; % Segmentation file in itkGray format
fname = 't1_class_binary'; % Filename for output file 
mrtrix_itkclass_wmmask(classfile, fname)

You could check the quality of white matter mask in mrTrix viewer (type mrview in Linux terminal).

[edit] Converting mrDiffusion data format into mrTrix data format

We (mostly Ariel?) developed the tool for converting the data format in mrDiffusion into MrTrix. Hereafter, we will describe the set of function which helps to convert the mrDiffusion data into mrTrix format (.mif) file.

The conversion from mrDiffusion format to mrTrix format has following steps.

1. Coverting raw diffusion data (.nii.gz format) into .mif format

First step is to convert DWI data in nifti format in .mif format. To do that, run

dwRawFile = 'dwi_raw_preprocessed.nii.gz' % Raw diffusion data in nifti format, and has been already preprocessed in mrDiffusion tool
files.dwi = 'dwi.mif' % File name for dwi file in .mif format
mrtrix_mrconvert(dwRawFile, files.dwi)

in MATLAB window.

2. Converting bval/bvecs file into mrTrix format.

MrTrix stores both bval and bvec into single file (.b). To convert the .bvals and .bvecs file into .b format, we run mrtrix_bfileFromBvecs.m

bvals = 'dwi_raw_preprocessed.bvals' % Full path to bval file in mrDiffusion format
bvecs = 'dwi_raw_preprocessed.bvecs' % Full path to bvec file in mrDiffusion format
files.b = 'dwi.b' % File name for .b file
mrtrix_bfileFromBvecs(bvecs, bvals, files.b)

3. Converting brain mask file into .mif format.

Use the brain mask files generated in mrDiffiusion, and convert it into .mif format.

brainMaskFile = '/Subject1/dti96dirtrilin/bin/brainMask.nii.gz'; % Full path to brain mask file generated by mrDiffusion preprocessing pipelines
files.brainmask = 'dwi_brainmask.mif'
mrtrix_mrconvert(brainMaskFile, files.brainmask, false);

4. Computing tensor from raw DWI data.

Compute diffusion tensor from raw DWI data, and save it in .mif format.

files.dt = 'dwi_dt.mif' % File name of .mif file stroing diffusion tensor information
mrtrix_dwi2tensor(files.dwi, files.dt, files,b);

5. Computing fractional anisotropy.

files.fa = 'dwi_fa.mif' % File name of .mif storing FA map
mrtrix_tensor2FA(files.dt, files.fa, files.brainmask);

6. Computing eigenvector (PDD) map for MrTrix viewer.

Compute eigenvector (PDD) map in .mif format for MrTrix viewer.

files.ev = 'dwi_ev.mif' % File name of .mif storing eigenvector (PDD) map
mrtrix_tensor2vector(files.dt, files.ev, files.fa);

7. Calculate the fiber response function.

Calculate the fiber response function utilized by MrTrix for the spherical deconvolution analysis.

files.response = 'dwi_response.mif';
mrtrix_response(files.brainmask, files.fa, files.sf, files.dwi,...
files.response, files.b, [], [], [], lmax, true);

We need to specify the parameter named "Lmax" here. Lmax defines the number of set of spherical harmonics to fit CSD model. In vistasoft-MrTrix bridge, the default value of Lmax is 6.

8. Fit the spherical deconvolution (CSD) model to DWI data.

files.csd = 'dwi_csd.mif';
mrtrix_csdeconv(files.dwi, files,response, lmax, files.csd, files.b, files.brainmask);

After finishing this step, now you could run the fiber tractography using CSD model!

From Brian: Presumably we need to make a example data for doing this? Are there any wrapper function for doing all of this stuffs? Specifying the selection of Lmax for computing CSD.

[edit] Run Tractography

The documentation of MrTrix tractography is here.

MrTrix provides three different tractography algorithms (DT_STREAM, SD_STREAM and SD_PROB).

We could run streamtrack from terminal, or also use several MATLAB functions we have (mrtrix_track.m, feTrack.m in LiFE).

There are several parameters we need to specify when we run MrTrix tractography.

- seed and -mask identify the seed voxels and white-matter mask. For running whole-brain tractography, we typically use white-matter regions defined by segmentation procedure as both seed and mask. Then tractography algorithms chose the voxels in white matter mask as seed voxels for bidirectional tracking. The alternative procedure is using gray/white matter interface as seed voxels. In both cases, the white matter mask can be defined by nifti in binary format (1, white matter; 0, others), and then we could convert the nifti into .mif format using mrconvert (or mrtrix_mrconvert in MATLAB).

- curvature defines the minimum radius of curvature in tractography. This is also constraining the angle in tractography, depending on the step size.

- num defines the maximum number of streamlines produced by tractography.

The example command line for whole-brain tractography (used in terminal):

streamtrack SD_PROB dwi_csd.mif -mask t1_class.mif -seed t1_class.mif -curvature 1 S1_SDPROB_500000.tck -num 500000

This command line use CSD file as an input for CSD Probabilistic tractography, and use white-matter mask as both seed and mask for tracking (whole-brain tractography).

[edit] Convert .tck file into .pdb file

MrTrix produces .tck file for storing streamline information, which is not compatible with Quench or mrDiffusion.

In order to convert .tck file into .pdb file, please use mrtrix_tck2pdb.m

mrtrix_tck2pdb('S1_SDPROB_lmax8_500000.tck', 'S1_SDPROB_lmax8_500000.pdb')

.pdb format is compatible with Quench, mrDiffusion, AFQ and LiFE.

[edit] Older descriptions

Following is the older description for VISTA lab internal members. Presumably we will drop this out in a near future.

Below are some notes and commands from an analysis using a HARDI data set from the VISTA Lab.

[edit] Some prep work

  • Compute a brain mask
 mrconvert dti_g712_b2000_aligned_trilin_avg.nii -coord 3 0 - | threshold -abs 350 - - | median3D - mask.mif
  • That wasn't so good, so I used mrconvert to copy over the mrDiffusion brain mask
 gunzip -c ../dti712/bin/brainMask.nii.gz > mask.nii
 mrconvert mask.nii mask.mif
  • Prepare grads file by transposing dti_g712_b2000_aligned_trilin_avg.bvecs and adding a column of dti_g712_b2000_aligned_trilin_avg.bvals

In matlab:

 >> grads=[dlmread('dti_g712_b2000_aligned_trilin_avg.bvecs'), dlmread('dti_g712_b2000_aligned_trilin_avg.bvals')];
 >> grads = [bvecs;bvals]
 >> dlmwrite('grads',grads',' ')

In terminal:

 gunzip -c  ../raw/dti_g712_b2000_aligned_trilin_avg.nii.gz >  dti_g712_b2000_aligned_trilin_avg.nii
 dwi2tensor -grad grads dti_g712_b2000_aligned_trilin_avg.nii dt.mif
  • Compute a fa.mif file
 tensor2FA dt.mif - | mrmult - mask.mif fa.mif
  • Compute a pdd file
 tensor2vector dt.mif - | mrmult - fa.mif pdd.mif
  • View the pdd file
 mrview pdd.mif

[edit] Constrained Spherical Deconvolution

  • Create single-fiber mask
 erode mask.mif - | erode - - | mrmult fa.mif - - | threshold - -abs 0.7 sf.mif
  • Create response function coefficients (~30 sec)
 estimate_response -grad grads dti_g712_b2000_aligned_trilin_avg.nii sf.mif response.txt
  • CSD (~30 minutes with 8 threads on tan- adjust # threads in ~/.mrtrix file) timing (adjust # threads in .mrtrix file): ~30 minutes with 8 threads on tan ~3 minutes with 32 threads on azure
 csdeconv -grad grads dti_g712_b2000_aligned_trilin_avg.nii response.txt -lmax 10 -mask mask.mif CSD10.mif
  • You can also let csdeconv pick the optimal lmax given your data:
 csdeconv -grad grads dti_g712_b2000_aligned_trilin_avg.nii response.txt -mask mask.mif CSD.mif

[edit] Whole-brain tractography

  • Generate a white matter mask for whole-brain tractography

This one didn't work so well for me:

 gen_WM_mask -grad grads dti_g712_b2000_aligned_trilin_avg.nii mask.mif wm.mif threshold wm.mif wm_t.mif -abs 0.4

So I just did this:

 erode mask.mif - | erode - - | mrmult fa.mif - - | threshold - -abs 0.25 wm.mif
  • Probabilistic
 streamtrack SD_PROB CSD10.mif -seed wm.mif -mask mask.mif all_100K.tck -num 100000 -trials 500
 streamtrack SD_PROB CSD10.mif -seed wm.mif -mask mask.mif all_1000K.tck -num 1000000 -trials 1000
  • STT
 streamtrack SD_STREAM CSD10.mif -seed wm.mif -mask mask.mif all_stt_200K.tck -num 200000
Personal tools