mlarray 0.0.34__tar.gz → 0.0.36__tar.gz

{mlarray-0.0.34 → mlarray-0.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.34
+Version: 0.0.36
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT

{mlarray-0.0.34 → mlarray-0.0.36}/docs/optimization.md

@@ -25,7 +25,7 @@ Instead of requiring users to be storage experts, MLArray introduces a **patch s
    * element size (bytes per pixel),
    * CPU cache sizes (L1 / L3 per core),
    * your patch size (2D or 3D),
-   * channel layout (via `channel_axis`),
+   * non-spatial axes layout (via `axis_labels`),
    * and then chooses block/chunk sizes that aim to keep decompression and reads cache-friendly.
 
 Practically: this means *reading a training patch should tend to require as few chunk/block touches as possible*, while keeping the decompressed working set aligned with CPU caches.
@@ -201,8 +201,6 @@ When to use:
 
 ## Notes and practical tips
 
-* **Patch optimization is currently implemented for 2D and 3D images** (and common channel handling). If your data falls outside that, you can still set `chunk_size`/`block_size` manually or let Blosc2 decide.
+* **Patch optimization is currently implemented for 2D and 3D images** (with at most one further non-spatial axis). If your data falls outside that, you can still set `chunk_size`/`block_size` manually or let Blosc2 decide.
 * The best patch size to use is usually the **patch size your dataloader requests most often** (training patch, not necessarily inference tile size).
 * If you’re unsure: start with the default (`patch_size='default'`) and only tune if profiling shows I/O bottlenecks.
-
-If you want, I can also help you add a short “How to pick patch_size” subsection tailored to typical pipelines (nnU-Net, 2D slice training, multi-channel inputs).

{mlarray-0.0.34 → mlarray-0.0.36}/docs/schema.md

@@ -58,15 +58,34 @@ Top-level metadata container.
 * **Description:** Spatial metadata for the image.
 * **Dataclass:** `MetaSpatial`.
 
-This section stores the information needed to interpret the array in physical space (e.g., voxel spacing, coordinate origin, and orientation). It also optionally captures array shape and channel layout to make downstream consumers more robust.
+This section stores the information needed to interpret the array in physical space (e.g., voxel spacing, coordinate origin, and orientation). It also optionally captures array shape and axes layout to make downstream consumers more robust.
 
 | field        | type                        | description                                                                              |
 | ------------ | --------------------------- | ---------------------------------------------------------------------------------------- |
 | spacing      | Optional[List[float]]       | Voxel spacing per spatial axis, length = `ndims`.                                        |
 | origin       | Optional[List[float]]       | Origin per spatial axis, length = `ndims`.                                               |
 | direction    | Optional[List[List[float]]] | Direction matrix, shape `[ndims][ndims]`.                                                |
-| shape        | Optional[List[int]]         | Array shape. If `channel_axis` is set, length = `ndims + 1`, otherwise length = `ndims`. |
-| channel_axis | Optional[int]               | Index of channel dimension in the full array, if present.                                |
+| shape        | Optional[List[int]]         | Full array shape, length = spatial + non-spatial axes.                                   |
+| axis_labels  | Optional[List[str,AxisLabel]]   | Per-axis labels or roles, length = full array `ndims`.                                   |
+| axis_units   | Optional[List[str]]         | Per-axis units, length = full array `ndims`.                                             |
+
+---
+
+#### AxisLabel
+
+Axis labels describe the semantic role of each axis. They may be provided as strings or enum values.
+
+| value         | description                                              |
+| ------------- | -------------------------------------------------------- |
+| spatial       | Generic spatial axis (used when no axis-specific label). |
+| spatial_x     | Spatial axis representing X.                             |
+| spatial_y     | Spatial axis representing Y.                             |
+| spatial_z     | Spatial axis representing Z.                             |
+| non_spatial   | Generic non-spatial axis.                                |
+| channel       | Channel axis (e.g., color channels or feature maps).     |
+| temporal      | Time axis.                                               |
+| continuous    | Continuous-valued axis (non-spatial).                    |
+| components    | Component axis (e.g., vector components).                |
 
 ---
 
@@ -131,9 +150,9 @@ This section records how the array was laid out on disk (chunking, blocking, pat
 
 | field      | type                  | description                                                            |
 | ---------- | --------------------- | ---------------------------------------------------------------------- |
-| chunk_size | Optional[List[float]] | Chunk size per axis, length = full array `ndims` (including channels). |
-| block_size | Optional[List[float]] | Block size per axis, length = full array `ndims` (including channels). |
-| patch_size | Optional[List[float]] | Patch size per spatial axis, length = `ndims` (channels excluded).     |
+| chunk_size | Optional[List[float]] | Chunk size per axis, length = full array `ndims` (including non-spatial axes). |
+| block_size | Optional[List[float]] | Block size per axis, length = full array `ndims` (including non-spatial axes). |
+| patch_size | Optional[List[float]] | Patch size per spatial axis, length = `ndims` (non-spatial axes excluded).     |
 
 ---
 

{mlarray-0.0.34 → mlarray-0.0.36}/docs/usage.md

@@ -128,6 +128,43 @@ image.save("with-metadata.mla")
 
 ---
 
+## Non-spatial data usage (Channels, temporal, ...)
+
+Use `axis_labels` to mark which axes are spatial and which are non-spatial
+(channels, temporal, components, etc.). Spatial metadata (`spacing`, `origin`,
+`direction`) is specified only for the spatial axes, while the full array shape
+includes both spatial and non-spatial axes.
+
+```python
+import numpy as np
+from mlarray import MLArray, MetaSpatial
+
+# Example shape: (time, z, y, x, channels)
+array = np.random.random((2, 6, 4, 4, 3, 2))
+
+axis_labels = [
+    MetaSpatial.AxisLabel.temporal,
+    MetaSpatial.AxisLabel.spatial_z,
+    MetaSpatial.AxisLabel.spatial_y,
+    "spatial_x",  # Possible to pass predefined labels as string as well
+    MetaSpatial.AxisLabel.channel,
+    "some-other-type"  # Possible to pass arbitrary strings as well
+]
+
+image = MLArray(
+    array,
+    spacing=(2.5, 0.7, 0.7),  # spatial axes only (z, y, x)
+    origin=(0.0, 0.0, 0.0),
+    axis_labels=axis_labels,
+)
+
+# Optional per-axis units (length = full array ndims)
+image.meta.spatial.axis_units = ["s", "mm", "mm", "mm", ""]
+image.save("time-series.mla", patch_size=None)
+```
+
+
+
 ## Patch size variants
 
 MLArray stores arrays in a chunked layout to enable efficient partial reads. You can control how data is chunked using `patch_size` (recommended in most cases), or manually specify chunk and block sizes when you need full control.

{mlarray-0.0.34 → mlarray-0.0.36}/examples/example_channel.py

@@ -1,14 +1,14 @@
 import numpy as np
 import os
 from pathlib import Path
-from mlarray import MLArray, Meta, MetaBbox
+from mlarray import MLArray, Meta, MetaBbox, MetaSpatial
 import json
 
 
 if __name__ == '__main__':
     print("Creating array...")
     array = np.random.random((32, 64, 64, 3))
-    channel_axis = 3
+    axis_labels = (MetaSpatial.AxisLabel.spatial_z, MetaSpatial.AxisLabel.spatial_y, MetaSpatial.AxisLabel.spatial_x, MetaSpatial.AxisLabel.channel)
     spacing = np.array((2, 2.5, 4))
     origin = (1, 1, 1)
     direction = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
@@ -20,7 +20,7 @@ if __name__ == '__main__':
         os.remove(filepath)
 
     print("Initializing image...")
-    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, channel_axis=channel_axis, meta=Meta(source=source_meta, bbox=MetaBbox(bboxes)))
+    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, axis_labels=axis_labels, meta=Meta(source=source_meta, bbox=MetaBbox(bboxes)))
     print("Saving image...")
     image.save(filepath)
 

