Get from Ico-github-logo

Highlights from
Mean square displacement analysis of particles trajectories


5.0 | 10 ratings Rate this file 60 Downloads (last 30 days) File Size: 26.9 KB File ID: #40692
image thumbnail

Mean square displacement analysis of particles trajectories



08 Mar 2013 (Updated )

A MATLAB class for the mean square displacement analysis of particle trajectories, with a tutorial.

| Watch this File

File Information

Mean square displacement (MSD) analysis is a technique commonly used in colloidal studies and biophysics to determine what is the mode of displacement of particles followed over time. In particular, it can help determine whether the particle is:
- freely diffusing;
- transported;
- bound and limited in its movement.
On top of this, it can also derive an estimate of the parameters of the movement, such as the diffusion coefficient.

@msdanalyzer is a MATLAB per-value class that helps performing this kind of analysis. The user provides several trajectories he measured, and the class can derive meaningful quantities for the determination of the movement modality.

@msdanalyzer can deal with tracks (particle trajectories) that do not start all at the same time, have different lengths, have missing detections (gaps: a particle fails to be detected in one or several frame then reappear), and do not have the same time sampling. As soon as you added your tracks to the class, everything is transparent. It offers facilities to plot and inspect the data, whether for individual particles, or on ensemble average quantities. It has several methods for correcting for drift, which is the main source of error in the analysis. Once corrected, the data can analyzed via the MSD curves or via the velocity autocorrelation. Automated fits of the MSD curves are included (but they require you have the curve fitting toolbox), allowing to derive the type of motion and its characteristics.

Included is a rather long tutorial with references, that will introduce you to the problem using numerical simulations, make you reproduce published results, and detail how the class work. Some basis of physics are required.

If you use this tool for your work, we kindly ask you to cite the following article for which it was created:

Nadine Tarantino, Jean-Yves Tinevez, Elizabeth Faris Crowell, Bertrand Boisson, Ricardo Henriques, Musa Mhlanga, Fabrice Agou, Alain Israël, and Emmanuel Laplantine. TNF and IL-1 exhibit distinct ubiquitin requirements for inducing NEMO-IKK supramolecular structures. J Cell Biol (2014) vol. 204 (2) pp. 231-45


Shaded Error Bar inspired this file.

Required Products Curve Fitting Toolbox
MATLAB release MATLAB 8.0 (R2012b)
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (35)
11 Dec 2014 Renjie

Hi Jean-Yves,
now it is ok, Thank you for your help, and this code is very useful.

Kind regards,

03 Dec 2014 Jean-Yves Tinevez

Hi @Renjie
It looks like an installation problem. MSDanalyzer is shipped as a class, so you need to install it as a class. Check that the folder containing @msdanalyzer is in the path, but not the @msdanalyzer folder itself.
Tell me if it works.

01 Dec 2014 Renjie  
01 Dec 2014 Renjie

Hi Jean-Yves,

First I need to say it is a very useful program, thank you for your sharing. However, following the tutorial, the first step is error, when I input mc=msdanalyzer(2,'μm','s'); the matlab will say there is no function for 'private'. Did you find this situation? can you help me for this?

Thank you so much for your help.

Kind regards,


18 Nov 2014 Jean-Yves Tinevez

Hi @Javad
It's always the same bug. Just check my comment below on its origin and how to fix it.

17 Nov 2014 Javad

Hi Jean-Yves,

First I'd like to appreciate you for sharing your comprehensive program. I tried several times to run it with my own trajectories but I got the following error:
1/ 525Error using -
Matrix dimensions must agree.

Error in msdanalyzer/computeMSD (line 86)
delta = dr2 - mean_msd(index_in_all_delays);

I did not go through the subroutines but can I ask you that weather you used smoothing or any kind of noise reduction procedure in your code or not?

Kind regards,

10 Oct 2014 Jean-Yves Tinevez

Hi @Liam, and thanks for the feedback.
What you mention here resembles a known bug. If the frame interval of the movie you want to analyze is defined over too many digits (something like 0.18374531289123648392716 seconds), the class gets confused when binning intervals together, which ultimately triggers the error you got.
Could you please check what is the frame interval in your case? Cropping it to a few digits should solve the problem.

08 Oct 2014 Liam

Hi Jean-Yves,

Great piece of software! Very useful. However I used it for Imaris tracks analysis and got the following error:

Computing velocity autocorrelation of 152 tracks... [...] 17/152Error using +
Matrix dimensions must agree.

Error in msdanalyser/computeVCorr (line 1266)
sum_vcorr(index_in_all_delays) = sum_vcorr(index_in_all_delays) + lvcorr;

Error in XTMeanSquareDisplacementGrapher (line 137)
msd = msd.computeVCorr;

