mlxradiomics 0.1.0.dev5__tar.gz → 0.1.0.dev6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of mlxradiomics might be problematic. Click here for more details.

Files changed (32) hide show
  1. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/PKG-INFO +18 -14
  2. mlxradiomics-0.1.0.dev6/README.md +45 -0
  3. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/pyproject.toml +2 -1
  4. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/__init__.py +1 -1
  5. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/io.py +48 -8
  6. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/medmlx.py +4 -2
  7. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/spatial.py +2 -0
  8. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/transforms.py +1 -0
  9. mlxradiomics-0.1.0.dev5/README.md +0 -42
  10. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/.gitignore +0 -0
  11. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/LICENSE +0 -0
  12. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/THIRD_PARTY_NOTICES.md +0 -0
  13. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/_runtime.py +0 -0
  14. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/_typing.py +0 -0
  15. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/config.py +0 -0
  16. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/distributions.py +0 -0
  17. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/eigen.py +0 -0
  18. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/engine.py +0 -0
  19. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/histogram.py +0 -0
  20. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/lbp.py +0 -0
  21. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/lbp3d.py +0 -0
  22. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/mesh_tables.json +0 -0
  23. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/pipeline.py +0 -0
  24. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/precision.py +0 -0
  25. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/preprocessing.py +0 -0
  26. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/recursive_gaussian.py +0 -0
  27. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/reduction.py +0 -0
  28. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/shape.py +0 -0
  29. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/spline.py +0 -0
  30. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/statistics.py +0 -0
  31. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/texture.py +0 -0
  32. {mlxradiomics-0.1.0.dev5 → mlxradiomics-0.1.0.dev6}/src/mlxradiomics/wavelet_tables.json +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: mlxradiomics
3
- Version: 0.1.0.dev5
3
+ Version: 0.1.0.dev6
4
4
  Summary: Apple Silicon Metal radiomics with bounded voxel batches.
5
5
  License-Expression: Apache-2.0 AND MIT AND BSD-3-Clause
6
6
  License-File: LICENSE
@@ -9,6 +9,7 @@ Classifier: Operating System :: MacOS :: MacOS X
9
9
  Requires-Python: <3.15,>=3.13
10
10
  Requires-Dist: medmlx-core==0.2.5
11
11
  Requires-Dist: mlx==0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'
12
+ Requires-Dist: nibabel<6,>=5.3
12
13
  Requires-Dist: numpy<3,>=2.0
13
14
  Requires-Dist: pyyaml<7,>=6
14
15
  Requires-Dist: simpleitk==2.5.6
@@ -36,24 +37,27 @@ source .venv/bin/activate
36
37
  uv pip install "mlxradiomics==0.1.0.dev5"
37
38
  ```
38
39
 
39
- With aligned `image` and `mask` NumPy arrays:
40
+ ## MedMLX runner
41
+
42
+ With an aligned image and label-mask file:
40
43
 
41
44
  ```python
