Metadata-Version: 2.1
Name: btrack
Version: 0.3.7
Summary: BayesianTracker is a simple Python/C++ based framework for multi-object tracking
Home-page: https://github.com/quantumjot/BayesianTracker
Author: Alan R. Lowe
Author-email: a.lowe@ucl.ac.uk
License: LICENSE.md
Platform: UNKNOWN
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: cvxopt (>=1.2.0)
Requires-Dist: h5py (>=2.10.0)
Requires-Dist: matplotlib (>=3.1.1)
Requires-Dist: numpy (>=1.17.3)
Requires-Dist: scipy (>=1.3.1)

# Bayesian Tracker (bTrack)

**WORK IN PROGRESS** :microscope::computer:  
http://lowe.cs.ucl.ac.uk/cellx.html


BayesianTracker (`btrack`) is a multi object tracking algorithm, specifically
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.

<!-- [![SquiggleCube](http://lowe.cs.ucl.ac.uk/images/bayesian_tracker.png)](http://lowe.cs.ucl.ac.uk)  
*Example of tracking objects in 3D space* -->

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.

<!-- [![LineageTree](http://lowe.cs.ucl.ac.uk/images/bayesian_tracker_lineage_tree.png)](http://lowe.cs.ucl.ac.uk)   -->
[![LineageTree](https://raw.githubusercontent.com/quantumjot/BayesianTracker/master/examples/render.png)](http://lowe.cs.ucl.ac.uk/cellx.html)  
*Automated cell tracking and lineage tree reconstruction*. Cell divisions are highlighted in red.





### Example: Tracking mammalian cells in time-lapse microscopy experiments

We developed BayesianTracker to enable us to track cells in large populations
over very long periods of time, reconstruct lineages and study cell movement or
sub-cellular protein localisation. Below is an example of tracking cells:

[![CellTracking](http://lowe.cs.ucl.ac.uk/images/youtube.png)](https://youtu.be/EjqluvrJGCg)  
*Video of tracking*





---
### Citation

More details of how the tracking algorithm works and how it can be applied to
tracking cells in time-lapse microscopy data can be found in our publication:

**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{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}
}
```

You can also --> :star: :wink:

---

### Installation

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

*NOTE TO WINDOWS USERS*: We have not tested this on Windows, although the
following works on the Ubuntu shell for Win10. The setup instructions below have
 been tested on Ubuntu 18.04 LTS and OS X 10.15.

 #### Installing the latest stable version
 ```sh
 pip install btrack
 ```


 #### (Advanced) Installing the latest development version

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

*Optional*: You can compile the tracker from source using the `build.sh` script.

---
### 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 |
| ------------- | ----- | -------------------------------------------- | ---- |
| *In progress* | Basic | Loading your own data                        | -
| Complete      | Basic | Object tracking with btrack                  | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1A1PRM0a3Z0ufszdnVxntcaEDzU_Vh4u9)|
| Complete      | Basic | Data import options                          | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1V2TtJ5FGqSILTuThSRg5j9crsBsorUmy)|
| *In progress* | Advanced | Object tracking with btrack (2D/3D)       | -
| *In progress* | Advanced | Configuration options                     | -
| Complete      | Advanced | How to compile btrack from source         | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/19t5HBV76_Js8M3LX63CwiXzemax7Tvsk)|


---

### Usage with Napari

You can visualize the output using our plugin (called `arboretum`) for the open source image viewer [`Napari`](https://github.com/napari/napari). We provide example code here:

| Status        | Notebook                                     | Link |
| ------------- | -------------------------------------------- | ---- |
| *In progress* | Visualizing bTrack output using arboretum    | [GitHub](https://github.com/quantumjot/arboretum)

---

### Usage from Python

BayesianTracker can be used simply as follows:

```python
import btrack
from btrack.utils import import_HDF

# NOTE(arl):  This should be from your image segmentation code
objects = import_HDF('/path/to/your/objects.hdf5', filter_using=None)

# 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 optimiser
  tracker.optimize()

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

Tracks themselves are python objects with properties:

```python
# 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 and children
print(track_zero.ID)
print(track_zero.root)
print(track_zero.parent)
print(track_zero.children)

```

Tracks can also be exported in the LBEP format:
```python
from btrack.utils import export_LBEP

export_LBEP('/path/to/your/res_track.txt', tracks)
```

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

### Input data
Observations can be provided in three basic formats:
+ a simple JSON file
+ HDF5 for larger/more complex datasets, or
+ using your own code as a `PyTrackObject`.

HDF5 is the *default* format for data interchange, where additional information
such as images or metadata can also be stored.  

More detail in the wiki:
https://github.com/quantumjot/BayesianTracker/wiki/3.-Importing-data


