Data

Tools

Indexes

Applications

Experiments

Open Source Science

trackastra

Transformer-based cell tracking for live-cell microscopy

https://github.com/weigertlab/trackastra

Science Score: 26.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (16.7%) to scientific vocabulary
Last synced: 9 months ago · JSON representation

Repository

Transformer-based cell tracking for live-cell microscopy

Basic Info
  • Host: GitHub
  • Owner: weigertlab
  • License: bsd-3-clause
  • Language: Python
  • Default Branch: main
  • Homepage:
  • Size: 49.5 MB
Statistics
  • Stars: 85
  • Watchers: 6
  • Forks: 22
  • Open Issues: 5
  • Releases: 13
Created over 2 years ago · Last pushed 10 months ago
Metadata Files
Readme License Citation

README.md

Optimus Prime

[![PyPI](https://img.shields.io/pypi/v/trackastra)](https://pypi.org/project/trackastra/) ![Python](https://img.shields.io/pypi/pyversions/trackastra) ![Build](https://img.shields.io/github/actions/workflow/status/weigertlab/trackastra/python-package-conda.yml?branch=main) [![License](https://img.shields.io/github/license/weigertlab/trackastra)](https://github.com/weigertlab/trackastra/blob/main/LICENSE)

Trackastra - Tracking by Association with Transformers

Trackastra is a cell tracking approach that links already segmented cells in a microscopy timelapse by predicting associations with a transformer model that was trained on a diverse set of microscopy videos.

Overview

Reference

Paper: Trackastra: Transformer-based cell tracking for live-cell microscopy

@inproceedings{gallusser2024trackastra, title={Trackastra: Transformer-based cell tracking for live-cell microscopy}, author={Gallusser, Benjamin and Weigert, Martin}, booktitle={European conference on computer vision}, pages={467--484}, year={2024}, organization={Springer} }

Examples

Nuclei tracking | Bacteria tracking :-: | :-: |

Installation

This repository contains the Python implementation of Trackastra.

Please first set up a Python environment (with Python version 3.10 or higher), preferably via conda or mamba.

Simple installation

Trackastra can then be installed from PyPI using pip: bash pip install trackastra

With ILP support

For tracking with an integer linear program (ILP, which is optional) bash conda create --name trackastra python=3.10 --no-default-packages conda activate trackastra conda install -c conda-forge -c gurobi -c funkelab ilpy pip install "trackastra[ilp]"

📄

Development installation

bash conda create --name trackastra python=3.10 --no-default-packages conda activate trackastra conda install -c conda-forge -c gurobi -c funkelab ilpy git clone https://github.com/weigertlab/trackastra.git pip install -e "./trackastra[ilp,dev]"

📄

Notes/Troubleshooting

  • For the optional ILP linking, this will install motile and binaries for two discrete optimizers:

  1. The Gurobi Optimizer. This is a commercial solver, which requires a valid license. Academic licenses are provided for free, see here for how to obtain one.

  2. The SCIP Optimizer, a free and open source solver. If motile does not find a valid Gurobi license, it will fall back to using SCIP.

    • On MacOS, installing packages into the conda environment before installing ilpy can cause problems.
    • 2024-06-07: On Apple M3 chips, you might have to use the nightly build of torch and torchvision, or worst case build them yourself.

Usage: Tracking with a pretrained model

The input to Trackastra is a sequence of images and their corresponding cell (instance) segmentations.

demo

The available pretrained models are described in detail here.

Tracking with Trackastra can be done via:

icon Napari plugin

For a quick try of Trackastra on your data, please use our napari plugin, which already comes with pretrained models included.

icon Python API

All you need are the following two numpy arrays: - imgs: a microscopy time lapse of shape time,(z),y,x. - masks: corresponding instance segmentation of shape time,(z),y,x.

The predicted associations can then be used for linking with several modes:

  • greedy_nodiv (greedy linking with no division) - fast, no additional dependencies
  • greedy (greedy linking with division) - fast, no additional dependencies
  • ilp (ILP based linking) - slower but more accurate, needs motile

Apart from that, no hyperparameters to choose :)

📄 Show python example
```python import torch from trackastra.model import Trackastra from trackastra.tracking import graph_to_ctc, graph_to_napari_tracks from trackastra.data import example_data_bacteria device = "automatic" # explicit choices: [cuda, mps, cpu] # load some test data images and masks imgs, masks = example_data_bacteria() # Load a pretrained model model = Trackastra.from_pretrained("general_2d", device=device) # or from a local folder # model = Trackastra.from_folder('path/my_model_folder/', device=device) # Track the cells track_graph = model.track(imgs, masks, mode="greedy") # or mode="ilp", or "greedy_nodiv" # Write to cell tracking challenge format ctc_tracks, masks_tracked = graph_to_ctc( track_graph, masks, outdir="tracked", ) ``` You then can visualize the tracks with [napari](https://github.com/napari/napari): ```python # Visualise in napari napari_tracks, napari_tracks_graph, _ = graph_to_napari_tracks(track_graph) import napari v = napari.Viewer() v.add_image(imgs) v.add_labels(masks_tracked) v.add_tracks(data=napari_tracks, graph=napari_tracks_graph) ```

icon Fiji (via TrackMate)

Trackastra is one of the available trackers in TrackMate. For installation and usage instructions take a look at this tutorial.

icon Docker images

Some of our models are available as docker images on Docker Hub. Currently, we only provide CPU-based docker images.

Track within a docker container with the following command, filling the <VARIABLES>:

bash docker run -it -v <LOCAL_DATA_DIR>:/data -v <LOCAL_RESULTS_DIR>:/results bentaculum/trackastra-track:<MODEL_TAG> --input_test /data/<DATASET_IN_CTC_FORMAT> --detection_folder <TRA/SEG/ETC>"

📄 Show example with Cell Tracking Challenge model:

bash wget http://data.celltrackingchallenge.net/training-datasets/Fluo-N2DH-GOWT1.zip chmod -R 775 Fluo-N2DH-GOWT1 docker pull bentaculum/trackastra-track:model.ctc-linking.ilp docker run -it -v ./:/data -v ./:/results bentaculum/trackastra-track:model.ctc-linking.ilp --input_test data/Fluo-N2DH-GOWT1/01 --detection_folder TRA

icon Command Line Interface

After installing Trackastra, simply run in your terminal

bash trackastra track --help

to build a command for tracking directly from images and corresponding instance segmentation masks saved on disk as two series of TIF files.

Usage: Training a model on your own data

To run an example - clone this repository and got into the scripts directory with cd trackastra/scripts. - download the Fluo-N2DL-HeLa dataset from the Cell Tracking Challenge into data/ctc.

Now, run bash python train.py --config example_config.yaml

Generally, training data needs to be provided in the Cell Tracking Challenge (CTC) format, i.e. annotations are located in a folder containing one or several subfolders named TRA, with masks and tracklet information.

Owner

  • Name: weigertlab
  • Login: weigertlab
  • Kind: organization

GitHub Events

Total
  • Create event: 12
  • Release event: 4
  • Issues event: 20
  • Watch event: 29
  • Delete event: 1
  • Issue comment event: 40
  • Push event: 60
  • Pull request event: 17
  • Fork event: 13
Last Year
  • Create event: 12
  • Release event: 4
  • Issues event: 20
  • Watch event: 29
  • Delete event: 1
  • Issue comment event: 40
  • Push event: 60
  • Pull request event: 17
  • Fork event: 13

Issues and Pull Requests

Last synced: 9 months ago

All Time
  • Total issues: 7
  • Total pull requests: 9
  • Average time to close issues: 2 months
  • Average time to close pull requests: 1 day
  • Total issue authors: 6
  • Total pull request authors: 5
  • Average comments per issue: 2.71
  • Average comments per pull request: 0.22
  • Merged pull requests: 4
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 7
  • Pull requests: 9
  • Average time to close issues: 2 months
  • Average time to close pull requests: 1 day
  • Issue authors: 6
  • Pull request authors: 5
  • Average comments per issue: 2.71
  • Average comments per pull request: 0.22
  • Merged pull requests: 4
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • kevinyamauchi (3)
  • 1595813520 (2)
  • raeesahhy (2)
  • imzhangyd (2)
  • ajinkya-kulkarni (1)
  • constantinpape (1)
  • mimuelle (1)
  • istan-ding (1)
  • stefanhahmann (1)
  • ripaul (1)
  • ElpadoCan (1)
  • won5830 (1)
  • tinevez (1)
  • Aseem139 (1)
  • po60nani (1)
Pull Request Authors
  • bentaculum (5)
  • JoOkuma (2)
  • C-Achard (2)
  • anwai98 (2)
  • maweigert (1)
  • JojoDevel (1)
  • kevinyamauchi (1)
  • tinevez (1)
  • ripaul (1)
Top Labels
Issue Labels
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 518 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 13
  • Total maintainers: 2
pypi.org: trackastra

Tracking by Association with Transformers

  • Versions: 13
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 518 Last month
Rankings
Dependent packages count: 10.9%
Average: 36.0%
Dependent repos count: 61.2%
Maintainers (2)
maweigert bentaculum
Last synced: 9 months ago

Dependencies

pyproject.toml pypi