Tracx- a toolbox for tracking non-motile 2D cell cultures¶
Tracx is a MATLAB generic toolbox for cell tracking from various microscopy image modalities such as Bright-field (BF), phase contrast (PhC) or fluorescence (FL) with an automated track quality assessment in absence of a ground truth. It allows to track cells of any shape independent of the cell type. Its modular design allows to use a labeled segmentation mask from any segmentation algorithm along with the raw images! It offers a variety of control and plotting options as well as the generation of animated movies. Additionally there are methods to reconstruct the genealogy for asymmetrical and symmetrically dividing cells.
Tracx allows users to define their own project specifications in xml format, making the toolbox suitable for automating the batch processing of large experiments with thousands of cells and images.
Why using Tracx?¶
The only tool giving you an estimate how good tracking was without the need of a manually curated ground truth.
Can be used independently from a segmentation software. Segmentation algorithms are often tuned for a specific image modality and cell type, therefore keeping segmentation and tracking seperate allows for more flexibility.
Frame by frame tracking allows for live interaction with running experiments (feed back microscopy)
Installation¶
If you run Tracx from source you need to have a fully licensed version of MATLAB (for GUI >R2020a) including the following toolboxes:
Image Processing Toolbox
Signal Processing Toolbox
Statistics and Machine Learning Toolbox
Parallel Computing Toolbox
Fuzzy Logic Toolbox (optional)
Mapping Toolbox (optional)
Installation with git:
Clone this repo including the submodules and add it to your MATLAB path.
$ git clone --recurse-submodules https://gitlab.com/csb.ethz/tracx.git
Then navigate to the folder you cloned the repo and then past the following code to your MATLAB terminal. This will add Tracx to the MATLAB path and makes its functionalities available to you.
addpath(genpath('tracx'));
Manual download of the repository:
Download this repo, unzip it and add it to your MATLAB path. Replace `C:PATHTO` with the actual path on your filesystem where you downloaded Tracx to and run the following code in your MATLAB terminal. This will add Tracx to the MATLAB path and makes its functionalities available to you.
addpath(genpath('C:\PATH\TO\tracxdevel-master\tracxdevel-master'));
Note
An error might occur depending on your platform and MATLAB version used in combination with your internet proxy / certificates. “Error using urlreadwrite (line 98) Error downloading URL. Your network connection may be down or your proxy settings improperly configured.” A potential fix is described here: https://ch.mathworks.com/matlabcentral/answers/92506-how-can-i-configure-matlab-to-allow-access-to-self-signed-https-servers
Usage¶
Start by first generating a new Tracx instance. See Extended usage for more details.
Tracker = TracX.Tracker();
Note
You can assign it to any other variable name of your liking instead of calling it Tracker. We will call it Tracker for simplicity throughout the documentation and demo scripts.
Optionally you can also start the GUI (graphical user interface). See GUI for details.
TracX.GUI.TracXGUI();
Note
The Tracx GUI requires MATLAB R2020a or newer.
Running Tracx for the first time will automatically check and install missing dependencies.
INITIALIZE: Welcome to TracX!
CHECK: Image Processing Toolbox, Signal Processing Toolbox, Parallel Computing Toolbox
DONE: Checking required Matlab Toolbox
CHECK: Full installation of external dependencies.
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/cellxmaskinterface/-/archive/CellXMaskInterfaceTracX/cellxmaskinterface-CellXMaskInterfaceTracX.zip
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/MatlabProgressBar/-/archive/MatlabProgressBarTracX/MatlabProgressBar-MatlabProgressBarTracX.zip
INFO: Download started
INFO: Download successfull https://github.com/siyideng/texttoimage/archive/refs/heads/master.zip
INFO: Download started
INFO: Download successfull https://gitlab.com/csb.ethz/matlab-tree/-/archive/tracx-tree/matlab-tree-tracx-tree.zip
DONE: All dependencies successfully installed.
INFO: INFO: TracX version 1.0.0 is ready.
Create a new Tracx project¶
Before creating a new Tracx project you need:
A set of brightfield or phase contrast or fluorescence microscopy images in the form of TIF files, one file per timepoint, position, channel, etc. These raw images (ideally 16 bit) will be used for the Tracx fingerprints.
A corresponding set of segmentation masks (segmented cells or nuclei). The segmentation masks need to be generated by third-party software (e.g. CellX or Cellpose or similar), as Tracx does not include a segmentation functionality. Labeled masks are preferred over binary masks. These files should also be provided as TIF files and have the same image dimensions as the raw images.
Optional: Any number of additional fluorescence channels that will then be quantified by the algorithm, provided in the same file format and image dimensions.
File names:
Ideally, the file names take the format ChannelName_positionXXYYZZZ_timeTTTT.tif, e.g. Brightfield_position0101000_time0001.tif. Position refers to the x and y component of the well position and to the z-plane; it can be set to 0101000 as a default, if this does not apply to your experiment. The GUI contains a name parser interface that can be used to transform your original file names to the Tracx format using MATLAB® regular expressions, if they do not yet conform to this format (see extended guide below).
Specific requirements for 3D-data (3D + time):
The file format should be in the form of one z-stack per timepoint and channel, as a multi-page TIF file containing the z-planes. If all z-planes are provided as separate files, or all planes and timepoints are provided as one single frame, these can be transformed in the GUI. However, the channels need to be separate.
If the above requirements are fulfilled you can create a new Tracx project as follows:
% [String] Name of the project / experiment.
projectName = 'myProject';
% [String] File name identifier of raw images used
% to calculate the fingerprint (i.e. Brightfield).
fileIdentifierFingerprintImages = 'BF';
% [String] Well position identifier if multi well
% experiment was performed to use.
fileIdentifierWellPositionFingerprint = [];
% [String] File identifier of fluorescent images to be used
% for asymmetrical lineage reconstruction.
fileIdentifierCellLineage = 'mKate';
% [Array, x, y, w, h] Image crop coordinates, in case only part
% of an image was segmented (CellX segmentation only).
imageCropCoordinateArray = [480 445 383 323];
% [Int] Max number of frames to track.
movieLength = 30;
% [String] Image directory to be used for the current project.
imageDir = 'C:\\myProject\\rawImages'
% [String] Directory containing the segmentation results for the current project.
segmentationResultDir = 'C:\\myProject\\CellXResults'
% [String] Cell division type. Either asymmetrical or symmetrical.
cellDivisionType = 'asym';
Tracker.createNewTrackingProject(...
projectName, imageDir, segmentationResultDir, ...
fileIdentifierFingerprintImages, ...
fileIdentifierWellPositionFingerprint, ...
fileIdentifierCellLineage, ...
imageCropCoordinateArray, movieLength, cellDivisionType);
Start tracking¶
Tracker.runTracker()
Post tracking¶
% Save tracking result control images
Tracker.saveTrackerProjectControlImages()
% Save current state of the tracker instance
Tracker.saveCurrentTrackerState()
% Export the project configuration
Tracker.saveTrackingProject()
% Save tracking results as csv table
Tracker.saveTrackerResultsAsTable()
Further help / troubleshooting¶
For further help, such as how to convert your data into the proper format or how to define the Tracx parameters, please read the respective sections in Extended usage or GUI.
The API reference of the Tracx classes and methods can also provide further help in respect to which input and which output is expected as well as a short description about a function’s purpose.
License¶
Tracx is licensed under BSD-3 clause. Copyright © 2017-2021 ETH Zurich, Andreas P. Cuny, Tomas Kuendig, Aaron Ponti, Joerg Stelling; D-BSSE; CSB Group. For details License.
Contributing¶
The authors as well as the 3rd parties libraries we appreciate and use of Tracx are listed under Contributors .
If you like to contribute yourselves please read the section How to contribute.