MRtrix tutorial available on OSF

Really helpful!

Hi everybody.

First of all thanks to Marta for this nice tutorial! :slight_smile:

However, I have tried it with her data, and came to the part where dwipreproc needs to be done and I keep getting this error which I cannot surely identify.

The command is:

dwipreproc dwi_den_unr.mif dwi_den_unr_preproc.mif -pe_dir AP -rpe_pair -se_epi b0_pair.mif -eddy_options " --slm=linear"

The error is:

dwipreproc: [ERROR] Command failed: fsl5.0-topup --imain=topup_in.nii --datain=topup_datain.txt --out=field --fout=field_map.nii.gz --config=/usr/share/fsl/5.0/etc/flirtsch/b02b0.cnf (dwipreproc:743)
dwipreproc: Output of failed command:
dwipreproc: Changing back to original directory (/home/david/Pictures/Human_Connectome/DWI)
dwipreproc: Script failed while executing the command: fsl5.0-topup --imain=topup_in.nii --datain=topup_datain.txt --out=field --fout=field_map.nii.gz --config=/usr/share/fsl/5.0/etc/flirtsch/b02b0.cnf
dwipreproc: For debugging, inspect contents of temporary directory: /home/david/Pictures/Human_Connectome/DWI/dwipreproc-tmp-FF4JJ6/

Any thoughts?


dwipreproc dwi_den_unr.mif dwi_den_unr_preproc.mif -rpe_none -pe_dir AP

Works fine, so I guess its not FSL problem

I got the same problem when I try the command from Marta’s pre-derived files (located in Suplemmentary materials)

So I think I found the problem. On my other machine when I do the preproc script mrtrix calls topup (and not fsl5.0-topup) and everything works fine. Does anyone have the idea of what could have gone wrong?
Both machines are on linux mint 19.

First off, calling dwipreproc with the -rpe_none effectively bypasses the topup step, so this doesn’t mean that FSL works fine… But given the lack of output from the topup invocation, I’d agree there’s a chance that it’s not finding the fsl5.0-topup command. Have you tried running that command in the terminal directly? If you type fsl5.0-topup in the terminal, do you get a
command not found error?

Also, can you post the output the successful dwipreproc call? Looking at how eddy is invoked might give us a clue as to why the topup call is failing.

Thank you for your answer!

When I type both fsl5.0-topup or just topup I get the description of the command in terminal. I tried unlinking fsl5.0-topup from topup located in the /bin, and then mrtrix calls topup command but still gives the same error. Everything else on fsl works perfectly fine.

Eventually (since it was brand new workstation) I installed newest ubuntu, and run the FSL 6.0 python script for the installation, and now everything works fine.

In case it’s relevant, linking to a recent external contribution to MRtrix3 that will alter the invocation of FSL commands from MRtrix3 scripts following the next tag update. Based on the description there, I would suggest that FSL commands prefixed with “fsl5.0-*” should ideally not appear in your PATH at all; these should reside in some unlinked location, and the FSL configuration script should be responsible for providing soft-links to these that do not include the prefix.

But given the lack of output from the topup invocation, I’d agree there’s a chance that it’s not finding the fsl5.0-topup command.

No, there’d be a different error if the executable couldn’t be found.

topup has been observed to fail silently (i.e. no text on stdout or stderr) if it is unable to allocate sufficient memory; it’s conceivable that it could do similar in other circumstances, but that is beyond my knowledge and control. But given my description above, it’s possible that topup is crashing out due to FSL not being configured correctly, even if the commands are discoverable within PATH.

A post was split to a new topic: Processing of volumes prior to dwipreproc

Hi Marlene,

What are the steps if I want to substitute the position coordinates in tckedit –include -0.6,-16.5,-16.0,3 sift_1mio.tck cst.tck with an ROI? Could you give me an example?

Thank you,

Hi Mahmoud,

I’m not sure I understand the question right. You say you want to replace the position coordinates with an ROI, but those position coordinates are a ROI. My guess is that by ROI you mean a binary mask? In that case, it’s really easy to use the tckedit command with such a binary mask. You can directly provide that image to tckedit, e.g. (assuming your binary mask is called “roiMask.mif” and your desired output “roi.tck”):

tckedit -include roiMask.mif sift_1mio.tck roi.tck

