MRtrix tutorial available on OSF


Hi to all MRtrix3 users!

I just wanted to share some resources with you: At this year’s MICCAI conference, there was a contest on the best tutorial. For that, I wrote a step-by-step tutorial on MRtrix3, which explains how you analyze raw multi-shell DWI data. In there, you’ll learn how to:

  1. preprocess the data, and get some idea of what the purpose of each of the analysis steps is,
  2. create a whole-brain tractogram and filter out specific tracts of interest,
  3. create a structural connectivity matrix,
  4. use the connectome visualization tool.

Additionally, I’m providing tutorial data – both the raw dicom data as well as any files which are to be created throughout the tutorial. Throughout the tutorial, I’m providing example code which can be directly used on that test data.

If you want to find out more, just visit the OSF tutorial website:

Thanks and enjoy,



It’s really cool. very helpful, thanks!


Thank you for your feedback, @zonglei, glad you can make use of it :+1:


Hi @martahedl
MRtrix3 doc tell us to run mrgibbs first, and then run dwidenoise because the former may change the noise structure( But I noticed you reverse their order in your tutorial. Do you think which order is better?


@Zonglei The wording of the description in mrdegibbs can be misleading. “This command” in the following refers to mrdegibbs: “Similarly, if you intend running dwidenoise, you should run this command afterwards, since it has the potential to alter the noise structure, which would impact on dwidenoise’s performance.” So denoising should be performed before mrdegibbs.


Thanks @maxpietsch for clarifying this :slight_smile:
@zonglei: Thanks for paying attention. If anything else seems unclear, don’t hesitate to bring it up!


First of all, awesome tutorial. I really appreciate the amount of effort that your team is investing into this tutorial.

I am a medical student without any background in computing, trying to learn MRtrix with this tutorial.

I am current facing an issue with page 6 of the BATMAN_tutorial, step 2.2

I tried following with the details as follow:

Arthurs-MacBook-Pro:DWI arthur$ dwidenoise dwi_raw.mif dwi_den.mif –noise noise.mif

dwidenoise: [ERROR] Expected exactly 2 arguments (4 supplied)

dwidenoise: [ERROR] Usage: dwidenoise dwi out

dwidenoise: [ERROR] Yours: dwidenoise dwi_raw.mif dwi_den.mif –noise noise.mif

May I know if I have missed out on anything?

Thank you



If you copy and pasted the code into a terminal there is a chance that the ‘-’ before ‘noise’ is a dash instead of a minus sign. Try typing this character into the terminal instead.


Awesome. Thanks for the help! :slight_smile:


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.

split this topic #16

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,



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?


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.