inTRACKtive

inTRACKtive(preprint) is an application for data-efficient visualization and sharing of cell tracking data in the browser. The viewer allows users to navigate the tracked cells through time with a time slider, select specific cells, and trace cell lineages. The view of the explored lineage selections can be shared with a simple link, making it ideal for collaboration, education, and showcasing. This viewer eliminates the local setup of native software, making advanced lineage tracing and in silico fate mapping accessible to everyone with a browser. It is built in TypeScript, using React and Three.js, bundled with Vite, using Zarr.js for light-weight data loading and the CZI SDS component library. The viewer utilizes a specialized tracking data format for asynchronous lazy data loading and on-the-fly interactivity. This tool makes it possible for everyone to visualize, host, and interact with your cell tracking data!

This tool was originally built to explore the light-sheet 3D cell tracking results of the Virtual Embryo Zoo

Supplementary_Video1.mov

(Vimeo for the high-resolution version)

Table of contents

inTRACKtive (preprint) has three main use-cases:

1. Explore the Virtual Embryo Zoo (↓1. Explore the Virtual Embryo Zoo↓)

2. Visualize your own cell tracking data (↓2. Visualize your own tracking data↓)

3. Host your own customized inTRACKtive client (↓3. Host your own customized viewer↓)

Below we will explain each use-case in more detail.

1. Explore the Virtual Embryo Zoo

collapse

The Virtual Embryo Zoo (preprint) is a growing platform that empowers researchers to investigate single-cell embryogenesis of six commonly studied model organisms: Drosophila, zebrafish, C. elegans, Ascidian, mouse, and Tribolium. The Virtual Embryo Zoo webpage uses inTRACKtive for an intuitive and accessible web-based interface.

Supplementary_Video2.mov

(Vimeo for the high-resolution version)

See the image below with the explanation of the inTRACKtive UI:

Figure 1 - UI overview

(↑Back to table of contents↑)

2. Visualize your own cell tracking data

collapse

We tried to make it as easy as possible to visualize your own data with inTRACKtive, there are currently three pathways you can follow: i) use the command-line interface for data conversion and hosting, ii) open inTRACKtive from the napari plugin, or iii) from a Jupyter Notebook. All three options are outlined below, after the note regarding the file format.

Note: Tracking data format

In order to view your own cell tracking data with inTRACKtive, make sure your data is in the following format (which is the standard Ultrack format):

|   track_id |   t |   z |   y |   x |   parent_track_id |
|-----------:|----:|----:|----:|----:|------------------:|
|          1 |   0 | 361 | 415 | 266 |                -1 |
|          1 |   1 | 364 | 419 | 269 |                -1 |
|          2 |   2 | 331 | 421 | 259 |                 1 |
|          2 |   3 | 335 | 397 | 265 |                 1 |
|          2 |   4 | 334 | 390 | 275 |                 1 |
|          3 |   2 | 422 | 405 | 291 |                 1 |
|          3 |   3 | 423 | 400 | 300 |                 1 |
|          3 |   4 | 419 | 398 | 302 |                 1 |

where track_id is the label of each track (consistent over time), and parent_track_id the track_id of the parent cell after cell division. In this example, cell 1 divides into cells 2 and 3 in at t=2. Make sure that t is continuous and starts at 0 and that track_id is integer-valued and starts from 1. The can be in a csv format, or pandas.dataFrame, or anything equivalent. We are working on conversion script from popular cell tracking algorithms into our format, they will be available soon.

For inTRACKtive, the data described above needs to be converted into our specialized Zarr format. We have python and command-line functions (see below at point i), while the napari and Jupyter Notebook solutions do this under the hood.

The common first step for all three approaches is to start with a clean conda environment, and git install the package:

conda create -n intracktive python
conda activate intracktive
pip install intracktive

---

i) Command-line interface to convert and host your own data for inTRACKtive

This approach consists of two steps: converting the tracking data into our specialized Zarr format, and hosting the data to make it accessible for the browser.

For the first step, we assume your cell tracking data is saved as tracks.csv in the format as described above (5-6 columns, with column names: track_id, t, (z), y, x, parent_track_id]), where z is optional. This tracks.csv file can be converted to our Zarr format using the following command-line function (found in /python/src/intracktive/convert.py):

intracktive convert --csv_file /path/to/tracks.csv

This function converts tracks.csv to tracks_bundle.zarr (if interested, see the Zarr format). Change /path/to/tracks.csv into the actual path to you tracks.csv. By default, tracks_bundle.zarr is saved in the same directory as tracks.csv, unless --out_dir is specified as the extra parameter to the function call (see the function itself for more details). The conversion script works for 2D and 3D datasets (when the column z is not present, a 2D dataset is assumed, i.e., all z-values will be set to 0)

By default, all the cells are represented by equally-sized dots in inTRACKtive. The conversion script has the option of giving each cell a different size. For this: 1) make sure tracks.csv has an extra column named radius, and 2) use the flag --add_radius when calling the conversion script:

