mspdetect 0.1.0__tar.gz

mspdetect-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Build
+
+on:
+  release:
+    types: [ created ]
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build package from source
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Install Python 3
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install build tools
+        run: |
+          python3 -m pip install build --user
+      - name: Build package
+        run: |
+          python3 -m build
+      - name: Upload to CI runner
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-package
+          path: dist/
+
+  pypi-publish:
+    name: Publish built package on PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build
+
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mspdetect
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    steps:
+      # retrieve your distributions here
+      - name: Download from CI runner
+        uses: actions/download-artifact@v4
+        with:
+          name: built-package
+          path: dist/
+      - name: Publish on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mspdetect-0.1.0/.github/workflows/testpypi.yml

@@ -0,0 +1,59 @@
+name: Test Build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build package from source
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Install Python 3
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install build tools
+        run: |
+          python3 -m pip install build --user
+      - name: Build package
+        run: |
+          python3 -m build
+      - name: Upload to CI runner
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-package
+          path: dist/
+
+  testpypi-publish:
+    name: Publish built package on TestPyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build
+
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mspdetect
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    steps:
+      # retrieve your distributions here
+      - name: Download from CI runner
+        uses: actions/download-artifact@v4
+        with:
+          name: built-package
+          path: dist/
+      - name: Publish on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

mspdetect-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write  # to post the coverage comment on PRs
+      contents: write       # to store coverage data/badge on a branch
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm needs the tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev, viz]"
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+      - run: pytest --cov=mspdetect
+      - name: Coverage comment
+        if: matrix.python-version == '3.12' # report once, not four times
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}

mspdetect-0.1.0/.gitignore

@@ -0,0 +1,136 @@
+# VS Code
+.vscode/*
+.history/*
+
+# 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/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+**/_version.py
+
+# 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/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+static/
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# documentation
+docs/_build/
+docs/build/
+pdocs/
+pdoc3/
+docs/jupyter_execute
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.test
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# MacOs stuff
+.DS_Store

mspdetect-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-merge-conflict
+  - id: check-toml
+  - id: check-yaml
+  - id: check-json
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.12.1
+  hooks:
+    - id: ruff
+      args: [ --fix ]
+    - id: ruff-format
+- repo: https://github.com/kynan/nbstripout
+  rev: 0.8.1
+  hooks:
+  - id: nbstripout
+- repo: https://github.com/compilerla/conventional-pre-commit
+  rev: v4.2.0
+  hooks:
+  - id: conventional-pre-commit
+    stages: [commit-msg]
+    args:
+    - build       # changes of the build system or dependencies
+    - change      # commit alters the implementation of an existing feature
+    - chore       # technical or maintenance task not related to feature or user story
+    - ci          # edits to the continuous integration scripts/configuration
+    - deprecate   # a feature or functionality will be deprecated
+    - docs        # add, update of revise the documentation
+    - feat        # a new feature was implemented (bump MINOR version)
+    - fix         # an issue or bug has been fixed (bump PATCH version)
+    - perf        # performance improvements that do not alter existing behaviour
+    - refactor    # update shuffles code around but does not alter functionality
+    - remove      # a feature or functionality is removed
+    - style       # source code is improved w.r.t. its code quality
+    - test        # commits enhance or add to the test suite
+    - merge       # merge one branch into another. Should be ignored by git-chglog
+    - revert      # revert previous commit(s). Should be ignored by git-chglog

mspdetect-0.1.0/.readthedocs.yml

@@ -0,0 +1,28 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+  fail_on_warning: false
+
+# tell RTD to install the package with the docs optional requirements
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

mspdetect-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-10-26
+
+### Documentation
+
+- Add documentation.
+- Create changelog.
+
+### Miscellaneous Tasks
+
+- Update repository URLs after transfer to lycosystem.
+- Add github workflows for publishing.
+
+### Refactor
+
+- Restructure mspdetect package.
+
+### Bug Fixes
+
+- Fix imports and logging.
+- Fix bug in widget to correctly visualise sagittal cropping.
+- Fix memory issues.
+- Fix visualisation issues.
+- Adjust optimisation.
+
+### Features
+
+- Add MSP detection algorithm.
+- Add volume computation of structures.
+- Add more options for cropping.
+- Add possibility to specify patient list.
+- Add possibility to crop shoulders for msp detection.
+- Add configs for checking parameter input.
+
+
+[0.1.0]: https://github.com/lycosystem/mspdetect/releases/tag/0.1.0

mspdetect-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the article below."
+title: "mspdetect: mid-sagittal plane detection in head and neck planning CTs"
+type: software
+license: MIT
+repository-code: "https://github.com/lycosystem/mspdetect"
+authors:
+  - family-names: Keller
+    given-names: Loris
+  - family-names: Pérez Haas
+    given-names: Yoel
+  - family-names: Bührer
+    given-names: Noemi
+# TODO: fill in once the article is published
+preferred-citation:
+  type: article
+  title: "TODO: article title"
+  authors:
+    - family-names: Bührer
+      given-names: Noemi
+  journal: "TODO"
+  year: 2026