42
- from mlxradiomics import Settings, extract
43
-
44
- # image and mask are aligned NumPy arrays; spacing follows array-axis order.
45
- result = extract(
46
- image, mask, spacing=(3.0, 1.0, 1.0),
47
- settings=Settings(label=2, bin_width=25,
48
- features=("firstorder_Mean", "glcm_Contrast")),
49
- voxel=True,
45
+ from mlxradiomics.medmlx import run
46
+
47
+ result = run(
48
+ image_path="image.nii.gz",
49
+ mask_path="mask.nii.gz",
50
+ output_dir="features",
50
51
  )
51
- mean_map = result.features["original_firstorder_Mean"]
52
52
  ```
53
53
 
54
- Use `voxel=False` for ROI features. File input and the MedMLX runner work with
55
- the standard installation; SimpleITK and YAML support are included. No model
56
- weights are required.
54
+ File I/O and YAML support are included in the standard installation. No model
55
+ weights are required. The [API guide](docs/technical.md) covers label selection, parameter
56
+ files, voxel maps and the lower-level array interface.
57
+
58
+ ## Documentation
59
+
60
+ [API, settings and validation](docs/technical.md)
57
61
 
58
62
  ## License
59
63
 
@@ -0,0 +1,45 @@
1
+ # mlxradiomics
2
+
3
+ Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
4
+
5
+ | Input | Output |
6
+ | :--- | :--- |
7
+ | Aligned image + label mask | ROI features or voxel maps |
8
+
9
+ **Apple Silicon · Metal · Python 3.13 / 3.14** · [uv](https://docs.astral.sh/uv/)
10
+
11
+ ## Quick start
12
+
13
+ ```bash
14
+ uv venv --python 3.13
15
+ source .venv/bin/activate
16
+ uv pip install "mlxradiomics==0.1.0.dev5"
17
+ ```
18
+
19
+ ## MedMLX runner
20
+
21
+ With an aligned image and label-mask file:
22
+
23
+ ```python
24
+ from mlxradiomics.medmlx import run
25
+
26
+ result = run(
27
+ image_path="image.nii.gz",
28
+ mask_path="mask.nii.gz",
29
+ output_dir="features",
30
+ )
31
+ ```
32
+
33
+ File I/O and YAML support are included in the standard installation. No model
34
+ weights are required. The [API guide](docs/technical.md) covers label selection, parameter
35
+ files, voxel maps and the lower-level array interface.
36
+
37
+ ## Documentation
38
+
39
+ [API, settings and validation](docs/technical.md)
40
+
41
+ ## License
42
+
43
+ Apache-2.0; license and third-party notices are included in the distribution.
44
+
45
+ For research and education. Outputs require human review.
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  classifiers = ["Operating System :: MacOS :: MacOS X"]
7
7
  name = "mlxradiomics"
8
- version = "0.1.0.dev5"
8
+ version = "0.1.0.dev6"
9
9
  description = "Apple Silicon Metal radiomics with bounded voxel batches."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.13,<3.15"
@@ -15,6 +15,7 @@ dependencies = [
15
15
  "numpy>=2.0,<3",
16
16
  "mlx==0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'",
17
17
  "medmlx-core==0.2.5",
18
+ "nibabel>=5.3,<6",
18
19
  "SimpleITK==2.5.6",
19
20
  "PyYAML>=6,<7",
20
21
  ]
@@ -31,7 +31,7 @@ if TYPE_CHECKING:
31
31
  from mlxradiomics.transforms import TransformSettings as TransformSettings
32
32
  from mlxradiomics.transforms import feature_images as feature_images
33
33
 
34
- __version__ = "0.1.0.dev5"
34
+ __version__ = "0.1.0.dev6"
35
35
 
36
36
  _EXPORT_MODULES = {
37
37
  "Result": "engine",
@@ -1,15 +1,16 @@
1
1
  """NIfTI/NRRD volume I/O and PyRadiomics-style parameter loading for the runner.
2
2
 
3
- Reading and writing use SimpleITK, which already understands both formats and
4
- is a plain imaging-I/O dependency, not the upstream PyRadiomics package.
3
+ Reading and writing use SimpleITK. NiBabel also checks NIfTI image values before
4
+ extraction because SimpleITK 2.5.6 replaces stored non-finite voxels with zero.
5
5
  """
6
6
 
7
7
  from __future__ import annotations
8
8
 
9
9
  import dataclasses
10
+ import gzip
10
11
  from collections.abc import Mapping
11
12
  from pathlib import Path
12
- from typing import Literal, cast
13
+ from typing import Literal, Protocol, cast
13
14
 
14
15
  import numpy as np
15
16
  from medmlx_core import MissingDependencyError
@@ -21,6 +22,18 @@ from mlxradiomics.config import Settings
21
22
  _VOLUME_SUFFIXES = (".nii", ".nii.gz", ".nrrd", ".nhdr")
22
23
 
23
24
 
25
+ class _NiftiImage(Protocol):
26
+ def get_fdata(self) -> NDArray[np.float64]:
27
+ """Return scaled image values in NiBabel's default float64 precision."""
28
+ ...
29
+
30
+
31
+ class _NiftiReader(Protocol):
32
+ def load(self, filename: str) -> _NiftiImage:
33
+ """Load an image with its on-disk voxel values intact."""
34
+ ...
35
+
36
+
24
37
  @dataclasses.dataclass(frozen=True)
25
38
  class Volume:
26
39
  """A 2D/3D volume in this package's array-axis convention (NumPy order).
@@ -42,6 +55,7 @@ class Volume:
42
55
  direction: tuple[float, ...]
43
56
 
44
57
  def __post_init__(self) -> None:
58
+ """Reject arrays, spacing, origin or direction outside the documented contract."""
45
59
  ndim = self.array.ndim
46
60
  if ndim not in (2, 3) or any(size == 0 for size in self.array.shape):
47
61
  raise ValueError("volume must have a nonempty 2D or 3D shape")
@@ -67,11 +81,29 @@ def _require_volume_path(path: str | Path) -> Path:
67
81
  return source
68
82
 
69
83
 
84
+ def _require_single_file_nifti(source: Path) -> None:
85
+ """Reject paired NIfTI/Analyze headers disguised as single-file ``.nii`` inputs.
86
+
87
+ SimpleITK 2.5.6 reads header bytes as voxels for these names, so they must
88
+ be converted to a single-file image or a supported NRRD before extraction.
89
+ """
90
+ with gzip.open(source, "rb") if source.name.endswith(".gz") else source.open("rb") as stream:
91
+ header = stream.read(348)
92
+ magic1, magic2 = header[344:348], header[4:8]
93
+ header1 = header[:4] in (b"\x5c\x01\0\0", b"\0\0\x01\x5c")
94
+ header2 = header[:4] in (b"\x1c\x02\0\0", b"\0\0\x02\x1c")
95
+ analyze = header1 and magic1 not in (b"n+1\0", b"ni1\0")
96
+ if (header1 and magic1 == b"ni1\0") or (header2 and magic2 == b"ni2\0") or analyze:
97
+ raise ValueError(f"detached NIfTI/Analyze input is unsupported: {source}")
98
+
99
+
70
100
  def _read(path: str | Path, *, integer: bool) -> Volume:
71
101
  # Shared reader: ``integer`` selects mask rules (integer labels) over image rules (finite).
72
102
  import SimpleITK as sitk
73
103
 
74
104
  source = _require_volume_path(path)
105
+ if source.name.endswith((".nii", ".nii.gz")):
106
+ _require_single_file_nifti(source)
75
107
  image = sitk.ReadImage(source.as_posix())
76
108
  if image.GetDimension() not in (2, 3):
77
109
  raise ValueError(f"expected a 2D or 3D volume: {source}")
@@ -83,6 +115,14 @@ def _read(path: str | Path, *, integer: bool) -> Volume:
83
115
  array = np.asarray(raw)
84
116
  if not integer and not np.all(np.isfinite(array)):
85
117
  raise ValueError(f"image contains non-finite voxels: {source}")
118
+ if not integer and source.name.endswith((".nii", ".nii.gz")):
119
+ import nibabel as nib
120
+
121
+ # ITK's NIfTI reader zeroes NaN and infinities before SimpleITK exposes
122
+ # the array; inspect the scaled source values with NiBabel as well.
123
+ values = cast(_NiftiReader, nib).load(source.as_posix()).get_fdata()
124
+ if not np.all(np.isfinite(values)):
125
+ raise ValueError(f"image contains non-finite voxels: {source}")
86
126
  return Volume(
87
127
  array=array,
88
128
  # SimpleITK orders spacing/origin/direction x-first; this package's arrays
@@ -96,11 +136,11 @@ def _read(path: str | Path, *, integer: bool) -> Volume:
96
136
  def read_image(path: str | Path) -> Volume:
97
137
  """Read a 2D/3D NIfTI or NRRD image preserving pixel type and physical geometry.
98
138
 
99
- SimpleITK read errors propagate, including ``RuntimeError`` for unreadable files.
139
+ SimpleITK and NiBabel read errors propagate for unreadable files.
100
140
 
101
141
  Raises:
102
- ValueError: If the file is missing, has an unsupported suffix, is not a single-channel
103
- 2-D or 3-D volume, or contains non-finite values.
142
+ ValueError: If the file is missing, has an unsupported suffix or detached NIfTI
143
+ header, is not a single-channel 2-D or 3-D volume, or contains non-finite values.
104
144
  """
105
145
 
106
146
  return _read(path, integer=False)
@@ -112,8 +152,8 @@ def read_mask(path: str | Path) -> Volume:
112
152
  SimpleITK read errors propagate, including ``RuntimeError`` for unreadable files.
113
153
 
114
154
  Raises:
115
- ValueError: If the file is missing, has an unsupported suffix, is not a single-channel
116
- 2-D or 3-D volume, or has a non-integer pixel type.
155
+ ValueError: If the file is missing, has an unsupported suffix or detached NIfTI
156
+ header, is not a single-channel 2-D or 3-D volume, or has a non-integer pixel type.
117
157
  """
118
158
 
119
159
  return _read(path, integer=True)
@@ -71,6 +71,8 @@ class RunDetails(TypedDict):
71
71
 
72
72
 
73
73
  class RunResult(TypedDict):
74
+ """Written output paths and run metadata returned by :func:`run`."""
75
+
74
76
  outputs: RunOutputs
75
77
  details: RunDetails
76
78
 
@@ -224,8 +226,8 @@ def run(
224
226
  outputs that alias the supplied image, mask or params paths are refused.
225
227
  Outputs that alias one another are also refused. These are preflight
226
228
  checks; they cannot prevent concurrent path changes, and writes are not atomic.
227
- If either input is a detached NRRD, NIfTI or Analyze image, existing outputs
228
- are never replaced, because they may alias a data file referenced by the header.
229
+ Existing outputs are never replaced for detached NRRD inputs, because they
230
+ may alias a referenced data file. Paired NIfTI/Analyze inputs are rejected.
229
231
 
230
232
  Returns:
231
233
  ``outputs.features_json`` always points to a metadata-plus-values (ROI) or
@@ -57,6 +57,7 @@ class ImageSettings:
57
57
  pad_distance: int = 5
58
58
 
59
59
  def __post_init__(self) -> None:
60
+ """Reject an untyped interpolator, non-boolean flags or invalid spacing and padding."""
60
61
  if type(self.interpolator) is not Interpolator:
61
62
  raise ValueError("interpolator must be an Interpolator value")
62
63
  if type(self.correct_mask) is not bool:
@@ -78,6 +79,7 @@ class ImagePair:
78
79
  mask: Volume
79
80
 
80
81
  def __post_init__(self) -> None:
82
+ """Reject an image and mask that differ in shape or physical geometry."""
81
83
  if self.image.array.shape != self.mask.array.shape or (
82
84
  self.image.spacing != self.mask.spacing or self.image.origin != self.mask.origin
83
85
  or self.image.direction != self.mask.direction
@@ -75,6 +75,7 @@ class TransformSettings:
75
75
  gradient_use_spacing: bool = True
76
76
 
77
77
  def __post_init__(self) -> None:
78
+ """Reject mistyped fields, out-of-range parameters and unresolved wavelet names."""
78
79
  if type(self.scratch_mib) is not int or self.scratch_mib < 1:
79
80
  raise ValueError("scratch_mib must be a positive integer")
80
81
  if type(self.lbp2d_method) is not LBPMethod:
@@ -1,42 +0,0 @@
1
- # mlxradiomics
2
-
3
- Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
4
-
5
- | Input | Output |
6
- | :--- | :--- |
7
- | Aligned image + label mask | ROI features or voxel maps |
8
-
9
- **Apple Silicon · Metal · Python 3.13 / 3.14** · [uv](https://docs.astral.sh/uv/)
10
-
11
- ## Quick start
12
-
13
- ```bash
14
- uv venv --python 3.13
15
- source .venv/bin/activate
16
- uv pip install "mlxradiomics==0.1.0.dev5"
17
- ```
18
-
19
- With aligned `image` and `mask` NumPy arrays:
20
-
21
- ```python
22
- from mlxradiomics import Settings, extract
23
-
24
- # image and mask are aligned NumPy arrays; spacing follows array-axis order.
25
- result = extract(
26
- image, mask, spacing=(3.0, 1.0, 1.0),
27
- settings=Settings(label=2, bin_width=25,
28
- features=("firstorder_Mean", "glcm_Contrast")),
29
- voxel=True,
30
- )
31
- mean_map = result.features["original_firstorder_Mean"]
32
- ```
33
-
34
- Use `voxel=False` for ROI features. File input and the MedMLX runner work with
35
- the standard installation; SimpleITK and YAML support are included. No model
36
- weights are required.
37
-
38
- ## License
39
-
40
- Apache-2.0; license and third-party notices are included in the distribution.
41
-
42
- For research and education. Outputs require human review.