Welcome to DiffusionLab’s documentation!¶
DiffusionLab is software designed to extract valuable information about the motion from single-molecule or particle trajectories obtained with e.g. super-resolution localization microscopy. DiffusionLab allows for facile segmentation of tracks in ‘populations’ based on their properties. The diffusion constant can be estimated with a method tailored to population characteristics and therefore allows the analysis of complex heterogeneous data sets.
- Version
0.99
Getting Started¶
Introduction¶
In tracking experiments – common in the field of chemistry, biology, and physics – time-lapse movies are obtained of to-be-tracked object(s) of interest. This is often molecules, proteins, or colloids. Dedicated software can record the location of the object in each frame and group the positions over time that belong to the same object. The groups of locations are called tracks (or trajectories) and contain information about, among others, the motion of these molecules or particles. This motion can contain value information about the tracked object itself and its surroundings, but this is often not straightforward to obtain for either two reasons:
Trajectories contain only a few locations due to fast motion out of focus or limited stability of the tracked object, and can therefore not be analyzed individually.
The trajectories with different fundamental behavior are present in the same data set.
DiffusionLab is software that was designed to deal with the problems described above, but has grown into a versatile track motion analysis software. By first performing a segmentation of the tracks into user-defined categories, erroneous tracks can be removed and tracks with the same motion behavior can be grouped. The model can be tailored to each group individually and computed for the tracks. The mean motion behavior of a group can be computed if the tracks are too short to be analyzed individually. The suggested workflow can be found here.
Installation¶
DiffusionLab is available as MATLAB App, which is shipped as MATLAB App Installer (.mlappinstall). The App can be installed in MATLAB by clicking Install App in the APP tab. After installation, the App is available in the App toolstrip under ‘MY APPS’.
MATLAB’s Curve Fitting Toolbox and Image Processing Toolbox need to be installed to use all DiffusionLab’s features. Type ver in the MATLAB Command Window and press enter to check which toolboxes are installed. To install the missing toolboxes, go to the ‘Home’ ribbon tab > Add-Ons > Get Add-Ons and search for the ‘Curve Fitting Toolbox’ and ‘Image Processing Toolbox’ to install them.
Software has been written and tested in MATLAB 2019b.
Upgrading¶
To upgrade DiffusionLab to a new version, first uninstall the current version by clicking the App with the right mouse button and press Uninstall. Follow the installation procedure above to install the new version of the APP.
Warning
Make sure to first uninstall the old version before installing a new one. Two installed versions of the same APP can give rise to unexpected behavior.
Workflow¶
The suggested workflow is the following:
Localization, tracking, and export in DoM or Localizer
Import in DiffusionLab
Compute track properties
Plot track(s) and/or properties and identify desired populations
Segment in desired populations and use the plot previews to assess the segmentation
Compute the diffusion for all populations with the most desired diffusion estimator
Plot results and save figures
When the trajectories contain too few locations to be analyzed individually with a reasonable error, it is recommended to analyze the mean motion behavior of the population. Both the mean squared displacement (MSD) and cumulative probability density (CPD) analysis allow the fitting of the population mean.
Any steps 3–7 can be skipped if only partial functionality is needed.
Usage¶
Export for DiffusionLab¶
DiffusionLab supports the import of tracks from DoM v.1.1.6 and Localizer for Igor Pro. Support requests for formats can be sent to the developers.
DoM v.1.1.6¶
DoM is an ImageJ plugin for localization and tracking of single-molecule fluorescence time lapse movies. The software is freely available here. The results can be exported via the ImageJ “Results” table. The steps are the following:
Open your movie in ImageJ
Analyze > DoM v.1.1.6 > Detect molecules and perform “Detect molecules and fit” with the optimized settings for your system. Use a “fitting iterations number” of 5
Analyze > DoM v.1.1.6 > Link Particles to Tracks
Go to the “Results” table and go to File > Save As and save the table as .csv file
Macros are available in the group for batch localization and linking into tracks.
Localizer for Igor Pro¶
Localizer is a plugin for Igor Pro for localization and tracking of single-molecule fluorescence time lapse movies. The software is freely available here. Tracks can be computed and exported following:
Localizer > Read CCD data > Read CCD data from disk…
Press >> on the movie viewer and perform Localization and Tracking
Localizer > Manipulate Particle Tracks > Save tracks to text file…
Supported Localization algorithms are:
Gaussian fitting
Gaussian fitting (fixed width)
Ellipsoidal Gaussian fitting
MLEwG
Warning
The localization algorithm is recognized by the number of columns in the output file. If this changes, the columns are interpreted incorrectly.
COMSOL¶
COMSOL is a commercial software packing for multiphysics modelling and allows single-particle trajectory simulation. For this, the Particle tracing module should be installed. Tracks can be exported follwing:
To do!
Warning
COMSOL exports the coordinates in three dimensions. The functionality of DiffusionLab for 3D trajectories is limited and some track properties are only computed in the XY-plane. A warning in the MATLAB log window appears when this occurs, and explains which track properties have been affected.
DiffusionLab GUI¶
Assuming that DiffusionLab has been installed, the graphical user interface (GUI) can be found and opened in the APP toolstrip under ‘MY APPS’. The GUI of DiffusionLab is given in Figure 1. The options will be discussed in the following sections.
Overview of the graphical user interface (GUI) of DiffusionLab¶
Import & Save Tracks¶
Tracks can be imported from DoM results tables, Localizer text files, and COMSOL text files with the options in the menu File > Import tracks. Loading of large files can take while; DiffusionLab will output the path of the loaded file followed by ‘done’ in the Command Window.
In order to do quantitative (motion) analysis of the trajectories, the track settings have to be set in the Compute properties panel. The Pixel size is the length of a single pixel edge in nanometers, the Frame time the time between frames in seconds, and Exposure time is the time the shutter is open per frame in seconds. This assumes that the time in raw data is given in frames and the coordinates in pixels. If not, these values should be considered as a conversion factor from the unit in the raw data to the unit given in the GUI (see Hint). The Exposure time is only used to compute the motion blur constant in the diffusion constant estimators following the Berglund camera-based single-particle tracking model. 1 It can be set to zero to not include motion blur in the analysis.
Hint
If the coordinates in the raw data are given in micrometers, the Pixel size is 1000 (nanometer/micrometer). This situation often occurs when working with simulated tracks, e.g. from COMSOL.
Note
The pixel size, frame time, and exposure time can be changed anytime, and all new figures are plotted with the new values.
The current DiffusionLab session can be saved and restored via File > Load / Save. The saved file has an extension *.mat.
Segmentation¶
The standard track properties of the loaded tracks are computed with Compute track properties. Additionally, the mean squared displacement (MSD) values are computed for plotting and fitting.
The Population is a group of tracks with – preferably – similar diffusion characteristics. Populations can be managed in the Segmentation panel. The current Population can be selected in the first dropdown menu Population # in the Selection panel. Each Population has a number of Tracks, which can be selected based on the Track ID in the second dropdown menu Track #. The computed track properties can be selected in the bottom two menu’s, which are respectively the Track property 1 and Track property 2.
Property table¶
The properties of the individual tracks are displayed in the track table. The population and track property of interest can be set using Population # and Track property 1, respectively. All tracks within a population have a unique track ID, which can be used to find the track back in the Plot tracks using the Label option. The tracks are sorted from low to high value of their current property. Invalid values are indicated by NaN.
Warning
The track IDs change when tracks are added or removed from a population and do not remain the constant throughout the analysis.
Manual Segmentation¶
Segmentation is performed on the current Population # with the Track property 1. The threshold value is given in the field Property threshold and must be a scalar numeric value. The filter is selected via Use property 1 as filter, but not directly applied. The settings during the filter selection are saved and the filter has to be reapplied when the user wishes to change Population # or Track property 1. The tracks and MSD can be plotted with Preview all filtered tracks and Preview all filtered MSDs and the filter can be applied with Apply filter to all tracks or deleted with Reset filter. The Delete current population button deletes the currently selected population and cannot be reversed. The currently selected Population # can be merged using Delete current population with the population number in the dropdown menu next to the button. This resets the diffusion constant estimator and the motion analysis settings will be lost. The result of the all segmentation steps can be displayed as decision tree with the Plot decision tree button.
Note
Selection of a filter via Use property 1 as filter allows the user to preview filtered tracks and their mean squared displacements. This allows manual tweaking of the Property threshold. The application of the filter to the current population is done via the Apply filter to all tracks button.
Segmentation Using Machine Learning¶
The trajectories can be segmented with a classification tree or other supervised machine learning tools available in MATLAB. DiffusionLab comes with an additional tool that allows the user to create a training set for supervised machine learning. This tool Classification Trainer (for DiffusionLab) allows rapid manual classification of trajectories in up to five user-defined categories, and is shown in Figure 2. It can be opened via Classification > Classification Trainer in the DiffusionLab main window. The training set can be used to train a classification tree or be imported into MATLAB’s Classification Learner app.
Overview of the graphical user interface (GUI) for classification.¶
The current population that is open in DiffusionLab when opening Classification Trainer is loaded and made available for classification in Classification Trainer. A new training set is started by pressing New training set or saved training set can be loaded directly via Load training set in the General panel. Up to five categories can be added via Add category and deleted likewise with Delete category. Deletion of a category results in the permanent deletion of the tracks from the training set. The categories can be named with Rename category and these names are stored in the population and used as label in the decision tree when displayed using Plot decision tree in the DiffusionLab main window.
Note
The training set is saved in SI units and is thus compatible regardless the pixel size and frame time of processed data sets. This means that the pixel size and frame time cannot be changed after the classified tracks have been added to the training set.
Training is done in batches. The number of tracks per batch is given in the field No. tracks to classify and the minimum number of track points in the batch is given in the field Minimum track points in the Training panel. The progress of the training is followed in the text field in the Training panel. Preliminary cancellation with Cancel training results in no tracks from that batch being added to the training set. During training, user is shown a plot of a trajectory and asked to classify this track into one of the created categories. The red dot is the minimum bounding circle center and the green dot the center of mass of the track. The scale of the plot can be set Auto for auto scale or a manual Plot range (m) can be given in meters. Assignment of a track into a category can be done by clicking the respective button or via the hotkeys marked below. The last assignment can be redone by pressing Go back and allows the user to revisit the classification of the last track.
Hint
To create a training set with tracks from multiple data sets, one can save the training set and open it when a different data set is loaded from DiffusionLab. The trained tracks from the new data set will be appended to the loaded training set.
Hint
If the hotkeys do not respond, please click next to plot window.
A decision tree can be trained from the currently loaded training set in the panel Segmentation tree. The tree is computed with Compute tree and the mximum number of splits allowed in the decision tree is set in the field Max. number of splits. The tree is displayed in the log window and plotted after computation or via the button View tree. The tree uses all standard track properties for training. The currently opened population in DiffusionLab can be segmented with this tree using Segment DiffusionLab. This action will close the Classification Trainer and open DiffusionLab with the segmentation executed.
Note
The splits of the classication tree are not included in the decision tree available in the DiffusionLab main window Plot decision tree. Please save the decision tree before proceeding with Segment DiffusionLab.
The classification and track properties of the tracks in the training set can be exported for MATLAB’s Classification Learner app via Export for Classification Learner. The Classification Learner app can be opened with MATLAB Classification Learner. Here, also a subset of track properties can be selected for classification and the full toolbox of supervised machine learning in MATLAB can be used including:
Decision trees
Discriminant analysis
Naive Bayes classifiers
Support vector machines
Nearest neighbor classifiers
Ensemble classifiers
Classification Learner can also be opened from the DiffusionLab main window via Classification > MATLAB Classification Learner. The trained model in Classification Learner can be exported via export model or export compact model. The current population in DiffusionLab can be segmented with this save model via Classification > Segment with model CL.
Visualization¶
The tracks and their properties can be plotted in the Plot properties menu. The Line thickness and Colormap can be set for all plots. The currently selected Track # and its properties can be plotted with Plot selected track and its mean squared displacement curve with Plot selected MSD.
When the checkbox Plot for all populations (opts below) is selected, all populations are plotted in a single figure, while when the checkbox is unselected only the current Population # is plotted. Plot tracks displays the coordinates of all tracks and the Label check box toggles the Track IDs of the last plot. This functionality remains after plotting and can be used to correlate the track’s coordinate to its properties. Plot MSD shows the mean squared displacement curves of population(s). Box plot of 1st property plots a box plot of the current First property with the central mark indicating the mean, the box top and bottom edges the 25th and 75th percentiles, respectively, and the whiskers the most extreme data points that are not considered outliers. Outliers are indicated with plus symbols. Histogram of 1st property plots a histogram of the First property with counts or probability selected with the Probability checkbox and linear or logarithmic binning toggled by the Logarithmic binning checkbox. Plot squared displacement is a special case of the histogram plot and and uses the same (Probability and Logarithmic binning) checkboxes. It plots the squared displacement after a set Delay index: in the number of frames, which should be an integer. The Spatial map of the 1st property plots a Voronoi diagram of the track’s center of mass coordinates. The tracks at the edges are enclosed by a convex hull. If the spatial map is plotted for a single population, the color of the Voronoi cells represents the value if the First property. The No edges checkbox toggles whether the edges of the Voronoi cells are plotted and the No centers of mass checkbox toggles whether the centers of mass are plotted. Plot track property correlation plots the correlation between the First property and Second property. Diffusion estimator specific plots generates a popup menu in which a plot can be selected. The menu is only available when a diffusion estimator has been computed. These plots might use the current Track #.
Hint
The Delay index can be set as an individual number (e.g. 2), as a vector of individual numbers (e.g. 2,4,5,9), or as a vector with a regular interval (e.g. 1:5 = 1,2,3,4,5 and 1:2:9 = 1,3,5,7,9) following MATLAB’s syntax.
Display units¶
The units used to display and export properties and motion analysis are dependent on the length and time scale of the trajectories. Therefore, the display units can be set manually in View > Units. Default units are SI units. Like the pixel size, frame time, and exposure time, these changes have direct effect on the track table and on all newly plotted figures.
Motion Estimation¶
The diffusion constant can be computed per track, population or both, depending on the selected estimator in the dropdown meanu No diffusion estimator. The diffusion model is selected in the dropdown menu Select diffusion model, which is automatically updated with the available models for the current diffusion estimator. Diffusion estimator options button gives a pop-up menu in which the settings for diffusion estimation can be tailored. For additional information on the required input, type “doc Dest” in the MATLAB Command Window and select the diffusion estimator for more information. Set current estimator to all populations sets the current estimator and its settings to all populations. Compute diffusion computes the diffusion constant per track, population or both depending on the diffusion estimator. The all pop. checkbox allows the user to compute the diffusion for all populations. Fit results for individual tracks are added to the track properties and fit results of the population can be displayed using Report diffusion population. Plots that are only available for a specific diffusion estimator can be displayed via Diffusion-estimator specific plots. Some plots display results per track and the current track Track # is taken for the plot. Details of the diffusion estimators can be found in diffusion estimators.
Save & Export Results¶
A DiffusionLab session can be saved as MATLAB-file by clicking the File > Save button. The contents of the Track table can be copied to the clipboard by pressing Copy table to clipboard. This allows the user to easily transfer the computed track properties to other plotting software. All track properties can be exported via File > Export > Properties to table and saved in various formats. The tracks can be exported to the MATLAB workspace for scripting (not documented) via File > Export > Tracks to workspace.
All open figures apart from DiffusionLab, that is also other figures and GUI’s unrelated to DiffusionLab, will be closed via File > Close all open figures.
The plots can be saved in a wide range of pixel and vector images via File > Export > Figure using the GUI in Figure 3. The extension can be selected and the default is svg. The width W and height H of the saved figure can be selected in the desired units, default is centimeters. A name for the project can be set in the Project name field or the title, which is set as a prefix to the save name. The title of the figure is taken when the checkbox Append figure title is selected, otherwise only the project name is taken. The title is not saved in the figure itself. Saved figures are not overwritten and number is used as suffix to the save name. Export all open figures saves all open figures apart from DiffusionLab, that is also other figures and GUI’s unrelated to DiffusionLab, with the specified settings. Export current open figure saves the last selected figure.
Overview of the graphical user interface (GUI) for figure export.¶
Debugging¶
For troubleshooting, debug mode can be toggled on in Help > Debug, which provides extensive error messages and the lines of the where the error occurs. During normal usage, this box should be toggled off. When reporting errors, always make sure the error message with debug mode on is provided.
References
- 1
Berglund, A.J., 2010. Statistics of camera-based single-particle tracking. Physical Review E, 82(1), p.011917
Resources¶
Track Properties¶
Track properties are features that describe an aspect of a track. This can relate to for instance the shape or number of points. In DiffusionLab, these track properties are used to segment the tracks into smaller populations with similar motion behavior.
Note
A good set of track properties for segmentation describe features that are different between the intended populations. DiffusionLab provides a large selection of track properties, and depending on the intended populations the best subset of track properties can differ between data sets.
Standard Track Properties¶
The standard track properties are computed in the same way regardless the settings in DiffusionLab via Compute properties.
Number of points¶
Description: number of consecutive localizations.
Physical interpretation:
Mobility
Photostability
Statistical significance
Units: -.
Length¶
Description: the sum of all the individual displacements.
Physical interpretation:
Mobility
Photostability
Units: length.
MinBoundCircleRadius¶
Description: radius of the smallest enclosing circle that can be drawn around the localization coordinates, i.e. minimum bounding circle (MBC).
Physical interpretation:
spatial extension of localization coordinates
Units: length.
MBC minus CoM¶
Description: the distance between the center of the MinBoundCircleRadius and the center of mass, calculated as a percentage of the MBC radius. 1
Physical interpretation:
Evenness spatial distribution localizations. It gives an indication of how homogeneously points are distributed spatially.
Units: -.
Entropy¶
Description: Shannon’s entropy of the distribution of the localization coordinates within the enclosing square that is defined by two times MinBoundCircleRadius. 1
Physical interpretation:
Statistical measurement of spatial randomness
Units: -.
Tortuosity¶
Description: the ratio of the distance between start and end points versus the length of the track.
Physical interpretation:
start-to-end directionality.
Units: -.
Elongation¶
Description: weight of the first principal component of localization coordinates.
Physical interpretation:
Directionality of localizations
Units: -.
Elongation angle¶
Description: direction of the first principal component of localization coordinates
Physical interpretation:
Direction of localizations
Units: -.
Other Track Properties¶
The optional track properties are specified in the diffusion constant estimator and are dependent on the settings thereof.
Localization error¶
Description: imprecision in the localization. The deviation of a localization estimate from its true position is ideally normally distributed in one dimension. The localization error is defined as the standard deviation of this normal distribution.
Units: length.
Underlying Descriptors¶
The standard track properties categorized by their main descriptors are given in Table 1.
Descriptor |
Track property |
|---|---|
Mobility, photostability |
Number of points, length |
Spatial directionality |
Tortuosity, elongation, elongation angle |
Uniformity spatial distribution |
Minimum bounding circle radius, MBCC minus CoM, entropy |
References
- 1(1,2)
Hendriks, F.C., Meirer, F., Kubarev, A.V., Ristanović, Z., Roeffaers, M.B., Vogt, E.T., Bruijnincx, P.C. and Weckhuysen, B.M., 2017. Single-molecule fluorescence microscopy reveals local diffusion coefficients in the pore network of an individual catalyst particle. Journal of the American Chemical Society, 139(39), pp.13632-13635.
- 2
Vestergaard, C.L., Blainey, P.C. and Flyvbjerg, H., 2014. Optimal estimation of diffusion coefficients from single-particle trajectories. Physical Review E, 89(2), p.022726.
Diffusion estimators¶
In this resource section, the available diffusion estimators are documented.
The motion blur coefficient \(R\) is computed following equation S9 in Lindén et al. 1 . A continuous exposure at the beginning of each frame is assumed.
MSD¶
Mean-squared displacement (MSD) analysis is performed both on the individual tracks MSD as the population MSD. As the number of displacements contributing to the mean decreases at longer delay times and the bias increases, it is recommended to not fit the full MSD curve. The fit range can be set in the Diffusion estimator options menu.
Clipping factor: maximum fraction of the total number of delay times, when value < 1 or the number of delay times included in the fit when value > 1. Please note that a delay time of zero is excluded from the fit.
Minimum points taken for fit: minimum number of delay times taken for fit regardless of the clipping factor.
Diffusion-estimator specific plots:
Plot MSD fit of track: plots the MSD fit of the current track.
plot MSD fit of all tracks: plots the population MSD fit of the current population.
MSD_normal¶
Model for normal Brownian motion. Fits the fit range of the MSD \(<r^2>\) with 2
\(d\): dimension
\(D\): diffusion constant
\(t\): delay time
\(\sigma\): localization error
\(R\): motion blur constant
\(\Delta t\): frame time
The diffusion signal-to-noise (SNR) is calculated following Vestergaard et al. 3
The \(D\), \(\sigma^2\), and \(\textrm{SNR}\) are added as track properties.
MSD_confined¶
Model for trapping in domains. Fits the fit range of the MSD \(<r^2>\) with 4
\(<r^2>_0\): squared confinement length
\(t\): delay time
\(\tau\): confinement time
The \(<r^2>_0\) and \(\tau\) are added as track properties. More information on the relation between the squared confiment length and the confiment domain size can be found in Qian el al. 4
MSD_directed¶
Model for normal Brownian motion in a flow. Fits the fit range of the MSD \(<r^2>\) with 5
\(d\): dimension
\(D\): diffusion constant
\(t\): delay time
\(\sigma\): localization error
\(R\): motion blur constant
\(\Delta t\): frame time
\(v\): velocity
The \(D\), \(\sigma^2\), \(v\), and \(\textrm{SNR}\) are added as track properties.
References
- 1
Lindén, M. and Elf, J., 2018. Variational algorithms for analyzing noisy multistate diffusion trajectories. Biophysical journal, 115(2), pp.276-282.
- 2
Michalet, X. and Berglund, A.J., 2012. Optimal diffusion coefficient estimation in single-particle tracking. Physical Review E, 85(6), p.061916.
- 3
Vestergaard, C.L., Blainey, P.C. and Flyvbjerg, H., 2014. Optimal estimation of diffusion coefficients from single-particle trajectories. Physical Review E, 89(2), p.022726.
- 4(1,2)
Qian, H., Sheetz, M.P. and Elson, E.L., 1991. Single particle tracking. Analysis of diffusion and flow in two-dimensional systems. Biophysical journal, 60(4), pp.910-921.
- 5
Saxton, M.J., 2007. Modeling 2D and 3D diffusion. In Methods in membrane lipids (pp. 295-321). Humana Press.