mspdetect-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loris Keller, Yoel Pérez Haas, Noemi Bührer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mspdetect-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: mspdetect
+Version: 0.1.0
+Summary: Automatic mid-sagittal plane detection in head and neck planning CTs.
+Author: Loris Keller, Yoel Pérez Haas, Noemi Bührer
+License-Expression: MIT
+Project-URL: source, https://github.com/lycosystem/mspdetect
+Project-URL: documentation, https://mspdetect.readthedocs.io
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: nibabel>=5.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Requires-Dist: ipywidgets>=8.0; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: git-cliff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: autodoc_pydantic; extra == "docs"
+Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
+Dynamic: license-file
+
+# mspdetect
+
+Automatic detection of the **mid-sagittal plane (MSP)** in head and neck planning CTs, and
+metrics of structures relative to it (left/right volumes, laterality and distance of the
+tumour to the midline).
+
+The plane is found by maximising the left-right symmetry of the bone: bone voxels are mirrored
+across a candidate plane and compared with the CT intensity at the mirrored position.
+
+> **Research software.** mspdetect is not a medical device and must not be used for clinical
+> decisions. Always check results visually (see [Visualization](https://mspdetect.readthedocs.io/en/stable/visualization.html)).
+
+## Installation
+
+Requires Python ≥ 3.10.
+
+```bash
+pip install "mspdetect[viz] @ git+https://github.com/lycosystem/mspdetect"
+```
+
+`[viz]` adds plotting (matplotlib, ipywidgets) and can be omitted.
+
+## Usage
+
+### Python
+
+```python
+import mspdetect as msp
+
+case = msp.load_case(
+    "data/patient01",
+    image="CT",
+    structures={"GTVp": "ROI__[GTVp]", "Body": "ROI__[EXTERNAL]", "Parotid_L": "ROI__[Parotid_L]"},
+)
+result = msp.detect_msp(case)                     # default settings, see DetectionConfig
+print(result.plane)                               # normal and offset in world coordinates
+
+metrics = msp.compute_metrics(case, result.plane, structures=["Parotid_L"], target="GTVp")
+msp.save_result(result, "results/patient01")      # msp.json + details.npz
+```
+
+Settings are passed as a `DetectionConfig`, e.g.
+`msp.DetectionConfig(crop={"reference": None})` to use the whole scan.
+
+### Command line
+
+```bash
+mspdetect check-config config.yaml   # validate and print all settings (incl. defaults)
+mspdetect run config.yaml            # detect the plane of all patients
+mspdetect metrics config.yaml        # compute metrics from the detected planes
+```
+
+See the [command line documentation](https://mspdetect.readthedocs.io/en/stable/cli.html) for the behaviour of the commands and all configuration options.
+
+## Inputs and outputs
+
+Input are NIfTI files containing the CT in Hounsfield units and, optionally, binary structure masks of the Body, GTVp, or other structures. All volumes are reoriented to RAS+ on loading.
+
+The outputs contain the detected plane, objective values along other information such as the package version, settings, etc. Planes are stored in **world coordinates**.
+
+When calculating metrics on the detected planes, for each specified structure (`metrics.structures`) a handful of information related to the detected MSP will be determined, e.g. the side, the distance to the MSP, lateral extent, etc.
+
+See the [documentation](https://mspdetect.readthedocs.io/en/stable/conventions.html) for further details.
+
+
+## Method
+
+1. **Crop** a slab of slices around the reference structure (fixed margins or a fixed-size
+   window), optionally extended to the mandible and cropped laterally to exclude the shoulders.
+2. **Bone**: voxels inside `Body` with HU in `hu_range` (default 300–2800).
+3. **Grid search** over the normal's azimuth and polar angle, for planes through the bone's
+   centre of mass, scored with the sum of squared differences between each bone voxel and the
+   (cubic-interpolated) CT at its mirror position. A robust Huber threshold δ is estimated
+   from the residuals (1.345 · 1.4826 · MAD).
+4. **Optimisation** of the Huber loss with BFGS, starting from the best grid plane and using
+   the δ of that plane. With `n_starts > 1`, further starts from the next-best grid planes are
+   run, each with the δ of its own grid plane. Since these starts minimise different Huber
+   losses, the plane with the lowest final quadratic loss (independent of δ) is returned as
+   the best, and `first_start_agrees` reports whether the first start reached the same plane
+   (within 0.5° and 0.5 mm).
+
+
+## Citation
+
+If you use mspdetect, please cite the article in [`CITATION.cff`](https://github.com/lycosystem/mspdetect/blob/main/CITATION.cff).

mspdetect-0.1.0/README.md

@@ -0,0 +1,85 @@
+# mspdetect
+
+Automatic detection of the **mid-sagittal plane (MSP)** in head and neck planning CTs, and
+metrics of structures relative to it (left/right volumes, laterality and distance of the
+tumour to the midline).
+
+The plane is found by maximising the left-right symmetry of the bone: bone voxels are mirrored
+across a candidate plane and compared with the CT intensity at the mirrored position.
+
+> **Research software.** mspdetect is not a medical device and must not be used for clinical
+> decisions. Always check results visually (see [Visualization](https://mspdetect.readthedocs.io/en/stable/visualization.html)).
+
+## Installation
+
+Requires Python ≥ 3.10.
+
+```bash
+pip install "mspdetect[viz] @ git+https://github.com/lycosystem/mspdetect"
+```
+
+`[viz]` adds plotting (matplotlib, ipywidgets) and can be omitted.
+
+## Usage
+
+### Python
+
+```python
+import mspdetect as msp
+
+case = msp.load_case(
+    "data/patient01",
+    image="CT",
+    structures={"GTVp": "ROI__[GTVp]", "Body": "ROI__[EXTERNAL]", "Parotid_L": "ROI__[Parotid_L]"},
+)
+result = msp.detect_msp(case)                     # default settings, see DetectionConfig
+print(result.plane)                               # normal and offset in world coordinates
+
+metrics = msp.compute_metrics(case, result.plane, structures=["Parotid_L"], target="GTVp")
+msp.save_result(result, "results/patient01")      # msp.json + details.npz
+```
+
+Settings are passed as a `DetectionConfig`, e.g.
+`msp.DetectionConfig(crop={"reference": None})` to use the whole scan.
+
+### Command line
+
+```bash
+mspdetect check-config config.yaml   # validate and print all settings (incl. defaults)
+mspdetect run config.yaml            # detect the plane of all patients
+mspdetect metrics config.yaml        # compute metrics from the detected planes
+```
+
+See the [command line documentation](https://mspdetect.readthedocs.io/en/stable/cli.html) for the behaviour of the commands and all configuration options.
+
+## Inputs and outputs
+
+Input are NIfTI files containing the CT in Hounsfield units and, optionally, binary structure masks of the Body, GTVp, or other structures. All volumes are reoriented to RAS+ on loading.
+
+The outputs contain the detected plane, objective values along other information such as the package version, settings, etc. Planes are stored in **world coordinates**.
+
+When calculating metrics on the detected planes, for each specified structure (`metrics.structures`) a handful of information related to the detected MSP will be determined, e.g. the side, the distance to the MSP, lateral extent, etc.
+
+See the [documentation](https://mspdetect.readthedocs.io/en/stable/conventions.html) for further details.
+
+
+## Method
+
+1. **Crop** a slab of slices around the reference structure (fixed margins or a fixed-size
+   window), optionally extended to the mandible and cropped laterally to exclude the shoulders.
+2. **Bone**: voxels inside `Body` with HU in `hu_range` (default 300–2800).
+3. **Grid search** over the normal's azimuth and polar angle, for planes through the bone's
+   centre of mass, scored with the sum of squared differences between each bone voxel and the
+   (cubic-interpolated) CT at its mirror position. A robust Huber threshold δ is estimated
+   from the residuals (1.345 · 1.4826 · MAD).
+4. **Optimisation** of the Huber loss with BFGS, starting from the best grid plane and using
+   the δ of that plane. With `n_starts > 1`, further starts from the next-best grid planes are
+   run, each with the δ of its own grid plane. Since these starts minimise different Huber
+   losses, the plane with the lowest final quadratic loss (independent of δ) is returned as
+   the best, and `first_start_agrees` reports whether the first start reached the same plane
+   (within 0.5° and 0.5 mm).
+
+
+## Citation
+
+If you use mspdetect, please cite the article in [`CITATION.cff`](https://github.com/lycosystem/mspdetect/blob/main/CITATION.cff).

mspdetect-0.1.0/docs/source/api/batch.rst

@@ -0,0 +1,16 @@
+Batch
+======
+
+Batch processing
+-----------------
+
+.. automodule:: mspdetect.batch
+    :members:
+    :show-inheritance:
+
+Results storage
+----------------
+
+.. automodule:: mspdetect.results
+    :members:
+    :show-inheritance:

mspdetect-0.1.0/docs/source/api/data.rst

@@ -0,0 +1,16 @@
+Data loading and preprocessing
+===============================
+
+Data Loading
+-------------
+
+.. automodule:: mspdetect.io
+    :members:
+    :show-inheritance:
+
+Preprocessing
+--------------
+
+.. automodule:: mspdetect.preprocessing
+    :members:
+    :show-inheritance: