xnattools 1.0.0__tar.gz

xnattools-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Pycharm
+.idea
+
+# Cache
+*.pyc
+*__pycache__*
+.pytest_cache
+
+# Django
+*migrations
+
+# Tox
+.tox
+*.egg-info
+
+# Test
+tests_output
+test_image
+lai_erasmusmc
+project_example.py
+/XNATTools_old
+/XNATExplorer
+/logs
+.coverage
+
+requirements.txt
+# VSCode
+.vscode
+
+# env files
+.env.local
+.venv
+
+# created diretories
+xnattools_dcm2nii_*
+
+# created docs
+public/
+doc/_build

xnattools-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026-present Biomedical Imaging Group Rotterdam, Department of Radiology and Nuclear Medicine, Erasmus MC, Rotterdam, The Netherlands
+
+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.

xnattools-1.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: xnattools
+Version: 1.0.0
+Summary: Python scripts for handy operations on XNAT data.
+Project-URL: Documentation, https://radiology.gitlab.io/radiomics/xnattools/
+Project-URL: Homepage, https://gitlab.com/radiology/radiomics/xnattools
+Project-URL: Issues, https://gitlab.com/radiology/radiomics/xnattools/-/issues
+Author-email: "Martijn P. A. Starmans" <m.starmans@erasmusmc.nl>, "Erik H.M. Kemper" <e.h.m.kemper@erasmusmc.nl>, Frederik Hartmann <f.hartmann@erasmusmc.nl>
+License: Copyright (c) 2026-present Biomedical Imaging Group Rotterdam, Department of Radiology and Nuclear Medicine, Erasmus MC, Rotterdam, The Netherlands
+        
+        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.
+License-File: LICENSE
+Keywords:  data,medical imaging,research,science,xnat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: click<9.0.0,>=8.1.7
+Requires-Dist: dcm2niix<2.0.0,>=1.0.20241211
+Requires-Dist: dicom2nifti==2.4.11
+Requires-Dist: matplotlib<4.0.0,>=3.10.1
+Requires-Dist: numpy<3.0.0,>=2.2.4
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pydantic>=2.12.3
+Requires-Dist: pydicom<3.0.2,>=2.4.4
+Requires-Dist: pytest-mock>=3.15.1
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: simpleitk<3.0.0,>=2.4.1
+Requires-Dist: tk>=0.1.0
+Requires-Dist: tox<5.0.0,>=4.25.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: urllib3>=2.7.0
+Requires-Dist: xnat<0.8.0,>=0.7.1
+Provides-Extra: dev
+Requires-Dist: bump-my-version>=1.2.7; extra == 'dev'
+Requires-Dist: ruff>=0.15.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2025.12.19; extra == 'docs'
+Requires-Dist: myst-parser>=4.0.1; extra == 'docs'
+Requires-Dist: sphinx-autoapi>=3.7.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
+Requires-Dist: sphinx-design>=0.6.1; extra == 'docs'
+Requires-Dist: sphinx>=8.1.3; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
+Requires-Dist: pytest>=9.0.2; extra == 'test'
+Requires-Dist: requests>=2.33.1; extra == 'test'
+Requires-Dist: xnat4tests>=0.4.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# xnattools
+
+xnattools is a python package for handy operations on XNAT data.
+
+# Documentation
+The complete documentation is available at [https://radiology.gitlab.io/radiomics/xnattools/](https://radiology.gitlab.io/radiomics/xnattools/) . The following example is a small part of [tutorials](https://radiology.gitlab.io/radiomics/xnattools/tutorials.html). Please refer to the documentation for additional tutorials, examples, how-to guides, and developer guides.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+1. Installed `xnattools`. For example using pip:
+    ```shell
+    pip install xnattools
+    ```
+2. Set up your XNAT credentials using one of these methods:
+
+   **Option 1: Using `.netrc` file** (recommended)
+
+   Create or edit `~/.netrc` with your XNAT credentials:
+
+   ```text
+   machine xnat.example.com
+    login your-xnat-username
+    password your-xnat-password
+   ```
+
+   **Option 2: Using `.env.local` file**
+
+   Create a `.env.local` file in your project directory:
+
+   ```text
+   XNAT_USER=your-xnat-username
+   XNAT_PASS=your-xnat-password
+   ```
+
+3. Access to an XNAT server with at least one project.
+
+## Basic Example: Running `dcm2nifti`
+
+This example shows how to convert DICOM files to NIfTI format for a specific subject.
+
+### Python API
+
+```python
+from pathlib import Path
+import xnattools as xt
+
+tools = [xt.Dcm2niftiSettings()]
+settings = xt.GeneralSettings(
+    system_url="https://xnat.example.com",
+    project_id="MY_XNAT_PROJECT",
+    subjects=["SUBJECT_001"],
+    output_dir=Path.cwd(),
+)
+xt.run_tools(tools_to_run=tools, general_settings=settings)
+```
+
+### Command Line
+
+```shell
+xnattools dcm2nifti https://xnat.example.com YOUR_PROJECT_ID \
+    --subjects SUBJECT_001
+```
+
+Replace `YOUR_PROJECT_ID` with your actual XNAT project ID and `SUBJECT_001` with a valid subject ID from your project.
+
+To use a custom output directory for intermediate files:
+
+### Python API
+
+```python
+from pathlib import Path
+import xnattools as xt
+
+tools = [xt.Dcm2niftiSettings()]
+settings = xt.GeneralSettings(
+    system_url="https://xnat.example.com",
+    project_id="MY_XNAT_PROJECT",
+    subjects=["SUBJECT_001"],
+    output_dir=Path.cwd(),
+)
+xt.run_tools(tools_to_run=tools, general_settings=settings)
+```
+
+### Command Line
+
+```shell
+xnattools dcm2nifti https://xnat.example.com YOUR_PROJECT_ID \
+    --subjects SUBJECT_001 \
+    --output-dir /path/to/temp
+```
+# Authors
+- [Martijn P. A. Starmans](https://gitlab.com/MStarmans91) : [m.starmans@erasmusmc.nl](mailto:m.starmans@erasmusmc.nl)
+- [Erik Kemper](https://gitlab.com/EHMKemper) : [e.h.m.kemper@erasmusmc.nl](mailto:e.h.m.kemper@erasmusmc.nl@erasmusmc.nl)
+- [Frederik Hartmann](https://gitlab.com/Frederik-Hartmann) : [f.hartmann@erasmusmc.nl](mailto:f.hartmann@erasmusmc.nl)

xnattools-1.0.0/README.md

@@ -0,0 +1,96 @@
+# xnattools
+
+xnattools is a python package for handy operations on XNAT data.
+
+# Documentation
+The complete documentation is available at [https://radiology.gitlab.io/radiomics/xnattools/](https://radiology.gitlab.io/radiomics/xnattools/) . The following example is a small part of [tutorials](https://radiology.gitlab.io/radiomics/xnattools/tutorials.html). Please refer to the documentation for additional tutorials, examples, how-to guides, and developer guides.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+1. Installed `xnattools`. For example using pip:
+    ```shell
+    pip install xnattools
+    ```
+2. Set up your XNAT credentials using one of these methods:
+
+   **Option 1: Using `.netrc` file** (recommended)
+
+   Create or edit `~/.netrc` with your XNAT credentials:
+
+   ```text
+   machine xnat.example.com
+    login your-xnat-username
+    password your-xnat-password
+   ```
+
+   **Option 2: Using `.env.local` file**
+
+   Create a `.env.local` file in your project directory:
+
+   ```text
+   XNAT_USER=your-xnat-username
+   XNAT_PASS=your-xnat-password
+   ```
+
+3. Access to an XNAT server with at least one project.
+
+## Basic Example: Running `dcm2nifti`
+
+This example shows how to convert DICOM files to NIfTI format for a specific subject.
+
+### Python API
+
+```python
+from pathlib import Path
+import xnattools as xt
+
+tools = [xt.Dcm2niftiSettings()]
+settings = xt.GeneralSettings(
+    system_url="https://xnat.example.com",
+    project_id="MY_XNAT_PROJECT",
+    subjects=["SUBJECT_001"],
+    output_dir=Path.cwd(),
+)
+xt.run_tools(tools_to_run=tools, general_settings=settings)
+```
+
+### Command Line
+
+```shell
+xnattools dcm2nifti https://xnat.example.com YOUR_PROJECT_ID \
+    --subjects SUBJECT_001
+```
+
+Replace `YOUR_PROJECT_ID` with your actual XNAT project ID and `SUBJECT_001` with a valid subject ID from your project.
+
+To use a custom output directory for intermediate files:
+
+### Python API
+
+```python
+from pathlib import Path
+import xnattools as xt
+
+tools = [xt.Dcm2niftiSettings()]
+settings = xt.GeneralSettings(
+    system_url="https://xnat.example.com",
+    project_id="MY_XNAT_PROJECT",
+    subjects=["SUBJECT_001"],
+    output_dir=Path.cwd(),
+)
+xt.run_tools(tools_to_run=tools, general_settings=settings)
+```
+
+### Command Line
+
+```shell
+xnattools dcm2nifti https://xnat.example.com YOUR_PROJECT_ID \
+    --subjects SUBJECT_001 \
+    --output-dir /path/to/temp
+```
+# Authors
+- [Martijn P. A. Starmans](https://gitlab.com/MStarmans91) : [m.starmans@erasmusmc.nl](mailto:m.starmans@erasmusmc.nl)
+- [Erik Kemper](https://gitlab.com/EHMKemper) : [e.h.m.kemper@erasmusmc.nl](mailto:e.h.m.kemper@erasmusmc.nl@erasmusmc.nl)
+- [Frederik Hartmann](https://gitlab.com/Frederik-Hartmann) : [f.hartmann@erasmusmc.nl](mailto:f.hartmann@erasmusmc.nl)

xnattools-1.0.0/pyproject.toml

@@ -0,0 +1,214 @@
+# see documentation, e.g.
+# - https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#declaring-project-metadata
+# - https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
+# - https://www.python.org/dev/peps/pep-0621/
+
+# ---- Project Info and Dependencies ----
+
+[project.urls] # adjust these when publishing
+Documentation = "https://radiology.gitlab.io/radiomics/xnattools/"
+Homepage = "https://gitlab.com/radiology/radiomics/xnattools"
+Issues = "https://gitlab.com/radiology/radiomics/xnattools/-/issues"
+
+# command line interface (CLI) entry points
+[project.scripts]
+xnattools = "xnattools.cli:main"
+
+[project]
+name = "xnattools"
+version = "1.0.0"
+description = "Python scripts for handy operations on XNAT data."
+authors = [
+    { name = "Martijn P. A. Starmans", email = "m.starmans@erasmusmc.nl" },
+    { name = "Erik H.M. Kemper", email = "e.h.m.kemper@erasmusmc.nl" },
+    { name = "Frederik Hartmann", email = "f.hartmann@erasmusmc.nl" },
+]
+requires-python = ">=3.10"
+keywords = ["xnat","research","science","medical imaging"," data"]
+license = {file = "LICENSE"}
+readme = {file = "README.md", content-type = "text/markdown"}
+
+# classifiers are used to categorize the project, adjust as needed
+# see https://pypi.org/classifiers/
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English", # Natural language of the project
+    "Intended Audience :: Developers", # Intended audience
+    "Intended Audience :: Science/Research",
+    "Development Status :: 3 - Alpha", # Development status, e.g., 1 - Planning, 2 - Pre-Alpha, 3 - Alpha, 4 - Beta, 5 - Production/Stable
+    "Programming Language :: Python :: 3", # Supported Python versions
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+# ---- Main dependencies ----
+
+dependencies = [
+    "click (>=8.1.7,<9.0.0)",
+    "tox>=4.25.0,<5.0.0",
+    "numpy>=2.2.4,<3.0.0",
+    "simpleitk (>=2.4.1,<3.0.0)",
+    "pydicom>=2.4.4,<3.0.2",
+    "xnat>=0.7.1,<0.8.0",
+    "dcm2niix>=1.0.20241211,<2.0.0",
+    "dicom2nifti==2.4.11",
+    "matplotlib (>=3.10.1,<4.0.0)",
+    "python-dotenv>=1.1.1",
+    "tqdm>=4.67.1",
+    "tk>=0.1.0",
+    "pydantic>=2.12.3",
+    "pandas>=2.3.3",
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+    "urllib3>=2.7.0",
+]
+
+
+# ---- Additional dependency groups ----
+
+[project.optional-dependencies]
+dev = [
+    "bump-my-version>=1.2.7",
+    "ruff>=0.15.4",
+]
+
+docs = [
+    "furo>=2025.12.19",
+    "myst-parser>=4.0.1",
+    "sphinx>=8.1.3",
+    "sphinx-autoapi>=3.7.0",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.6.1",
+]
+test = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "requests>=2.33.1",
+    "xnat4tests>=0.4.1",
+]
+
+# ---- Build system ----
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+# ---- Hatch virtual environment settings ----
+
+# main dependencies
+[tool.hatch.envs.default]
+installer = "uv"
+
+# dev dependencies
+[tool.hatch.envs.dev]
+installer = "uv"
+features = ["dev"]
+
+[tool.hatch.envs.dev.scripts]
+bump = "bump-my-version {args}"
+
+# docs dependencies
+[tool.hatch.envs.docs]
+installer = "uv"
+features = ["docs"]
+
+[tool.hatch.envs.docs.scripts]
+coverage = "sphinx-build -b coverage doc doc/_build/coverage"
+build-html = "sphinx-build -b html ./doc public"
+doctest = "sphinx-build -b doctest doc doc/_build/doctest"
+
+# hatch test dependencies
+[tool.hatch.envs.hatch-test]
+installer = "uv"
+features = ["test"]
+default-args = ["tests"]
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.14", "3.13", "3.12", "3.11", "3.10"]
+
+# ---- pytest settings ----
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow_docker_test: Tests that require a running docker (XNAT) which is slow to setup"
+]
+
+# ---- ruff settings ----
+
+[tool.ruff]
+line-length = 120
+output-format = "concise"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+# Enable Pyflakes `E` and `F` codes by default.
+select = ["ALL"]
+ignore = [
+    "ANN204", # Missing return type annotation for special (dunder) method
+    "ANN401", # Allow Any
+    "COM812", # Resolve absence of a trailing comma
+    "FBT",    # Using boolean function arguments
+    "TD",     # TODOs
+    "FIX001", # Resolve FIXMEs
+    "FIX002", # Resolve TODOs
+    "B028",   # No explicit `stacklevel` keyword argument found in warning
+    # No docstrings required in the following cases
+    "D100", # Missing module docstring
+    "D104", # Missing public package docstring
+    "D105", # Missing docstring in magic method
+    "D107", # Missing docstring in `__init__`
+    "D415", # Missing period in first line of docstring
+]
+pydocstyle.convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can ignore a few extra rules
+"tests/**.py" = [
+    "ANN201", # Missing return type annotation for public function
+    "ANN205", # Missing return type annotation for staticmethod
+    "PT011",  # Missing `match` parameter in `pytest.raises()`
+    "S101",   # Use of assert is detected
+    "SLF001",   # Access of private members
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["xnattools"]
+force-single-line = true
+no-lines-before = ["future","standard-library","third-party","first-party","local-folder"]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel", "tomllib"]
+
+[tool.ruff.lint.pep8-naming]
+ignore-names = ["SimpleITK"] # allow import as sitk despite N813
+
+# ---- bumpversion settings ----
+
+[tool.bumpversion]
+current_version = "1.0.0"
+tag = false
+tag_name = "v{new_version}"
+commit = true
+commit_args = "--no-verify" # pre-commit ruff settings are not parsed correctly in bump-my-verion
+message = "Bump version: {current_version} → {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+
+#[[tool.bumpversion.files]]
+#filename = "CITATION.cff"

xnattools-1.0.0/src/xnattools/__init__.py

@@ -0,0 +1,17 @@
+from importlib.metadata import version
+from xnattools.core import run_tools
+from xnattools.dataclasses.core import GeneralSettings
+from xnattools.dataclasses.datmat import DatMatSettings
+from xnattools.dataclasses.dcm2nifti import Dcm2niftiSettings
+from xnattools.dataclasses.dcm2snapshots import Dcm2snapshotsSettings
+from xnattools.dataclasses.scanmetadata import ScanMetaDataSettings
+
+__version__ = version("xnattools")
+__all__ = [
+    "DatMatSettings",
+    "Dcm2niftiSettings",
+    "Dcm2snapshotsSettings",
+    "GeneralSettings",
+    "ScanMetaDataSettings",
+    "run_tools",
+]