Giter VIP home page Giter VIP logo

bayesiantracker's Introduction

PyPI Downloads

Bayesian Tracker (btrack) ๐Ÿ”ฌ๐Ÿ’ป

BayesianTracker (btrack) is a Python library for multi object tracking, used to reconstruct trajectories in crowded fields. Here, we use a probabilistic network of information to perform the trajectory linking. This method uses spatial information as well as appearance information for track linking.

The tracking algorithm assembles reliable sections of track that do not contain splitting events (tracklets). Each new tracklet initiates a probabilistic model, and utilises this to predict future states (and error in states) of each of the objects in the field of view. We assign new observations to the growing tracklets (linking) by evaluating the posterior probability of each potential linkage from a Bayesian belief matrix for all possible linkages.

The tracklets are then assembled into tracks by using multiple hypothesis testing and integer programming to identify a globally optimal solution. The likelihood of each hypothesis is calculated for some or all of the tracklets based on heuristics. The global solution identifies a sequence of high-likelihood hypotheses that accounts for all observations.

Cell tracking in time-lapse imaging data

We developed btrack for cell tracking in time-lapse microscopy data.

LineageTree
Automated cell tracking and lineage tree reconstruction. Visualization is provided by our plugin to Napari, arboretum.

CellTracking
Video of tracking, showing automatic lineage determination

Read about the science:
http://lowe.cs.ucl.ac.uk/cellx.html

You can also --> โญ ๐Ÿ˜‰


Installation

BayesianTracker has been tested with Python 3.7+ on OS X, Linux and Win10. The tracker and hypothesis engine are mostly written in C++ with a Python wrapper.

Installing the latest stable version

$ pip install btrack

(Advanced) Installing the latest development version

If you would rather install the latest development version, and/or compile directly from source, you can clone and install from this repo:

$ git clone https://github.com/quantumjot/BayesianTracker.git
$ conda env create -f ./BayesianTracker/environment.yml
$ conda activate btrack
$ cd BayesianTracker
$ pip install -e .

Addtionally, the build.sh script will download Eigen source, run the makefile and pip install.


Usage in Colab notebooks

If you do not want to install a local copy, you can run the tracker in a Colab notebook. Please note that these examples are work in progress and may change:

Status Level Notebook Link
Complete Basic Data import options Open In Colab
Complete Basic Object tracking with btrack Open In Colab
In progress Advanced Configuration options -
Complete Advanced How to compile btrack from source Open In Colab

Usage with Napari

You can run btrack with a GUI and visualize the output using our plugin (called arboretum) for the open source image viewer Napari.

Status Notebook Link
In progress Visualizing btrack output using arboretum GitHub

Usage from Python

BayesianTracker can be used simply as follows:

import btrack
from btrack.dataio import import_CSV

# NOTE(arl): This should be from your image segmentation code
objects = import_CSV('/path/to/your/objects.csv')

# initialise a tracker session using a context manager
with btrack.BayesianTracker() as tracker:

  # configure the tracker using a config file
  tracker.configure_from_file('/path/to/your/models/cell_config.json')

  # append the objects to be tracked
  tracker.append(objects)

  # set the volume (Z axis volume is set very large for 2D data)
  tracker.volume=((0,1200),(0,1600),(-1e5,1e5))

  # track them (in interactive mode)
  tracker.track_interactive(step_size=100)

  # generate hypotheses and run the global optimizer
  tracker.optimize()

  # get the tracks as a python list
  tracks = tracker.tracks

Tracks themselves are python objects with properties:

# get the first track
track_zero = tracks[0]

# print the length of the track
print(len(track_zero))

# print all of the xyzt positions in the track
print(track_zero.x)
print(track_zero.y)
print(track_zero.z)
print(track_zero.t)

# print the fate of the track
print(track_zero.fate)

# print the track ID, root node, parent node, children and generational depth
print(track_zero.ID)
print(track_zero.root)
print(track_zero.parent)
print(track_zero.children)
print(track_zero.generation)

