mlxradiomics 0.1.0.dev3__py3-none-any.whl

mlxradiomics/__init__.py

@@ -0,0 +1,81 @@
+"""PyRadiomics-compatible radiomics features computed with MLX on the Apple Silicon GPU.
+
+Research software. Feature values are compared with a pinned PyRadiomics revision on
+synthetic inputs (see docs/technical.md); no IBSI or clinical validation is claimed.
+
+Names other than ``FEATURES`` and ``Settings`` are imported on first access, so
+``import mlxradiomics`` does not import MLX, SimpleITK or the PyRadiomics reference.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, cast
+
+from mlxradiomics.config import FEATURES, Settings
+
+if TYPE_CHECKING:
+    from mlxradiomics.engine import Result as Result
+    from mlxradiomics.engine import extract as extract
+    from mlxradiomics.io import Volume as Volume
+    from mlxradiomics.lbp import LBPMethod as LBPMethod
+    from mlxradiomics.pipeline import ImageExtraction as ImageExtraction
+    from mlxradiomics.pipeline import extract_images as extract_images
+    from mlxradiomics.spatial import ImagePair as ImagePair
+    from mlxradiomics.spatial import ImageSettings as ImageSettings
+    from mlxradiomics.spatial import Interpolator as Interpolator
+    from mlxradiomics.spatial import extract_files as extract_files
+    from mlxradiomics.spatial import load_image_pair as load_image_pair
+    from mlxradiomics.transforms import FeatureImage as FeatureImage
+    from mlxradiomics.transforms import ImageType as ImageType
+    from mlxradiomics.transforms import TransformSettings as TransformSettings
+    from mlxradiomics.transforms import feature_images as feature_images
+
+__version__ = "0.1.0.dev3"
+
+_EXPORT_MODULES = {
+    "Result": "engine",
+    "extract": "engine",
+    "Volume": "io",
+    "ImagePair": "spatial",
+    "ImageSettings": "spatial",
+    "Interpolator": "spatial",
+    "extract_files": "spatial",
+    "load_image_pair": "spatial",
+    "ImageExtraction": "pipeline",
+    "extract_images": "pipeline",
+    "FeatureImage": "transforms",
+    "ImageType": "transforms",
+    "TransformSettings": "transforms",
+    "feature_images": "transforms",
+    "LBPMethod": "lbp",
+}
+__all__ = [
+    "FEATURES",
+    "Settings",
+    "Result",
+    "extract",
+    "Volume",
+    "ImagePair",
+    "ImageSettings",
+    "Interpolator",
+    "extract_files",
+    "load_image_pair",
+    "ImageExtraction",
+    "extract_images",
+    "FeatureImage",
+    "ImageType",
+    "TransformSettings",
+    "feature_images",
+    "LBPMethod",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Import a public name on first access and cache it in the module namespace."""
+    module = _EXPORT_MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = cast(object, getattr(import_module(f"mlxradiomics.{module}"), name))
+    globals()[name] = value
+    return value

mlxradiomics/_runtime.py

@@ -0,0 +1,28 @@
+"""The package executes only on Apple Silicon Metal through the shared runtime."""
+
+from collections.abc import Callable
+from platform import machine, system
+from typing import TYPE_CHECKING, cast
+
+import numpy as np
+from medmlx_core import MissingDependencyError, import_mlx
+from numpy.typing import NDArray
+
+from mlxradiomics._typing import EvaluationRuntime
+
+if TYPE_CHECKING:
+    import mlx.core as mx
+else:
+    if system() != "Darwin" or machine() != "arm64":
+        raise MissingDependencyError(
+            "mlxradiomics requires macOS arm64 with an accessible Metal GPU",
+            hint="Run on Apple Silicon; host preprocessing and upstream recording need no Metal.",
+        )
+    mx = import_mlx()
+
+
+__all__ = ["array_from_bool", "evaluate", "mx"]
+
+# MLX accepts NumPy bool arrays; its DLPack constructor annotation omits them.
+array_from_bool = cast(Callable[[NDArray[np.bool_]], mx.array], mx.array)
+evaluate = cast(EvaluationRuntime, mx).eval

