mlxradiomics 0.1.0.dev8__tar.gz → 0.1.0.dev9__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 (34) hide show
  1. mlxradiomics-0.1.0.dev9/.gitignore +38 -0
  2. mlxradiomics-0.1.0.dev9/PKG-INFO +193 -0
  3. mlxradiomics-0.1.0.dev9/README.md +156 -0
  4. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/pyproject.toml +42 -11
  5. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/__init__.py +2 -2
  6. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/medmlx.py +73 -51
  7. mlxradiomics-0.1.0.dev8/.gitignore +0 -14
  8. mlxradiomics-0.1.0.dev8/PKG-INFO +0 -67
  9. mlxradiomics-0.1.0.dev8/README.md +0 -45
  10. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/LICENSE +0 -0
  11. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/THIRD_PARTY_NOTICES.md +0 -0
  12. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/_runtime.py +0 -0
  13. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/_typing.py +0 -0
  14. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/config.py +0 -0
  15. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/distributions.py +0 -0
  16. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/eigen.py +0 -0
  17. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/engine.py +0 -0
  18. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/histogram.py +0 -0
  19. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/io.py +0 -0
  20. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/lbp.py +0 -0
  21. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/lbp3d.py +0 -0
  22. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/mesh_tables.json +0 -0
  23. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/pipeline.py +0 -0
  24. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/precision.py +0 -0
  25. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/preprocessing.py +0 -0
  26. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/recursive_gaussian.py +0 -0
  27. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/reduction.py +0 -0
  28. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/shape.py +0 -0
  29. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/spatial.py +0 -0
  30. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/spline.py +0 -0
  31. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/statistics.py +0 -0
  32. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/texture.py +0 -0
  33. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/transforms.py +0 -0
  34. {mlxradiomics-0.1.0.dev8 → mlxradiomics-0.1.0.dev9}/src/mlxradiomics/wavelet_tables.json +0 -0