There are many additional options, including the ability to define object models.

Importing data

Observations can be provided in several basic formats:

  • a simple CSV or JSON file
  • HDF5 for larger/more complex datasets, or
  • using your own code from numpy arrays or pandas data arrays.

For example, CSV data of the format:

t x   y   z
0 300 300 0
1 301 299 1
2 302 288 2
...

can be imported:

from btrack.dataio import import_CSV
objects = import_CSV('/path/to/your/objects.csv')

More detail the colab notebooks above.

Exporting data

Tracks can also be exported in CSV and/or the LBEP format:

from btrack.dataio import export_CSV
from btrack.dataio import export_LBEP

# export tracks in CSV format
export_CSV('/path/to/your/tracks.csv', tracks)

# export the LBEP table of lineage information
export_LBEP('/path/to/your/lbep_tracks.txt', tracks)

Dealing with very large datasets

btrack supports three different methods:

  • EXACT - (DEFAULT) exact calculation of Bayesian belief matrix, but can be slow on large datasets
  • APPROXIMATE - approximate calculation, faster, for use with large datasets. This has an additional max_search_radius parameter, which sets the local spatial search radius (isotropic, pixels) of the algorithm.
  • CUDA - GPU implementation of the EXACT method (in progress)

For most cell datasets (<1000 cells per time point) we recommend EXACT. If you have larger datasets, we recommend APPROXIMATE.

If the tracking does not complete, and is stuck on the optimization step, this means that your configuration is poorly suited to your data. Try turning off optimization, followed by modifying the parameters of the config file.

import btrack
from btrack.constants import BayesianUpdates

with btrack.BayesianTracker() as tracker:

    # configure the tracker and change the update method
    tracker.configure_from_file('/path/to/your/models/cell_config.json')
    tracker.update_method = BayesianUpdates.APPROXIMATE
    tracker.max_search_radius = 100
    ...

Citation

More details of how this type of tracking approach can be applied to tracking cells in time-lapse microscopy data can be found in the following publications:

Automated deep lineage tree analysis using a Bayesian single cell tracking approach
Ulicna K, Vallardi G, Charras G and Lowe AR.
bioRxiv (2020)
https://www.biorxiv.org/content/early/2020/09/10/2020.09.10.276980

Local cellular neighbourhood controls proliferation in cell competition
Bove A, Gradeci D, Fujita Y, Banerjee S, Charras G and Lowe AR.
Mol. Biol. Cell (2017)
https://doi.org/10.1091/mbc.E17-06-0368

@article {Ulicna2020.09.10.276980,
  author = {Ulicna, Kristina and Vallardi, Giulia and Charras, Guillaume and Lowe, Alan R.},
  title = {Automated deep lineage tree analysis using a Bayesian single cell tracking approach},
  elocation-id = {2020.09.10.276980},
  year = {2020},
  doi = {10.1101/2020.09.10.276980},
  publisher = {Cold Spring Harbor Laboratory},
  URL = {https://www.biorxiv.org/content/early/2020/09/10/2020.09.10.276980},
  eprint = {https://www.biorxiv.org/content/early/2020/09/10/2020.09.10.276980.full.pdf},
  journal = {bioRxiv}
}
@article{Bove07112017,
  author = {Bove, Anna and Gradeci, Daniel and Fujita, Yasuyuki and Banerjee,
    Shiladitya and Charras, Guillaume and Lowe, Alan R.},
  title = {Local cellular neighborhood controls proliferation in cell competition},
  volume = {28},
  number = {23},
  pages = {3215-3228},
  year = {2017},
  doi = {10.1091/mbc.E17-06-0368},
  URL = {http://www.molbiolcell.org/content/28/23/3215.abstract},
  eprint = {http://www.molbiolcell.org/content/28/23/3215.full.pdf+html},
  journal = {Molecular Biology of the Cell}
}

bayesiantracker's People

Contributors

quantumjot avatar volkerh avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.