# 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 (2D or 3D).
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. ByoTrack is based on numpy, pytorch and numba allowing fast computations with the access to the full python ecosystem.
Overview:
* Video
* Able to read most classical format (supported by opencv) + tiff
* Supports 2D and 3D.
* 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
* Nearest neighbors using optical flow, kalman filters or both (KOFT) [9]
* 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
* Optical Flow
* Support for Open-CV and Scikit-Image algorithms. Can be used for particle linking, track stitching
and interpolations.
## 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)
- KalmanLinker & KOFTLinker
- torch_kf: [Install torch-kf](https://github.com/raphaelreme/torch-kf#install)
- 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)
- tifffile: [Install tifffile](https://github.com/cgohlke/tifffile#quickstart)
- SkimageOpticalFlow
- scikit-image: [Install scikit-image](https://scikit-image.org/docs/stable/user_guide/install.html)
For visualization, with `byotrack.visualize` module you need to [install matplotlib](https://matplotlib.org/stable/install/index.html).
## 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.
* [9] R. Reme, A. Newson, E. Angelini, J.-C. Olivo-Marin and T. Lagache,
"Particle tracking in biological images with optical-flow enhanced
kalman filtering", in International Symposium on Biomedical Imaging
(ISBI2024).
Raw data
{
"_id": null,
"home_page": "https://github.com/raphaelreme/byotrack",
"name": "byotrack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=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/b7/22/3a769e76cbc0ff69f403ba852dcfac605718334eaf7c9deeab0601cc08c3/byotrack-1.1.0.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 (2D or 3D).\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. ByoTrack is based on numpy, pytorch and numba allowing fast computations with the access to the full python ecosystem.\n\nOverview:\n* Video\n * Able to read most classical format (supported by opencv) + tiff\n * Supports 2D and 3D.\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 * Nearest neighbors using optical flow, kalman filters or both (KOFT) [9]\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* Optical Flow\n * Support for Open-CV and Scikit-Image algorithms. Can be used for particle linking, track stitching\n and interpolations.\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- KalmanLinker & KOFTLinker\n - torch_kf: [Install torch-kf](https://github.com/raphaelreme/torch-kf#install)\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 - tifffile: [Install tifffile](https://github.com/cgohlke/tifffile#quickstart)\n- SkimageOpticalFlow\n - scikit-image: [Install scikit-image](https://scikit-image.org/docs/stable/user_guide/install.html)\n\nFor visualization, with `byotrack.visualize` module you need to [install matplotlib](https://matplotlib.org/stable/install/index.html).\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., \"Icy:\n an open bioimage informatics platform for extended reproducible\n research\", Nature methods, vol. 9, no. 7, pp. 690\u2013696, 2012.\n* [2] J.-C. Olivo-Marin, \"Extraction of spots in biological images\n using multiscale products\", Pattern Recognition, vol. 35, no. 9,\n pp. 1989\u20131996, 2002.\n* [3] U. Schmidt, M. Weigert, C. Broaddus, and G. Myers, \"Cell detection\n with star-convex polygons\", 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, \"Multiple hypothesis\n tracking for cluttered biological image sequences\",\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., \"Tracking calcium\n dynamics from individual neurons in behaving animals\",\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* [9] R. Reme, A. Newson, E. Angelini, J.-C. Olivo-Marin and T. Lagache,\n \"Particle tracking in biological images with optical-flow enhanced\n kalman filtering\", in International Symposium on Biomedical Imaging\n (ISBI2024).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Biological particle tracking with Python",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/raphaelreme/byotrack"
},
"split_keywords": [
"tracking",
" biologie",
" machine learning",
" statistics",
" optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0baffef753640e267bea3d68d6835e9e97558a7a676a988595ca1a8a1d2ae74e",
"md5": "319846ab76a37a76bdebb909fc39ad18",
"sha256": "77548fef345075bc0bc6c59906e18a3344ac6dbbf74aac7d3ac4be43ffb06a79"
},
"downloads": -1,
"filename": "byotrack-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "319846ab76a37a76bdebb909fc39ad18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 102153,
"upload_time": "2024-10-23T15:13:37",
"upload_time_iso_8601": "2024-10-23T15:13:37.168760Z",
"url": "https://files.pythonhosted.org/packages/0b/af/fef753640e267bea3d68d6835e9e97558a7a676a988595ca1a8a1d2ae74e/byotrack-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b7223a769e76cbc0ff69f403ba852dcfac605718334eaf7c9deeab0601cc08c3",
"md5": "bfb591cc3904083b480501d09778057b",
"sha256": "9858b5d72af3a866c137c0cbb0b94fae893a633b62018862eaaded75cd574ce5"
},
"downloads": -1,
"filename": "byotrack-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bfb591cc3904083b480501d09778057b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 79613,
"upload_time": "2024-10-23T15:13:38",
"upload_time_iso_8601": "2024-10-23T15:13:38.731439Z",
"url": "https://files.pythonhosted.org/packages/b7/22/3a769e76cbc0ff69f403ba852dcfac605718334eaf7c9deeab0601cc08c3/byotrack-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 15:13:38",
"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
