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.
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/.gitignore +0 -1
- mlxradiomics-0.1.0.dev10/PKG-INFO +339 -0
- mlxradiomics-0.1.0.dev10/README.md +301 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/THIRD_PARTY_NOTICES.md +57 -3
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/pyproject.toml +8 -11
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/__init__.py +33 -5
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/_json.py +23 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/_publication.py +277 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/_runtime.py +45 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/_typing.py +275 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/aggregation.py +228 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/config.py +377 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/count_statistics.py +48 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/distributions.py +262 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/eigen.py +55 -25
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/engine.py +783 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/export.py +343 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/filters.py +1215 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/ibsi_manifest.json +8086 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/intensity_histogram.py +297 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/io.py +190 -18
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/ivh.py +248 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/lbp.py +256 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/lbp3d.py +208 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/local_intensity.py +156 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/matrices.py +257 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/medmlx.py +445 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/mesh_tables.json +2307 -1
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/morphology.py +363 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/parameters.py +404 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/pipeline.py +346 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/precision.py +235 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/preprocessing.py +124 -34
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/py.typed +0 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/recursive_gaussian.py +367 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/riesz_steering.py +733 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/shape.py +1881 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/spatial.py +519 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/statistics.py +725 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/study.py +165 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/texture.py +63 -59
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/transforms.py +1139 -0
- mlxradiomics-0.1.0.dev10/src/mlxradiomics/voxel_output.py +172 -0
- mlxradiomics-0.1.0.dev9/PKG-INFO +0 -193
- mlxradiomics-0.1.0.dev9/README.md +0 -156
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/_runtime.py +0 -28
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/_typing.py +0 -110
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/config.py +0 -191
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/distributions.py +0 -107
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/engine.py +0 -519
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/lbp.py +0 -135
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/lbp3d.py +0 -143
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/medmlx.py +0 -379
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/pipeline.py +0 -135
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/precision.py +0 -101
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/recursive_gaussian.py +0 -193
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/shape.py +0 -269
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/spatial.py +0 -286
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/statistics.py +0 -201
- mlxradiomics-0.1.0.dev9/src/mlxradiomics/transforms.py +0 -326
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/LICENSE +0 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/histogram.py +0 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/reduction.py +0 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/spline.py +0 -0
- {mlxradiomics-0.1.0.dev9 → mlxradiomics-0.1.0.dev10}/src/mlxradiomics/wavelet_tables.json +0 -0
|
@@ -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
|
+
[](https://pypi.org/project/mlxradiomics/)
|
|
46
|
+
[](https://pypi.org/project/mlxradiomics/)
|
|
47
|
+
[](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev10/LICENSE)
|
|
48
|
+
[](https://github.com/ml-explore/mlx)
|
|
49
|
+
[](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
|
+
[](https://pypi.org/project/mlxradiomics/)
|
|
8
|
+
[](https://pypi.org/project/mlxradiomics/)
|
|
9
|
+
[](https://github.com/MedMLX/mlx-radiomics/blob/v0.1.0.dev10/LICENSE)
|
|
10
|
+
[](https://github.com/ml-explore/mlx)
|
|
11
|
+
[](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.
|