mlxradiomics/_typing.py

@@ -0,0 +1,173 @@
+"""Protocols for MLX/Metal calls and typed dictionaries for result and report payloads."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Literal, NotRequired, Protocol, TypedDict
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from mlx.core import Dtype, array
+
+type HostArray = NDArray[np.generic]
+type FloatArray = NDArray[np.float64]
+type Features = dict[str, float | FloatArray]
+
+
+class Evaluate(Protocol):
+    def __call__(self, *arrays: array) -> None: ...
+
+
+class EvaluationRuntime(Protocol):
+    @property
+    def eval(self) -> Evaluate: ...
+
+
+class IndexedAddition(Protocol):
+    def add(self, value: array) -> array: ...
+
+
+class MetalKernel(Protocol):
+    def __call__(
+        self,
+        *,
+        inputs: Sequence[array],
+        grid: tuple[int, int, int],
+        threadgroup: tuple[int, int, int],
+        output_shapes: Sequence[tuple[int, ...]],
+        output_dtypes: Sequence[Dtype],
+        init_value: float | None = None,
+    ) -> list[array]: ...
+
+
+class SettingsPayload(TypedDict):
+    """Plain-dict copy of ``Settings`` (``dataclasses.asdict``), as stored in metadata."""
+
+    gldm_alpha: int
+    bin_width: float
+    bin_count: int | None
+    normalize: bool
+    normalize_scale: float
+    remove_outliers: float | None
+    resegment_range: tuple[float, ...] | None
+    resegment_mode: Literal["absolute", "relative", "sigma"]
+    resegment_shape: bool
+    label: int
+    distances: tuple[int, ...]
+    symmetrical_glcm: bool
+    force2d_axis: int | None
+    masked_kernel: bool
+    kernel_radius: int
+    voxel_array_shift: float
+    scratch_mib: int
+    max_gray_levels: int
+    features: tuple[str, ...]
+
+
+class ImageGeometryPayload(TypedDict):
+    """Physical placement of the arrays that were processed.
+
+    ``shape`` and ``spacing`` follow NumPy array-axis order. ``origin`` and ``direction``
+    keep the ITK physical x/y/z order; ``direction`` is the flattened row-major matrix.
+    """
+
+    shape: tuple[int, ...]
+    spacing: tuple[float, ...]
+    origin: tuple[float, ...]
+    direction: tuple[float, ...]
+
+
+class ExecutionMetadata(TypedDict):
+    """Provenance of one extraction, returned as ``Result.metadata``.
+
+    ``spacing`` is in the unit of the supplied spacing (mm for image files), one entry per
+    array axis. ``gray_levels`` is the highest gray-level bin index (1 when only shape
+    features were requested). ``batch_size`` and ``scratch_estimate_bytes`` are set in
+    voxel mode, ``gray_levels_by_image`` when derived images are extracted, and
+    ``image_geometry`` for file extraction.
+    """
+
+    settings: SettingsPayload
+    device: str
+    precision: str
+    voxel: bool
+    spacing: tuple[float, ...]
+    histogram_method: str
+    preprocessing: str
+    gray_levels: int
+    gray_levels_by_image: NotRequired[dict[str, int]]
+    batch_size: NotRequired[int]
+    scratch_estimate_bytes: NotRequired[int]
+    image_geometry: NotRequired[ImageGeometryPayload]
+
+
+class VoxelMemory(TypedDict):
+    """Voxel-mode batch size (centers per batch) and the estimated scratch bytes it implies."""
+
+    batch_size: int
+    scratch_estimate_bytes: int
+
+
+class Comparison(TypedDict):
+    """Per-feature comparison with the reference; ``max_absolute_error`` is over finite pairs."""
+
+    feature: str
+    passed: bool
+    compared_values: int
+    mismatches: int
+    max_absolute_error: float | None
+    reference_nan_count: int
+
+
+class QualificationRecord(TypedDict):
+    """One synthetic case run in ROI or voxel mode against the pinned PyRadiomics.
+
+    ``median_speedup`` is the median PyRadiomics time divided by the median MLX time.
+    """
+
+    case: str
+    synthetic: bool
+    voxel: bool
+    settings: SettingsPayload
+    spacing: tuple[float, ...]
+    shape: tuple[int, ...]
+    selected_voxels: int
+    comparison: list[Comparison]
+    passed: bool
+    pyradiomics_seconds: list[float]
+    mlx_seconds: list[float]
+    median_speedup: float
+    execution: ExecutionMetadata
+    mlx_gpu_peak_memory_bytes: int
+
+
+class QualificationReport(TypedDict):
+    """JSON report written by ``mlxradiomics-qualify`` (``schema_version`` 1)."""
+
+    schema_version: int
+    mlxradiomics_version: str
+    pyradiomics_commit: str
+    pyradiomics_version: str
+    mlx_version: str
+    numpy_version: str
+    python: str
+    platform: str
+    device: str
+    precision: str
+    histogram_method: str
+    workload: str
+    device_info: dict[str, str | int]
+    absolute_tolerance: float
+    relative_tolerance: float
+    passed: bool
+    records: list[QualificationRecord]
+    scope: str
+    performance_gate: str
+    ibsi_qualification: str
+    metal_qualification: str
+    reference_voxel_batch: int
+    reference_2d_representation: str
+    unsupported_cases: dict[str, str]
+    proposed_performance_targets: dict[str, float]

mlxradiomics/config.py

@@ -0,0 +1,187 @@
+"""Feature catalogue and extraction settings.
+
+Unsupported settings raise ``ValueError``; nothing falls back to another backend.
+"""
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import Literal
+
+# Feature names per family, spelled as in PyRadiomics (firstorder -> RadiomicsFirstOrder,
+# glcm -> RadiomicsGLCM, gldm -> RadiomicsGLDM, ngtdm -> RadiomicsNGTDM,
+# glrlm -> RadiomicsGLRLM, glszm -> RadiomicsGLSZM, shape -> RadiomicsShape,
+# shape2D -> RadiomicsShape2D). Deprecated PyRadiomics aliases are not included.
+FIRST_ORDER = (
+    "Mean", "Minimum", "Maximum", "Range", "Variance", "Skewness", "Kurtosis",
+    "Energy", "TotalEnergy", "RootMeanSquared", "Entropy", "Uniformity",
+    "10Percentile", "90Percentile", "Median", "InterquartileRange",
+    "MeanAbsoluteDeviation", "RobustMeanAbsoluteDeviation",
+)
+GLCM = (
+    "Autocorrelation", "Contrast", "Correlation", "DifferenceAverage",
+    "JointEnergy", "JointEntropy", "Id", "Idm", "JointAverage", "ClusterProminence",
+    "ClusterShade", "ClusterTendency", "DifferenceEntropy", "DifferenceVariance", "Imc1",
+    "Imc2", "Idmn", "Idn", "InverseVariance", "MaximumProbability", "SumAverage",
+    "SumEntropy", "SumSquares", "MCC",
+)
+GLDM = (
+    "SmallDependenceEmphasis", "LargeDependenceEmphasis", "GrayLevelNonUniformity",
+    "DependenceNonUniformity", "DependenceNonUniformityNormalized", "GrayLevelVariance",
+    "DependenceVariance", "DependenceEntropy", "LowGrayLevelEmphasis", "HighGrayLevelEmphasis",
+    "SmallDependenceLowGrayLevelEmphasis", "SmallDependenceHighGrayLevelEmphasis",
+    "LargeDependenceLowGrayLevelEmphasis", "LargeDependenceHighGrayLevelEmphasis",
+)
+NGTDM = ("Coarseness", "Contrast", "Busyness", "Complexity", "Strength")
+GLRLM = (
+    "ShortRunEmphasis", "LongRunEmphasis", "GrayLevelNonUniformity",
+    "GrayLevelNonUniformityNormalized", "RunLengthNonUniformity",
+    "RunLengthNonUniformityNormalized", "RunPercentage", "GrayLevelVariance", "RunVariance",
+    "RunEntropy", "LowGrayLevelRunEmphasis", "HighGrayLevelRunEmphasis",
+    "ShortRunLowGrayLevelEmphasis", "ShortRunHighGrayLevelEmphasis",
+    "LongRunLowGrayLevelEmphasis", "LongRunHighGrayLevelEmphasis",
+)
+GLSZM = (
+    "SmallAreaEmphasis", "LargeAreaEmphasis", "GrayLevelNonUniformity",
+    "GrayLevelNonUniformityNormalized", "SizeZoneNonUniformity",
+    "SizeZoneNonUniformityNormalized", "ZonePercentage", "GrayLevelVariance", "ZoneVariance",
+    "ZoneEntropy", "LowGrayLevelZoneEmphasis", "HighGrayLevelZoneEmphasis",
+    "SmallAreaLowGrayLevelEmphasis", "SmallAreaHighGrayLevelEmphasis",
+    "LargeAreaLowGrayLevelEmphasis", "LargeAreaHighGrayLevelEmphasis",
+)
+SHAPE = ("MeshVolume", "VoxelVolume", "SurfaceArea", "SurfaceVolumeRatio", "Sphericity",
+         "Maximum3DDiameter", "Maximum2DDiameterSlice", "Maximum2DDiameterColumn",
+         "Maximum2DDiameterRow", "MajorAxisLength", "MinorAxisLength", "LeastAxisLength",
+         "Elongation", "Flatness")
+SHAPE2D = ("MeshSurface", "PixelSurface", "Perimeter", "PerimeterSurfaceRatio", "Sphericity",
+           "MaximumDiameter", "MajorAxisLength", "MinorAxisLength", "Elongation")
+FAMILIES = {"firstorder": FIRST_ORDER, "glcm": GLCM, "gldm": GLDM, "ngtdm": NGTDM,
+            "glrlm": GLRLM, "glszm": GLSZM, "shape": SHAPE, "shape2D": SHAPE2D}
+# Selectable feature names, "<family>_<Name>"; result keys add an image-type prefix.
+FEATURES = tuple(f"{family}_{name}" for family, names in FAMILIES.items() for name in names)
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Feature selection and preprocessing options for one extraction.
+
+    Field names correspond to PyRadiomics settings (``bin_width`` is ``binWidth``,
+    ``gldm_alpha`` is ``gldm_a``, and so on). Intensities are in the image's own units
+    (HU for CT). ``distances`` and ``kernel_radius`` are in voxels, not physical units.
+
+    Attributes:
+        gldm_alpha: A neighbor counts as dependent when its gray level differs from the
+            center by at most this many bins (GLDM alpha).
+        bin_width: Fixed bin width. Bin edges are multiples of ``bin_width`` counted from
+            zero, not from the ROI minimum, as in PyRadiomics (this differs from the
+            IBSI fixed-bin-size definition). Ignored, and not validated, when
+            ``bin_count`` is set.
+        bin_count: Fixed number of bins between the sampled minimum and maximum. Takes
+            precedence over ``bin_width``; must not exceed ``max_gray_levels``.
+        normalize: Normalize the whole image (not just the ROI) to zero mean and unit
+            sample standard deviation, before resegmentation and binning.
+        normalize_scale: Factor applied after normalization (and after outlier clipping).
+        remove_outliers: Requires ``normalize``. Clip normalized values to plus or minus
+            this many standard deviations before scaling.
+        resegment_range: One or two thresholds, inclusive. One keeps voxels at or above
+            it; two keep voxels between them. Applied to the label's voxels after
+            normalization.
+        resegment_mode: ``"absolute"`` uses the thresholds as given, ``"relative"``
+            multiplies them by the maximum ROI intensity, and ``"sigma"`` uses
+            ``mean + threshold * std`` of the ROI intensities.
+        resegment_shape: If true, shape features use the resegmented mask; otherwise
+            they use the original label mask.
+        label: Mask value selecting the ROI; the mask is compared by equality.
+        distances: GLCM, GLDM and NGTDM neighbor distances. Each is a Chebyshev
+            (maximum-norm) distance in voxels, so distance 1 in 3-D gives 26 neighbors.
+            GLRLM and GLSZM always use distance 1, as PyRadiomics does.
+        symmetrical_glcm: Add each GLCM to its transpose before computing features.
+        force2d_axis: If set, neighbor directions stay in the plane perpendicular to this
+            NumPy axis (PyRadiomics ``force2D`` with ``force2Ddimension``), and
+            ``shape2D`` on a 3-D array uses the single slice along it.
+        masked_kernel: Voxel mode only. If true, local neighborhoods sample only ROI
+            voxels. If false, they sample the whole image, and gray-level discretization
+            also uses the whole image; output centers still lie in the ROI.
+        kernel_radius: Voxel mode only. Half-width in voxels of the cubic neighborhood
+            around each center (flattened along ``force2d_axis`` if set).
+        voxel_array_shift: Added to intensities before Energy, TotalEnergy and
+            RootMeanSquared only.
+        scratch_mib: Working-memory budget in MiB used to size voxel batches and shape-mesh
+            chunks. It is an estimate, not an operating-system limit.
+        max_gray_levels: Upper bound on the number of gray levels; larger values raise.
+        features: Names from ``FEATURES``. The default is every non-shape feature (93);
+            shape features must be listed explicitly.
+    """
+
+    gldm_alpha: int = 0
+    bin_width: float = 25.0
+    bin_count: int | None = None
+    normalize: bool = False
+    normalize_scale: float = 1.0
+    remove_outliers: float | None = None
+    resegment_range: tuple[float, ...] | None = None
+    resegment_mode: Literal["absolute", "relative", "sigma"] = "absolute"
+    resegment_shape: bool = False
+    label: int = 1
+    distances: tuple[int, ...] = (1,)
+    symmetrical_glcm: bool = True
+    force2d_axis: int | None = None
+    masked_kernel: bool = True
+    kernel_radius: int = 1
+    voxel_array_shift: float = 0.0
+    scratch_mib: int = 64
+    max_gray_levels: int = 256
+    features: tuple[str, ...] = tuple(n for n in FEATURES if not n.startswith("shape"))
+
+    def validate(self, ndim: int) -> None:
+        """Raise ``ValueError`` if any field is unsupported.
+
+        Args:
+            ndim: Dimensionality of the image the settings will be applied to; only used
+                to check that ``force2d_axis`` indexes an array axis.
+        """
+        self._validate_preprocessing()
+        if type(self.gldm_alpha) is not int or self.gldm_alpha < 0:
+            raise ValueError("gldm_alpha must be a nonnegative integer")
+        if self.bin_count is None and (not isfinite(self.bin_width) or self.bin_width <= 0):
+            raise ValueError("bin_width must be finite and positive")
+        if type(self.label) is not int or self.label <= 0:
+            raise ValueError("label must be a positive integer")
+        if not self.distances or any(type(x) is not int or x < 1 for x in self.distances):
+            raise ValueError("distances must contain positive integers")
+        if len(set(self.distances)) != len(self.distances):
+            raise ValueError("distances must be unique")
+        if self.force2d_axis is not None and self.force2d_axis not in range(ndim):
+            raise ValueError("force2d_axis must index a NumPy image axis")
+        if type(self.masked_kernel) is not bool or type(self.symmetrical_glcm) is not bool:
+            raise ValueError("masked_kernel and symmetrical_glcm must be booleans")
+        for name in ("kernel_radius", "scratch_mib", "max_gray_levels"):
+            if type(getattr(self, name)) is not int or getattr(self, name) < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        if not isfinite(self.voxel_array_shift):
+            raise ValueError("voxel_array_shift must be finite")
+        if not self.features or len(set(self.features)) != len(self.features):
+            raise ValueError("features must be a nonempty unique selection")
+        unsupported = set(self.features) - set(FEATURES)
+        if unsupported:
+            raise ValueError(f"unsupported features: {sorted(unsupported)}")
+
+    def _validate_preprocessing(self) -> None:
+        if self.bin_count is not None and (
+            type(self.bin_count) is not int or not 1 <= self.bin_count <= self.max_gray_levels
+        ):
+            raise ValueError("bin_count must be a positive integer <= max_gray_levels")
+        if type(self.normalize) is not bool or type(self.resegment_shape) is not bool:
+            raise ValueError("normalize and resegment_shape must be booleans")
+        if not isfinite(self.normalize_scale) or self.normalize_scale <= 0:
+            raise ValueError("normalize_scale must be finite and positive")
+        if self.remove_outliers is not None and (
+            not isfinite(self.remove_outliers) or self.remove_outliers <= 0 or not self.normalize
+        ):
+            raise ValueError("remove_outliers requires normalization and a finite positive value")
+        if self.resegment_mode not in {"absolute", "relative", "sigma"}:
+            raise ValueError("resegment_mode must be absolute, relative, or sigma")
+        if self.resegment_range is not None and (
+            len(self.resegment_range) not in (1, 2)
+            or any(not isfinite(value) for value in self.resegment_range)
+        ):
+            raise ValueError("resegment_range must contain one or two finite thresholds")

