u-track3D

u-track goes 3D!

Table of Contents

1. Associated paper
2. Accessing and loading the code into matlab
3. Description of example datasets:
4. Script usage
5. Reproducing the u-track3D paper with the tutorial scripts
6. Performances
7. GUI walk-through (Beta version)
   1. Getting started and loading data
   2. Detection, tracking and review on the whole volumetric sequence
   3. Definition of DynROI and tracking in DynROI
8. Known issues
9. Milestones
10. Software Requirements

Associated paper

u-track3D tackles on-going challenges in the interpretation and quantitative analysis of large arrangements of 3D trajectories as it arises with the measurement of intracellular dynamics with light-sheet microscopy. The software is associated to the following publication.

u-track3D: Measuring, navigating, and validating dense particle trajectories in three dimensions, Cell Reports Methods, 2023, written by Philippe Roudot, Wesley R Legant, Qiongjing Zou, Kevin M Dean, Tadamoto Isogai, Erik S Welf, Ana F David, Daniel W Gerlich, Reto Fiolka, Eric Betzig, and Gaudenz Danuser.

Accessing and loading the code into matlab

Download the code in the path of your choice:

git clone https://github.com/DanuserLab/u-track3D.git

Then in Matlab, one can import the code either through the matlab navigation panel (right click on code folder, add folder and subfolder) or through the command line as:

addpath(genpath('<path/to/code>'))

Description of example datasets:

The tutorial scripts automatically download and process the following datasets:

Endocytosis dataset: Breast cancer cells expressing eGFP-labelled alpha subunit of the AP-2 complex imaged with diaSLM by K. Dean (Dean et. al. 2016). The raw data has been cropped and limited to 50 time point (540MB).

Mitosis dataset: HeLa cells undergoing mitosis and expressing eGFP-labeled EB3 and mCherry-labeled CENPA imaged in dual-channel lattice light-sheet microscopy by W. Legant (David et. al. 2019). The raw data has been cropped, the entire sequence has been made available.

Script usage

Scripting is generally recommended for the analysis of a large number of acquisitions due to its flexibility and automated rendering capabilities. At the moment, the scripting library also provides more features than the GUI:

• A larger set of dynROIs are available
• Trackability computations
• Fully automated mipping overlay and video production
• Point cloud rendering for faster display of detection mask

After cloning the repo and adding the code folder path to Matlab, you will find the following tutorial script in the repository:

tutoscript/tutoScriptBasicROI.m

This script demonstrates a generic workflow for detection, tracking and the visualization of static ROIs defined automatically around randomly selected tracks. The example dataset describes endocytic pits in a moving cells. It is downloaded automatically. The following features are demonstrated:

• Detection
• Tracking
• Building dynROI automatically around tracks selected randomly
• Rendering and exporting a visualization of tracking results

Example dataset: Endocytosis dataset

tutoscript/tutoScriptAdvancedVisualization.m

This script demonstrates the various approaches available to visualize and create movies of tracking results. Example dataset describes endocytic pits in a moving cells. It is downloaded automatically. The following features are demonstrated:

• Detection & Tracking rendering on orthogonal MIP with various rendering styles, exporting to gif, avi and pngs.
• Exporting detection and trajectory for rendering in the Amira software.
• Fast volume rendering through sparse point cloud representation.
• Saving and Sideloading detection and tracking results

Example dataset: Endocytosis dataset

tutoscript/tutoScriptDynROIFollowingTrackSet.m

This script demonstrates a workflow for detection, tracking and the definition of dynROIs that fit and follows all the detected trajectories. The example dataset describes endocytic pits in a moving cells. It is downloaded automatically. The following features are demonstrated:

• Detection
• Tracking
• Building dynROI automatically around a set of tracks
• Rendering and exporting a visualization of tracking results in the dynROI.

Example dataset: Endocytosis dataset

tutoscript/tutoScriptTrackability.m

This script demonstrates a workflow for detection, tracking and the estimation of trackability on static ROI selected randomly. The example dataset describes endocytic pits in a moving cells. It is downloaded automatically. The following features are demonstrated:

• Detection
• Tracking with trackability
• Selecting a ROI automatically around a track selected randomly.
• Rendering and exporting a visualization of tracking and trackability results
• Plotting trackability scores for the ROI

Example dataset: Endocytosis dataset

tutoscript/tutoScriptDualChannels.m

This script demonstrates detection, tracking and building dynROI accross multiple channels. The example dataset describes a cell during early stages of mitosis, it is downloaded automatically. The following features are demonstrated:

• Detection and tracking with scale selectivity on the EB3 Channels (channel 1)
• Detection and tracking on the kinetochore channel (channel 2)
• Sideloading previous detection and tracking results with process parameters
• Building a dynROI between two trajectories measured on two different channels.
• Rendering

Example dataset: Mitosis datasets