intracktive convert --csv_file path/to/tracks.csv --add_radius

Or use intracktive convert --help for the documentation on the inputs and outputs

In order for the viewer to access the data, the data must be hosted at a location the browser can access. For testing and visualizing data on your own computer, the easiest way is to host the data via localhost. This repository contains a tool to host the data locally:

intracktive serve path/to/data

where path/to/data is the full path to the folder containing your data (e.g., tracks_bundle.zarr). Note that the path should not include the Zarr filename, so if the tracks_bundle.zarr is located in your Downloads folder, use intracktive server ~/Downloads. The tool will create a localhost with a name similar to http://127.0.0.1:8000/.

Open this link in the browser, navigate to the exact dataset, right-click on the dataset (tracks-bundle.zarr) and copy link (depending on the browser). Then, open the inTRACKtive viewer, paste the copied link into the viewer (use the 🌐 icon in the lower-left corner), and visualize your own data!

---

ii) Open inTRACKtive using a Jupyter Notebook

To make the previous two proccesses (conversion + hosting data) easier, we compiled them into a single python function, which is demonstration in a Jupyter Notebook (/napari/src/intracktive/examples).

dataframe_to_browser(data, zarr_dir)

where data is a pandas.dataFrame containing the tracking data, and zarr_dir to directory on your computer to save the Zarr file. The dataframe_to_browser function, under the hood, sequentially: 1) converts pd.dataFrame to Zarr, 2) saves the Zarr in the specified location, 3) spins up a localhost at that location, and 4) launches a browser window of inTRACKtive with as dataUrl the zarr in the localhost. All in a function call.

⚠️ Currently dataframe_to_browser only works for Chrome and Firefox

iii) Open inTRACKtive using the napari widget

Using the same capabilities of the dataframe_to_browser, we made a napari widget. The widget (intracktiveWidget) is part of the python package after pip install, and automatically shows up in the napari widget list (plugins>inTRACKtive). To keep the inTRACKtive python package light-weight, napari is not listed as one of it's dependecies. To make use of the napari widget, please pip install napari[all] in the same conda environment as inTRACKtive. The widget takes the tracking data from a tracks layer in napari and opens an inTRACKtive browser window with the data. We provide an example of how to use the widget in a Jupyter Notebook (/napari/src/intracktive/examples).

Figure 2 - the inTRACKtive napari widget

Some notes:

• The user can select a tracks layer to open in inTRACKtive
• The user can choose the directory of where to save the Zarr (either provide a directory, or leave black, and the widget will save in a temporary location)

(↑Back to table of contents↑)

3. Host your own customized viewer

collapse

If you want to host your own customizable inTRACKtive, we recommend to fork the repo. To run the viewer locally, you need to install with npm:

npm install

Then, you can run the development server with:

npm run dev

For testing, use npm run test or npm run coverage

To customize the viewer, personalize the settings by simply changing elements in CONFIG.json. The following settings can be changed:

• branding:
  • name ("University of XX")
  • path to logo ("/path/to/logo.png")
• data:
  • path to default dataset ("https://public/XXX_bundle.zarr/")
• parameters:
  • max number of points allowed to select, before warning pops up (100)
  • colormap of the track highlights ("viridis-inferno")
  • size of points (0.1)
  • color of the cells ([0, 0.8, 0.8]) = cyan
  • color of the selected cells ([0.9, 0, 0.9]) = pink
  • color of the previewed cells ([0.8, 0.8, 0]) = yellow

Of course, any other setting can be personalized by actively changing the code of inTRACKtive. For more technical details check the architecture documentation of the application.

(↑Back to table of contents↑)

Collaborators

This tool has been developed by the Loïc A. Royer Group from the Chan Zuckerberg Biohub San Francisco and the Chan Zuckerberg Initiative.

Team:

• Teun A.P.M. Huijben
• Ashley Anderson
• Andy Sweet
• Erin Hoops
• Connor Larsen
• Kyle Awayan
• Jordão Bragantini
• Chi-Li Chiu
• Loïc A. Royer

Contact us

If you have any questions, requests or awesome ideas, please contact us:

Teun Huijben (teun.huijben@czbiohub.org / Twitter/X)

Loïc A. Royer (loic.royer@czbiohub.org / Twitter/X)

Citation

If you use inTRACKtive in your research, please cite the following preprint:

@article {Huijben2024.10.18.618998,
	author = {Huijben, Teun A.P.M. and Anderson, Ashley G. and Sweet, Andrew and Hoops, Erin and Larsen, Connor and Awayan, Kyle and Bragantini, Jordao and Chiu, Chi-Li and Royer, Loic A.},
	title = {inTRACKtive - A Web-Based Tool for Interactive Cell Tracking Visualization},
	year = {2024},
	doi = {10.1101/2024.10.18.618998},
	publisher = {Cold Spring Harbor Laboratory},
	URL = {https://www.biorxiv.org/content/early/2024/10/20/2024.10.18.618998},
	journal = {bioRxiv}
}