mlarray-0.0.36/examples/example_non_spatial.py

@@ -0,0 +1,42 @@
+import numpy as np
+import os
+from pathlib import Path
+from mlarray import MLArray, Meta, MetaBbox, MetaSpatial
+import json
+
+
+if __name__ == '__main__':
+    print("Creating array...")
+    array = np.random.random((2, 6, 4, 4, 3, 2))
+    axis_labels = [
+        MetaSpatial.AxisLabel.temporal,
+        MetaSpatial.AxisLabel.spatial_z,
+        MetaSpatial.AxisLabel.spatial_y,
+        "spatial_x",  # Possible to pass predefined labels as string as well
+        MetaSpatial.AxisLabel.channel,
+        "some-other-type"  # Possible to pass arbitrary strings as well
+    ]
+    spacing = np.array((2, 2.5, 4))
+    origin = (1, 1, 1)
+    direction = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+    source_meta = {"tmp1": "This is an image", "tmp2": 5, "tmp3": {"test1": 16.4587, "test2": [1, 2, 3, 4, 5, 6]}}
+    bboxes = [[[0, 1], [0, 1], [0, 1]]]
+    filepath = "tmp.mla"
+
+    if Path(filepath).is_file():
+        os.remove(filepath)
+
+    print("Initializing image...")
+    image = MLArray(array, spacing=spacing, origin=origin, direction=direction, axis_labels=axis_labels, meta=Meta(source=source_meta, bbox=MetaBbox(bboxes)))
+    image.meta.spatial.axis_units = ["s", "mm", "mm", "mm", ""]
+    print("Saving image...")
+    image.save(filepath, patch_size=None)
+
+    print("Loading image...")
+    image = MLArray(filepath)
+    print(json.dumps(image.meta.to_mapping(), indent=2, sort_keys=True))
+    print("Image mean value: ", np.mean(image.to_numpy()))
+    print("Some array data: \n", image[:2, :2, 0])
+
+    if Path(filepath).is_file():
+        os.remove(filepath)

{mlarray-0.0.34 → mlarray-0.0.36}/mlarray/__init__.py

@@ -17,6 +17,7 @@ if TYPE_CHECKING:
         MetaSpatial,
         MetaStatistics,
         MetaVersion,
+        AxisLabel
     )
     from mlarray.utils import is_serializable
     from mlarray.cli import cli_print_header, cli_convert_to_mlarray
