Tracking in 3D

This repository holds all of the codes used in [(https://arxiv.org/pdf/2511.10174)]. The way the data is processed is entirely described in the supplementary information of the articles.

What is this repository for?

Tracking particles in three-dimension. The software allows for tracking particle in three-dimension when a time-series of z-stack is provided to it. If only a single 2D image is provided for each time point, the tracking is then perform in 2D.

How do I get set up?

You will need to install bio-format for some of the extension (.his) see https://www.openmicroscopy.org/bio-formats/downloads/ where you can download the matlab toolbox.

2D Calibration

Only for working with 3D time-series acquired on a multiplane setup. As explained in the paper we use a sample where fluorescent beads are spun cast onto a coverslip and we acquired a few z stack making sure that the range of the z stack is large enought so the beads will be in focus at some point in each of the planes.

To get the 2D calibration file you will have to run mainPlaneCalibration.m

To run this code you just have to provide the main folder of analysis (folder containing subfolder each containing 1 Movie) for example: file.path = 'C:\Users\X\Documents\2020-Data\August\28\2DCal' file.ext = '.ome.tif'

The data will be saved in the same path. When using mainTrackingExp.m you will need to provide that path as the calibration: path2Cal = 'C:\Users\X\Documents\2020-Data\August\28\2DCal'

The software will automatically search for the calibration file that is saved by mainPlaneCalibration.m.

If a single frame has more than 650 rows (eg. 1300x2048 px), the data will be recognized as two-channel data. The frame will be split at row 650 with channel 1 on the top rows and channel 2 below.

SR Calibration

Only to use when using 3D multiplane data, in a tracking experiment for subpixel accuracy.

The SRCalibration is run on the same data as the 2D Calibration. You need to run mainSRCalibration.m. This code will correct mismatch between the different z planes with subpixel accuracy it is therefore not mandatory but adviced to increase the accuracy of your tracked trace.

To run this code you just have to provide the main folder of analysis (folder containing subfolder each containing 1 Movie) for example: file.path = 'C:\Users\X\Documents\2020-Data\August\28\2DCal' file.ext = '.ome.tif'

The data will be saved in the same path. When using mainTrackingExp.m you will need to provide that path as the calibraiton: path2SRCal = 'C:\Users\X\Documents\2020-Data\August\28\2DCal'

The software will automatically search for the SRcalibration file that is saved by mainSRCalibration.m.

Therefore, in mainTrackingExp.m both path2Cal and path2SRCal should have the same path given.

If the data was recognized as two channel data, the code will automatically run the SR calibration on both channels seperately. If subpixel alignment between the channels is also important, the parameter 'info.AlignChannels' (line 26) should be activated ('on').

2D time-series

If you're data is composed of a time-series of 2D images (standard widefield or confocal microscope), the main code you will be using is the mainMultiModalExp.m.

The first block two blocks of code in mainTrackingExp.m aim are intended for user input:

path2ZCal and path2SRCal are only used for 3D analysis and need specialized calibration files, thus they should be left empty for the software to know that they should not be used: path2ZCal = []; path2SRCal = [];

file.path should be the path to the main folder of your analysis, that is, a folder that contains subfolder (e.g. mov1,mov2,mov3) which contains the data files. This convoluted system is due to the way our microscope encapsulated each dataset in a new subfolder which makes it easier for us to process. However, this allows to process multiple data set simultaneously. Typically you want to analyze data in group acquired in the same conditions. Here is an example of folder in which you want to process the folder containing data acquired on the 28 of August (the date, month, etc... are not needed, it is just an example taken out of the way I organize my data but there is no restriction as to the naming of the folders and subfolders as long as they exist on your computer or connected hard drive):

file.path = 'C:\Users\X\Documents\2020-Data\August\28' path2Cal is also for 3D multiplane data and should therefore be left empty here: path2Cal = [];

Now you can press run!

First, a dialog should popup where you can change all the user parameters:

1. The left column contains parameters that are applicable for both channels: 1.1 Ext: should give the extension you are using. Currently the code can only process .ome.tif (3D), .his and .tif files. If you have another extension, we advice you to either convert the movie to .tif using imagej or to contact us so we can perform the modifications needed(see contact info at the bottom).4 1.2 info.type = 'normal'; indicates wheter, in the movie, the object of interest are bright (darkfield or fluorescence == 'normal') or dark ('transmission') 1.3 info.runMethod = 'load'; 'load' mean that, in the case there is already some processed data stored, the code just loads the previously obtained results, in the case you want to rerun, put on 'run'. 1.4 calibrate = 'true' or 'false'; Rerun the calibration or not 1.5 draw ROI = 'on' or 'off'; Draw manually a region of interest, pixels outside of that region will not be used in analysis. Only possible when running the calibration 1.6 Dimension = '3D' or '2D'; 1.7 multiModal = 'on' or 'off'; multimodal 'on' means dealing with data from two channels, 'off' means a single channel 1.8.1 and 1.8.2 Channel1 and Channel2; Here you choose what type of analysis you want to perform in each channel. If multiModal is set to 'off', only Channel1 can be selected for analysis. Choices are Translational Tracking, Rotational Tracking (only possible in multimodal mode with both channels on 'Rotational Tracking'), Differential dynamic microscopy (DDM), Temporal image correlation microscopy (TICS), quantitative phase imaging (QPI), segmentation. Selecting one of these will result in the selection of the right parameters in the second (and third) column. More information about each analysis can be found later in this paragraph. 1.9 Pixel size in nanometer 1.10 FWHM: Full width at half max, = expected width of the diffraction pattern for a single emitter in pixels (mostly 3) 1.11 Frame2Load: what frames from the movie you want to analyse, either 'all', or a selection (eg. select first 200 frames, type '1:200' or frame 300 to 500 type '300:500') 1.12 Test Frame: frame on which the detections of single emitters will be plotted (to validate detection) 1.13 Bipyramid: dimensions of long and short axis of bipyramid particle, only when two channels are selected for rotational tracking 1.14 Rotational calibration 'on' or 'off': analysis of 2D sample of nanoparticles for calibration 1.15 Rad Time: rotational speed of lambda/2 polarizer when doing rotational calibration.

2. The 2nd and 3rd column are for user variables specific on the selected analysis per channel. The different options are listed in the next points 3 to 7.

3. Translational tracking 3.1 fitMethod is what fit you want to use either the phasor approach from Martens et al 2018 or a 2D gaussian. The phasor approach is significantly faster and has similar accuracy so we picked it as default 3.2 zMethod is only used for 3D data so you do not need to mind its value in this case. 3.3 detectionMethod: 'MaxLR' (maximum likelihood) or 'intensity' 3.4 Background substraction: 'off' or a scalar e.g '10' => If you put a scalar, the background will be filtered away with a spheric kernel of that size. So make sure that the kernal size is always bigger than your points of interest. 3.5 Fitting 'on' or 'off': Super resultion fitting of points of interest, 'on' when tracking single emitters (nanoparticles and molecules), 'off' when tracking irregular shapes (bacteria, biological structures). Fitting 'on' performs the superresultion gaussian fitting on the PSF, when off, the center coordinate of the bright segment is used (and thus less accurate for single emitters). 3.6 euDist (nm): Tolerated error on the localisation to identify two localizations from different channels as the same particle. So, only important when working with particles that are visible in both channels. The euDist restrict the range to look in the other channel to search for the same particle. 3.7 Delta: region of interest drawn around a candidate particle to perfrom the superresultion fit (6 or 10 is best) 3.8 chi2: detection threshold. If you are looking at very bright object going slightly above 80 could be good 80-120 (if you see that detection is done on diffraction rings for instance). On the other hand you might want to put it as low as 24 if you are working with very dim particles (e.g. single-molecules). 3.9 consThresh: Important when working with multiplane data, in how many planes has a particle to be visible to be recognized as a particle (eg. when consThres is on 4, a particle needs to be visible in at least 4 planes, otherwise it is trashed). 3.10 radius: maximum step between two frames a particle can take (nm) 3.11 memory: how long a particle can be invisible (eg. particle is 3 frames not detected, but again in the 4th frame, then it might still be saved in the old trajectory if memory > 3, if memory <3 then a new trajectory will be constructed) 3.12 Correct Drift: correct all coordinates of each frames by substracting the collective motion between each frame. Only needed when you see drift in the data, and only thrustworthy to use if you have more than 20 detection in every frame.

4. Rotational Tracking: Same parameters as Translational tracking

5. Segmentation 5.1 GlobalBgThr: Threshold used to substract the global background (background equal over full frame) 5.2 ShowSegmentation: Show a figure with the preview of the segmentation 5.3 Threshold: used for local thresholding by Otsu 5.3 Disk dim: diameter of disk to do local background substraction, should be bigger than features of interest

6. Phase 6.1 Pixelsize z: average spacing between the planes (nm) 6.2 NA detection: NA of objective 6.3 NA illumination: 0 for coherent light 6.4 Refractive index: from sample (eg. watery solution = 1.33) 6.5 Central wavelength: of illumination light 6.6 Bandwith: of illumination light 6.7 alpha: calibration factor 6.8 axial cutoff: depends on NA illumination (see Descloux 2018) 6.9-11 mirror around x, z, fourier: see Descloux 2018 6.12 Calibrate alpha: 'on' or 'off'

7. DDM 7.1 Particle radius: in nm 7.2 Exposure time: in sec 7.3 Wavelength: peak wavelength from emission 7.4 NA: from objective 7.5 Temperature of sample, in Kelvin 7.6-7 Qmin and Qmax: selection of wavevectors to analyse (spatial scale of the moving features of interest) 7.8 Scanning reconstruction: Construct small window that rolls over frame to construct a map (computationally quite heavy!) 7.9 CorrectBleaching: multiply every frame with a factor so the average intensity in every frame is constant 7.10 Angular anisotropy: more motion in a specific direction or not? 7.11 fitrange D: how many datapoints are used to fit diffusion from MSD 7.12-14: min, max, expected D: create boundary conditions to restrict the fitting

8. TICS 8.1 Exposure time: in sec 8.2 Particle radius: in nm 8.3 Temperature of sample, in Kelvin 8.4 TICS window: average neighbouring pixels (= losing resultion) 8.5 Calculate omega: 'on' = calculate omega from movie itself, 'off' = use theoretical omega (from diffraction limit) 8.6 Plot fit on SACF: show window that shows fit of SACF to calculate omega 8.7 Frames to calculate SACF on 8.9 Wavelength: peak wavelength from emission 8.10 NA: from objective

The code will then run and hopefully after some minutes you will get a popup saying that your data was sucessfully saved.

3D time-series

We only use .ome.tif files and can only process multiplane microscopy data at the moment so if you are not using the same format we advice you to contact us (see contact below) for information about how to get setup or if you want us to extend the code so you can process your data.

If using the same format as us here is the information you need to get setup (please read the 2D section too, only the info specific to 3D will be explained here):

In addition to the information provided above you will need to take a bit more care with the following: info.zMethod is intensity by default and use the same methods as in the paper in which we used this code ([insert Link]). PSFE is possible but need an additional calibration file (zCalibration). 3DFit is still in development and is therefore not advice.

info.calibrate can be change to true if it turned out that your 2D calibration (that determines the distance between your planes, more details later) was not good and you recalculated, you will need to recalibrate the experimental data with the new calibration.

Output Data from tracking code

1. Translational Tracking Coordinate of the detected particles before and after fitting are saved in the subfolder of the respective movie. If you are only interested in localizing and not tracking you can therefore use this .mat file to process your data further. The tracked particles for the movie in all subfolder is saved in the main folder as trackResults.mat. It contains a structure containing info about the parameter used, the path where of the data from which it was taken and the traces. The traces are contain in a cell array as follow:

1. First column: 1 cell for each trace containing a table with the x,y,z coordinate and other intermediate results, once loaded into matlab it can be access as follow: trackRes.trace{i,1}.row trackRes.trace{i,1}.col trackRes.trace{i,1}.z where row index correspond to y, col index corresponds to x, and i correspond to the index of the trace you want to extract.
2. Second column: Contains the index to which movie the particle belong so if you would ever run different condition together or want to compare different movies from the same condition you can do it by separating the particle list according to the movie they were taken from.

Analysis of traces

To further analyse the traces, the script mainCalcMSD_microrheology.m should be ran. You can immediately press run and a pop-up will open for the user parameters:

1. File Path: filepath to the main folder containing all the subfolders with data from the same experiment (same path as file.path in the tracking code)
2. Experiment: select between Tracking (single channel), Tracking and segmentation, Tracking and Phase, Rotational Tracking or Dual color tracking (two channels)
3. Filename: Filename of the file containing the traces (= output file from the tracking code. In the latest version both traces3D_ or trackResults_ work)
4. Dimension: 2D or 3D traces?
5. Exposure time: in sec
6. Temperature: in Kelvin 7-8. Radius: of the nanoparticles (in each channel)
7. DiffFit: number of datapoints to use in fit on MSD to calculate diffusion coefficient
8. MinSize: Trajectories shorter than minsize are discarded
9. CutTraces: either 0 or a number. 0 means that the full trajectory is analysed as such, so every trajectory yields 1 diffusion value (or any other parameter). If cutTraces is said to 50, then first the first 50 datapoints from the trajectory will be analysed, then 2:51, 3:52,... end-50:end. This can be used when the behaviour of the trajectory changes during the length of it, while this dynamic behaviour needs to be captures (eg. transition between two states, and the trajectory is first brownian but becomes more and more confined).
10. Extension: type of file for output
11. StepsizeAnalysis: when 'on', the diffusion is not calculated from the MSD, but from every step size. Every step size is now a datapoint that can be used to construct a distrubution of diffusion behaviour.

Who do I talk to?

If you have any problem just contact Steven Huysecom (steven.huysecom@kuleuven.be) or Boris Louis (boris.louis@kuleuven.be)D