ULTRACK

Large-scale cell tracking under segmentation uncertainty.

Overview

Ultrack is a versatile and scalable cell tracking method designed to address the challenges of tracking cells across 2D, 3D, and multichannel timelapse recordings, especially in complex and crowded tissues where segmentation is often ambiguous. By evaluating multiple candidate segmentations and employing temporal consistency, Ultrack ensures robust performance under segmentation uncertainty. Ultrack's methodology is explained here.

https://github.com/royerlab/ultrack/assets/21022743/10aace9c-0e0e-4310-a103-f846683cfc77

Zebrafish imaged using DaXi whole embryo tracking.

Features

Versatile Cell Tracking: Supports 2D, 3D, and multichannel datasets.
Robust Under Segmentation Uncertainty: Evaluates multiple candidate segmentations.
High Performance: Scales from small in vitro datasets to terabyte-scale developmental time-lapses.
Integration: Compatible with FiJi, napari, and high-performance clusters via SLURM.

Installation

Install or update conda.

To avoid conflicts between different packages, we recommend using conda to create an isolated environment:

conda create -n ultrack python=3.11 higra gurobi pytorch pyqt -c pytorch -c gurobi -c conda-forge
conda activate ultrack
pip install ultrack

NOTE: gurobi and -c gurobi are optional but recommended; they can be installed later, as shown below.

Usage

ATTENTION: every time you need to run this software, you'll have to activate this environment

conda activate ultrack

Here is a basic example to get you started:

import napari
from ultrack import MainConfig, Tracker

# __main__ is recommended to avoid multi-processing errors
if __name__ == "__main__":
      # Load your data
      foreground = ...
      contours = ...

      # Create config
      config = MainConfig()

      # Run tracking
      tracker = Tracker(config)
      tracker.track(foreground=foreground, edges=contours)

      # Visualize results in napari
      tracks, graph = tracker.to_tracks_layer()
      napari.view_tracks(tracks[["track_id", "t", "z", "y", "x"]], graph=graph)
      napari.run()

More usage examples can be found here, including their environment files and installation instructions.

Documentation

Comprehensive documentation is available here.

These additional developer documentation are available:

Parameter configuration schema.
Intermediate segmentation and tracking SQL database are here.

Gurobi Setup

Install Gurobi using Conda

In your existing Conda environment, install Gurobi with the following command:

conda install -c gurobi gurobi

Obtain and Activate an Academic License

Register at Gurobi's website with your academic email.
Navigate to the Gurobi's named academic license page
Follow the instructions to get your license key.
Activate your license, In your Conda environment, run:

grbgetkey YOUR_LICENSE_KEY

Replace YOUR_LICENSE_KEY with the key you received. Follow the prompts to complete activation.

Verify Installation

Verify Gurobi's installation by running:

ultrack check_gurobi

Depending on the operating system, the gurobi library might be missing and you need to install it from here.

Who is using Ultrack?

Here is a list of projects and papers that are and have used ultrack:

DaXi Project: Ultrack was used for tracking zebrafish embryos using high-resolution light-sheet microscopy as part of the DaXi project, demonstrating its capability to handle large-scale datasets efficiently. See paper here.
Zebrahub.org project: Ultrack is employed in projects hosted on ZebraHub.org to track and analyze zebrafish embryonic development. See preprint here.
Single-cell transcriptional dynamics in a living vertebrate: Ultrack was used for segmenting and tracking nuclei in light-sheet microscopy datasets of developing zebrafish embryos. See preprint here.

Contributing

We welcome contributions from the community! To get started, please read our contributing guidelines. Then, report issues and submit pull requests on GitHub.

License

This project is licensed under the BSD-3 License - see the LICENSE file for details.

Citing

If you use ultrack in your research, please cite the following papers, the algorithm and the biological applications and software.

@article{bragantini2023ucmtracking,
      title={Large-Scale Multi-Hypotheses Cell Tracking Using Ultrametric Contours Maps},
      author={Jordão Bragantini and Merlin Lange and Loïc Royer},
      year={2023},
      eprint={2308.04526},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

@article{bragantini2024ultrack,
  title={Ultrack: pushing the limits of cell tracking across biological scales},
  author={Bragantini, Jordao and Theodoro, Ilan and Zhao, Xiang and Huijben, Teun APM and Hirata-Miyasaki, Eduardo and VijayKumar, Shruthi and Balasubramanian, Akilandeswari and Lao, Tiger and Agrawal, Richa and Xiao, Sheng and others},
  journal={bioRxiv},
  pages={2024--09},
  year={2024},
  publisher={Cold Spring Harbor Laboratory}
}

And the respective auxiliary methods (e.g. Cellpose, napari, etc) depending on your usage.

Acknowledgements

We acknowledge the contributions of the community and specific individuals. Detailed acknowledgments can be found in our documentation.

royerlab / ultrack

readme