# ByoTrack
[](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml)
[](https://byotrack.readthedocs.io/en/latest/?badge=latest)
**ByoTrack** is a Python library that enables tracking of biological object in videos.
Many bioimage informatics tools already implement their own tracking tools (Icy [1], ImageJ [6], ...) but most of them are implemented in Java which makes it difficult for non-Java developers to experiment with the code. It is also difficult to integrate deep learning algorithms (mainly developed in Python) into these software.
We provide a unified python API for tracking that can be easily extended with new (and old) algorithms. We also provide implementations of well-known algorithms following our API.
Overview:
* Video
* Able to read classical format (supported by opencv) + tiff
* Particle Tracking
* MultiStepTracker (Detect / Link / Refine)
* Particle Detections
* Wavelet Detector [2] (Similar as the one in Icy [1] but coded in pytorch)
* Stardist [3] (Inference only. Training should be done with the [official implementation](https://github.com/stardist/stardist))
* Particle Linking
* EMHT [4] (Wraps the implementation in Icy [1], requires Icy to be installed)
* u-track / TrackMate [7] (Wraps the TrackMate [6, 8] implementation in ImageJ/Fiji, requires Fiji to be installed)
* Tracks Refining
* Cleaning
* EMC2 [5]: Track stitching (gap closing)
* Interpolate missing positions
## Install
```bash
$ pip install byotrack
```
Some tracker implementations require additional dependencies that are not installed with the library, to use them you need to install their dependencies on your own.
Here is the complete list:
- StarDistDetector
- stardist (+ tensorflow): [Install stardist](https://github.com/stardist/stardist#installation>)
- IcyEMHTLinker
- Icy: [Download Icy](https://icy.bioimageanalysis.org/download/)
- Spot Tracking Blocks plugin: [Install an Icy plugin](https://icy.bioimageanalysis.org/tutorial/how-to-install-an-icy-plugin/)
- TrackMateLinker
- Fiji: [Download Fiji](https://imagej.net/downloads)
For visualization, wtih `byotrack.visualize` module you need to install matplotlib.
## Getting started
```python
import byotrack
# Load some specific implementations
from byotrack.implementation.detector.wavelet import WaveletDetector
from byotrack.implementation.linker.icy_emht import IcyEMHTLinker
from byotrack.implementation.refiner.cleaner import Cleaner
from byotrack.implementation.refiner.stitching import EMC2Stitcher
# Read a video from a path, normalize and aggregate channels
video = byotrack.Video(video_path)
transform_config = VideoTransformConfig(aggregate=True, normalize=True, q_min=0.01, q_max=0.999)
video.set_transform(transform_config)
# Create a multi step tracker
## First the detector
## Smaller scale <=> search for smaller spots
## The noise threshold is linear with k. If you increase it, you will retrieve less spots.
detector = WaveletDetector(scale=1, k=3.0, min_area=5)
## Second the linker
## Hyperparameters are automatically chosen by Icy
linker = IcyEMHTLinker(icy_path)
## Finally refiners
## If needed you can add Cleaning and Stitching operations
refiners = []
if True:
refiners.append(Cleaner(5, 3.5)) # Split tracks on position jumps and drop small ones
refiners.append(EMC2Stitcher()) # Merge tracks if they track the same particle
tracker = byotrack.MultiStepTracker(detector, linker, refiners)
# Run the tracker
tracks = tracker.run(video)
# Save tracks
byotrack.Track.save(tracks, output_path)
```
Please refer to the [official documentation](https://byotrack.readthedocs.io/en/latest/).
## Contribute
In coming...
## Cite us
```bibtex
@article{hanson2024automatic,
title={Automatic monitoring of neural activity with single-cell resolution in behaving Hydra},
author={Hanson, Alison and Reme, Raphael and Telerman, Noah and Yamamoto, Wataru and Olivo-Marin, Jean-Christophe and Lagache, Thibault and Yuste, Rafael},
journal={Scientific Reports},
volume={14},
number={1},
pages={5083},
year={2024},
publisher={Nature Publishing Group UK London}
}
```
## References
* [1] F. De Chaumont, S. Dallongeville, N. Chenouard, et al., “Icy:
an open bioimage informatics platform for extended reproducible
research”, Nature methods, vol. 9, no. 7, pp. 690–696, 2012.
* [2] J.-C. Olivo-Marin, “Extraction of spots in biological images
using multiscale products”, Pattern Recognition, vol. 35, no. 9,
pp. 1989–1996, 2002.
* [3] U. Schmidt, M. Weigert, C. Broaddus, and G. Myers, “Cell detection
with star-convex polygons,” in Medical Image Computing and
Computer Assisted Intervention–MICCAI 2018: 21st International
Conference, Granada, Spain, September 16-20, 2018, Proceedings,
Part II 11. Springer, 2018, pp. 265–273.
* [4] N. Chenouard, I. Bloch, and J.-C. Olivo-Marin, “Multiple hypothesis
tracking for cluttered biological image sequences”,
IEEE transactions on pattern analysis and machine intelligence,
vol. 35, no. 11, pp. 2736–3750, 2013.
* [5] T. Lagache, A. Hanson, J. Perez-Ortega, et al., “Tracking calcium
dynamics from individual neurons in behaving animals”,
PLoS computational biology, vol. 17, pp. e1009432, 10 2021.
* [6] J. Schindelin, I. Arganda-Carreras, E. Frise, et al., "Fiji:
an open-source platform for biological-image analysis", Nature
Methods, 9(7), 676–682, 2012.
* [7] K. Jaqaman, D. Loerke, M. Mettlen, et al., "Robust single-particle
tracking in live-cell time-lapse sequences.", Nature Methods, 5(8),
695–702, 2008.
* [8] J.-Y. Tinevez, N. Perry, J. Schindelin, et al., "TrackMate: An
open and extensible platform for single-particle tracking.",
Methods, 115, 80–90, 2017.
Raw data
{
"_id": null,
"home_page": "https://github.com/raphaelreme/byotrack",
"name": "byotrack",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.7",
"maintainer_email": null,
"keywords": "Tracking, biologie, machine learning, statistics, optimization",
"author": "Raphael Reme",
"author_email": "raphaelreme-dev@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/2f/74/84a6cf187a846277bb9322509bb6ea09ecf090e6718c3a875db7cc6ae7be/byotrack-0.5.3.tar.gz",
"platform": null,
"description": "# ByoTrack\n[](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml)\n[](https://byotrack.readthedocs.io/en/latest/?badge=latest)\n\n\n\n**ByoTrack** is a Python library that enables tracking of biological object in videos.\n\nMany bioimage informatics tools already implement their own tracking tools (Icy [1], ImageJ [6], ...) but most of them are implemented in Java which makes it difficult for non-Java developers to experiment with the code. It is also difficult to integrate deep learning algorithms (mainly developed in Python) into these software.\n\nWe provide a unified python API for tracking that can be easily extended with new (and old) algorithms. We also provide implementations of well-known algorithms following our API.\n\nOverview:\n* Video\n * Able to read classical format (supported by opencv) + tiff\n* Particle Tracking\n * MultiStepTracker (Detect / Link / Refine)\n* Particle Detections\n * Wavelet Detector [2] (Similar as the one in Icy [1] but coded in pytorch)\n * Stardist [3] (Inference only. Training should be done with the [official implementation](https://github.com/stardist/stardist))\n* Particle Linking\n * EMHT [4] (Wraps the implementation in Icy [1], requires Icy to be installed)\n * u-track / TrackMate [7] (Wraps the TrackMate [6, 8] implementation in ImageJ/Fiji, requires Fiji to be installed)\n* Tracks Refining\n * Cleaning\n * EMC2 [5]: Track stitching (gap closing)\n * Interpolate missing positions\n\n\n## Install\n\n```bash\n$ pip install byotrack\n```\n\nSome tracker implementations require additional dependencies that are not installed with the library, to use them you need to install their dependencies on your own.\nHere is the complete list:\n\n\n- StarDistDetector\n - stardist (+ tensorflow): [Install stardist](https://github.com/stardist/stardist#installation>)\n- IcyEMHTLinker\n - Icy: [Download Icy](https://icy.bioimageanalysis.org/download/)\n - Spot Tracking Blocks plugin: [Install an Icy plugin](https://icy.bioimageanalysis.org/tutorial/how-to-install-an-icy-plugin/)\n- TrackMateLinker\n - Fiji: [Download Fiji](https://imagej.net/downloads)\n\nFor visualization, wtih `byotrack.visualize` module you need to install matplotlib.\n\n## Getting started\n\n```python\nimport byotrack\n\n# Load some specific implementations\nfrom byotrack.implementation.detector.wavelet import WaveletDetector\nfrom byotrack.implementation.linker.icy_emht import IcyEMHTLinker\nfrom byotrack.implementation.refiner.cleaner import Cleaner\nfrom byotrack.implementation.refiner.stitching import EMC2Stitcher\n\n# Read a video from a path, normalize and aggregate channels\nvideo = byotrack.Video(video_path)\ntransform_config = VideoTransformConfig(aggregate=True, normalize=True, q_min=0.01, q_max=0.999)\nvideo.set_transform(transform_config)\n\n# Create a multi step tracker\n## First the detector\n## Smaller scale <=> search for smaller spots\n## The noise threshold is linear with k. If you increase it, you will retrieve less spots.\ndetector = WaveletDetector(scale=1, k=3.0, min_area=5)\n\n## Second the linker\n## Hyperparameters are automatically chosen by Icy\nlinker = IcyEMHTLinker(icy_path)\n\n## Finally refiners\n## If needed you can add Cleaning and Stitching operations\nrefiners = []\nif True:\n refiners.append(Cleaner(5, 3.5)) # Split tracks on position jumps and drop small ones\n refiners.append(EMC2Stitcher()) # Merge tracks if they track the same particle\n\ntracker = byotrack.MultiStepTracker(detector, linker, refiners)\n\n# Run the tracker\ntracks = tracker.run(video)\n\n# Save tracks\nbyotrack.Track.save(tracks, output_path)\n```\n\nPlease refer to the [official documentation](https://byotrack.readthedocs.io/en/latest/).\n\n## Contribute\n\nIn coming...\n\n## Cite us\n\n```bibtex\n@article{hanson2024automatic,\n title={Automatic monitoring of neural activity with single-cell resolution in behaving Hydra},\n author={Hanson, Alison and Reme, Raphael and Telerman, Noah and Yamamoto, Wataru and Olivo-Marin, Jean-Christophe and Lagache, Thibault and Yuste, Rafael},\n journal={Scientific Reports},\n volume={14},\n number={1},\n pages={5083},\n year={2024},\n publisher={Nature Publishing Group UK London}\n}\n```\n\n## References\n\n\n* [1] F. De Chaumont, S. Dallongeville, N. Chenouard, et al., \u201cIcy:\n an open bioimage informatics platform for extended reproducible\n research\u201d, Nature methods, vol. 9, no. 7, pp. 690\u2013696, 2012.\n* [2] J.-C. Olivo-Marin, \u201cExtraction of spots in biological images\n using multiscale products\u201d, Pattern Recognition, vol. 35, no. 9,\n pp. 1989\u20131996, 2002.\n* [3] U. Schmidt, M. Weigert, C. Broaddus, and G. Myers, \u201cCell detection\n with star-convex polygons,\u201d in Medical Image Computing and\n Computer Assisted Intervention\u2013MICCAI 2018: 21st International\n Conference, Granada, Spain, September 16-20, 2018, Proceedings,\n Part II 11. Springer, 2018, pp. 265\u2013273.\n* [4] N. Chenouard, I. Bloch, and J.-C. Olivo-Marin, \u201cMultiple hypothesis\n tracking for cluttered biological image sequences\u201d,\n IEEE transactions on pattern analysis and machine intelligence,\n vol. 35, no. 11, pp. 2736\u20133750, 2013.\n* [5] T. Lagache, A. Hanson, J. Perez-Ortega, et al., \u201cTracking calcium\n dynamics from individual neurons in behaving animals\u201d,\n PLoS computational biology, vol. 17, pp. e1009432, 10 2021.\n* [6] J. Schindelin, I. Arganda-Carreras, E. Frise, et al., \"Fiji:\n an open-source platform for biological-image analysis\", Nature\n Methods, 9(7), 676\u2013682, 2012.\n* [7] K. Jaqaman, D. Loerke, M. Mettlen, et al., \"Robust single-particle\n tracking in live-cell time-lapse sequences.\", Nature Methods, 5(8),\n 695\u2013702, 2008.\n* [8] J.-Y. Tinevez, N. Perry, J. Schindelin, et al., \"TrackMate: An\n open and extensible platform for single-particle tracking.\",\n Methods, 115, 80\u201390, 2017.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Biological particle tracking with Python",
"version": "0.5.3",
"project_urls": {
"Homepage": "https://github.com/raphaelreme/byotrack"
},
"split_keywords": [
"tracking",
" biologie",
" machine learning",
" statistics",
" optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30ede0ffa9d85b6befeb0e20fc3ab6961923114a02d680bf8879f5ab6d6d8044",
"md5": "fe3cf4e56f3644c4d68cf42072e329c5",
"sha256": "cf784621faccaf82e0625c91a5763833a44c3b5c3adffe941e59a90bc3110352"
},
"downloads": -1,
"filename": "byotrack-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe3cf4e56f3644c4d68cf42072e329c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.7",
"size": 60811,
"upload_time": "2024-04-12T13:12:31",
"upload_time_iso_8601": "2024-04-12T13:12:31.149059Z",
"url": "https://files.pythonhosted.org/packages/30/ed/e0ffa9d85b6befeb0e20fc3ab6961923114a02d680bf8879f5ab6d6d8044/byotrack-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f7484a6cf187a846277bb9322509bb6ea09ecf090e6718c3a875db7cc6ae7be",
"md5": "4d79e3087940bcd3ac0ee8fdfb43c7e5",
"sha256": "2e87ea1da3ebee28bca1bd2862d9f14eb4e3b11f220cbe5c924a13a8bb410711"
},
"downloads": -1,
"filename": "byotrack-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "4d79e3087940bcd3ac0ee8fdfb43c7e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.7",
"size": 47687,
"upload_time": "2024-04-12T13:12:32",
"upload_time_iso_8601": "2024-04-12T13:12:32.572257Z",
"url": "https://files.pythonhosted.org/packages/2f/74/84a6cf187a846277bb9322509bb6ea09ecf090e6718c3a875db7cc6ae7be/byotrack-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 13:12:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "raphaelreme",
"github_project": "byotrack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "byotrack"
}
JSON