Do you have a solution for this? (I'm afraid to say I have no knowledge of MatLab language...).

Many thanks!

15 Sep 2014 Jean-Yves Tinevez

Hi @LM,
I am a great admirer of the u-track software, but I did not create something that can arrange its results into the analyzer, sorry.
Thanks for feedback.

11 Sep 2014 LM  
11 Sep 2014 LM

Hello Jean-Yves,

first of all congrats to your fone program!
I have a question regarding the preparation of data for the analysis. It needs to be a cell array with the time points and x/y-coordinates. I use uTrack ( for tracking. This gives me the coordinates in a quite complicated way. I am rather new to matlab and have difficulties to arrange them as the msdanalyzer needs them.
So here is my question: Do you perhaps have already used uTrack for tracking or now a method by somebody else to extract the relevant data from the output?
Any help would be very much appreciated!


07 Aug 2014 Jean-Yves Tinevez

@Vid. Indeed the problem is caused by the frame interval having too many digits. This causes rounding errors while subtracting time position between frames, and some frame intervals are not pooled together.
This a severe flaw, originating from my design choice. Storing the frame intervals in physical units was a bad idea that leads to these errors and the only solution is to rewrite the analyzer and store the frame intervals as integer.
In the meantime, your fix works of course.

06 Aug 2014 Jean-Yves Tinevez

@Florent @Johannes. This clearly points to a MATLAB path problem. Remember that msdanalyzer is a class. What does
>> which msdanalyzer

05 Aug 2014 Vid Sustar


I've sent the xml file via email some time ago, but anyhow, with one colleague we backtracked the code.

Indeed the frameInterval in trackmate .xml file had too many decimals (due to Zeiss microscope software update).

I've solved it by adding a 100. line to ImportTrackmateTracks.m: metadata.frameInterval = digits(7);

Best regards,

05 Aug 2014 Johannes


I have the same problem as "Florent" with the addall "ma=ma.addAll(tracks)". Error message: "No appropriate method, property, or field addAll for class msdanalyzer.".

I checked the location of the Files with "which msdanalyzer":
C:\ProgramFiles\MATLAB\R2012a\toolbox\msd\msdanalyzer.m % msdanalyzer constructor


C:\Program Files\MATLAB\R2012a\toolbox\msd\addAll.m

If I get it right the file locations are ok and the code must be work?!

Best regards

29 Jul 2014 Jean-Yves Tinevez

Hi @Vid,
I suspect this is caused by a problem found by a good friend, related to rounding errors with float frame intervals. Could you send me via email the XML file of the tracks?

23 Jul 2014 Vid Sustar


When using msdanalyser with xml file from trackmate I get a message:
Computing MSD of 44 tracks... 1/ 44Error using -
Matrix dimensions must agree.

Error in msdanalyzer/computeMSD (line 487)
delta = dr2 - mean_msd(index_in_all_delays);

How could this problem be solved?

Best regards,

Vid Sustar

16 Jul 2014 Jean-Yves Tinevez

Hi @Florent
It seems like an installation problem.
What does the 'which msdanalyzer' command says?
What does 'help msdanalyzer' says?

15 Jul 2014 Florent SPAGNI

Hi Jean-Yves,
I have a problem with a class type with your matlab files especially for the addall "ma = ma.addAll(tracks);".
I have this error message printed on the terminal: "No appropriate method, property, or field addAll for class msdanalyzer.".
Did you have this message in the past or have a solution to make it work?
Looking forward to reading to you very soon.
Best regards

14 Apr 2014 Gurthwin  
29 Jan 2014 Jean-Yves Tinevez

For the record: @Gurthwin sent me his track for me to investigate and I found them to be faulty. In some cases, the times of two consecutive detections were the same, so we had dT = 0 for them, which caused the msdanalyzer not to work properly.
Gurthwin is investigating the cause of the problem on his side, and I released a new version that checks that the tracks provided don't have this problem.

17 Jan 2014 Gurthwin

Hi Jean-Yves

I would be able to send you the data.


17 Jan 2014 Jean-Yves Tinevez

It looks like a touchy part of the code. I would need the data that generates the error to fix it. Can you contact me via email to send it?

16 Jan 2014 Gurthwin


This is really a wonderful tool for MSD analysis. I have attempted to submit some of my own tracks but I am greeted with the following error msg in the command window:
Computing MSD of 208 tracks... 3/ 208??? Error using ==> minus
Matrix dimensions must agree.

Error in ==> msdanalyzer>msdanalyzer.computeMSD at 470
delta = dr2 - mean_msd(index_in_all_delays);

I am pretty sure that the tracks are correct. What do you suggest I do?


29 Nov 2013 Jean-Yves Tinevez

@Fredik: Hi Fredik.
Actually no: this MATLAB class is a per-value class, which means that the updates are lost if you do not re-assign the changed object to a new reference.
So in fact you need to do something like that:
>> msd = msd.addTracks(...);
each time.

29 Nov 2013 Fredrik

Its a really nice little class that will be very useful I think. Especially nice to see such good documentation.

I have one problem Im hoping to get assistance with:
In principle everything that should update the properties throw out a new obj looking like it should (with eg added trajectories etc). But the object operated on did not save the updates. If I change the constructor to take trajectories it works and they persist as an object property but cannot be changed.

I am using Matlab 2012a if that should matter.
I dont have any other problems with similar classes that I use.

Would appreciate any input on this.


09 Nov 2013 Jean-Yves Tinevez

Hi. The tool is documented in the html tutorial you will find in the download. Just read it, and you will find the info you need.

08 Nov 2013 Sadiye Velioglu

I really want to use this msdanalyzer, but I could not find any documentation for usage. What type of file (trajectory) do I have to load for analysis? How can I load my trajectory?
Thanks a lot.

30 Oct 2013 Renee  
29 Aug 2013 Yilong Jia


09 Aug 2013 Yilong Jia  
08 Aug 2013 Nilesh Raval  
17 Jul 2013 Peter  
18 Jun 2013 Matt Baker

Great documentation. Standalone it is a very useful tutorial for understanding MSD computation, but additionally is very functional for diffusion coefficient computation across myriad situations.

23 Apr 2013 Harish Chandra  
29 Jan 2014

- Safeguards to ensure that the tracks provided are not erroneous.
- Links to the paper for which this work was created, now that it is out.

08 Jul 2014

Link to source on github, and to the online tutorial.

Contact us