Initial commit

.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish, Build and Release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: contains(github.ref, 'tags')
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U setuptools setuptools_scm wheel twine build
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TWINE_API_KEY }}
+        run: |
+          git tag
+          python -m build .
+          twine upload dist/*

.gitignore

@@ -0,0 +1,143 @@
+/data/*
+!/data/.gitkeep
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+checkpoints1/
+
+notebooks/
+
+_version.py

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, EPFL
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE.txt
+include README.md
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

README.md

@@ -0,0 +1,55 @@
+![EPFL Center for Imaging logo](https://imaging.epfl.ch/resources/logo-for-gitlab.svg)
+# 💫 Tumor nodules tracking in mice CT scans
+
+We provide a Python package for tracking tumor nodules in mice CT scans. The project is based on [Trackpy](https://github.com/soft-matter/trackpy) and [Laptrack](https://github.com/yfukai/laptrack/tree/main) (algorithms from both libraries are implemented). It also provides a registration utility to align CT scans before tracking objects based on segmentation masks of the lungs cavity produced by the [mouselungseg](https://gitlab.com/epfl-center-for-imaging/mouselungseg) model.
+
+[[`Installation`](#installation)] [[`Usage`](#usage)]
+
+This project is part of a collaboration between the [EPFL Center for Imaging](https://imaging.epfl.ch/) and the [De Palma Lab](https://www.epfl.ch/labs/depalma-lab/).
+
+## Installation
+
+We recommend performing the installation in a clean Python environment. Install our package from PyPi:
+
+```sh
+pip install mousetumortrack
+```
+
+or from the repository:
+
+```sh
+pip install git+https://github.com/EPFL-Center-for-Imaging/mousetumortrack.git
+```
+
+or clone the repository and install with:
+
+```sh
+git clone git+https://github.com/EPFL-Center-for-Imaging/mousetumortrack.git
+cd mouselungseg
+pip install -e .
+```
+
+## Usage
+
+Track tumor nodules from a labelled 3D timesereies array:
+
+```py
+from mousetumortrack import run_tracking
+
+linkage_df, grouped_df, labels_timeseries_tracked = run_tracking(labels_timeseries)
+```
+
+For more details, see [example.py](./scripts/example.py).
+
+## Issues
+
+If you encounter any problems, please file an issue along with a detailed description.
+
+## License
+
+This model is licensed under the [BSD-3](LICENSE.txt) license.
+
+## Related projects
+
+- [Mouse Tumor Net](https://gitlab.com/epfl-center-for-imaging/mousetumornet) | Detect tumor nodules in mice CT scans.
+- [Mouse Lungs Seg](https://gitlab.com/epfl-center-for-imaging/mouselungseg) | Detect the lungs cavity in mice CT scans.

pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "mousetumortrack"
+dynamic = ["version"]
+description = "Tracking tumor nodules in mice CT scans."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+authors = [{ name = "Mallory Wittwer", email = "mallory.wittwer@epfl.ch" }]
+
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+
+dependencies = [
+    "numpy",
+    "pandas",
+    "scikit-image",
+    "trackpy",
+    "laptrack",
+    "vedo",
+    "mouselungseg",
+]
+
+[project.urls]
+homepage = "https://github.com/EPFL-Center-for-Imaging/mousetumortrack"
+repository = "https://github.com/EPFL-Center-for-Imaging/mousetumortrack"
+
+[build-system]
+requires = ["setuptools>=42.0.0", "wheel", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]
+
+[tool.setuptools_scm]
+write_to = "src/mousetumortrack/_version.py"
+version_scheme = "guess-next-dev"
+local_scheme = "no-local-version"

scripts/example.py

@@ -0,0 +1,39 @@
+import sys
+import tifffile
+from time import perf_counter
+
+from mousetumortrack import run_tracking
+
+if __name__=='__main__':
+    _, labels_timeseries_file, images_series_file = sys.argv
+    labels_timeseries = tifffile.imread(labels_timeseries_file)
+    images_timeseries = tifffile.imread(images_series_file)
+    n_frames = len(labels_timeseries)
+
+    # With Trackpy
+    t0 = perf_counter()
+    *_, labels_timeseries_trackpy = run_tracking(labels_timeseries, method="trackpy")
+    print(perf_counter() - t0)
+
+    # With Laptrack
+    t0 = perf_counter()
+    *_, labels_timeseries_laptrack = run_tracking(labels_timeseries, method="laptrack")
+    print(perf_counter() - t0)
+
+    # With Laptrack and mouselungseg registration
+    t0 = perf_counter()
+    *_, labels_timeseries_laptrack_reg = run_tracking(
+        labels_timeseries,
+        image_timeseries=images_timeseries,
+        with_lungs_registration=True, 
+        method="laptrack",
+    )
+    print(perf_counter() - t0)
+
+    # import napari
+    # viewer = napari.Viewer(ndisplay=3)
+    # viewer.add_labels(labels_timeseries, name="Labels (Untracked)")
+    # viewer.add_labels(labels_timeseries_trackpy, name="Labels (Trackpy)")
+    # viewer.add_labels(labels_timeseries_laptrack, name="Labels (Laptrack)")
+    # viewer.add_labels(labels_timeseries_laptrack_reg, name="Labels (Laptrack+reg)")
+    # napari.run()

src/mousetumortrack/__init__.py

@@ -0,0 +1,2 @@
+from mousetumortrack.track import run_tracking
+from mousetumortrack.register import register_timeseries_from_lungs_mask