mlxradiomics 0.1.0.dev9__tar.gz → 0.1.0.dev10__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 (65) hide show
  1. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/.gitignore +0 -1
  2. mlxradiomics-0.1.0.dev10/PKG-INFO +339 -0
  3. mlxradiomics-0.1.0.dev10/README.md +301 -0
  4. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/THIRD_PARTY_NOTICES.md +57 -3
  5. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/pyproject.toml +8 -11
  6. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/__init__.py +33 -5
  7. mlxradiomics-0.1.0.dev10/src/mlxradiomics/_json.py +23 -0
  8. mlxradiomics-0.1.0.dev10/src/mlxradiomics/_publication.py +277 -0
  9. mlxradiomics-0.1.0.dev10/src/mlxradiomics/_runtime.py +45 -0
  10. mlxradiomics-0.1.0.dev10/src/mlxradiomics/_typing.py +275 -0
  11. mlxradiomics-0.1.0.dev10/src/mlxradiomics/aggregation.py +228 -0
  12. mlxradiomics-0.1.0.dev10/src/mlxradiomics/config.py +377 -0
  13. mlxradiomics-0.1.0.dev10/src/mlxradiomics/count_statistics.py +48 -0
  14. mlxradiomics-0.1.0.dev10/src/mlxradiomics/distributions.py +262 -0
  15. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/eigen.py +55 -25
  16. mlxradiomics-0.1.0.dev10/src/mlxradiomics/engine.py +783 -0
  17. mlxradiomics-0.1.0.dev10/src/mlxradiomics/export.py +343 -0
  18. mlxradiomics-0.1.0.dev10/src/mlxradiomics/filters.py +1215 -0
  19. mlxradiomics-0.1.0.dev10/src/mlxradiomics/ibsi_manifest.json +8086 -0
  20. mlxradiomics-0.1.0.dev10/src/mlxradiomics/intensity_histogram.py +297 -0
  21. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/io.py +190 -18
  22. mlxradiomics-0.1.0.dev10/src/mlxradiomics/ivh.py +248 -0
  23. mlxradiomics-0.1.0.dev10/src/mlxradiomics/lbp.py +256 -0
  24. mlxradiomics-0.1.0.dev10/src/mlxradiomics/lbp3d.py +208 -0
  25. mlxradiomics-0.1.0.dev10/src/mlxradiomics/local_intensity.py +156 -0
  26. mlxradiomics-0.1.0.dev10/src/mlxradiomics/matrices.py +257 -0
  27. mlxradiomics-0.1.0.dev10/src/mlxradiomics/medmlx.py +445 -0
  28. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/mesh_tables.json +2307 -1
  29. mlxradiomics-0.1.0.dev10/src/mlxradiomics/morphology.py +363 -0
  30. mlxradiomics-0.1.0.dev10/src/mlxradiomics/parameters.py +404 -0
  31. mlxradiomics-0.1.0.dev10/src/mlxradiomics/pipeline.py +346 -0
  32. mlxradiomics-0.1.0.dev10/src/mlxradiomics/precision.py +235 -0
  33. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/preprocessing.py +124 -34
  34. mlxradiomics-0.1.0.dev10/src/mlxradiomics/py.typed +0 -0
  35. mlxradiomics-0.1.0.dev10/src/mlxradiomics/recursive_gaussian.py +367 -0
  36. mlxradiomics-0.1.0.dev10/src/mlxradiomics/riesz_steering.py +733 -0
  37. mlxradiomics-0.1.0.dev10/src/mlxradiomics/shape.py +1881 -0
  38. mlxradiomics-0.1.0.dev10/src/mlxradiomics/spatial.py +519 -0
  39. mlxradiomics-0.1.0.dev10/src/mlxradiomics/statistics.py +725 -0
  40. mlxradiomics-0.1.0.dev10/src/mlxradiomics/study.py +165 -0
  41. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/texture.py +63 -59
  42. mlxradiomics-0.1.0.dev10/src/mlxradiomics/transforms.py +1139 -0
  43. mlxradiomics-0.1.0.dev10/src/mlxradiomics/voxel_output.py +172 -0
  44. mlxradiomics-0.1.0.dev9/PKG-INFO +0 -193
  45. mlxradiomics-0.1.0.dev9/README.md +0 -156
  46. mlxradiomics-0.1.0.dev9/src/mlxradiomics/_runtime.py +0 -28
  47. mlxradiomics-0.1.0.dev9/src/mlxradiomics/_typing.py +0 -110
  48. mlxradiomics-0.1.0.dev9/src/mlxradiomics/config.py +0 -191
  49. mlxradiomics-0.1.0.dev9/src/mlxradiomics/distributions.py +0 -107
  50. mlxradiomics-0.1.0.dev9/src/mlxradiomics/engine.py +0 -519
  51. mlxradiomics-0.1.0.dev9/src/mlxradiomics/lbp.py +0 -135
  52. mlxradiomics-0.1.0.dev9/src/mlxradiomics/lbp3d.py +0 -143
  53. mlxradiomics-0.1.0.dev9/src/mlxradiomics/medmlx.py +0 -379
  54. mlxradiomics-0.1.0.dev9/src/mlxradiomics/pipeline.py +0 -135
  55. mlxradiomics-0.1.0.dev9/src/mlxradiomics/precision.py +0 -101
  56. mlxradiomics-0.1.0.dev9/src/mlxradiomics/recursive_gaussian.py +0 -193
  57. mlxradiomics-0.1.0.dev9/src/mlxradiomics/shape.py +0 -269
  58. mlxradiomics-0.1.0.dev9/src/mlxradiomics/spatial.py +0 -286
  59. mlxradiomics-0.1.0.dev9/src/mlxradiomics/statistics.py +0 -201
  60. mlxradiomics-0.1.0.dev9/src/mlxradiomics/transforms.py +0 -326
  61. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/LICENSE +0 -0
  62. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/histogram.py +0 -0
  63. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/reduction.py +0 -0
  64. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/spline.py +0 -0
  65. {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/wavelet_tables.json +0 -0
@@ -35,4 +35,3 @@ htmlcov/
35
35
  *.h5
36
36
  *.npy
37
37
  *.npz
38
- !tests/fixtures/**/*.npz
@@ -0,0 +1,339 @@
1
+ Metadata-Version: 2.5
2
+ Name: mlxradiomics
3
+ Version: 0.1.0.dev10
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.dev10/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 AND CC-BY-4.0
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: scipy<2,>=1.16.3
32
+ Requires-Dist: simpleitk==2.5.6
33
+ Provides-Extra: io
34
+ Provides-Extra: lbp
35
+ Requires-Dist: scipy==1.18.1; extra == 'lbp'
36
+ Requires-Dist: trimesh==4.9.0; extra == 'lbp'
37
+ Description-Content-Type: text/markdown
38
+
39
+ <div align="center">
40
+
41
+ # mlx-radiomics
42
+
43
+ Extract radiomics features and voxel maps on the Apple Silicon GPU with native MLX.
44
+
45
+ [![PyPI](https://img.shields.io/pypi/v/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
46
+ [![Python](https://img.shields.io/pypi/pyversions/mlxradiomics)](https://pypi.org/project/mlxradiomics/)
47
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev10/LICENSE)
48
+ [![Apple Silicon](https://img.shields.io/badge/Apple_Silicon-MLX-black?logo=apple)](https://github.com/ml-explore/mlx)
49
+ [![MedMLX](https://img.shields.io/badge/MedMLX-runtime-A51C30)](https://github.com/MedMLX/medmlx)
50
+
51
+ [MedMLX](https://github.com/MedMLX/medmlx)
52
+
53
+ [Scientific qualification](docs/scientific-qualification.md) · [Technical notes](docs/technical.md)
54
+
55
+ <img src="https://raw.githubusercontent.com/MedMLX/mlx-radiomics/v0.1.0.dev10/docs/showcase.png" alt="Radiomics voxel maps computed from an image and label mask" width="100%">
56
+
57
+ </div>
58
+
59
+ | Input | Output |
60
+ | :--- | :--- |
61
+ | Aligned image + label mask | ROI features or voxel maps |
62
+
63
+ ## Use with MedMLX
64
+
65
+ 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.
66
+
67
+ ```sh
68
+ uv tool install --python 3.13 "medmlx[vision,mcp]"
69
+ MEDMLX="$(uv tool dir --bin --color never)/medmlx"
70
+ mkdir -p "$HOME/medmlx-work"
71
+ claude mcp add --scope user medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"
72
+ ```
73
+
74
+ 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`.
75
+
76
+ > **For AI agents:** prefer the MedMLX MCP tools (`list_models`, `describe_model`, `model_readiness`, `run_model`, `get_job`) over writing Python against this package.
77
+
78
+ ## Install
79
+
80
+ ```bash
81
+ uv venv --python 3.13
82
+ source .venv/bin/activate
83
+ uv pip install "mlxradiomics>=0.1.0.dev10"
84
+ ```
85
+
86
+ ## Run
87
+
88
+ With an aligned image and label-mask file:
89
+
90
+ ```python
91
+ from mlxradiomics.medmlx import run
92
+
93
+ result = run(
94
+ image_path="image.nii.gz",
95
+ mask_path="mask.nii.gz",
96
+ output_dir="features",
97
+ )
98
+ ```
99
+
100
+ File I/O and YAML support are included in the standard installation. No model
101
+ weights are required.
102
+
103
+ ### Inputs and outputs
104
+
105
+ | Argument | Meaning |
106
+ | --- | --- |
107
+ | `image_path` | One 2D or 3D image: `.nii`, `.nii.gz`, `.nrrd` or `.nhdr` |
108
+ | `mask_path` | Integer label mask. A geometry mismatch is refused unless the params enable `correctMask` or `resampledPixelSpacing` |
109
+ | `output_dir` | Directory for the outputs; created if missing |
110
+ | `params` or `params_path` | Optional PyRadiomics-style settings, as a mapping or a YAML file; pass one at most. Supports `setting`, `featureClass` and `imageType` |
111
+ | `label` | Optional mask label; defaults to the params label, or 1 |
112
+ | `voxel` | `False` for one value per feature; `True` for one map per feature |
113
+ | `overwrite` | `False` by default, which refuses to replace existing outputs |
114
+ | `temporary_dir` | Existing directory for voxel scratch; defaults to the system temporary directory |
115
+ | `max_temporary_mib` | Positive integer cap for logical voxel scratch, excluding staged/final outputs; requires voxel mode |
116
+
117
+ ROI mode writes `features.json` and `features.csv`. Voxel mode writes `features.json`
118
+ and one float32 NIfTI per feature under `maps/`, on the processed grid and zero outside
119
+ the ROI. The runner spools evaluated ROI batches and writes one disk-backed map at
120
+ a time. Scratch includes the compact ROI spool and one full float32 grid; its logical
121
+ size is checked before extraction and each batch. Mapped pages can remain in process
122
+ RSS, so the scratch cap is not a RAM cap. Output staging stays in the output
123
+ directory and has a separate free-space admission estimate.
124
+ Temporary disk use grows with ROI size and feature count;
125
+ the Python APIs keep maps in memory unless you supply `voxel_sink`.
126
+ Feature keys look like `original_glcm_Contrast`. Runner parameter files
127
+ accept the supported PyRadiomics `setting`, `featureClass` and `imageType` sections,
128
+ including derived images, `resampledPixelSpacing`, `interpolator`, `correctMask` and
129
+ `padDistance`. Unsupported settings, image types and per-image overrides are rejected
130
+ before extraction. Effective settings and processed/source grids are recorded in
131
+ `features.json`.
132
+
133
+ Undefined features are NaN, and float32 overflow can give infinity. `features.json`
134
+ uses report schema 2: finite values are JSON numbers, and non-finite values are
135
+ the strings `"NaN"`, `"Infinity"` or `"-Infinity"`, including in metadata. CSV files
136
+ and voxel maps retain their numerical values. SimpleITK reads stored non-finite
137
+ NIfTI voxels as zero, so read voxel maps with NiBabel. With detached NRRD or NIfTI
138
+ data files, existing outputs are never
139
+ replaced, even with `overwrite=True`; use a new output directory for each run.
140
+ Invalid inputs raise `InvalidInputError`; extraction failures raise
141
+ `ModelExecutionError`.
142
+
143
+ The runner returns a standard MedMLX `outputs` list: reports, ROI measurements
144
+ and voxel scalar fields with their coordinate space. Maps identify `image_path`
145
+ as their voxel grid only when its shape and geometry are unchanged. Cropped or
146
+ resampled maps use physical coordinates and retain their source and processed
147
+ geometry in the report. Grouped
148
+ paths are under `result["files"]` (`features_json`, `features_csv` and `maps`).
149
+ This replaces the earlier dictionary-valued `outputs` return field. The saved
150
+ feature report remains schema 2.
151
+
152
+ The runner refuses symbolic-link output files and overlapping calls using the
153
+ same output directory. Each run writes private staging files before publication;
154
+ if publication fails, previous outputs are restored and new outputs removed.
155
+ Readers can observe individual file replacements during publication, and the files
156
+ of one run are not published as one atomic set, so consume outputs only after the
157
+ run has returned. The directory
158
+ lock releases when a process exits; abrupt termination can leave private staging,
159
+ which the next run in that directory reclaims. A rollback failure retains recovery
160
+ copies at the path reported by the error.
161
+
162
+ ### Features
163
+
164
+ `FEATURES` lists 190 selectable outputs, including all 116 non-deprecated
165
+ PyRadiomics names. The default remains the original 93 intensity and texture
166
+ outputs; request additions and shape features explicitly. A versioned manifest
167
+ maps 169 IBSI reference-valued public outputs to 167 scientific IDs. Five further
168
+ manual definitions, the oriented minimum bounding-box and minimum-volume enclosing
169
+ ellipsoid densities and the IVH area under the curve, are implemented without IBSI
170
+ reference values. Official-phantom comparisons retain the explicit AEE-area
171
+ reference exception. See the [scientific contract](docs/scientific-qualification.md) for
172
+ executed coverage and filter qualification.
173
+
174
+ | Family | Features | Modes |
175
+ | --- | ---: | --- |
176
+ | First order | 21 | ROI and voxel |
177
+ | Intensity histogram | 23 | ROI and voxel |
178
+ | GLCM | 26 | ROI and voxel |
179
+ | GLDM / NGLDM | 17 | ROI and voxel |
180
+ | NGTDM | 5 | ROI and voxel |
181
+ | GLRLM | 16 | ROI and voxel |
182
+ | GLSZM | 16 | ROI and voxel |
183
+ | GLDZM | 16 | ROI and voxel |
184
+ | Local intensity | 2 | 3D ROI |
185
+ | Intensity-volume histogram | 7 | ROI and voxel |
186
+ | Shape | 32 | 3D ROI |
187
+ | Shape2D | 9 | 2D ROI, or one slice of a 3D ROI |
188
+
189
+ `definition_profile="native"` preserves existing conventions; `"ibsi"` selects
190
+ explicit IBSI definitions, including sample-covariance shape axes. GLCM/GLRLM have six selectable aggregation modes;
191
+ GLSZM/GLDZM/NGTDM/GLDM have three. Fixed-count and fixed-width boundaries use exact
192
+ source-value comparisons. Local peaks use physical 1 cm³ spheres; IVH has its own
193
+ intensity calibration. The [technical examples](docs/technical.md#explicit-definitions-and-filters)
194
+ show profile, aggregation, IVH and filter settings in Python and parameter files.
195
+
196
+ ### Python API
197
+
198
+ ```python
199
+ from mlxradiomics import Settings, extract
200
+
201
+ # image and mask are aligned NumPy arrays; spacing follows their axis order.
202
+ result = extract(
203
+ image, mask, spacing=(3.0, 1.0, 1.0),
204
+ settings=Settings(label=2, bin_width=25, features=("firstorder_Mean", "glcm_Contrast")),
205
+ voxel=True,
206
+ )
207
+ mean_map = result.features["original_firstorder_Mean"]
208
+ ```
209
+
210
+ `FEATURES` lists every supported name. `Settings` also covers fixed-count binning
211
+ (`bin_count`), normalization, outlier removal, resegmentation, GLCM distances,
212
+ kernel radius and `masked_kernel`. With `masked_kernel=False`, neighbourhoods sample
213
+ the whole image but outputs stay inside the ROI. `scratch_mib` sets the batch size
214
+ from a scratch estimate; it is not a memory cap.
215
+
216
+ `extract_images` adds derived images through `TransformSettings`: square, square
217
+ root, logarithm, exponential, gradient, wavelets, LoG, LBP2D, LBP3D, mean,
218
+ Laws, Gabor and radial Simoncelli filters, IBSI sampled-kernel LoG, undecimated
219
+ separable wavelets, and Riesz transforms of a LoG or
220
+ Simoncelli base with optional local structure-tensor alignment. LBP3D needs
221
+ the `lbp` extra. Output keys carry the image prefix, such as
222
+ `wavelet-HHL_glcm_Contrast`. `extract_files` reads NIfTI or NRRD files and adds
223
+ `ImageSettings` for PyRadiomics-style resampling and mask correction. Its
224
+ `ibsi_interpolation=IbsiInterpolation(spacing=(3.0, 2.0, 2.0))` option selects the
225
+ centered IBSI grid and partial-volume mask through the Python file APIs; spacing
226
+ uses array axis order. Parameter files retain their PyRadiomics-style spatial
227
+ controls. Mismatched image and mask geometry requires explicit resampling or
228
+ mask correction.
229
+
230
+ Ordinary intensity resampling preserves fractional interpolated values regardless
231
+ of the source file's integer or floating storage. Masks retain integer labels.
232
+ LBP2D variance likewise retains fractional values for integer 3D inputs. Explicit
233
+ IBSI interpolation rounding remains controlled by its selected protocol.
234
+
235
+ `extract`, `extract_images` and `extract_files` accept `voxel_sink` in voxel mode
236
+ to consume evaluated batches without retaining full maps. Derived-image feature
237
+ names keep their prefixes; file-based batch coordinates follow the processed grid.
238
+ `export_images` and `export_files` add a supported disk-backed exporter: each
239
+ derived image gets its own bounded batch store, and one float32 NIfTI map at a
240
+ time is written through private staging and atomic publication. `run_study` runs
241
+ one or more cases and labels into separate `<case>/label-<n>` directories with an
242
+ explicit status for every combination.
243
+
244
+ ### Execution metadata
245
+
246
+ `extract`, `extract_images` and `extract_files` return execution metadata; the
247
+ runner saves it in `features.json` under `details.execution`.
248
+
249
+ | Field | Meaning |
250
+ | --- | --- |
251
+ | `runtime` | Package versions, Python, platform, Metal device and supplied `MLX_ENABLE_TF32` setting; null means unset |
252
+ | `settings` | Effective feature, binning, normalization, resegmentation and neighborhood options |
253
+ | `array_shape`, `array_dtype`, `spacing` | Processed shape, supplied dtype and spacing in NumPy axis order |
254
+ | `roi_voxels`, `excluded_voxels` | Intensity ROI size and array voxels outside it |
255
+ | `feature_validity` | Sample counts for every fully prefixed feature, including streamed and derived-image results |
256
+ | `transforms` | Effective derived-image settings |
257
+ | `source_geometry`, `image_geometry` | Input and processed grids: shape/spacing in NumPy order, origin/direction in ITK LPS order |
258
+ | `image_settings` | Effective file resampling, interpolation, correction and padding options |
259
+
260
+ Per-feature counts distinguish `finite`, `valid_zero` (a subset of finite),
261
+ `nan`, `positive_infinity`, `negative_infinity` and `excluded` (uncomputed map
262
+ background stored as zero). Finite, NaN, infinite and excluded counts sum to the
263
+ map's voxel count; ROI features have one computed sample and no excluded samples.
264
+ Counts accumulate before export, including when `voxel_sink` consumes batches,
265
+ and retain every derived-image prefix. Top-level ROI counts describe the intensity
266
+ ROI; shape follows the separately recorded `resegment_shape` setting.
267
+
268
+ ### Examples
269
+
270
+ Runnable scripts in [`examples/`](examples) cover the public workflows:
271
+
272
+ ```bash
273
+ python examples/roi_from_files.py image.nii.gz mask.nii.gz outputs/roi --label 1
274
+ python examples/derived_voxel_export.py image.nii.gz mask.nii.gz outputs/maps --label 1
275
+ python examples/multilabel_study.py outputs/study \
276
+ --case case-a image.nii.gz mask.nii.gz --labels 1 2
277
+ ```
278
+
279
+ Resampling and advanced parameter files use the same runner:
280
+
281
+ ```yaml
282
+ setting:
283
+ binWidth: 25
284
+ resampledPixelSpacing: [1.0, 1.0, 1.0]
285
+ interpolator: sitkLinear
286
+ padDistance: 1
287
+ imageType:
288
+ Original: {}
289
+ Wavelet:
290
+ level: 1
291
+ featureClass:
292
+ firstorder: [Mean, Entropy]
293
+ glcm: [Contrast, JointEntropy]
294
+ ```
295
+
296
+ Feature arithmetic is float32 on Metal; binning uses float64 on the host. Importing
297
+ the package does not import MLX. Computation needs Apple Silicon with Metal and has
298
+ no CPU fallback.
299
+
300
+ ### Limits
301
+
302
+ - Shape and physical local-intensity features are ROI-only. Local intensity and
303
+ intensity-dependent morphology require 3D input. Shape2D on a 3D input needs
304
+ `force2d_axis` and an ROI in exactly one slice on that axis. `force2d_axis` counts NumPy axes.
305
+ - Voxel mode needs at least two ROI voxels.
306
+ - The default recursive LoG needs a 3D image with at least four samples per axis, large enough for the
307
+ requested sigma. Each sigma/spacing ratio must be at most 200; singular or
308
+ numerically unresolved derivative normalization raises a precision error.
309
+ - LBP3D needs 3D data and a masked kernel; integer images must be 8- or 16-bit.
310
+ Samples too close to their binary threshold raise a precision error.
311
+ - GLCM direction validity is local to each ROI or voxel neighborhood. Empty
312
+ directions are omitted; MCC averages directions with at least two occupied row
313
+ and column gray levels and is NaN if none qualify. Map backgrounds remain 0.
314
+ - NGTDM counts only centers with at least one valid neighbor. No eligible centers
315
+ gives NaN. Native singular ratios distinguish positive infinity from undefined
316
+ `0/0`; the IBSI profile selects its explicit finite degenerate conventions.
317
+ - Paired NIfTI/Analyze headers named `.nii` or `.nii.gz` are rejected; convert them
318
+ to single-file NIfTI or NRRD.
319
+ - Unsupported settings raise an error; nothing falls back to PyRadiomics.
320
+ - IBSI 2 agreement for Simoncelli responses requires
321
+ `simoncelli_grid=FourierGrid.CENTERED` (parameter key `grid: centered`). The
322
+ default DFT grid follows the manual's text; on it the published Simoncelli maps
323
+ `8_a_2`/`8_a_3` and two IBSI 2 CT statistics fall outside the published tolerances.
324
+ - Simoncelli and Riesz filters are experimental. They use the MLX Metal FFT, and
325
+ MLX 0.32.4 has an out-of-bounds FFT write that can silently modify a neighbouring
326
+ array ([ml-explore/mlx#4733](https://github.com/ml-explore/mlx/issues/4733)). The
327
+ fix is merged upstream but not yet in an MLX release; this package moves its pin
328
+ once one is published. All other features do not use the FFT.
329
+ - Qualified hardware is Apple M5 Max with 128 GiB on macOS 27.2. Other Apple
330
+ Silicon generations, 16–32 GiB machines and other macOS versions are untested.
331
+ - Mathematical definitions and independent regressions are described in
332
+ [scientific qualification](docs/scientific-qualification.md).
333
+
334
+ Development setup is described in the [environment guide](environment/README.md).
335
+
336
+ ## License
337
+
338
+ [Apache-2.0](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev10/LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md), including CC BY 4.0 attribution
339
+ for adapted IBSI manifest definitions.
@@ -0,0 +1,301 @@
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.dev10/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
+ [Scientific qualification](docs/scientific-qualification.md) · [Technical notes](docs/technical.md)
16
+
17
+ <img src="https://raw.githubusercontent.com/MedMLX/mlx-radiomics/v0.1.0.dev10/docs/showcase.png" alt="Radiomics voxel maps computed from an image and label mask" width="100%">
18
+
19
+ </div>
20
+
21
+ | Input | Output |
22
+ | :--- | :--- |
23
+ | Aligned image + label mask | ROI features or voxel maps |
24
+
25
+ ## Use with MedMLX
26
+
27
+ 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.
28
+
29
+ ```sh
30
+ uv tool install --python 3.13 "medmlx[vision,mcp]"
31
+ MEDMLX="$(uv tool dir --bin --color never)/medmlx"
32
+ mkdir -p "$HOME/medmlx-work"
33
+ claude mcp add --scope user medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"
34
+ ```
35
+
36
+ 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`.
37
+
38
+ > **For AI agents:** prefer the MedMLX MCP tools (`list_models`, `describe_model`, `model_readiness`, `run_model`, `get_job`) over writing Python against this package.
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ uv venv --python 3.13
44
+ source .venv/bin/activate
45
+ uv pip install "mlxradiomics>=0.1.0.dev10"
46
+ ```
47
+
48
+ ## Run
49
+
50
+ With an aligned image and label-mask file:
51
+
52
+ ```python
53
+ from mlxradiomics.medmlx import run
54
+
55
+ result = run(
56
+ image_path="image.nii.gz",
57
+ mask_path="mask.nii.gz",
58
+ output_dir="features",
59
+ )
60
+ ```
61
+
62
+ File I/O and YAML support are included in the standard installation. No model
63
+ weights are required.
64
+
65
+ ### Inputs and outputs
66
+
67
+ | Argument | Meaning |
68
+ | --- | --- |
69
+ | `image_path` | One 2D or 3D image: `.nii`, `.nii.gz`, `.nrrd` or `.nhdr` |
70
+ | `mask_path` | Integer label mask. A geometry mismatch is refused unless the params enable `correctMask` or `resampledPixelSpacing` |
71
+ | `output_dir` | Directory for the outputs; created if missing |
72
+ | `params` or `params_path` | Optional PyRadiomics-style settings, as a mapping or a YAML file; pass one at most. Supports `setting`, `featureClass` and `imageType` |
73
+ | `label` | Optional mask label; defaults to the params label, or 1 |
74
+ | `voxel` | `False` for one value per feature; `True` for one map per feature |
75
+ | `overwrite` | `False` by default, which refuses to replace existing outputs |
76
+ | `temporary_dir` | Existing directory for voxel scratch; defaults to the system temporary directory |
77
+ | `max_temporary_mib` | Positive integer cap for logical voxel scratch, excluding staged/final outputs; requires voxel mode |
78
+
79
+ ROI mode writes `features.json` and `features.csv`. Voxel mode writes `features.json`
80
+ and one float32 NIfTI per feature under `maps/`, on the processed grid and zero outside
81
+ the ROI. The runner spools evaluated ROI batches and writes one disk-backed map at
82
+ a time. Scratch includes the compact ROI spool and one full float32 grid; its logical
83
+ size is checked before extraction and each batch. Mapped pages can remain in process
84
+ RSS, so the scratch cap is not a RAM cap. Output staging stays in the output
85
+ directory and has a separate free-space admission estimate.
86
+ Temporary disk use grows with ROI size and feature count;
87
+ the Python APIs keep maps in memory unless you supply `voxel_sink`.
88
+ Feature keys look like `original_glcm_Contrast`. Runner parameter files
89
+ accept the supported PyRadiomics `setting`, `featureClass` and `imageType` sections,
90
+ including derived images, `resampledPixelSpacing`, `interpolator`, `correctMask` and
91
+ `padDistance`. Unsupported settings, image types and per-image overrides are rejected
92
+ before extraction. Effective settings and processed/source grids are recorded in
93
+ `features.json`.
94
+
95
+ Undefined features are NaN, and float32 overflow can give infinity. `features.json`
96
+ uses report schema 2: finite values are JSON numbers, and non-finite values are
97
+ the strings `"NaN"`, `"Infinity"` or `"-Infinity"`, including in metadata. CSV files
98
+ and voxel maps retain their numerical values. SimpleITK reads stored non-finite
99
+ NIfTI voxels as zero, so read voxel maps with NiBabel. With detached NRRD or NIfTI
100
+ data files, existing outputs are never
101
+ replaced, even with `overwrite=True`; use a new output directory for each run.
102
+ Invalid inputs raise `InvalidInputError`; extraction failures raise
103
+ `ModelExecutionError`.
104
+
105
+ The runner returns a standard MedMLX `outputs` list: reports, ROI measurements
106
+ and voxel scalar fields with their coordinate space. Maps identify `image_path`
107
+ as their voxel grid only when its shape and geometry are unchanged. Cropped or
108
+ resampled maps use physical coordinates and retain their source and processed
109
+ geometry in the report. Grouped
110
+ paths are under `result["files"]` (`features_json`, `features_csv` and `maps`).
111
+ This replaces the earlier dictionary-valued `outputs` return field. The saved
112
+ feature report remains schema 2.
113
+
114
+ The runner refuses symbolic-link output files and overlapping calls using the
115
+ same output directory. Each run writes private staging files before publication;
116
+ if publication fails, previous outputs are restored and new outputs removed.
117
+ Readers can observe individual file replacements during publication, and the files
118
+ of one run are not published as one atomic set, so consume outputs only after the
119
+ run has returned. The directory
120
+ lock releases when a process exits; abrupt termination can leave private staging,
121
+ which the next run in that directory reclaims. A rollback failure retains recovery
122
+ copies at the path reported by the error.
123
+
124
+ ### Features
125
+
126
+ `FEATURES` lists 190 selectable outputs, including all 116 non-deprecated
127
+ PyRadiomics names. The default remains the original 93 intensity and texture
128
+ outputs; request additions and shape features explicitly. A versioned manifest
129
+ maps 169 IBSI reference-valued public outputs to 167 scientific IDs. Five further
130
+ manual definitions, the oriented minimum bounding-box and minimum-volume enclosing
131
+ ellipsoid densities and the IVH area under the curve, are implemented without IBSI
132
+ reference values. Official-phantom comparisons retain the explicit AEE-area
133
+ reference exception. See the [scientific contract](docs/scientific-qualification.md) for
134
+ executed coverage and filter qualification.
135
+
136
+ | Family | Features | Modes |
137
+ | --- | ---: | --- |
138
+ | First order | 21 | ROI and voxel |
139
+ | Intensity histogram | 23 | ROI and voxel |
140
+ | GLCM | 26 | ROI and voxel |
141
+ | GLDM / NGLDM | 17 | ROI and voxel |
142
+ | NGTDM | 5 | ROI and voxel |
143
+ | GLRLM | 16 | ROI and voxel |
144
+ | GLSZM | 16 | ROI and voxel |
145
+ | GLDZM | 16 | ROI and voxel |
146
+ | Local intensity | 2 | 3D ROI |
147
+ | Intensity-volume histogram | 7 | ROI and voxel |
148
+ | Shape | 32 | 3D ROI |
149
+ | Shape2D | 9 | 2D ROI, or one slice of a 3D ROI |
150
+
151
+ `definition_profile="native"` preserves existing conventions; `"ibsi"` selects
152
+ explicit IBSI definitions, including sample-covariance shape axes. GLCM/GLRLM have six selectable aggregation modes;
153
+ GLSZM/GLDZM/NGTDM/GLDM have three. Fixed-count and fixed-width boundaries use exact
154
+ source-value comparisons. Local peaks use physical 1 cm³ spheres; IVH has its own
155
+ intensity calibration. The [technical examples](docs/technical.md#explicit-definitions-and-filters)
156
+ show profile, aggregation, IVH and filter settings in Python and parameter files.
157
+
158
+ ### Python API
159
+
160
+ ```python
161
+ from mlxradiomics import Settings, extract
162
+
163
+ # image and mask are aligned NumPy arrays; spacing follows their axis order.
164
+ result = extract(
165
+ image, mask, spacing=(3.0, 1.0, 1.0),
166
+ settings=Settings(label=2, bin_width=25, features=("firstorder_Mean", "glcm_Contrast")),
167
+ voxel=True,
168
+ )
169
+ mean_map = result.features["original_firstorder_Mean"]
170
+ ```
171
+
172
+ `FEATURES` lists every supported name. `Settings` also covers fixed-count binning
173
+ (`bin_count`), normalization, outlier removal, resegmentation, GLCM distances,
174
+ kernel radius and `masked_kernel`. With `masked_kernel=False`, neighbourhoods sample
175
+ the whole image but outputs stay inside the ROI. `scratch_mib` sets the batch size
176
+ from a scratch estimate; it is not a memory cap.
177
+
178
+ `extract_images` adds derived images through `TransformSettings`: square, square
179
+ root, logarithm, exponential, gradient, wavelets, LoG, LBP2D, LBP3D, mean,
180
+ Laws, Gabor and radial Simoncelli filters, IBSI sampled-kernel LoG, undecimated
181
+ separable wavelets, and Riesz transforms of a LoG or
182
+ Simoncelli base with optional local structure-tensor alignment. LBP3D needs
183
+ the `lbp` extra. Output keys carry the image prefix, such as
184
+ `wavelet-HHL_glcm_Contrast`. `extract_files` reads NIfTI or NRRD files and adds
185
+ `ImageSettings` for PyRadiomics-style resampling and mask correction. Its
186
+ `ibsi_interpolation=IbsiInterpolation(spacing=(3.0, 2.0, 2.0))` option selects the
187
+ centered IBSI grid and partial-volume mask through the Python file APIs; spacing
188
+ uses array axis order. Parameter files retain their PyRadiomics-style spatial
189
+ controls. Mismatched image and mask geometry requires explicit resampling or
190
+ mask correction.
191
+
192
+ Ordinary intensity resampling preserves fractional interpolated values regardless
193
+ of the source file's integer or floating storage. Masks retain integer labels.
194
+ LBP2D variance likewise retains fractional values for integer 3D inputs. Explicit
195
+ IBSI interpolation rounding remains controlled by its selected protocol.
196
+
197
+ `extract`, `extract_images` and `extract_files` accept `voxel_sink` in voxel mode
198
+ to consume evaluated batches without retaining full maps. Derived-image feature
199
+ names keep their prefixes; file-based batch coordinates follow the processed grid.
200
+ `export_images` and `export_files` add a supported disk-backed exporter: each
201
+ derived image gets its own bounded batch store, and one float32 NIfTI map at a
202
+ time is written through private staging and atomic publication. `run_study` runs
203
+ one or more cases and labels into separate `<case>/label-<n>` directories with an
204
+ explicit status for every combination.
205
+
206
+ ### Execution metadata
207
+
208
+ `extract`, `extract_images` and `extract_files` return execution metadata; the
209
+ runner saves it in `features.json` under `details.execution`.
210
+
211
+ | Field | Meaning |
212
+ | --- | --- |
213
+ | `runtime` | Package versions, Python, platform, Metal device and supplied `MLX_ENABLE_TF32` setting; null means unset |
214
+ | `settings` | Effective feature, binning, normalization, resegmentation and neighborhood options |
215
+ | `array_shape`, `array_dtype`, `spacing` | Processed shape, supplied dtype and spacing in NumPy axis order |
216
+ | `roi_voxels`, `excluded_voxels` | Intensity ROI size and array voxels outside it |
217
+ | `feature_validity` | Sample counts for every fully prefixed feature, including streamed and derived-image results |
218
+ | `transforms` | Effective derived-image settings |
219
+ | `source_geometry`, `image_geometry` | Input and processed grids: shape/spacing in NumPy order, origin/direction in ITK LPS order |
220
+ | `image_settings` | Effective file resampling, interpolation, correction and padding options |
221
+
222
+ Per-feature counts distinguish `finite`, `valid_zero` (a subset of finite),
223
+ `nan`, `positive_infinity`, `negative_infinity` and `excluded` (uncomputed map
224
+ background stored as zero). Finite, NaN, infinite and excluded counts sum to the
225
+ map's voxel count; ROI features have one computed sample and no excluded samples.
226
+ Counts accumulate before export, including when `voxel_sink` consumes batches,
227
+ and retain every derived-image prefix. Top-level ROI counts describe the intensity
228
+ ROI; shape follows the separately recorded `resegment_shape` setting.
229
+
230
+ ### Examples
231
+
232
+ Runnable scripts in [`examples/`](examples) cover the public workflows:
233
+
234
+ ```bash
235
+ python examples/roi_from_files.py image.nii.gz mask.nii.gz outputs/roi --label 1
236
+ python examples/derived_voxel_export.py image.nii.gz mask.nii.gz outputs/maps --label 1
237
+ python examples/multilabel_study.py outputs/study \
238
+ --case case-a image.nii.gz mask.nii.gz --labels 1 2
239
+ ```
240
+
241
+ Resampling and advanced parameter files use the same runner:
242
+
243
+ ```yaml
244
+ setting:
245
+ binWidth: 25
246
+ resampledPixelSpacing: [1.0, 1.0, 1.0]
247
+ interpolator: sitkLinear
248
+ padDistance: 1
249
+ imageType:
250
+ Original: {}
251
+ Wavelet:
252
+ level: 1
253
+ featureClass:
254
+ firstorder: [Mean, Entropy]
255
+ glcm: [Contrast, JointEntropy]
256
+ ```
257
+
258
+ Feature arithmetic is float32 on Metal; binning uses float64 on the host. Importing
259
+ the package does not import MLX. Computation needs Apple Silicon with Metal and has
260
+ no CPU fallback.
261
+
262
+ ### Limits
263
+
264
+ - Shape and physical local-intensity features are ROI-only. Local intensity and
265
+ intensity-dependent morphology require 3D input. Shape2D on a 3D input needs
266
+ `force2d_axis` and an ROI in exactly one slice on that axis. `force2d_axis` counts NumPy axes.
267
+ - Voxel mode needs at least two ROI voxels.
268
+ - The default recursive LoG needs a 3D image with at least four samples per axis, large enough for the
269
+ requested sigma. Each sigma/spacing ratio must be at most 200; singular or
270
+ numerically unresolved derivative normalization raises a precision error.
271
+ - LBP3D needs 3D data and a masked kernel; integer images must be 8- or 16-bit.
272
+ Samples too close to their binary threshold raise a precision error.
273
+ - GLCM direction validity is local to each ROI or voxel neighborhood. Empty
274
+ directions are omitted; MCC averages directions with at least two occupied row
275
+ and column gray levels and is NaN if none qualify. Map backgrounds remain 0.
276
+ - NGTDM counts only centers with at least one valid neighbor. No eligible centers
277
+ gives NaN. Native singular ratios distinguish positive infinity from undefined
278
+ `0/0`; the IBSI profile selects its explicit finite degenerate conventions.
279
+ - Paired NIfTI/Analyze headers named `.nii` or `.nii.gz` are rejected; convert them
280
+ to single-file NIfTI or NRRD.
281
+ - Unsupported settings raise an error; nothing falls back to PyRadiomics.
282
+ - IBSI 2 agreement for Simoncelli responses requires
283
+ `simoncelli_grid=FourierGrid.CENTERED` (parameter key `grid: centered`). The
284
+ default DFT grid follows the manual's text; on it the published Simoncelli maps
285
+ `8_a_2`/`8_a_3` and two IBSI 2 CT statistics fall outside the published tolerances.
286
+ - Simoncelli and Riesz filters are experimental. They use the MLX Metal FFT, and
287
+ MLX 0.32.4 has an out-of-bounds FFT write that can silently modify a neighbouring
288
+ array ([ml-explore/mlx#4733](https://github.com/ml-explore/mlx/issues/4733)). The
289
+ fix is merged upstream but not yet in an MLX release; this package moves its pin
290
+ once one is published. All other features do not use the FFT.
291
+ - Qualified hardware is Apple M5 Max with 128 GiB on macOS 27.2. Other Apple
292
+ Silicon generations, 16–32 GiB machines and other macOS versions are untested.
293
+ - Mathematical definitions and independent regressions are described in
294
+ [scientific qualification](docs/scientific-qualification.md).
295
+
296
+ Development setup is described in the [environment guide](environment/README.md).
297
+
298
+ ## License
299
+
300
+ [Apache-2.0](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev10/LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md), including CC BY 4.0 attribution
301
+ for adapted IBSI manifest definitions.