mlxradiomics/distributions.py

@@ -0,0 +1,105 @@
+"""Features computed from count matrices: GLDM, GLRLM, GLSZM and NGTDM.
+
+Inputs are integer counts held in float32 arrays with a leading batch axis (one row per
+ROI or per voxel center). The formulas follow the PyRadiomics feature classes of the
+same names; the tests compare them with PyRadiomics at rtol=atol=1e-4.
+"""
+
+from mlxradiomics._runtime import mx
+from mlxradiomics.reduction import sum_rows
+
+# Same epsilon as PyRadiomics (numpy.spacing(1)); keeps log2 finite where p == 0.
+EPS = 2.220446049250313e-16
+
+
+def size_statistics(counts: mx.array, family: str) -> dict[str, mx.array]:
+    """Compute GLDM, GLRLM or GLSZM features for a batch of count matrices.
+
+    Args:
+        counts: Array ``(batch, Ng, Ns)``. Axis 1 is the gray level ``i = 1..Ng`` and axis
+            2 the dependence size, run length or zone size ``j = 1..Ns``. Gray levels keep
+            their original indices, so levels absent from a row stay in the matrix with
+            zero counts.
+        family: ``"gldm"``, ``"glrlm"`` or ``"glszm"``. Selects the feature names, for
+            example ``SmallDependenceEmphasis``, ``ShortRunEmphasis`` or
+            ``SmallAreaEmphasis``.
+
+    Returns:
+        Feature name without the family prefix mapped to a ``(batch,)`` float32 array.
+        ``RunPercentage`` (GLRLM) and ``ZonePercentage`` (GLSZM) are included only for
+        those families.
+    """
+    counts = counts.astype(mx.float32)
+    total = sum_rows(counts)
+    p = counts / mx.maximum(total[:, None, None], 1)
+    i = mx.arange(1, counts.shape[1] + 1, dtype=mx.float32)[None, :, None]
+    j = mx.arange(1, counts.shape[2] + 1, dtype=mx.float32)[None, None, :]
+    pg, ps = mx.sum(counts, axis=2), mx.sum(counts, axis=1)
+    mean_i, mean_j = sum_rows(p * i), sum_rows(p * j)
+    size, small, large, low, high, entropy, variance, percentage = {
+        "gldm": ("Dependence", "SmallDependence", "LargeDependence", "LowGrayLevel",
+                 "HighGrayLevel", "DependenceEntropy", "DependenceVariance", None),
+        "glrlm": ("RunLength", "ShortRun", "LongRun", "LowGrayLevelRun",
+                  "HighGrayLevelRun", "RunEntropy", "RunVariance", "RunPercentage"),
+        "glszm": ("SizeZone", "SmallArea", "LargeArea", "LowGrayLevelZone",
+                  "HighGrayLevelZone", "ZoneEntropy", "ZoneVariance", "ZonePercentage"),
+    }[family]
+    features = {
+        small + "Emphasis": sum_rows(p / j**2),
+        large + "Emphasis": sum_rows(p * j**2),
+        "GrayLevelNonUniformity": sum_rows(pg**2) / total,
+        "GrayLevelNonUniformityNormalized": sum_rows(pg**2) / total**2,
+        size + "NonUniformity": sum_rows(ps**2) / total,
+        size + "NonUniformityNormalized": sum_rows(ps**2) / total**2,
+        "GrayLevelVariance": sum_rows(p * (i - mean_i[:, None, None])**2),
+        variance: sum_rows(p * (j - mean_j[:, None, None])**2),
+        entropy: -sum_rows(p * mx.log2(p + EPS)),
+        low + "Emphasis": sum_rows(p / i**2),
+        high + "Emphasis": sum_rows(p * i**2),
+        small + "LowGrayLevelEmphasis": sum_rows(p / (i**2 * j**2)),
+        small + "HighGrayLevelEmphasis": sum_rows(p * i**2 / j**2),
+        large + "LowGrayLevelEmphasis": sum_rows(p * j**2 / i**2),
+        large + "HighGrayLevelEmphasis": sum_rows(p * i**2 * j**2),
+    }
+    if percentage is not None:
+        features[percentage] = total / sum_rows(counts * j)
+    return features
+
+
+def ngtdm_statistics(counts: mx.array) -> dict[str, mx.array]:
+    """Compute NGTDM features for a batch of per-gray-level neighborhood statistics.
+
+    Args:
+        counts: Array ``(batch, Ng, 2)``. ``[..., 0]`` is the number of eligible center
+            voxels at gray level ``i`` (in the mask with at least one valid neighbor).
+            ``[..., 1]`` is the sum, over those voxels, of the absolute difference between
+            ``i`` and the mean gray level of their valid neighbors.
+
+    Returns:
+        Feature name without the ``ngtdm_`` prefix mapped to a ``(batch,)`` float32 array.
+        Coarseness is 1e6 when its denominator is zero; Contrast is 0 with a single gray
+        level present; Busyness and Strength are 0 when their denominators are zero.
+    """
+    n, s = counts[:, :, 0], counts[:, :, 1]
+    total = sum_rows(n)
+    p = n / mx.maximum(total[:, None], 1)
+    levels = mx.arange(1, n.shape[1] + 1, dtype=mx.float32)[None, :]
+    present = n > 0
+    ng = sum_rows(present.astype(mx.int32))
+    pi, pj = p[:, :, None], p[:, None, :]
+    si, sj = s[:, :, None], s[:, None, :]
+    i, j = levels[:, :, None], levels[:, None, :]
+    pairs = present[:, :, None] & present[:, None, :]
+    ps = sum_rows(p * s)
+    busyness = sum_rows(mx.where(pairs, mx.abs(i * pi - j * pj), 0))
+    contrast = sum_rows(pi * pj * (i - j)**2) * sum_rows(s) / mx.maximum(total, 1)
+    strength = sum_rows(mx.where(pairs, (pi + pj) * (i - j)**2, 0))
+    complexity = sum_rows(mx.where(pairs, mx.abs(i - j) * (pi * si + pj * sj)
+                                   / mx.maximum(pi + pj, EPS), 0))
+    return {
+        "Coarseness": mx.where(ps == 0, 1e6, 1 / ps),
+        "Contrast": mx.where(ng > 1, contrast / mx.maximum(ng * (ng - 1), 1), 0),
+        "Busyness": mx.where(busyness > 0, ps / busyness, 0),
+        "Complexity": complexity / mx.maximum(total, 1),
+        "Strength": mx.where(sum_rows(s) > 0, strength / sum_rows(s), 0),
+    }