mlarray 0.0.43__tar.gz → 0.0.45__tar.gz

{mlarray-0.0.43 → mlarray-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.43
+Version: 0.0.45
 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.45/examples/example_in_memory_constructors.py

@@ -0,0 +1,84 @@
+from pathlib import Path
+
+import numpy as np
+
+from mlarray import MLArray
+
+
+def main():
+    shape = (2, 4, 4)
+
+    a_empty = MLArray.empty(
+        shape=shape,
+        dtype=np.float32,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+    a_empty[...] = np.arange(np.prod(shape), dtype=np.float32).reshape(shape)
+
+    a_zeros = MLArray.zeros(
+        shape=shape,
+        dtype=np.float32,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+    a_ones = MLArray.ones(
+        shape=shape,
+        dtype=np.float32,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+    a_full = MLArray.full(
+        shape=shape,
+        fill_value=5,
+        dtype=np.float32,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+
+    a_arange = MLArray.arange(0, 16, 1, shape=(4, 4), patch_size=None)
+    a_linspace = MLArray.linspace(
+        0.0, 1.0, num=8, shape=(2, 4), endpoint=False, patch_size=None
+    )
+
+    a_empty_like = MLArray.empty_like(
+        a_full, patch_size=None, chunk_size=(1, 4, 4), block_size=(1, 2, 2)
+    )
+    a_empty_like[...] = 11
+    a_zeros_like = MLArray.zeros_like(
+        a_full, patch_size=None, chunk_size=(1, 4, 4), block_size=(1, 2, 2)
+    )
+    a_ones_like = MLArray.ones_like(
+        a_full, patch_size=None, chunk_size=(1, 4, 4), block_size=(1, 2, 2)
+    )
+    a_full_like = MLArray.full_like(
+        a_full,
+        fill_value=9,
+        patch_size=None,
+        chunk_size=(1, 4, 4),
+        block_size=(1, 2, 2),
+    )
+
+    print("empty sum:", float(a_empty[...].sum()))
+    print("zeros sum:", float(a_zeros[...].sum()))
+    print("ones sum:", float(a_ones[...].sum()))
+    print("full sum:", float(a_full[...].sum()))
+    print("arange:", a_arange[...])
+    print("linspace:", a_linspace[...])
+    print("empty_like unique:", np.unique(a_empty_like[...]))
+    print("zeros_like sum:", float(a_zeros_like[...].sum()))
+    print("ones_like sum:", float(a_ones_like[...].sum()))
+    print("full_like sum:", float(a_full_like[...].sum()))
+
+    out_path = Path("example_in_memory_constructors_output.mla")
+    a_full_like.save(out_path)
+    loaded = MLArray(out_path)
+    print("saved shape:", loaded.shape, "dtype:", loaded.dtype)
+
+
+if __name__ == "__main__":
+    main()

{mlarray-0.0.43 → mlarray-0.0.45}/mlarray/mlarray.py

@@ -328,6 +328,734 @@ class MLArray:
         self._validate_and_add_meta(self.meta)
         self._write_metadata()
 
+    @staticmethod
+    def _normalize_shape(shape: Union[int, List, Tuple, np.ndarray]) -> Tuple[int, ...]:
+        if isinstance(shape, (int, np.integer)):
+            return (int(shape),)
+        return tuple(int(v) for v in shape)
+
+    def _resolve_like_input(self, x, dtype, meta):
+        if isinstance(x, MLArray):
+            if x._store is None or x.meta is None or x.meta._has_array.has_array is False:
+                raise TypeError("Input MLArray has no array data loaded.")
+            shape = self._normalize_shape(x.shape)
+            src_dtype = x.dtype
+            if meta is None:
+                meta = deepcopy(x.meta)
+        elif hasattr(x, "shape") and hasattr(x, "dtype"):
+            shape = self._normalize_shape(x.shape)
+            src_dtype = x.dtype
+        else:
+            raise TypeError(
+                "x must be an MLArray or an array-like object with shape and dtype."
+            )
+
+        dtype = src_dtype if dtype is None else dtype
+        return shape, np.dtype(dtype), meta
+
+    def _construct_in_memory(
+            self,
+            shape: Union[int, List, Tuple, np.ndarray],
+            dtype: np.dtype,
+            store_builder,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Internal generic constructor for in-memory Blosc2-backed MLArrays.
+
+        Args:
+            shape (Union[int, List, Tuple, np.ndarray]): Target array shape.
+            dtype (np.dtype): Target dtype.
+            store_builder (Callable): Callable receiving normalized kwargs and
+                returning a Blosc2 NDArray.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. Dict values are stored as
+                ``meta.source``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization. Use ``"default"`` to use the default
+                patch size of 192.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+                Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters. If None, defaults to
+                ``{'codec': blosc2.Codec.LZ4HC, 'clevel': 8}``.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters. If None, defaults to
+                ``{'nthreads': num_threads}``.
+        """
+        shape = self._normalize_shape(shape)
+        dtype = np.dtype(dtype)
+
+        self._validate_and_add_meta(meta, has_array=True)
+        spatial_axis_mask = (
+            [True] * len(shape)
+            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,
+            shape,
+            dtype.itemsize,
+            spatial_axis_mask,
+        )
+        self.meta._has_array.has_array = True
+
+        blosc2.set_nthreads(num_threads)
+        if cparams is None:
+            cparams = {"codec": blosc2.Codec.LZ4HC, "clevel": 8}
+        if dparams is None:
+            dparams = {"nthreads": num_threads}
+
+        self._store = store_builder(
+            shape=shape,
+            dtype=dtype,
+            chunks=self.meta.blosc2.chunk_size,
+            blocks=self.meta.blosc2.block_size,
+            cparams=cparams,
+            dparams=dparams,
+        )
+
+        self._update_blosc2_meta()
+        self._validate_and_add_meta(self.meta)
+
+    @classmethod
+    def empty(
+            cls,
+            shape: Union[int, List, Tuple, np.ndarray],
+            dtype: np.dtype,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray with uninitialized values.
+
+        Args:
+            shape (Union[int, List, Tuple, np.ndarray]): Shape of the output
+                array.
+            dtype (np.dtype): Numpy dtype for the output array.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. Dict values are stored as
+                ``meta.source``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization. Use ``"default"`` to use the default
+                patch size of 192.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+                Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters used when writing chunks.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters used when reading chunks.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+        """
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.empty(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def zeros(
+            cls,
+            shape: Union[int, List, Tuple, np.ndarray],
+            dtype: np.dtype,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray filled with zeros.
+
+        Args:
+            shape (Union[int, List, Tuple, np.ndarray]): Shape of the output
+                array.
+            dtype (np.dtype): Numpy dtype for the output array.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+                Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+        """
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.zeros(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def ones(
+            cls,
+            shape: Union[int, List, Tuple, np.ndarray],
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray filled with ones.
+
+        Args:
+            shape (Union[int, List, Tuple, np.ndarray]): Shape of the output
+                array.
+            dtype (np.dtype): Numpy dtype for the output array. If None, uses
+                ``blosc2.DEFAULT_FLOAT``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+                Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+        """
+        dtype = blosc2.DEFAULT_FLOAT if dtype is None else dtype
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.ones(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def full(
+            cls,
+            shape: Union[int, List, Tuple, np.ndarray],
+            fill_value: Union[bytes, int, float, bool],
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray filled with ``fill_value``.
+
+        Args:
+            shape (Union[int, List, Tuple, np.ndarray]): Shape of the output
+                array.
+            fill_value (Union[bytes, int, float, bool]): Fill value used for all
+                elements in the output.
+            dtype (np.dtype): Numpy dtype for the output array. If None, inferred
+                from ``fill_value``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+                Ignored when ``patch_size`` is provided.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+                Ignored when ``patch_size`` is provided.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+        """
+        if dtype is None:
+            if isinstance(fill_value, bytes):
+                dtype = np.dtype(f"S{len(fill_value)}")
+            else:
+                dtype = np.dtype(type(fill_value))
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.full(fill_value=fill_value, **kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def arange(
+            cls,
+            start: Union[int, float],
+            stop: Optional[Union[int, float]] = None,
+            step: Optional[Union[int, float]] = 1,
+            dtype: np.dtype = None,
+            shape: Optional[Union[int, List, Tuple, np.ndarray]] = None,
+            c_order: bool = True,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = None,
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray with evenly spaced values.
+
+        Behavior mirrors :func:`blosc2.arange` while also applying MLArray
+        metadata and chunk/block optimization settings.
+
+        Args:
+            start (Union[int, float]): Start of interval. If ``stop`` is None,
+                this value is treated as stop and start becomes 0.
+            stop (Optional[Union[int, float]]): End of interval (exclusive).
+            step (Optional[Union[int, float]]): Spacing between values.
+            dtype (np.dtype): Output dtype. If None, inferred similarly to
+                ``blosc2.arange``.
+            shape (Optional[Union[int, List, Tuple, np.ndarray]]): Target output
+                shape. If None, shape is inferred from start/stop/step.
+            c_order (bool): Store in C order (row-major) if True.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization. Defaults to None for this method.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            ValueError: If ``shape`` is inconsistent with
+                ``start``/``stop``/``step``.
+        """
+        if step is None:
+            step = 1
+        if stop is None:
+            stop = start
+            start = 0
+
+        num = int((stop - start) / step)
+        if shape is None:
+            shape = (max(num, 0),)
+        else:
+            shape = cls._normalize_shape(shape)
+            if math.prod(shape) != num:
+                raise ValueError(
+                    "The shape is not consistent with the start, stop and step values"
+                )
+
+        if dtype is None:
+            dtype = (
+                blosc2.DEFAULT_FLOAT
+                if np.any([np.issubdtype(type(d), float) for d in (start, stop, step)])
+                else blosc2.DEFAULT_INT
+            )
+
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.arange(
+                start=start,
+                stop=stop,
+                step=step,
+                c_order=c_order,
+                **kwargs,
+            ),
+        )
+        return class_instance
+
+    @classmethod
+    def linspace(
+            cls,
+            start: Union[int, float, complex],
+            stop: Union[int, float, complex],
+            num: Optional[int] = None,
+            dtype: np.dtype = None,
+            endpoint: bool = True,
+            shape: Optional[Union[int, List, Tuple, np.ndarray]] = None,
+            c_order: bool = True,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = None,
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray with evenly spaced samples.
+
+        Behavior mirrors :func:`blosc2.linspace` while also applying MLArray
+        metadata and chunk/block optimization settings.
+
+        Args:
+            start (Union[int, float, complex]): Start value of the sequence.
+            stop (Union[int, float, complex]): End value of the sequence.
+            num (Optional[int]): Number of samples. Required when ``shape`` is
+                None.
+            dtype (np.dtype): Output dtype. If None, inferred similarly to
+                ``blosc2.linspace``.
+            endpoint (bool): Whether ``stop`` is included.
+            shape (Optional[Union[int, List, Tuple, np.ndarray]]): Target output
+                shape. If None, inferred from ``num``.
+            c_order (bool): Store in C order (row-major) if True.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization. Defaults to None for this method.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            ValueError: If neither ``shape`` nor ``num`` is specified, or if the
+                provided ``shape`` and ``num`` are inconsistent.
+        """
+        if shape is None:
+            if num is None:
+                raise ValueError("Either `shape` or `num` must be specified.")
+            shape = (num,)
+        else:
+            shape = cls._normalize_shape(shape)
+            num = math.prod(shape) if num is None else num
+
+        if math.prod(shape) != num or num < 0:
+            msg = f"Shape is not consistent with the specified num value {num}."
+            if num < 0:
+                msg += "num must be nonnegative."
+            raise ValueError(msg)
+
+        if dtype is None:
+            dtype = (
+                blosc2.DEFAULT_COMPLEX
+                if np.any([np.issubdtype(type(d), complex) for d in (start, stop)])
+                else blosc2.DEFAULT_FLOAT
+            )
+
+        class_instance = cls()
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.linspace(
+                start=start,
+                stop=stop,
+                num=num,
+                endpoint=endpoint,
+                c_order=c_order,
+                **kwargs,
+            ),
+        )
+        return class_instance
+
+    @classmethod
+    def empty_like(
+            cls,
+            x,
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray with the same shape as ``x``.
+
+        Args:
+            x: Source object. Can be an ``MLArray`` or any array-like object
+                exposing ``shape`` and ``dtype``.
+            dtype (np.dtype): Output dtype. If None, inferred from ``x``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. If ``x`` is an ``MLArray`` and ``meta``
+                is None, metadata is copied from ``x``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            TypeError: If ``x`` is not an ``MLArray`` and has no ``shape``/``dtype``.
+        """
+        class_instance = cls()
+        shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.empty(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def zeros_like(
+            cls,
+            x,
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray of zeros with the same shape as ``x``.
+
+        Args:
+            x: Source object. Can be an ``MLArray`` or any array-like object
+                exposing ``shape`` and ``dtype``.
+            dtype (np.dtype): Output dtype. If None, inferred from ``x``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. If ``x`` is an ``MLArray`` and ``meta``
+                is None, metadata is copied from ``x``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            TypeError: If ``x`` is not an ``MLArray`` and has no ``shape``/``dtype``.
+        """
+        class_instance = cls()
+        shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.zeros(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def ones_like(
+            cls,
+            x,
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray of ones with the same shape as ``x``.
+
+        Args:
+            x: Source object. Can be an ``MLArray`` or any array-like object
+                exposing ``shape`` and ``dtype``.
+            dtype (np.dtype): Output dtype. If None, inferred from ``x``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. If ``x`` is an ``MLArray`` and ``meta``
+                is None, metadata is copied from ``x``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            TypeError: If ``x`` is not an ``MLArray`` and has no ``shape``/``dtype``.
+        """
+        class_instance = cls()
+        shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.ones(**kwargs),
+        )
+        return class_instance
+
+    @classmethod
+    def full_like(
+            cls,
+            x,
+            fill_value: Union[bool, int, float, complex],
+            dtype: np.dtype = None,
+            meta: Optional[Union[Dict, Meta]] = None,
+            patch_size: Optional[Union[int, List, Tuple]] = "default",
+            chunk_size: Optional[Union[int, List, Tuple]] = None,
+            block_size: Optional[Union[int, List, Tuple]] = None,
+            num_threads: int = 1,
+            cparams: Optional[Union[Dict, blosc2.CParams]] = None,
+            dparams: Optional[Union[Dict, blosc2.DParams]] = None,
+        ):
+        """Create an in-memory MLArray filled with ``fill_value`` and shape of ``x``.
+
+        Args:
+            x: Source object. Can be an ``MLArray`` or any array-like object
+                exposing ``shape`` and ``dtype``.
+            fill_value (Union[bool, int, float, complex]): Fill value used for
+                all elements in the output.
+            dtype (np.dtype): Output dtype. If None, inferred from ``x``.
+            meta (Optional[Union[Dict, Meta]]): Optional metadata attached to
+                the created ``MLArray``. If ``x`` is an ``MLArray`` and ``meta``
+                is None, metadata is copied from ``x``.
+            patch_size (Optional[Union[int, List, Tuple]]): Patch size hint for
+                chunk/block optimization.
+            chunk_size (Optional[Union[int, List, Tuple]]): Explicit chunk size.
+            block_size (Optional[Union[int, List, Tuple]]): Explicit block size.
+            num_threads (int): Number of threads for Blosc2 operations.
+            cparams (Optional[Union[Dict, blosc2.CParams]]): Blosc2 compression
+                parameters.
+            dparams (Optional[Union[Dict, blosc2.DParams]]): Blosc2
+                decompression parameters.
+
+        Returns:
+            MLArray: A newly created in-memory MLArray instance.
+
+        Raises:
+            TypeError: If ``x`` is not an ``MLArray`` and has no ``shape``/``dtype``.
+        """
+        class_instance = cls()
+        shape, dtype, meta = class_instance._resolve_like_input(x, dtype, meta)
+        class_instance._construct_in_memory(
+            shape=shape,
+            dtype=dtype,
+            meta=meta,
+            patch_size=patch_size,
+            chunk_size=chunk_size,
+            block_size=block_size,
+            num_threads=num_threads,
+            cparams=cparams,
+            dparams=dparams,
+            store_builder=lambda **kwargs: blosc2.full(fill_value=fill_value, **kwargs),
+        )
+        return class_instance
+
     def close(self):
         """Flush metadata and close the underlying store.
 
@@ -1010,12 +1738,19 @@ class MLArray:
             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.")
+        if (chunk_size is not None and block_size is None) or (chunk_size is None and block_size is not None):
+            raise RuntimeError("If either chunk/block size is used then both must be set.")
 
         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
+            elif meta_blosc2 is not None and (meta_blosc2.chunk_size is not None):
+                chunk_size = meta_blosc2.chunk_size
+                block_size = meta_blosc2.block_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] * num_spatial_axes
+        if chunk_size is not None or block_size is not None:
+            patch_size = None
 
         patch_size = [patch_size] * len(shape) if isinstance(patch_size, int) else patch_size
 

{mlarray-0.0.43 → mlarray-0.0.45}/mlarray.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.43
+Version: 0.0.45
 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.43 → mlarray-0.0.45}/mlarray.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ docs/why.md
 examples/example_asarray.py
 examples/example_bboxes_only.py
 examples/example_channel.py
+examples/example_in_memory_constructors.py
 examples/example_metadata_only.py
 examples/example_non_spatial.py
 examples/example_open.py
@@ -39,6 +40,7 @@ mlarray.egg-info/requires.txt
 mlarray.egg-info/top_level.txt
 tests/test_asarray.py
 tests/test_bboxes.py
+tests/test_constructors.py
 tests/test_create.py
 tests/test_metadata.py
 tests/test_open.py

mlarray-0.0.45/tests/test_constructors.py

@@ -0,0 +1,135 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import blosc2
+import numpy as np
+
+from mlarray import MLArray
+
+
+class TestInMemoryConstructors(unittest.TestCase):
+    def test_empty_and_save_roundtrip(self):
+        shape = (4, 8, 8)
+        arr = MLArray.empty(
+            shape=shape,
+            dtype=np.float32,
+            patch_size=None,
+            chunk_size=(1, 4, 4),
+            block_size=(1, 2, 2),
+            num_threads=1,
+            cparams={"codec": blosc2.Codec.LZ4HC, "clevel": 1},
+            dparams={"nthreads": 1},
+        )
+
+        data = np.arange(np.prod(shape), dtype=np.float32).reshape(shape)
+        arr[...] = data
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = Path(tmpdir) / "in-memory-empty.mla"
+            arr.save(path)
+            loaded = MLArray(path)
+
+            self.assertEqual(loaded.shape, shape)
+            self.assertTrue(np.allclose(loaded[...], data))
+
+    def test_zeros_ones_full(self):
+        shape = (3, 5)
+
+        zeros = MLArray.zeros(
+            shape=shape,
+            dtype=np.int32,
+            patch_size=None,
+            chunk_size=(3, 5),
+            block_size=(1, 5),
+        )
+        ones = MLArray.ones(
+            shape=shape,
+            dtype=np.float32,
+            patch_size=None,
+            chunk_size=(3, 5),
+            block_size=(1, 5),
+        )
+        full = MLArray.full(
+            shape=shape,
+            fill_value=7,
+            dtype=np.int16,
+            patch_size=None,
+            chunk_size=(3, 5),
+            block_size=(1, 5),
+        )
+
+        self.assertTrue(np.array_equal(zeros[...], np.zeros(shape, dtype=np.int32)))
+        self.assertTrue(np.array_equal(ones[...], np.ones(shape, dtype=np.float32)))
+        self.assertTrue(np.array_equal(full[...], np.full(shape, 7, dtype=np.int16)))
+
+    def test_arange_and_linspace(self):
+        arr1 = MLArray.arange(0, 12, 2, patch_size=None, num_threads=1)
+        self.assertTrue(np.array_equal(arr1[...], np.arange(0, 12, 2)))
+
+        arr2 = MLArray.arange(0, 12, 2, shape=(2, 3), patch_size=None, num_threads=1)
+        self.assertTrue(np.array_equal(arr2[...], np.arange(0, 12, 2).reshape(2, 3)))
+
+        lin = MLArray.linspace(
+            0.0, 1.0, num=6, shape=(2, 3), endpoint=False, patch_size=None, num_threads=1
+        )
+        self.assertTrue(
+            np.allclose(lin[...], np.linspace(0.0, 1.0, 6, endpoint=False).reshape(2, 3))
+        )
+
+    def test_like_methods_and_meta_copy(self):
+        base = MLArray.full(
+            shape=(2, 3, 4),
+            fill_value=5,
+            dtype=np.int16,
+            meta={"case": "meta-copy"},
+            patch_size=None,
+            chunk_size=(1, 3, 4),
+            block_size=(1, 2, 2),
+        )
+
+        empty_like = MLArray.empty_like(
+            base, patch_size=None, chunk_size=(1, 3, 4), block_size=(1, 2, 2)
+        )
+        zeros_like = MLArray.zeros_like(
+            base, patch_size=None, chunk_size=(1, 3, 4), block_size=(1, 2, 2)
+        )
+        ones_like = MLArray.ones_like(
+            base,
+            dtype=np.float32,
+            patch_size=None,
+            chunk_size=(1, 3, 4),
+            block_size=(1, 2, 2),
+        )
+        full_like = MLArray.full_like(
+            base,
+            fill_value=9,
+            patch_size=None,
+            chunk_size=(1, 3, 4),
+            block_size=(1, 2, 2),
+        )
+
+        self.assertEqual(empty_like.shape, base.shape)
+        self.assertEqual(zeros_like.shape, base.shape)
+        self.assertEqual(ones_like.shape, base.shape)
+        self.assertEqual(full_like.shape, base.shape)
+
+        self.assertTrue(
+            np.array_equal(zeros_like[...], np.zeros(base.shape, dtype=base.dtype))
+        )
+        self.assertTrue(
+            np.array_equal(ones_like[...], np.ones(base.shape, dtype=np.float32))
+        )
+        self.assertTrue(
+            np.array_equal(full_like[...], np.full(base.shape, 9, dtype=base.dtype))
+        )
+
+        self.assertEqual(zeros_like.meta.source.to_plain(), {"case": "meta-copy"})
+
+    def test_like_raises_for_invalid_input(self):
+        with self.assertRaises(TypeError):
+            MLArray.zeros_like(123)
+
+
+if __name__ == "__main__":
+    unittest.main()