byotrack


Namebyotrack JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://github.com/raphaelreme/byotrack
SummaryBiological particle tracking with Python
upload_time2024-10-23 15:13:38
maintainerNone
docs_urlNone
authorRaphael Reme
requires_python>=3.7
licenseMIT
keywords tracking biologie machine learning statistics optimization
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ByoTrack
[![Lint and Test](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml/badge.svg)](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml)
[![Documentation Status](https://readthedocs.org/projects/byotrack/badge/?version=latest)](https://byotrack.readthedocs.io/en/latest/?badge=latest)

![pipeline](docs/source/images/tracking.svg)

**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[![Lint and Test](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml/badge.svg)](https://github.com/raphaelreme/byotrack/actions/workflows/tests.yml)\n[![Documentation Status](https://readthedocs.org/projects/byotrack/badge/?version=latest)](https://byotrack.readthedocs.io/en/latest/?badge=latest)\n\n![pipeline](docs/source/images/tracking.svg)\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"
}
        
Elapsed time: 0.48904s