Hope that helps.


Hi Marlene,

Thanks for the clarification. I am working with images from 6months infants. What I’d like to do is to somehow segment some well-known tracts like CST. I do not have a binary mask for CST or any other tracts. What I have is an AAL atlas in T1w space from UNC.

I am not sure how effectively and accurately I can register that AAL atlas into DWI space? Any idea what is the best way to do this? The next question is that even if I have that atlas in DWI space how do I know which parts of the atlas should be used as seed ROI only give me CST?

Thank you,


1 Like

Hi everybody.

I am a medical doctor, learning how to use Mrtrix3 using BATMAN tutorial. First of all thanks to the excellent one.

However, I have tried it with her data, and have some problem when handling T1 data (4.1.1 Preparing a mask for streamline termination)

The command is:

flirt -in mean_b0_preprocessed.nii.gz -ref 5tt_nocoreg.nii.gz -interp nearestneighbour -dof 6 -omat diff2struct_fsl.mat

And the error is:
Image Exception : #75 :: 3D only method called by higher-dimensional volume.
3D only method called by higher-dimensional volume.

Do you have some idea about this error?

1 Like

I guess 5tt_nocoreg.nii.gz is a 4D volume and that’s why you receive that error. You need to somehow merge those volumes a 4D image to have a 3D image. Also, check to make sure mean_b0_preprocessed.nii.gz is a 3D volume too.


Thanks zeydabadi,
As you mentioned, 5tt_noncoreg.nii.gz is a 4D volume. As 5tt_noncoreg.nii.gz is derived from T1_raw.mif (a 3D image), here should I have used T1_raw.mif (or nii.gz) instead of 5tt_noncoreg.nii.gz?
I have confirmed mean_b0_preprocessed.nii.gz is a 3D volume.

I assume you should you use the 5tt_noncoreg.nii.gz but why it’s not in 3D, I don’t know. Maybe the Marlene can help.

Thanks Mahmoud,
I think 5tt_noncoreg.nii.gz provided in Supplementary_Files have 5 volumes(, which means this is a 4D image), too. So I wonder I shouldn’t use 5tt_noncoreg.nii.gz here. Am I right? I would appreciate it if I could receive a comment from Marlene.

Hi Mahmoud,

You can use labelconvert to do this. I show how to use this for the HCPMMP1 atlas in the tutorial. The procedure for the AAL atlas is very similar to this (section 8.1 in the appendix). However, a few things are different for the AAL atlas:

The AAL is – unlike the surface-based HCPMMP1 atlas – a volumetric atlas. This makes things easier for you since you do not have to do the FreeSurfer anatomical preprocessing in this case. However, you still have to register the AAL to the highresolution native T1 space in a first step (the AAL atlas is in standard space: MNI_152_2mm). There are several ways to do this, e.g. with MRtrix or FSL commands. I like to use FSL’s flirt tool for this. Here are a couple of commands with which you can achieve this (assuming you have done FSL’s anatomical preprocessing, which gave you a T1_biascorr_brain.nii.gz, and the AAL file in standard space is called “AAL.nii”):

flirt –in T1_biascorr_brain.nii.gz –ref $FSL_DIR/standard/MNI152_2mm_brain.nii.gz –omat highres2standard.mat –interp nearestneighbour –datatype int -inverse

convert_xfm –omat standard2highres.mat –inverse highres2standard.mat

flirt –in AAL.nii –ref T1_biascorr_brain.nii.gz –out aal2highres.nii.gz –applyxfm –init standard2highres.mat –interp nearestneighbour

You can then use labelconvert with the resultant file, e.g.

labelconvert aal2highres.nii.gz aalLUT_90_orig.txt aalLUT_90_ordered.txt aal2highres.mif

(In case you do not have these files, I uploaded the following three files on the OSF website: aalLUT_90_orig.txt, aalLUT_90_orig.txt, and AAL.nii. You can find those in the Supplementary Files directory here: However, please note that the color lookup tables I provide are for the 90 parcellation AAL atlas, and I ask you to verify it before using it).

Regarding your second question,