@@ -36,6 +37,7 @@ __all__ = [
     "MetaSpatial",
     "MetaStatistics",
     "MetaVersion",
+    "AxisLabel",
     "is_serializable",
     "cli_print_header",
     "cli_convert_to_mlarray",
@@ -61,6 +63,7 @@ _LAZY_ATTRS = {
     "MetaSpatial": ("mlarray.meta", "MetaSpatial"),
     "MetaStatistics": ("mlarray.meta", "MetaStatistics"),
     "MetaVersion": ("mlarray.meta", "MetaVersion"),
+    "AxisLabel": ("mlarray.meta", "AxisLabel"),
     "is_serializable": ("mlarray.utils", "is_serializable"),
     "cli_print_header": ("mlarray.cli", "cli_print_header"),
     "cli_convert_to_mlarray": ("mlarray.cli", "cli_convert_to_mlarray"),

{mlarray-0.0.34 → mlarray-0.0.36}/mlarray/meta.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from dataclasses import MISSING, dataclass, field, fields
-from typing import Any, Dict, List, Mapping, Optional, Type, TypeVar, Union
+from typing import Any, Mapping, Optional, Type, TypeVar, Union, TypeAlias, Iterable
+from enum import Enum
 
 import numpy as np
 from mlarray.utils import is_serializable
@@ -57,7 +58,7 @@ class BaseMeta:
         """Return a user-friendly string based on plain values."""
         return str(self.to_plain())
 
-    def to_mapping(self, *, include_none: bool = True) -> Dict[str, Any]:
+    def to_mapping(self, *, include_none: bool = True) -> dict[str, Any]:
         """Serialize to a mapping, recursively expanding nested BaseMeta.
 
         Args:
@@ -66,7 +67,7 @@ class BaseMeta:
         Returns:
             A dict of field names to serialized values.
         """
-        out: Dict[str, Any] = {}
+        out: dict[str, Any] = {}
         for f in fields(self):
             v = getattr(self, f.name)
             if v is None and not include_none:
@@ -125,7 +126,7 @@ class BaseMeta:
             A dict of field values, with nested BaseMeta expanded. SingleKeyBaseMeta
             overrides this to return its wrapped value.
         """
-        out: Dict[str, Any] = {}
+        out: dict[str, Any] = {}
         for f in fields(self):
             v = getattr(self, f.name)
             if v is None and not include_none:
@@ -251,7 +252,7 @@ class SingleKeyBaseMeta(BaseMeta):
         """Set the wrapped value."""
         self.value = v
 
-    def to_mapping(self, *, include_none: bool = True) -> Dict[str, Any]:
+    def to_mapping(self, *, include_none: bool = True) -> dict[str, Any]:
         """Serialize to a mapping with the single key.
 
         Args:
@@ -451,6 +452,109 @@ def _validate_float_int_matrix(value: Any, label: str, ndims: Optional[int] = No
         for v in row:
             if not isinstance(v, (float, int)):
                 raise TypeError(f"{label} must contain only floats or ints")
+            
+
+def validate_and_cast_axis_labels(
+    value: Any,
+    label: str,
+    ndims: Optional[int] = None,
+) -> tuple[Optional[list[str]], int, int]:
+    """
+    Validate axis labels/roles, normalize to list[str], and count spatial/non-spatial axes.
+
+    Args:
+        value: None or list-like of axis labels/roles (enum members or strings).
+        label: Label used in error messages.
+        ndims: If provided, enforce list length == ndims.
+
+    Returns:
+        (labels, n_spatial, n_non_spatial)
+
+    Raises:
+        TypeError: If value is not None and not list-like, or contains invalid items.
+        ValueError: If ndims is provided and length mismatch occurs.
+    """
+    if value is None:
+        return None, 0, 0
+
+    # Cast list / tuple / ndarray -> list
+    v = _cast_to_list(value, label)
+
+    # Enforce 1D list
+    for i, item in enumerate(v):
+        if isinstance(item, list):
+            raise TypeError(
+                f"{label} must be a 1D list (got nested list at index {i})"
+            )
+
+    if ndims is not None and len(v) != ndims:
+        raise ValueError(f"{label} must have length {ndims}")
+
+    spatial_enum_roles = {
+        AxisLabelEnum.spatial,
+        AxisLabelEnum.spatial_x,
+        AxisLabelEnum.spatial_y,
+        AxisLabelEnum.spatial_z,
+    }
+    spatial_string_roles = {r.value for r in spatial_enum_roles}
+
+    out: list[str] = []
+    n_spatial = 0
+    n_non_spatial = 0
+
+    for i, x in enumerate(v):
+        if isinstance(x, AxisLabelEnum):
+            out.append(x.value)
+            if x in spatial_enum_roles:
+                n_spatial += 1
+            else:
+                n_non_spatial += 1
+            continue
+
+        if isinstance(x, str):
+            out.append(x)
+            if x in spatial_string_roles:
+                n_spatial += 1
+            else:
+                n_non_spatial += 1
+            continue
+
+        raise TypeError(
+            f"{label}[{i}] must be a str or AxisLabelEnum "
+            f"(got {type(x).__name__})"
+        )
+
+    return out, n_spatial, n_non_spatial
+
+
+def _is_spatial_axis(label: Union[str, AxisLabelEnum]) -> bool:
+    """Return True if an axis label/role represents a spatial axis."""
+    if isinstance(label, AxisLabelEnum):
+        return label in {
+            AxisLabelEnum.spatial,
+            AxisLabelEnum.spatial_x,
+            AxisLabelEnum.spatial_y,
+            AxisLabelEnum.spatial_z,
+        }
+
+    if isinstance(label, str):
+        return label in {
+            AxisLabelEnum.spatial.value,
+            AxisLabelEnum.spatial_x.value,
+            AxisLabelEnum.spatial_y.value,
+            AxisLabelEnum.spatial_z.value,
+        }
+
+    return False
+
+
+def _spatial_axis_mask(
+    labels: Iterable[Union[str, AxisLabelEnum]],
+) -> list[bool]:
+    """Return a boolean mask indicating which axes are spatial."""
+    if labels is None:
+        return None
+    return [_is_spatial_axis(label) for label in labels]
 
 
 @dataclass(slots=True)
@@ -460,19 +564,18 @@ class MetaBlosc2(BaseMeta):
     Attributes:
         chunk_size: List of per-dimension chunk sizes. Length must match ndims.
         block_size: List of per-dimension block sizes. Length must match ndims.
-        patch_size: List of per-dimension patch sizes. Length must match ndims,
-            or (ndims - 1) when a channel axis is present.
+        patch_size: List of per-dimension patch sizes. Length must match spatial ndims.
     """
     chunk_size: Optional[list] = None
     block_size: Optional[list] = None
     patch_size: Optional[list] = None
 
-    def _validate_and_cast(self, *, ndims: Optional[int] = None, channel_axis: Optional[int] = None, **_: Any) -> None:
+    def _validate_and_cast(self, *, ndims: Optional[int] = None, spatial_ndims: Optional[int] = None, **_: Any) -> None:
         """Validate and normalize tiling sizes.
 
         Args:
-            ndims: Number of spatial dimensions.
-            channel_axis: Channel axis index when present.
+            ndims: Number of dimensions.
+            spatial_ndims: Number of spatial dimensions.
             **_: Unused extra context.
         """
         if self.chunk_size is not None:
@@ -484,9 +587,37 @@ class MetaBlosc2(BaseMeta):
             _validate_float_int_list(self.block_size, "meta._blosc2.block_size", ndims)
 
         if self.patch_size is not None:
-            _ndims = ndims if (ndims is None or channel_axis is None) else ndims - 1
+            spatial_ndims = ndims if spatial_ndims is None else spatial_ndims
             self.patch_size = _cast_to_list(self.patch_size, "meta._blosc2.patch_size")
-            _validate_float_int_list(self.patch_size, "meta._blosc2.patch_size", _ndims)
+            _validate_float_int_list(self.patch_size, "meta._blosc2.patch_size", spatial_ndims)
+
+
+class AxisLabelEnum(str, Enum):
+    """Axis label/role identifiers used for spatial metadata.
+
+    Attributes:
+        spatial: Generic spatial axis (used when no axis-specific label applies).
+        spatial_x: Spatial axis representing X.
+        spatial_y: Spatial axis representing Y.
+        spatial_z: Spatial axis representing Z.
+        non_spatial: Generic non-spatial axis.
+        channel: Channel axis (e.g., color channels or feature maps).
+        temporal: Time axis.
+        continuous: Continuous-valued axis (non-spatial).
+        components: Component axis (e.g., vector components).
+    """
+    spatial = "spatial"
+    spatial_x = "spatial_x"
+    spatial_y = "spatial_y"
+    spatial_z = "spatial_z"
+    non_spatial = "non_spatial"
+    channel = "channel"
+    temporal = "temporal"
+    continuous = "continuous"
+    components = "components"
+
+
+AxisLabel: TypeAlias = Union[str, AxisLabelEnum]
 
 
 @dataclass(slots=True)
@@ -497,42 +628,49 @@ class MetaSpatial(BaseMeta):
         spacing: Per-dimension spacing values. Length must match ndims.
         origin: Per-dimension origin values. Length must match ndims.
         direction: Direction cosine matrix of shape [ndims, ndims].
-        shape: Array shape. Length must match ndims, or (ndims + 1) when
-            channel_axis is set.
-        channel_axis: Index of the channel dimension, if any.
+        shape: Array shape. Length must match (spatial + non-spatial) ndims.
+        axis_labels: Per-axis labels or roles. Length must match ndims.
+        axis_units: Per-axis units. Length must match ndims.
+        _num_spatial_axes: Cached count of spatial axes derived from axis_labels.
+        _num_non_spatial_axes: Cached count of non-spatial axes derived from axis_labels.
     """
-    spacing: Optional[List] = None
-    origin: Optional[List] = None
-    direction: Optional[List[List]] = None
-    shape: Optional[List] = None
-    channel_axis: Optional[int] = None
-
-    def _validate_and_cast(self, *, ndims: Optional[int] = None, **_: Any) -> None:
+    AxisLabel = AxisLabelEnum
+    spacing: Optional[list[Union[int,float]]] = None
+    origin: Optional[list[Union[int,float]]] = None
+    direction: Optional[list[list[Union[int,float]]]] = None
+    shape: Optional[list[int]] = None
+    axis_labels: Optional[list[Union[str,AxisLabel]]] = None
+    axis_units: Optional[list[str]] = None
+    _num_spatial_axes: Optional[int] = None
+    _num_non_spatial_axes: Optional[int] = None
+
+    def _validate_and_cast(self, *, ndims: Optional[int] = None, spatial_ndims: Optional[int] = None, **_: Any) -> None:
         """Validate and normalize spatial fields.
 
         Args:
-            ndims: Number of spatial dimensions.
+            ndims: Number of dimensions.
+            spatial_ndims: Number of spatial dimensions.
             **_: Unused extra context.
         """
-        if self.channel_axis is not None:
-            _validate_int(self.channel_axis, "meta.spatial.channel_axis")
+        if self.axis_labels is not None:
+            self.axis_labels, self._num_spatial_axes, self._num_non_spatial_axes = validate_and_cast_axis_labels(self.axis_labels, "meta.spatial.axis_labels", ndims)
+        spatial_ndims = spatial_ndims if self._num_spatial_axes is None else self._num_spatial_axes
 
         if self.spacing is not None:
             self.spacing = _cast_to_list(self.spacing, "meta.spatial.spacing")
-            _validate_float_int_list(self.spacing, "meta.spatial.spacing", ndims)
+            _validate_float_int_list(self.spacing, "meta.spatial.spacing", spatial_ndims)
 
         if self.origin is not None:
             self.origin = _cast_to_list(self.origin, "meta.spatial.origin")
-            _validate_float_int_list(self.origin, "meta.spatial.origin", ndims)
+            _validate_float_int_list(self.origin, "meta.spatial.origin", spatial_ndims)
 
         if self.direction is not None:
             self.direction = _cast_to_list(self.direction, "meta.spatial.direction")
-            _validate_float_int_matrix(self.direction, "meta.spatial.direction", ndims)
+            _validate_float_int_matrix(self.direction, "meta.spatial.direction", spatial_ndims)
 
         if self.shape is not None:
-            _ndims = ndims if (ndims is None or self.channel_axis is None) else ndims + 1
             self.shape = _cast_to_list(self.shape, "meta.spatial.shape")
-            _validate_float_int_list(self.shape, "meta.spatial.shape", _ndims)
+            _validate_float_int_list(self.shape, "meta.spatial.shape", ndims)
 
 
 @dataclass(slots=True)
@@ -586,9 +724,9 @@ class MetaBbox(BaseMeta):
         labels: Optional labels aligned with bboxes. Each label may be a string,
             int, or float.
     """
-    bboxes: Optional[List[List[List[Union[int, float]]]]] = None
-    scores: Optional[List[Union[int, float]]] = None
-    labels: Optional[List[Union[str, int, float]]] = None
+    bboxes: Optional[list[list[list[Union[int, float]]]]] = None
+    scores: Optional[list[Union[int, float]]] = None
+    labels: Optional[list[Union[str, int, float]]] = None
 
     def _validate_and_cast(self, **_: Any) -> None:
         """Validate bounding box structure and related fields."""
@@ -635,7 +773,7 @@ class MetaSource(SingleKeyBaseMeta):
     Attributes:
         data: Arbitrary JSON-serializable metadata.
     """
-    data: Dict[str, Any] = field(default_factory=dict)
+    data: dict[str, Any] = field(default_factory=dict)
 
     def _validate_and_cast(self, **_: Any) -> None:
         """Validate that data is a JSON-serializable dict."""
@@ -652,7 +790,7 @@ class MetaExtra(SingleKeyBaseMeta):
     Attributes:
         data: Arbitrary JSON-serializable metadata.
     """
-    data: Dict[str, Any] = field(default_factory=dict)
+    data: dict[str, Any] = field(default_factory=dict)
 
     def _validate_and_cast(self, **_: Any) -> None:
         """Validate that data is a JSON-serializable dict."""
@@ -749,11 +887,12 @@ class Meta(BaseMeta):
     _image_meta_format: "MetaImageFormat" = field(default_factory=lambda: MetaImageFormat())
     _mlarray_version: "MetaVersion" = field(default_factory=lambda: MetaVersion())
 
-    def _validate_and_cast(self, *, ndims: Optional[int] = None, **_: Any) -> None:
+    def _validate_and_cast(self, *, ndims: Optional[int] = None, spatial_ndims: Optional[int] = None, **_: Any) -> None:
         """Coerce child metas and validate with optional context.
 
         Args:
-            ndims: Number of spatial dimensions for context-aware validation.
+            ndims: Number of dimensions for context-aware validation.
+            spatial_ndims: Number of spatial dimensions for context-aware validation.
             **_: Unused extra context.
         """
         self.source = MetaSource.ensure(self.source)
@@ -767,8 +906,8 @@ class Meta(BaseMeta):
         self._image_meta_format = MetaImageFormat.ensure(self._image_meta_format)
         self._mlarray_version = MetaVersion.ensure(self._mlarray_version)
 
-        self.spatial._validate_and_cast(ndims=ndims)
-        self._blosc2._validate_and_cast(ndims=ndims, channel_axis=getattr(self.spatial, "channel_axis", None))
+        self.spatial._validate_and_cast(ndims=ndims, spatial_ndims=spatial_ndims)
+        self._blosc2._validate_and_cast(ndims=ndims, spatial_ndims=spatial_ndims)
 
     def to_plain(self, *, include_none: bool = False) -> Any:
         """Convert to plain values, suppressing default sub-metas.
@@ -780,7 +919,7 @@ class Meta(BaseMeta):
             A dict of field values where default child metas are represented
             as None and optionally filtered out.
         """
-        out: Dict[str, Any] = {}
+        out: dict[str, Any] = {}
         for f in fields(self):
             v = getattr(self, f.name)
 

{mlarray-0.0.34 → mlarray-0.0.36}/mlarray/mlarray.py

@@ -5,7 +5,7 @@ import math
 from typing import Dict, Optional, Union, List, Tuple
 from pathlib import Path
 import os
-from mlarray.meta import Meta, MetaBlosc2
+from mlarray.meta import Meta, MetaBlosc2, AxisLabel, _spatial_axis_mask
 from mlarray.utils import is_serializable
 
 MLARRAY_SUFFIX = "mla"
@@ -21,7 +21,7 @@ class MLArray:
             origin: Optional[Union[List, Tuple, np.ndarray]] = None,
             direction: Optional[Union[List, Tuple, np.ndarray]] = None,
             meta: Optional[Union[Dict, Meta]] = None,
-            channel_axis: Optional[int] = None,
+            axis_labels: Optional[List[Union[str, AxisLabel]]] = None,
             num_threads: int = 1,
             copy: Optional['MLArray'] = None) -> None:
         """Initializes a MLArray instance.
@@ -46,8 +46,7 @@ class MLArray:
             meta (Optional[Dict | Meta]): Free-form metadata dictionary or Meta
                 instance. Must be JSON-serializable when saving. 
                 If meta is passed as a Dict, it will internally be converted into a Meta object with the dict being interpreted as meta.image metadata.
-            channel_axis (Optional[int]): Axis index that represents channels
-                in the array (e.g., 0 for CHW or -1 for HWC). If None, the array
+            axis_labels (Optional[List[Union[str, AxisLabel]]]): Per-axis labels or roles. Length must match ndims. If None, the array
                 is treated as purely spatial.
             num_threads (int): Number of threads for Blosc2 operations.
             copy (Optional[MLArray]): Another MLArray instance to copy metadata
@@ -58,13 +57,14 @@ class MLArray:
         self.support_metadata = None
         self.mmap = None
         self.meta = None
-        if isinstance(array, (str, Path)) and (spacing is not None or origin is not None or direction is not None or meta is not None or channel_axis is not None or copy is not None):
-            raise ("Spacing, origin, direction, meta, channel_axis or copy cannot be set when array is a filepath.")
+        if isinstance(array, (str, Path)) and (spacing is not None or origin is not None or direction is not None or meta is not None or axis_labels is not None or copy is not None):
+            raise ("Spacing, origin, direction, meta, axis_labels or copy cannot be set when array is a filepath.")
         if isinstance(array, (str, Path)):
             self._load(array, num_threads)
         else:
             self._store = array
-            self._validate_and_add_meta(meta, spacing, origin, direction, channel_axis, True)        
+            has_array = array is not None
+            self._validate_and_add_meta(meta, spacing, origin, direction, axis_labels, has_array)        
             if copy is not None:
                 self.meta.copy_from(copy.meta)
 
@@ -74,7 +74,7 @@ class MLArray:
             filepath: Union[str, Path],
             shape: Optional[Union[List, Tuple, np.ndarray]] = None,
             dtype: Optional[np.dtype] = None,
-            channel_axis: Optional[int] = None,
+            axis_labels: Optional[List[Union[str, AxisLabel]]] = None,
             mmap: str = 'r',
             patch_size: Optional[Union[int, List, Tuple]] = 'default',  # 'default' means that the default of 192 is used. However, if set to 'default', the patch_size will be skipped if self.patch_size is set from a previously loaded MLArray image. In that case the self.patch_size is used.
             chunk_size: Optional[Union[int, List, Tuple]]= None,
@@ -99,10 +99,10 @@ class MLArray:
                 ".b2nd" or ".mla".
             shape (Optional[Union[List, Tuple, np.ndarray]]): Shape of the array
                 to create. If provided, a new file is created. Length must match
-                the full array dimensionality (including channels if present).
+                the full array dimensionality (including non-spatial axes if present).
             dtype (Optional[np.dtype]): Numpy dtype for a newly created array.
-            channel_axis (Optional[int]): Axis index for channels in the array.
-                Used for patch/chunk/block calculations.
+            axis_labels (Optional[List[Union[str, AxisLabel]]]): Per-axis labels or roles. Length must match ndims. If None, the array
+                is treated as purely spatial. Used for patch/chunk/block calculations.
             mmap (str): Blosc2 mmap mode. One of "r", "r+", "w+", "c".
             patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
                 chunk/block optimization. Provide an int for isotropic sizes or
@@ -126,7 +126,7 @@ class MLArray:
                 inconsistent, or if mmap mode is invalid for creation.
         """
         class_instance = cls()
-        class_instance._open(filepath, shape, dtype, channel_axis, mmap, patch_size, chunk_size, block_size, num_threads, cparams, dparams)
+        class_instance._open(filepath, shape, dtype, axis_labels, mmap, patch_size, chunk_size, block_size, num_threads, cparams, dparams)
         return class_instance
 
     def _open(
@@ -134,7 +134,7 @@ class MLArray:
             filepath: Union[str, Path],
             shape: Optional[Union[List, Tuple, np.ndarray]] = None,
             dtype: Optional[np.dtype] = None,
-            channel_axis: Optional[int] = None,
+            axis_labels: Optional[list[Union[str, AxisLabel]]] = None,
             mmap: str = 'r',
             patch_size: Optional[Union[int, List, Tuple]] = 'default',  # 'default' means that the default of 192 is used. However, if set to 'default', the patch_size will be skipped if self.patch_size is set from a previously loaded MLArray image. In that case the self.patch_size is used.
             chunk_size: Optional[Union[int, List, Tuple]]= None,
@@ -159,10 +159,10 @@ class MLArray:
                 ".b2nd" or ".mla".
             shape (Optional[Union[List, Tuple, np.ndarray]]): Shape of the array
                 to create. If provided, a new file is created. Length must match
-                the full array dimensionality (including channels if present).
+                the full array dimensionality (including non-spatial axes if present).
             dtype (Optional[np.dtype]): Numpy dtype for a newly created array.
-            channel_axis (Optional[int]): Axis index for channels in the array.
-                Used for patch/chunk/block calculations.
+            axis_labels (Optional[List[Union[str, AxisLabel]]]): Per-axis labels or roles. Length must match ndims. If None, the array
+                is treated as purely spatial.
             mmap (str): Blosc2 mmap mode. One of "r", "r+", "w+", "c".
             patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
                 chunk/block optimization. Provide an int for isotropic sizes or
@@ -203,7 +203,8 @@ class MLArray:
         create_array = mmap == 'w+'
     
         if create_array:
-            self.meta._blosc2 = self._comp_and_validate_blosc2_meta(self.meta._blosc2, patch_size, chunk_size, block_size, shape, channel_axis)   
+            spatial_axis_mask = [True] * len(shape) if axis_labels is None else _spatial_axis_mask(axis_labels)
+            self.meta._blosc2 = self._comp_and_validate_blosc2_meta(self.meta._blosc2, patch_size, chunk_size, block_size, shape, spatial_axis_mask)   
             self.meta._has_array.has_array = True
         
         self.support_metadata = str(filepath).endswith(f".{MLARRAY_SUFFIX}")
@@ -332,7 +333,8 @@ class MLArray:
             raise RuntimeError(f"MLArray requires '.b2nd' or '.{MLARRAY_SUFFIX}' as extension.")
     
         if self._store is not None:
-            self.meta._blosc2 = self._comp_and_validate_blosc2_meta(self.meta._blosc2, patch_size, chunk_size, block_size, self._store.shape, self.meta.spatial.channel_axis)
+            spatial_axis_mask = [True] * self.ndim if self.meta.spatial.axis_labels is None else _spatial_axis_mask(self.meta.spatial.axis_labels)
+            self.meta._blosc2 = self._comp_and_validate_blosc2_meta(self.meta._blosc2, patch_size, chunk_size, block_size, self._store.shape, spatial_axis_mask)
             self.meta._has_array.has_array = True
     
         self.support_metadata = str(filepath).endswith(f".{MLARRAY_SUFFIX}")
@@ -568,7 +570,7 @@ class MLArray:
     
     @property
     def ndim(self) -> int:
-        """Returns the number of dimensions of the array.
+        """Returns the number of spatial and non-spatial dimensions of the array.
 
         Returns:
             int: Number of dimensions, or None if no array is loaded.
@@ -581,23 +583,21 @@ class MLArray:
     def _spatial_ndim(self) -> int:
         """Returns the number of spatial dimensions.
 
-        If ``channel_axis`` is set, the channel dimension is excluded.
-
         Returns:
             int: Number of spatial dimensions, or None if no array is loaded.
         """
         if self._store is None or self.meta._has_array.has_array == False:
             return None
         ndim = len(self._store.shape)
-        if self.meta.spatial.channel_axis is not None:
-            ndim -= 1
+        if self.meta.spatial._num_spatial_axes is not None:
+            ndim = self.meta.spatial._num_spatial_axes
         return ndim
 
     def comp_blosc2_params(
             self,
             image_size: Union[Tuple[int, int], Tuple[int, int, int], Tuple[int, int, int, int]],
             patch_size: Union[Tuple[int, int], Tuple[int, int, int]],
-            channel_axis: Optional[int] = None,
+            spatial_axis_mask: Optional[list[bool]] = None,
             bytes_per_pixel: int = 4,  # 4 byte are float32
             l1_cache_size_per_core_in_bytes: int = 32768,  # 1 Kibibyte (KiB) = 2^10 Byte;  32 KiB = 32768 Byte
             l3_cache_size_per_core_in_bytes: int = 1441792, # 1 Mibibyte (MiB) = 2^20 Byte = 1.048.576 Byte; 1.375MiB = 1441792 Byte
@@ -624,13 +624,11 @@ class MLArray:
         Args:
             image_size (Union[Tuple[int, int], Tuple[int, int, int], Tuple[int, int, int, int]]):
                 Image shape. Use a 2D, 3D, or 4D size; 2D/3D inputs are
-                internally expanded to 4D (with channels first).
+                internally expanded to 4D (with non-spatial axes first).
             patch_size (Union[Tuple[int, int], Tuple[int, int, int]]): Patch
                 size for spatial dimensions. Use a 2-tuple (x, y) or 3-tuple
                 (x, y, z).
-            channel_axis (Optional[int]): Axis index for channels in the
-                source array. If set, the size is moved to channels-first
-                for cache calculations.
+            spatial_axis_mask (Optional[list[bool]]): Mask indicating for every axis whether it is spatial or not.
             bytes_per_pixel (int): Number of bytes per element. Defaults to 4
                 for float32.
             l1_cache_size_per_core_in_bytes (int): L1 cache per core in bytes.
@@ -654,8 +652,14 @@ class MLArray:
             image_size = (1, *image_size)
             num_squeezes = 1
 
-        if channel_axis is not None:
-            image_size = _move_index_list(image_size, channel_axis+num_squeezes, 0)
+        non_spatial_axis = None
+        if spatial_axis_mask is not None:
+            non_spatial_axis_mask = [not b for b in spatial_axis_mask]
+            if sum(non_spatial_axis_mask) > 1:
+                raise RuntimeError("Automatic blosc2 optimization currently only supports one non-spatial axis. Please set chunk and block size manually.")
+            non_spatial_axis = next((i for i, v in enumerate(non_spatial_axis_mask) if v), None)
+            if non_spatial_axis is not None:
+                image_size = _move_index_list(image_size, non_spatial_axis+num_squeezes, 0)
 
         if len(image_size) != 4:
             raise RuntimeError("Image size must be 4D.")
@@ -663,11 +667,11 @@ class MLArray:
         if not (len(patch_size) == 2 or len(patch_size) == 3):
             raise RuntimeError("Patch size must be 2D or 3D.")
 
-        num_channels = image_size[0]
+        non_spatial_size = image_size[0]
         if len(patch_size) == 2:
             patch_size = [1, *patch_size]
         patch_size = np.array(patch_size)
-        block_size = np.array((num_channels, *[2 ** (max(0, math.ceil(math.log2(i)))) for i in patch_size]))
+        block_size = np.array((non_spatial_size, *[2 ** (max(0, math.ceil(math.log2(i)))) for i in patch_size]))
 
         # shrink the block size until it fits in L1
         estimated_nbytes_block = np.prod(block_size) * bytes_per_pixel
@@ -713,16 +717,16 @@ class MLArray:
         # better safe than sorry
         chunk_size = [min(i, j) for i, j in zip(image_size, chunk_size)]
 
-        if channel_axis is not None:
-            block_size = _move_index_list(block_size, 0, channel_axis+num_squeezes)
-            chunk_size = _move_index_list(chunk_size, 0, channel_axis+num_squeezes)
+        if non_spatial_axis is not None:
+            block_size = _move_index_list(block_size, 0, non_spatial_axis+num_squeezes)
+            chunk_size = _move_index_list(chunk_size, 0, non_spatial_axis+num_squeezes)
 
         block_size = block_size[num_squeezes:]
         chunk_size = chunk_size[num_squeezes:]
 
         return [int(value) for value in chunk_size], [int(value) for value in block_size]
     
-    def _comp_and_validate_blosc2_meta(self, meta_blosc2, patch_size, chunk_size, block_size, shape, channel_axis):
+    def _comp_and_validate_blosc2_meta(self, meta_blosc2, patch_size, chunk_size, block_size, shape, spatial_axis_mask):
         """Compute and validate Blosc2 chunk/block metadata.
 
         Args:
@@ -732,32 +736,32 @@ class MLArray:
                 or "default". See ``open``/``save`` for expected shapes.
             chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
             block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
-            shape (Union[List, Tuple, np.ndarray]): Full array shape including
-                channels if present.
-            channel_axis (Optional[int]): Channel axis index, if any.
+            shape (Union[List, Tuple, np.ndarray]): Full array shape including non-spatial axes.
+            spatial_axis_mask (Optional[list[bool]]): Mask indicating for every axis whether it is spatial or not.
 
         Returns:
             MetaBlosc2: Validated Blosc2 metadata instance.
         """
-        if patch_size is not None and patch_size != "default" and not ((len(shape) == 2 and channel_axis is None) or (len(shape) == 3 and channel_axis is None) or (len(shape) == 4 and channel_axis is not None) or (len(shape) == 4 and channel_axis is not None)):
-            raise NotImplementedError("Chunk and block size optimization based on patch size is only implemented for 2D and 3D images. Please set the chunk and block size manually or set to None for blosc2 to determine a chunk and block size.")
+        num_spatial_axes = sum(spatial_axis_mask)
+        num_non_spatial_axes = sum([not b for b in spatial_axis_mask])
+        if patch_size is not None and patch_size != "default" and (num_spatial_axes == 1 or num_spatial_axes > 3 or num_non_spatial_axes > 1):
+            raise NotImplementedError("Chunk and block size optimization based on patch size is only implemented for 2D and 3D spatial images with at most one further non-spatial axis. Please set the chunk and block size manually or set to None for blosc2 to determine a chunk and block size.")
         if patch_size is not None and patch_size != "default" and (chunk_size is not None or block_size is not None):
             raise RuntimeError("patch_size and chunk_size / block_size cannot both be explicitly set.")
 
-        ndims = len(shape) if channel_axis is None else len(shape) - 1
         if patch_size == "default": 
             if meta_blosc2 is not None and meta_blosc2.patch_size is not None:  # Use previously loaded patch size, when patch size is not explicitly set and a patch size from a previously loaded image exists
                 patch_size = meta_blosc2.patch_size
             else:  # Use default patch size, when patch size is not explicitly set and no patch size from a previously loaded image exists
-                patch_size = [MLARRAY_DEFAULT_PATCH_SIZE] * ndims
+                patch_size = [MLARRAY_DEFAULT_PATCH_SIZE] * num_spatial_axes
 
         patch_size = [patch_size] * len(shape) if isinstance(patch_size, int) else patch_size
 
         if patch_size is not None:
-            chunk_size, block_size = self.comp_blosc2_params(shape, patch_size, channel_axis)
+            chunk_size, block_size = self.comp_blosc2_params(shape, patch_size, spatial_axis_mask)
 
         meta_blosc2 = MetaBlosc2(chunk_size, block_size, patch_size)
-        meta_blosc2._validate_and_cast(ndims=len(shape), channel_axis=channel_axis)
+        meta_blosc2._validate_and_cast(ndims=len(shape), spatial_ndims=num_spatial_axes)
         return meta_blosc2
     
     def _read_meta(self):
@@ -780,7 +784,7 @@ class MLArray:
                 raise RuntimeError("Metadata is not serializable.")
             self._store.vlmeta["mlarray"] = metadata
     
-    def _validate_and_add_meta(self, meta, spacing=None, origin=None, direction=None, channel_axis=None, has_array=None):
+    def _validate_and_add_meta(self, meta, spacing=None, origin=None, direction=None, axis_labels=None, has_array=None):
         """Validate and attach metadata to the MLArray instance.
 
         Args:
@@ -792,7 +796,7 @@ class MLArray:
                 spatial axis.
             direction (Optional[Union[List, Tuple, np.ndarray]]): Direction
                 cosine matrix with shape (ndims, ndims).
-            channel_axis (Optional[int]): Channel axis index, if any.
+            axis_labels (Optional[List[Union[str, AxisLabel]]]): Per-axis labels or roles. Length must match ndims.
 
         Raises:
             ValueError: If ``meta`` is not None, dict, or Meta.
@@ -812,11 +816,13 @@ class MLArray:
             self.meta.spatial.origin = origin
         if direction is not None:
             self.meta.spatial.direction = direction
-        if channel_axis is not None:
-            self.meta.spatial.channel_axis = channel_axis
-        if self.meta._has_array.has_array or has_array:
+        if axis_labels is not None:
+            self.meta.spatial.axis_labels = axis_labels
+        if has_array == True:
+            self.meta._has_array.has_array = True
+        if self.meta._has_array.has_array:
             self.meta.spatial.shape = self.shape
-        self.meta.spatial._validate_and_cast(ndims=self._spatial_ndim)
+        self.meta.spatial._validate_and_cast(ndims=self.ndim, spatial_ndims=self._spatial_ndim)
 
     def _update_blosc2_meta(self):
         """Sync Blosc2 chunk and block sizes into metadata.

{mlarray-0.0.34 → mlarray-0.0.36}/mlarray.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.34
+Version: 0.0.36
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT

{mlarray-0.0.34 → mlarray-0.0.36}/mlarray.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ docs/usage.md
 docs/why.md
 examples/example_channel.py
 examples/example_metadata_only.py
+examples/example_non_spatial.py
 examples/example_open.py
 examples/example_save_load.py
 mlarray/__init__.py