@@ -0,0 +1,38 @@
1
+ # MedMLX standard
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv
6
+ build/
7
+ dist/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .mypy_cache/
11
+ .hypothesis/
12
+ .coverage
13
+ htmlcov/
14
+ .DS_Store
15
+ # Never commit secrets (Hugging Face tokens)
16
+ .env
17
+ # Never commit data or weights
18
+ /data/
19
+ /work/
20
+ /weights/
21
+ /models/
22
+ /checkpoints/
23
+ /outputs/
24
+ *.nii
25
+ *.nii.gz
26
+ *.dcm
27
+ *.nrrd
28
+ *.mha
29
+ *.mhd
30
+ *.safetensors
31
+ *.pt
32
+ *.pth
33
+ *.ckpt
34
+ *.bin
35
+ *.h5
36
+ *.npy
37
+ *.npz
38
+ !tests/fixtures/**/*.npz
@@ -0,0 +1,193 @@
1
+ Metadata-Version: 2.5
2
+ Name: mlxradiomics
3
+ Version: 0.1.0.dev9
4
+ Summary: Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX
5
+ Project-URL: Homepage, https://medmlx.org
6
+ Project-URL: Documentation, https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/README.md
7
+ Project-URL: Repository, https://github.com/MedMLX/mlx-radiomics
8
+ Project-URL: Issues, https://github.com/MedMLX/mlx-radiomics/issues
9
+ Project-URL: MedMLX, https://github.com/MedMLX/medmlx
10
+ Author: Joseph Sandoval, Alfredo Sandoval Jr.
11
+ License-Expression: Apache-2.0 AND MIT AND BSD-3-Clause
12
+ License-File: LICENSE
13
+ License-File: THIRD_PARTY_NOTICES.md
14
+ Keywords: apple-silicon,feature-extraction,medical-imaging,metal,mlx,pyradiomics,radiomics
15
+ Classifier: Development Status :: 3 - Alpha
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: Operating System :: MacOS :: MacOS X
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
23
+ Classifier: Topic :: Scientific/Engineering :: Image Processing
24
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
25
+ Requires-Python: <3.14,>=3.13
26
+ Requires-Dist: medmlx-core==0.2.6
27
+ Requires-Dist: mlx==0.32.4; platform_system == 'Darwin' and platform_machine == 'arm64'
28
+ Requires-Dist: nibabel<6,>=5.3
29
+ Requires-Dist: numpy<3,>=2.0
30
+ Requires-Dist: pyyaml<7,>=6
31
+ Requires-Dist: simpleitk==2.5.6
32
+ Provides-Extra: io
33
+ Provides-Extra: lbp
34
+ Requires-Dist: scipy==1.18.1; extra == 'lbp'
35
+ Requires-Dist: trimesh==4.9.0; extra == 'lbp'
36
+ Description-Content-Type: text/markdown
37
+
38
+ <div align="center">
39
+
40
+ # mlx-radiomics
41
+
42
+ Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
43
+
44
+ [![PyPI](https://img.shields.io/pypi/v/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
45
+ [![Python](https://img.shields.io/pypi/pyversions/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
46
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/LICENSE)
47
+ [![Apple Silicon](https://img.shields.io/badge/Apple_Silicon-MLX-black?logo=apple)](https://github.com/ml-explore/mlx)
48
+ [![MedMLX](https://img.shields.io/badge/MedMLX-runtime-A51C30)](https://github.com/MedMLX/medmlx)
49
+
50
+ [MedMLX](https://github.com/MedMLX/medmlx)
51
+
52
+ <img src="https://raw.githubusercontent.com/MedMLX/mlx-radiomics/v0.1.0.dev9/docs/showcase.png" alt="Radiomics voxel maps computed from an image and label mask" width="100%">
53
+
54
+ </div>
55
+
56
+ | Input | Output |
57
+ | :--- | :--- |
58
+ | Aligned image + label mask | ROI features or voxel maps |
59
+
60
+ ## Use with MedMLX
61
+
62
+ The [MedMLX MCP server](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md) is the lowest-friction way to use this model. It installs this runtime, and lets an AI agent describe, check and run `mlxradiomics` for you.
63
+
64
+ ```sh
65
+ uv tool install --python 3.13 "medmlx[vision,mcp]"
66
+ MEDMLX="$(uv tool dir --bin --color never)/medmlx"
67
+ mkdir -p "$HOME/medmlx-work"
68
+ claude mcp add --scope user medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"
69
+ ```
70
+
71
+ For Codex, use `codex mcp add medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"`. Other MCP clients take the same command and arguments. The same install provides the `medmlx` CLI, for example `medmlx describe mlxradiomics`.
72
+
73
+ > **For AI agents:** prefer the MedMLX MCP tools (`list_models`, `describe_model`, `model_readiness`, `run_model`, `get_job`) over writing Python against this package.
74
+
75
+ ## Install
76
+
77
+ ```bash
78
+ uv venv --python 3.13
79
+ source .venv/bin/activate
80
+ uv pip install "mlxradiomics>=0.1.0.dev9"
81
+ ```
82
+
83
+ ## Run
84
+
85
+ With an aligned image and label-mask file:
86
+
87
+ ```python
88
+ from mlxradiomics.medmlx import run
89
+
90
+ result = run(
91
+ image_path="image.nii.gz",
92
+ mask_path="mask.nii.gz",
93
+ output_dir="features",
94
+ )
95
+ ```
96
+
97
+ File I/O and YAML support are included in the standard installation. No model
98
+ weights are required.
99
+
100
+ ### Inputs and outputs
101
+
102
+ | Argument | Meaning |
103
+ | --- | --- |
104
+ | `image_path` | One 2D or 3D image: `.nii`, `.nii.gz`, `.nrrd` or `.nhdr` |
105
+ | `mask_path` | Integer label mask with the image's shape, spacing, origin and direction; nothing is resampled |
106
+ | `output_dir` | Directory for the outputs; created if missing |
107
+ | `params` or `params_path` | Optional PyRadiomics-style settings, as a mapping or a YAML file; pass one at most |
108
+ | `label` | Optional mask label; defaults to the params label, or 1 |
109
+ | `voxel` | `False` for one value per feature; `True` for one map per feature |
110
+ | `overwrite` | `False` by default, which refuses to replace existing outputs |
111
+
112
+ ROI mode writes `features.json` and `features.csv`. Voxel mode writes `features.json`
113
+ and one float32 NIfTI per feature under `maps/`, on the image grid and zero outside
114
+ the ROI. Feature keys look like `original_glcm_Contrast`. Runner parameter files
115
+ admit original-image extraction only; derived images and resampling need the Python
116
+ API.
117
+
118
+ Undefined features are NaN, and float32 overflow can give infinity. `features.json`
119
+ writes them as Python's `NaN` and `Infinity` tokens, which strict JSON parsers
120
+ reject. SimpleITK reads stored non-finite NIfTI voxels as zero, so read voxel maps
121
+ with NiBabel. With detached NRRD or NIfTI data files, existing outputs are never
122
+ replaced, even with `overwrite=True`; use a new output directory for each run.
123
+ Invalid inputs raise `InvalidInputError`; extraction failures raise
124
+ `ModelExecutionError`.
125
+
126
+ ### Features
127
+
128
+ All 116 non-deprecated PyRadiomics feature names are implemented. The default
129
+ selection is the 93 intensity and texture features; request shape features by name.
130
+
131
+ | Family | Features | Modes |
132
+ | --- | ---: | --- |
133
+ | First order | 18 | ROI and voxel |
134
+ | GLCM | 24 | ROI and voxel |
135
+ | GLDM | 14 | ROI and voxel |
136
+ | NGTDM | 5 | ROI and voxel |
137
+ | GLRLM | 16 | ROI and voxel |
138
+ | GLSZM | 16 | ROI and voxel |
139
+ | Shape | 14 | 3D ROI |
140
+ | Shape2D | 9 | 2D ROI, or one slice of a 3D ROI |
141
+
142
+ ### Python API
143
+
144
+ ```python
145
+ from mlxradiomics import Settings, extract
146
+
147
+ # image and mask are aligned NumPy arrays; spacing follows their axis order.
148
+ result = extract(
149
+ image, mask, spacing=(3.0, 1.0, 1.0),
150
+ settings=Settings(label=2, bin_width=25, features=("firstorder_Mean", "glcm_Contrast")),
151
+ voxel=True,
152
+ )
153
+ mean_map = result.features["original_firstorder_Mean"]
154
+ ```
155
+
156
+ `FEATURES` lists every supported name. `Settings` also covers fixed-count binning
157
+ (`bin_count`), normalization, outlier removal, resegmentation, GLCM distances,
158
+ kernel radius and `masked_kernel`. With `masked_kernel=False`, neighbourhoods sample
159
+ the whole image but outputs stay inside the ROI. `scratch_mib` sets the batch size
160
+ from a scratch estimate; it is not a memory cap.
161
+
162
+ `extract_images` adds derived images through `TransformSettings`: square, square
163
+ root, logarithm, exponential, gradient, wavelets, LoG, LBP2D and LBP3D. LBP3D needs
164
+ the `lbp` extra. Output keys carry the image prefix, such as
165
+ `wavelet-HHL_glcm_Contrast`. `extract_files` reads NIfTI or NRRD files and adds
166
+ `ImageSettings` for resampling and mask correction; mismatched image and mask
167
+ geometry fails unless you request one of them.
168
+
169
+ Feature arithmetic is float32 on Metal; binning uses float64 on the host. Importing
170
+ the package does not import MLX. Computation needs Apple Silicon with Metal and has
171
+ no CPU fallback.
172
+
173
+ ### Limits
174
+
175
+ - Shape features are ROI-only. Shape2D on a 3D input needs `force2d_axis` and an
176
+ ROI in exactly one slice on that axis. `force2d_axis` counts NumPy axes.
177
+ - Voxel mode needs at least two ROI voxels.
178
+ - LoG needs a 3D image with at least four samples per axis, large enough for the
179
+ requested sigma.
180
+ - LBP3D needs 3D data and a masked kernel; integer images must be 8- or 16-bit.
181
+ Samples too close to their binary threshold raise a precision error.
182
+ - Voxel-mode GLCM MCC fails on sparse batches with an empty retained angle.
183
+ - Paired NIfTI/Analyze headers named `.nii` or `.nii.gz` are rejected; convert them
184
+ to single-file NIfTI or NRRD.
185
+ - Unsupported settings raise an error; nothing falls back to PyRadiomics.
186
+ - Features are compared with pinned PyRadiomics on synthetic cases. No IBSI
187
+ conformance or clinical validation is claimed.
188
+
189
+ ## License
190
+
191
+ [Apache-2.0](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/LICENSE). See [third-party notices](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/THIRD_PARTY_NOTICES.md).
192
+
193
+ For research and education. Outputs require human review.
@@ -0,0 +1,156 @@
1
+ <div align="center">
2
+
3
+ # mlx-radiomics
4
+
5
+ Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
8
+ [![Python](https://img.shields.io/pypi/pyversions/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
9
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/LICENSE)
10
+ [![Apple Silicon](https://img.shields.io/badge/Apple_Silicon-MLX-black?logo=apple)](https://github.com/ml-explore/mlx)
11
+ [![MedMLX](https://img.shields.io/badge/MedMLX-runtime-A51C30)](https://github.com/MedMLX/medmlx)
12
+
13
+ [MedMLX](https://github.com/MedMLX/medmlx)
14
+
15
+ <img src="https://raw.githubusercontent.com/MedMLX/mlx-radiomics/v0.1.0.dev9/docs/showcase.png" alt="Radiomics voxel maps computed from an image and label mask" width="100%">
16
+
17
+ </div>
18
+
19
+ | Input | Output |
20
+ | :--- | :--- |
21
+ | Aligned image + label mask | ROI features or voxel maps |
22
+
23
+ ## Use with MedMLX
24
+
25
+ The [MedMLX MCP server](https://github.com/MedMLX/medmlx/blob/main/docs/mcp.md) is the lowest-friction way to use this model. It installs this runtime, and lets an AI agent describe, check and run `mlxradiomics` for you.
26
+
27
+ ```sh
28
+ uv tool install --python 3.13 "medmlx[vision,mcp]"
29
+ MEDMLX="$(uv tool dir --bin --color never)/medmlx"
30
+ mkdir -p "$HOME/medmlx-work"
31
+ claude mcp add --scope user medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"
32
+ ```
33
+
34
+ For Codex, use `codex mcp add medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"`. Other MCP clients take the same command and arguments. The same install provides the `medmlx` CLI, for example `medmlx describe mlxradiomics`.
35
+
36
+ > **For AI agents:** prefer the MedMLX MCP tools (`list_models`, `describe_model`, `model_readiness`, `run_model`, `get_job`) over writing Python against this package.
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ uv venv --python 3.13
42
+ source .venv/bin/activate
43
+ uv pip install "mlxradiomics>=0.1.0.dev9"
44
+ ```
45
+
46
+ ## Run
47
+
48
+ With an aligned image and label-mask file:
49
+
50
+ ```python
51
+ from mlxradiomics.medmlx import run
52
+
53
+ result = run(
54
+ image_path="image.nii.gz",
55
+ mask_path="mask.nii.gz",
56
+ output_dir="features",
57
+ )
58
+ ```
59
+
60
+ File I/O and YAML support are included in the standard installation. No model
61
+ weights are required.
62
+
63
+ ### Inputs and outputs
64
+
65
+ | Argument | Meaning |
66
+ | --- | --- |
67
+ | `image_path` | One 2D or 3D image: `.nii`, `.nii.gz`, `.nrrd` or `.nhdr` |
68
+ | `mask_path` | Integer label mask with the image's shape, spacing, origin and direction; nothing is resampled |
69
+ | `output_dir` | Directory for the outputs; created if missing |
70
+ | `params` or `params_path` | Optional PyRadiomics-style settings, as a mapping or a YAML file; pass one at most |
71
+ | `label` | Optional mask label; defaults to the params label, or 1 |
72
+ | `voxel` | `False` for one value per feature; `True` for one map per feature |
73
+ | `overwrite` | `False` by default, which refuses to replace existing outputs |
74
+
75
+ ROI mode writes `features.json` and `features.csv`. Voxel mode writes `features.json`
76
+ and one float32 NIfTI per feature under `maps/`, on the image grid and zero outside
77
+ the ROI. Feature keys look like `original_glcm_Contrast`. Runner parameter files
78
+ admit original-image extraction only; derived images and resampling need the Python
79
+ API.
80
+
81
+ Undefined features are NaN, and float32 overflow can give infinity. `features.json`
82
+ writes them as Python's `NaN` and `Infinity` tokens, which strict JSON parsers
83
+ reject. SimpleITK reads stored non-finite NIfTI voxels as zero, so read voxel maps
84
+ with NiBabel. With detached NRRD or NIfTI data files, existing outputs are never
85
+ replaced, even with `overwrite=True`; use a new output directory for each run.
86
+ Invalid inputs raise `InvalidInputError`; extraction failures raise
87
+ `ModelExecutionError`.
88
+
89
+ ### Features
90
+
91
+ All 116 non-deprecated PyRadiomics feature names are implemented. The default
92
+ selection is the 93 intensity and texture features; request shape features by name.
93
+
94
+ | Family | Features | Modes |
95
+ | --- | ---: | --- |
96
+ | First order | 18 | ROI and voxel |
97
+ | GLCM | 24 | ROI and voxel |
98
+ | GLDM | 14 | ROI and voxel |
99
+ | NGTDM | 5 | ROI and voxel |
100
+ | GLRLM | 16 | ROI and voxel |
101
+ | GLSZM | 16 | ROI and voxel |
102
+ | Shape | 14 | 3D ROI |
103
+ | Shape2D | 9 | 2D ROI, or one slice of a 3D ROI |
104
+
105
+ ### Python API
106
+
107
+ ```python
108
+ from mlxradiomics import Settings, extract
109
+
110
+ # image and mask are aligned NumPy arrays; spacing follows their axis order.
111
+ result = extract(
112
+ image, mask, spacing=(3.0, 1.0, 1.0),
113
+ settings=Settings(label=2, bin_width=25, features=("firstorder_Mean", "glcm_Contrast")),
114
+ voxel=True,
115
+ )
116
+ mean_map = result.features["original_firstorder_Mean"]
117
+ ```
118
+
119
+ `FEATURES` lists every supported name. `Settings` also covers fixed-count binning
120
+ (`bin_count`), normalization, outlier removal, resegmentation, GLCM distances,
121
+ kernel radius and `masked_kernel`. With `masked_kernel=False`, neighbourhoods sample
122
+ the whole image but outputs stay inside the ROI. `scratch_mib` sets the batch size
123
+ from a scratch estimate; it is not a memory cap.
124
+
125
+ `extract_images` adds derived images through `TransformSettings`: square, square
126
+ root, logarithm, exponential, gradient, wavelets, LoG, LBP2D and LBP3D. LBP3D needs
127
+ the `lbp` extra. Output keys carry the image prefix, such as
128
+ `wavelet-HHL_glcm_Contrast`. `extract_files` reads NIfTI or NRRD files and adds
129
+ `ImageSettings` for resampling and mask correction; mismatched image and mask
130
+ geometry fails unless you request one of them.
131
+
132
+ Feature arithmetic is float32 on Metal; binning uses float64 on the host. Importing
133
+ the package does not import MLX. Computation needs Apple Silicon with Metal and has
134
+ no CPU fallback.
135
+
136
+ ### Limits
137
+
138
+ - Shape features are ROI-only. Shape2D on a 3D input needs `force2d_axis` and an
139
+ ROI in exactly one slice on that axis. `force2d_axis` counts NumPy axes.
140
+ - Voxel mode needs at least two ROI voxels.
141
+ - LoG needs a 3D image with at least four samples per axis, large enough for the
142
+ requested sigma.
143
+ - LBP3D needs 3D data and a masked kernel; integer images must be 8- or 16-bit.
144
+ Samples too close to their binary threshold raise a precision error.
145
+ - Voxel-mode GLCM MCC fails on sparse batches with an empty retained angle.
146
+ - Paired NIfTI/Analyze headers named `.nii` or `.nii.gz` are rejected; convert them
147
+ to single-file NIfTI or NRRD.
148
+ - Unsupported settings raise an error; nothing falls back to PyRadiomics.
149
+ - Features are compared with pinned PyRadiomics on synthetic cases. No IBSI
150
+ conformance or clinical validation is claimed.
151
+
152
+ ## License
153
+
154
+ [Apache-2.0](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/LICENSE). See [third-party notices](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/THIRD_PARTY_NOTICES.md).
155
+
156
+ For research and education. Outputs require human review.
@@ -3,25 +3,53 @@ requires = ["hatchling>=1.27"]
3
3
  build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
- classifiers = ["Operating System :: MacOS :: MacOS X"]
6
+ classifiers = [
7
+ "Development Status :: 3 - Alpha",
8
+ "Intended Audience :: Developers",
9
+ "Intended Audience :: Science/Research",
10
+ "Operating System :: MacOS :: MacOS X",
11
+ "Programming Language :: Python :: 3",
12
+ "Programming Language :: Python :: 3 :: Only",
13
+ "Programming Language :: Python :: 3.13",
14
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
15
+ "Topic :: Scientific/Engineering :: Image Processing",
16
+ "Topic :: Scientific/Engineering :: Medical Science Apps.",
17
+ ]
18
+ keywords = [
19
+ "mlx",
20
+ "apple-silicon",
21
+ "metal",
22
+ "medical-imaging",
23
+ "radiomics",
24
+ "pyradiomics",
25
+ "feature-extraction",
26
+ ]
7
27
  name = "mlxradiomics"
8
- version = "0.1.0.dev8"
9
- description = "Apple Silicon Metal radiomics with bounded voxel batches."
28
+ version = "0.1.0.dev9"
29
+ description = "Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX"
10
30
  readme = "README.md"
11
- requires-python = ">=3.13,<3.15"
31
+ requires-python = ">=3.13,<3.14"
12
32
  license = "Apache-2.0 AND MIT AND BSD-3-Clause"
13
33
  license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
14
34
  dependencies = [
15
35
  "numpy>=2.0,<3",
16
- "mlx==0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'",
17
- "medmlx-core==0.2.5",
36
+ "mlx==0.32.4; platform_system == 'Darwin' and platform_machine == 'arm64'",
37
+ "medmlx-core==0.2.6",
18
38
  "nibabel>=5.3,<6",
19
39
  "SimpleITK==2.5.6",
20
40
  "PyYAML>=6,<7",
21
41
  ]
42
+ authors = [
43
+ { name = "Joseph Sandoval" },
44
+ { name = "Alfredo Sandoval Jr." },
45
+ ]
22
46
 
23
47
  [project.urls]
24
- Repository = "https://github.com/MedMLX/mlxradiomics"
48
+ Homepage = "https://medmlx.org"
49
+ Documentation = "https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev9/README.md"
50
+ Repository = "https://github.com/MedMLX/mlx-radiomics"
51
+ Issues = "https://github.com/MedMLX/mlx-radiomics/issues"
52
+ MedMLX = "https://github.com/MedMLX/medmlx"
25
53
 
26
54
  [project.optional-dependencies]
27
55
  io = [] # Compatibility extra; registered-runner I/O is included by default.
@@ -40,7 +68,12 @@ dev = [
40
68
  "trimesh==4.9.0",
41
69
  "ruff==0.15.21",
42
70
  "pyright==1.1.414",
43
- "pyradiomics==3.0.1a1+medmlx.1",
71
+ # Runtime dependencies of the PyRadiomics reference. The reference itself is built
72
+ # from the dev-only reference/pyradiomics by make env, outside this lock, so main
73
+ # (which has no reference/) still locks and syncs.
74
+ "PyWavelets==1.10.0",
75
+ "pykwalify==1.8.0",
76
+ "six==1.17.0",
44
77
  ]
45
78
 
46
79
  [tool.hatch.build.targets.wheel]
@@ -49,11 +82,9 @@ packages = ["src/mlxradiomics"]
49
82
  [tool.hatch.metadata]
50
83
  allow-direct-references = true
51
84
 
52
- [tool.uv.sources]
53
- pyradiomics = { path = "reference/pyradiomics" }
54
-
55
85
  [tool.uv]
56
86
  environments = ["sys_platform == 'darwin' and platform_machine == 'arm64'"]
87
+ required-environments = ["sys_platform == 'darwin' and platform_machine == 'arm64'"]
57
88
  conflicts = [[{ extra = "lbp" }, { group = "dev" }]]
58
89
 
59
90
  [tool.ruff]
@@ -1,7 +1,7 @@
1
1
  """PyRadiomics-compatible radiomics features computed with MLX on the Apple Silicon GPU.
2
2
 
3
3
  Research software. Feature values are compared with a pinned PyRadiomics revision on
4
- synthetic inputs (see docs/technical.md); no IBSI or clinical validation is claimed.
4
+ synthetic inputs; no IBSI or clinical validation is claimed.
5
5
 
6
6
  Names other than ``FEATURES`` and ``Settings`` are imported on first access, so
7
7
  ``import mlxradiomics`` does not import MLX, SimpleITK or the PyRadiomics reference.
@@ -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.dev8"
34
+ __version__ = "0.1.0.dev9"
35
35
 
36
36
  _EXPORT_MODULES = {
37
37
  "Result": "engine",
@@ -96,7 +96,7 @@ def _load_settings(
96
96
  if params is not None and params_path is not None:
97
97
  raise InvalidInputError("pass only one of params or params_path")
98
98
  try:
99
- loaded = load_params(Path(params_path)) if params_path else None
99
+ loaded = load_params(Path(params_path).expanduser()) if params_path else None
100
100
  source = params if params is not None else loaded
101
101
  settings = settings_from_params(source) if source is not None else Settings()
102
102
  if label is not None:
@@ -221,11 +221,13 @@ def run(
221
221
  params_path: A YAML file holding the same mapping.
222
222
  label: Optional mask-label override. ``None`` keeps the label from ``params`` or
223
223
  ``params_path``, or uses ``1`` if neither supplies a label.
224
- voxel: Extract one feature map per voxel instead of one value per feature.
224
+ voxel: Boolean; extract one feature map per voxel instead of one value per feature.
225
225
  overwrite: Boolean permission to replace existing outputs instead of refusing;
226
226
  outputs that alias the supplied image, mask or params paths are refused.
227
227
  Outputs that alias one another are also refused. These are preflight
228
- checks; they cannot prevent concurrent path changes, and writes are not atomic.
228
+ checks; they cannot prevent concurrent path changes. Each output is written
229
+ to a temporary file and renamed into place once every output is written, so
230
+ a failed run keeps earlier outputs.
229
231
  Existing outputs are never replaced for detached NRRD inputs, because they
230
232
  may alias a referenced data file. Paired NIfTI/Analyze inputs are rejected.
231
233
 
@@ -241,41 +243,53 @@ def run(
241
243
  which strict JSON parsers may reject.
242
244
 
243
245
  Raises:
244
- InvalidInputError: An input file is missing or invalid, image/mask
246
+ InvalidInputError: An input file is missing, unreadable or invalid, image/mask
245
247
  geometry disagrees, params are invalid, an output aliases a supplied input,
246
- or outputs exist and ``overwrite`` is false or is not a boolean.
248
+ ``voxel`` is not a boolean, or outputs exist and ``overwrite`` is false or is
249
+ not a boolean.
247
250
  ModelExecutionError: Extraction itself failed.
248
- RuntimeError: SimpleITK could not read an input volume.
249
251
  """
250
252
 
251
253
  if type(overwrite) is not bool:
252
254
  raise InvalidInputError("overwrite must be a boolean")
255
+ if type(voxel) is not bool: # JSON callers can send "false", which is truthy
256
+ raise InvalidInputError("voxel must be a boolean")
253
257
 
254
- from mlxradiomics.engine import extract
255
-
256
- source_image = Path(image_path)
257
- source_mask = Path(mask_path)
258
+ source_image = Path(image_path).expanduser()
259
+ source_mask = Path(mask_path).expanduser()
258
260
  try:
259
261
  image = read_image(source_image)
260
262
  mask = read_mask(source_mask)
261
- except ValueError as error:
263
+ except (ValueError, RuntimeError, OSError, EOFError) as error:
264
+ # SimpleITK raises RuntimeError, and gzip OSError or EOFError, for unreadable files.
262
265
  raise InvalidInputError(str(error)) from error
263
266
  _check_geometry(image, mask, image_path=source_image, mask_path=source_mask)
264
267
 
265
268
  settings = _load_settings(params, params_path, label)
266
269
 
267
- directory = Path(output_dir)
270
+ directory = Path(output_dir).expanduser()
268
271
  if directory.exists() and not directory.is_dir():
269
272
  raise InvalidInputError(f"output_dir is not a directory: {directory}")
270
273
  features_json = directory / FEATURES_JSON
271
274
  features_csv = directory / FEATURES_CSV if not voxel else None
272
- inputs = (source_image, source_mask, *((Path(params_path),) if params_path else ()))
275
+ inputs = (
276
+ source_image, source_mask, *((Path(params_path).expanduser(),) if params_path else ())
277
+ )
273
278
  fixed_outputs = (features_json,) if features_csv is None else (features_json, features_csv)
274
- _reject_input_aliases(fixed_outputs, inputs)
275
- _reject_output_aliases(fixed_outputs)
276
- existing = [path.as_posix() for path in (features_json, features_csv) if path and path.exists()]
279
+ # Voxel mode writes one map per selected feature, keyed like the extraction result.
280
+ map_paths = {
281
+ f"original_{name}": directory / MAPS_DIR / f"original_{name}.nii.gz"
282
+ for name in settings.features
283
+ } if voxel else {}
284
+ outputs = (*fixed_outputs, *map_paths.values())
285
+ _reject_input_aliases(outputs, inputs)
286
+ _reject_output_aliases(outputs)
287
+ # Refuse before extraction; maps can exist without features.json from an earlier run.
288
+ existing = [path.as_posix() for path in outputs if path.exists()]
277
289
  _check_output_replacement(existing, overwrite=overwrite, image=source_image, mask=source_mask)
278
290
 
291
+ from mlxradiomics.engine import extract
292
+
279
293
  try:
280
294
  result = extract(
281
295
  image.array, mask.array, settings=settings, spacing=image.spacing, voxel=voxel
@@ -284,17 +298,8 @@ def run(
284
298
  raise InvalidInputError(str(error)) from error
285
299
  except Exception as error:
286
300
  raise ModelExecutionError(f"mlxradiomics extraction failed: {error}") from error
287
-
288
- map_paths = {
289
- name: directory / MAPS_DIR / f"{name}.nii.gz" for name in result.features
290
- } if voxel else {}
291
- _reject_input_aliases(tuple(map_paths.values()), inputs)
292
- _reject_output_aliases((*fixed_outputs, *map_paths.values()))
293
- # Interrupted voxel runs may have maps without final features.json metadata.
294
- existing_maps = [path.as_posix() for path in map_paths.values() if path.exists()]
295
- _check_output_replacement(
296
- existing_maps, overwrite=overwrite, image=source_image, mask=source_mask,
297
- )
301
+ if voxel and set(result.features) != set(map_paths):
302
+ raise ModelExecutionError("voxel extraction did not return one map per selected feature")
298
303
 
299
304
  directory.mkdir(parents=True, exist_ok=True)
300
305
  details: RunDetails = {
@@ -307,30 +312,47 @@ def run(
307
312
  }
308
313
  maps: dict[str, str] = {}
309
314
  payload: dict[str, JsonValue]
310
- if voxel:
311
- for name, value in result.features.items():
312
- if not isinstance(value, np.ndarray):
313
- raise ModelExecutionError(f"voxel feature '{name}' did not return a map")
314
- map_path = map_paths[name]
315
- write_feature_map(map_path, value, reference=image)
316
- maps[name] = map_path.resolve().as_posix()
317
- payload = {
318
- "schema_version": 1, "mode": "voxel", "details": cast(JsonValue, details),
319
- "maps": cast(JsonValue, maps),
320
- }
321
- else:
322
- values: dict[str, float] = {}
323
- for name, value in result.features.items():
324
- if isinstance(value, np.ndarray):
325
- raise ModelExecutionError(f"ROI feature '{name}' did not return a scalar")
326
- values[name] = value
327
- assert features_csv is not None # not voxel, so features_csv was set above
328
- _write_csv(features_csv, values)
329
- payload = {
330
- "schema_version": 1, "mode": "roi", "details": cast(JsonValue, details),
331
- "features": cast(JsonValue, values),
332
- }
333
- features_json.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
315
+ # Write beside each target and rename only once every output is written, so a failed
316
+ # run keeps earlier outputs.
317
+ staged: dict[Path, Path] = {}
318
+
319
+ def stage(target: Path) -> Path:
320
+ temporary = target.with_name(f".{os.getpid()}.{target.name}")
321
+ staged[target] = temporary
322
+ return temporary
323
+
324
+ try:
325
+ if voxel:
326
+ for name, value in result.features.items():
327
+ if not isinstance(value, np.ndarray):
328
+ raise ModelExecutionError(f"voxel feature '{name}' did not return a map")
329
+ map_path = map_paths[name]
330
+ write_feature_map(stage(map_path), value, reference=image)
331
+ maps[name] = map_path.resolve().as_posix()
332
+ payload = {
333
+ "schema_version": 1, "mode": "voxel", "details": cast(JsonValue, details),
334
+ "maps": cast(JsonValue, maps),
335
+ }
336
+ else:
337
+ values: dict[str, float] = {}
338
+ for name, value in result.features.items():
339
+ if isinstance(value, np.ndarray):
340
+ raise ModelExecutionError(f"ROI feature '{name}' did not return a scalar")
341
+ values[name] = value
342
+ assert features_csv is not None # not voxel, so features_csv was set above
343
+ _write_csv(stage(features_csv), values)
344
+ payload = {
345
+ "schema_version": 1, "mode": "roi", "details": cast(JsonValue, details),
346
+ "features": cast(JsonValue, values),
347
+ }
348
+ stage(features_json).write_text(
349
+ json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8"
350
+ )
351
+ for target, temporary in staged.items():
352
+ os.replace(temporary, target)
353
+ finally:
354
+ for temporary in staged.values():
355
+ temporary.unlink(missing_ok=True)
334
356
 
335
357
  return {
336
358
  "outputs": {
@@ -1,14 +0,0 @@
1
- __pycache__/
2
- *.py[cod]
3
- .pytest_cache/
4
- .ruff_cache/
5
- .venv
6
- dist/
7
- build/
8
- results/
9
- *.nii
10
- *.nii.gz
11
- *.dcm
12
- *.npz
13
- !tests/fixtures/darwin-arm64/*.npz
14
- *.egg-info/
@@ -1,67 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: mlxradiomics
3
- Version: 0.1.0.dev8
4
- Summary: Apple Silicon Metal radiomics with bounded voxel batches.
5
- Project-URL: Repository, https://github.com/MedMLX/mlxradiomics
6
- License-Expression: Apache-2.0 AND MIT AND BSD-3-Clause
7
- License-File: LICENSE
8
- License-File: THIRD_PARTY_NOTICES.md
9
- Classifier: Operating System :: MacOS :: MacOS X
10
- Requires-Python: <3.15,>=3.13
11
- Requires-Dist: medmlx-core==0.2.5
12
- Requires-Dist: mlx==0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'
13
- Requires-Dist: nibabel<6,>=5.3
14
- Requires-Dist: numpy<3,>=2.0
15
- Requires-Dist: pyyaml<7,>=6
16
- Requires-Dist: simpleitk==2.5.6
17
- Provides-Extra: io
18
- Provides-Extra: lbp
19
- Requires-Dist: scipy==1.18.1; extra == 'lbp'
20
- Requires-Dist: trimesh==4.9.0; extra == 'lbp'
21
- Description-Content-Type: text/markdown
22
-
23
- # mlxradiomics
24
-
25
- Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
26
-
27
- | Input | Output |
28
- | :--- | :--- |
29
- | Aligned image + label mask | ROI features or voxel maps |
30
-
31
- **Apple Silicon · Metal · Python 3.13 / 3.14** · [uv](https://docs.astral.sh/uv/)
32
-
33
- ## Quick start
34
-
35
- ```bash
36
- uv venv --python 3.13
37
- source .venv/bin/activate
38
- uv pip install "mlxradiomics==0.1.0.dev8"
39
- ```
40
-
41
- ## MedMLX runner
42
-
43
- With an aligned image and label-mask file:
44
-
45
- ```python
46
- from mlxradiomics.medmlx import run
47
-
48
- result = run(
49
- image_path="image.nii.gz",
50
- mask_path="mask.nii.gz",
51
- output_dir="features",
52
- )
53
- ```
54
-
55
- File I/O and YAML support are included in the standard installation. No model
56
- weights are required. The [API guide](https://github.com/MedMLX/mlxradiomics/blob/main/docs/technical.md) covers label selection, parameter
57
- files, voxel maps and the lower-level array interface.
58
-
59
- ## Documentation
60
-
61
- [API, settings and validation](https://github.com/MedMLX/mlxradiomics/blob/main/docs/technical.md)
62
-
63
- ## License
64
-
65
- Apache-2.0; license and third-party notices are included in the distribution.
66
-
67
- For research and education. Outputs require human review.
@@ -1,45 +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.dev8"
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](https://github.com/MedMLX/mlxradiomics/blob/main/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](https://github.com/MedMLX/mlxradiomics/blob/main/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.