To improve computation time, you want to adjust the number of core available to performed parallelizable tasks. To do so, use the parpool(#) function with # the number of parallelizable core on your machine.

Reproducing the u-track3D paper with the tutorial scripts

The scripts reproduce the majority of features used in numerical experiments presented in the u-track3D paper. Because of the large size of the datasets used in the paper, the script operates on smaller datasets that are amenable to direct download by the community. Here is the detail of the features that are demonstrated, their associated figures in the paper, and the script that reproduces them. One script can demonstrate several feature with a same dataset:

Feature	Figure	Script
Tracking Brownian motions described by endocytic events	Fig 2	tutoScriptBasicROI
Building dynROI around tracks	Fig 3	tutoScriptDynROIFollowingTrackSet
Multiscale Detections (Pole, KT, plus-ends)	Fig 4	tutoScriptDualChannels
Building conical dynROI between MT Poles and Chromosomes	Fig 4	tutoScriptDualChannels
Tracking restricted to a dynROI	Fig 6	tutoScriptTrackability
Trackability	Fig 6	tutoScriptTrackability

Here is a list of the measurements that cannot be reproduced with those scripts and datasets due to the size of the associated datasets:

• Endocytic events lifetime analysis on on Breast Cancer Cell imaging (Fig1.b,c)
• Microtubule instability response to biochemical inhibition (Fig1.e,g).
• Adhesion shape studies (Fig2.a-d).
• Interpolar plane estimation from prometaphase to metaphase (Fig 2.f-i.)

Performances

The software is CPU-optimized and has been tested on the following machines.

Computer main features	OS	script	Time (s)
Intel Xeon E5-2680 28 cores @ 2.4 GHz - 528 GB Ram	Linux	trackingEndocyticPits_visualLibraryDemo (incl. rendering)	142
Intel Xeon E5-2680 16 cores @ 2.7 GHz - 32 GB Ram	Linux	trackingEndocyticPits_visualLibraryDemo (incl. rendering)	206

GUI walk-through (Beta version)

The GUI is generally recommended for the analysis of a couple files and test the capacity of u-track3D on a given type of dataset. With straightforward data loading and a simplified execution pipeline, the GUI is designed toward an intuitive first experience.

Getting started and loading data

Create a parallel pool for parallel computing in matlab using either the command line or the graphical interface. Add the code folder in Matlab path. Then launch the GUI in the command line with:

u_quantify()

Then click "new" to create a new movie

If the data follows the bioformat standard, then open "Import Movie using Bioformat " and select the file, or first file of a sequence. If not, the format must be in a single tiff file per time point and each channel must be placed in a single folder. Use the "add channel" dialog to point to each channel folder

Then launch the "u-track3D" application.

In order to keep the set of operation linear, u-track3D is organized in seven processes:

1. Maximum Intensity Projection (MIP) rendering
2. Detection on the full volume
3. Tracking on the full volume
4. Definition of a Dynamic Region Of Interest (DynROI)
5. Maximum Intensity Projection (MIP) rendering in the DynROI
6. Detection in the DynROI
7. Tracking in the DynROI

Detection, tracking and review on the whole volumetric sequence

Each process must be parameterized or "setup" before being run. Sometime it merely involves opening the setup dialog and accepting the defaults by clicking "apply", as for example below with the MIP rendering process in the case of a single channel. This step ensures that the users explore the capacity the algorithm to adapt the parameters to their datasets.

The detection parameters propose different algorithms for detection, the default approach being the one presented in the u-track3D paper. In this beta version, the "Scales" dialog define the scales used for filtering and the Alpha value define sensitivity. Further improvement will be made to separate different type of algorithms.

Click "Apply" and then "Run" in the control pannel to run the first two processes, then review the results by clicking on "Results" in step 2. Results can be seen overlayed over a MIP:

Or by slicing the volume

The parameterization of the tracking algorithm first provides control over the maximum gap size, the minimum track size to be considered among other several controls.

The control of Frame-to-frame linking and gap closing is performered in separated views:

Once tracks are computed ("Apply" parameter and click on "run"), trajectories can be reviewed similarly to the review of detections.

Definition of DynROI and tracking in DynROI

The estimation of trajectories open the door to the dynROI in step 4. Several variation of dynROI estimation are made available such as:

• fitTrackSetFrameByFrame: fit an optimal box following a group of tracks over time. Motions are estimated on a frame-by-frame basis, ideal when the structural changes are important over time, but local changes are smooth over a few frames.
• fitTrackSetRegistered: fit an optimal box following a group of tracks over time. Motion are estimated with respect to the first frame, ideal when the structural changes are slow overtime but the local motions measured in the trajectories are highly stochastic.
• fitDetSetFrameByFrame: same as "fitTrackSetFrameByFrame" using detection instead of tracks.
• fitDetSetRegister: same as "fitTrackSetRegistered" using detection instead of tracks.

More dynROI types will be made available and documented in the near future.

The review of dynROI location can be carried out using the MIP view in the Results panel:

The voxels described by the dynROI can then be displayed by toggling on the "Dynamic ROI Raw Image" dialog. Here is a gif produced through the "save frames" dialog:

The last three remaining process 5 to 7 behave similarly to step 1 to 3, except that the dynROI built must be specified for the process to run properly using the "Build Dynamic ROI Process" drop-down menu as shown below for the detection process:

and for tracking process:

Known issues

• The set of parameters for detection is confusing. Further streamlining improvement will be made for a smaller set of parameters to be visible.
• Detection and tracking sets used for dynROI estimation must be set manually, even when there is only one option.
• The Detection set must be selected before the last tracking step. This problem is also being solved.

Milestones

• Adding Amira trajectory export in addition to detection in example script
• Demonstrate trackability in the script
• Fix annoying requirement in the GUI work flow (cf. Known Issues)
• Adding a script for basic ROI randomely selected <2022-07-07 Thu>
• Adding a script for dual channel manipulation <2022-07-07 Thu>
• A more complete test on mac and windows
• Add an example of script-based Bioformat import
• Adding more types of DynROI in the GUI

Software Requirements

• This software requires the following Matlab toolboxes

  • Matlab (tested on 2018a to 2022a)
  • Computer Vision Toolbox
  • Image Processing Toolbox
  • Control System Toolbox
  • Optimization Toolbox
  • Image Processing Toolbox
  • Statistics and Machine Learning Toolbox
  • Curve Fitting Toolbox
  • Computer Vision Toolbox
  • Parallel Computing Toolbox

• This software has been tested on the following OS

  • Linux Red Hat 7

---

Danuser Lab Website

Software Links