anu_ctlab_io.zarr
=================

.. py:module:: anu_ctlab_io.zarr

.. autoapi-nested-parse::

   Read and write data from/to the ANU CTLab zarr data format.

   This is an optional extra module, and must be explicitly installed to be used (e.g., ``pip install anu_ctlab_io[zarr]``).







Package Contents
----------------

.. py:class:: OMEZarrVersion(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   OME-Zarr specification version to use when writing.


   .. py:attribute:: v05
      :value: '0.5'



.. py:function:: dataset_to_zarr(dataset, path, datatype = None, dataset_id = None, ome_zarr_version = OMEZarrVersion.v05, max_shard_size_mb = None, history = None, chunk_size_mb = None, chunks = 'auto', shards = 'auto', create_array_kwargs = None, dimension_separator_threshold = 64, **extra_attrs)

   Write a :any:`Dataset` to Zarr format.

   By default, chunks and shards use power-of-two square or cubic shapes targeting
   ``32**3`` and ``512**3`` elements respectively. Shapes are trimmed to the array
   dimensions, and shards are rounded up to chunk multiples.

   :param dataset: The :any:`Dataset` to write.
   :param path: Path to write the Zarr store.
   :param datatype: The data type identifier. If None, attempts to infer from dataset.
   :param dataset_id: Unique identifier for the dataset. Auto-generated if not provided.
   :param ome_zarr_version: OME-Zarr specification version to use.
       Set to :any:`OMEZarrVersion.v05` (default) to write OME-Zarr V0.5 group format.
       Set to ``None`` to write a simple Zarr V3 array with mango metadata.
   :param max_shard_size_mb: Maximum shard size in MB for Zarr v3 sharding.
       Deprecated and ignored.
       Passing this emits a warning and leaves layout selection to ``chunks``/``shards``.
   :param history: Dictionary of history entries to add.
       Keys should be identifiers, values are history strings.
   :param chunk_size_mb: Target chunk size in MB for automatic chunking.
       Deprecated and ignored.
       Passing this emits a warning and leaves layout selection to ``chunks``/``shards``.
   :param chunks: Explicit chunk shape as a tuple shape (e.g., ``(10, 512, 512)``), int (target # of elements), or ``'auto'``.
       Can be provided on its own to write a non-sharded Zarr array, or together with ``shards`` to use the sharding codec.
       An integer specifies the target number of elements for an automatically derived layout.
       ``'auto'`` uses a default target corresponding to ``32**3`` or ``256**2`` elements.
       To write without sharding, pass ``shards=None`` explicitly.
       A value of ``0`` in a shape tuple means "span this axis" — the full array axis for unsharded writes, or the full shard axis when ``shards`` is also provided.
   :param shards: Explicit shard shape as a tuple shape (e.g., ``(100, 512, 512)``), int (target # of elements), or ``'auto'``.
       May be provided together with an explicit ``chunks`` tuple.
       Providing an explicit shard shape with ``chunks='auto'`` is an error.
       An integer specifies the target number of elements for an automatically derived layout.
       Use ``None`` to disable sharding, or ``'auto'`` to use the default target of ``512**3`` or ``8192**2`` elements.
       A value of ``0`` in a shape tuple means "span the full array axis".
       When provided, the user is responsible for ensuring shard shapes are evenly divisible by chunk shapes.
   :param create_array_kwargs: Additional keyword arguments to pass to zarr.create_array().
       For example, to set compression: ``create_array_kwargs={'compressors': [ZstdCodec(level=5)]}``.
   :param dimension_separator_threshold: Use ``'/'`` as the chunk key dimension
       separator when the number of chunks exceeds this threshold; otherwise use
       ``'.'``. ``None`` uses the Zarr default of ``'/'``.
   :param extra_attrs: Additional attributes to include in mango metadata.


.. py:function:: dataset_from_zarr(path, **kwargs)

   Loads a :any:`Dataset` from the path to a zarr.

   This method is used by :any:`Dataset.from_path`, by preference call that constructor directly.

   :param Path: The path to the zarr to be loaded
   :param kwargs: Currently this method consumes no kwargs, but will pass provided kwargs to ``dask.Array.from_path``.