I think using the AAL to identify the CST is not the way to go. I’m not an expert here, but aren’t there any atlases of white matter pathways? Alternatively, you could try to identify the CST in every of your subjects by tracking through a ROI (in the white matter) through which you know the CST must pass (e.g. how in section 4.4 in the tutorial, which shows how to use tckedit to identify the CST). However, this is a subjective procedure, so I recommend this only as an exploratory analysis. An atlas would be the preferrable option for a standardized analysis.

Hope this helps.



Hi @tkimura,

the problem here is indeed the latest version of FSL (which I guess you have) expects a single 3D volume as a fieldmap (the old version would only read the first volume if the fieldmap was 4D; for another discussion on this see;1e8be9c7.1811). One easy way around this is to split the 4D 5tt_nocoreg.nii.gz into 3D volumes. This can be achieved, e.g. with fslsplit:

fslsplit 5tt_nocoreg.nii.gz myprefix -t

This command will split the 5tt_nocoreg-image into 5 3D volumes, where “prefix” denotes the prefix of each of the volumes (like this, your outputs will be called “prefix0000.nii.gz” for the first 3D volume of 5tt_nocoreg, “prefix0001.nii.gz” for the second volume, etc.). Now you can use either of those 3D images with flirt, e.g.

flirt -in mean_b0_preprocessed.nii.gz -ref prefix0000.nii.gz -interp nearestneighbour -dof 6 -omat diff2struct_fsl.mat

I now this is a little complicated, but the best way I can think of right now. Let me know if you find a quicker way. However, I just ran these commands myself and can confirm that they work and that the resulting diff2struct_fsl.mat is correct.

Hope this helps.



Hi Marlene,

Thanks for your helpful comment. Now command flirt works without error. But I checked the results and found that 5tt_noncoreg.mif has wrong direction (axial image has changed to saggital). As maybe I did something wrong, I will try to fix and let you know.


1 Like

You definitely don’t want to be using the 5 separate tissue partial volume images for registration: apart from the fact that the registration algorithm may not be able to find a good alignment between an individual tissue image and a template T1-weighted image based on its internal image matching cost function, resulting in a bad alignment, doing this five separate times would give you five tissue images with five different transforms!

You want to perform the registration using the most appropriate images for such (e.g. T1-weighted image & mean b=0 image), and then apply the transformation that was optimised by the registration algorithm to any other images that you wish to undergo the same transformation. I.e. If your 5TT image is intrinsically aligned with the T1 image data (given it was calculated from such), and you then estimate a transformation that aligns the T1 image with the DWI data, then applying that same transformation to the 5TT image will make those data also align with the DWIs.

1 Like

Hi Marlene,

Excellent tutorial, I didn’t realize MRTrix had so many capabilities!

A few quick questions:

  1. Does MRTrix have any graphical interface for drawing ROIs manually?

  2. When tracking, you showed the use of anatomical constraints to ensure streamlines start and end at the WM/GM interface. Then used cortical (or sub-cortical) labels for connectome generation. What happens if the streamlines stop just short of labels (for example if my labels don’t exactly align or match the WM/GM boundary)? Will they not be counted in the connectome generation?

  3. Does MRTrix have any capabilities for connectome generations using meshes as opposed to labels? For example mesh of WM/GM interface or mid-cortex mesh. Similarly, can meshes be used, for use with anatomical constrained tractography, or should this be converted to binary masks?

Thank you very much,

Does MRTrix have any graphical interface for drawing ROIs manually?

In mrview, click the “Tools” button on the toolbar, then select “ROI tool”. You can open existing ROIs or create new ones, and activate editing by clicking the “Edit” button within that tool.

What happens if the streamlines stop just short of labels (for example if my labels don’t exactly align or match the WM/GM boundary)? Will they not be counted in the connectome generation?

tck2connectome by default will search for any labelled voxel within a 2mm radius of the streamline termination point, precisely for this reason.

Does MRTrix have any capabilities for connectome generations using meshes as opposed to labels?

Not yet. But if the parcels are relatively large, then the difference in outcome between using a native mesh representation and using a voxel-based representation of such should be minimal.

Similarly, can meshes be used, for use with anatomical constrained tractography, or should this be converted to binary masks?

Again, not yet. But ACT does not require the tissues to be defined as binary masks: a partial volume fraction representation means that complex shapes of tissue interface surfaces can be represented without too much loss of precision.