ome zarr chunks (#1092)

* ome zarr chunks
* set scale factors to emtpy list + fix unit tests
* mypy
* lowercase to fix unit test linux
* bump ome zarr in pyproject toml
* dask accessor is now always loaded
* deduplicate storage option util; use chunks from data when not specified in storage options
* simplify, document and test the chunk helper functions
* guard against storage_options["chunks"]="" + Change ValueError
* remove data argument from _prepare_storage_options()
* remove data argument from _prepare_storage_options()
---------
Co-authored-by: Luca Marconato <m.lucalmer@gmail.com>

Author: ArneDefauw

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 "networkx",
 "numba>=0.55.0",
 "numpy",
-"ome_zarr>=0.12.2",
+"ome_zarr>=0.14.0",
 "pandas",
 "pooch",
 "pyarrow",

src/spatialdata/__init__.py

@@ -4,6 +4,8 @@
 fromimportlib.metadataimportversion
 fromtypingimportTYPE_CHECKING, Any
 
+importspatialdata.models._accessor# noqa: F401
+
 __version__=version("spatialdata")
 
 _submodules= {
@@ -129,15 +131,8 @@
 "settings",
 ]
 
-_accessor_loaded=False
-
 
 def__getattr__(name: str) ->Any:
-global_accessor_loaded
-ifnot_accessor_loaded:
-_accessor_loaded=True
-importspatialdata.models._accessor# noqa: F401
-
 ifnamein_submodules:
 returnimportlib.import_module(f"spatialdata.{name}")
 ifnamein_LAZY_IMPORTS:

src/spatialdata/_io/io_raster.py

@@ -1,7 +1,8 @@
 from __future__ importannotations
 
+fromcollections.abcimportSequence
 frompathlibimportPath
-fromtypingimportAny, Literal
+fromtypingimportAny, Literal, TypeGuard
 
 importdask.arrayasda
 importnumpyasnp
@@ -38,6 +39,126 @@
 )
 
 
+def_is_flat_int_sequence(value: object) ->TypeGuard[Sequence[int]]:
+# e.g. "", "auto" or b"auto"
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnall(isinstance(v, int) forvinvalue)
+
+
+def_is_dask_chunk_grid(value: object) ->TypeGuard[Sequence[Sequence[int]]]:
+ifisinstance(value, str|bytes):
+returnFalse
+ifnotisinstance(value, Sequence):
+returnFalse
+returnlen(value) >0andall(_is_flat_int_sequence(axis_chunks) foraxis_chunksinvalue)
+
+
+def_is_regular_dask_chunk_grid(chunk_grid: Sequence[Sequence[int]]) ->bool:
+"""Check whether a Dask chunk grid is regular (zarr-compatible).
+
+ A grid is regular when every axis has at most one unique chunk size among all but the last
+ chunk, and the last chunk is not larger than the first.
+
+ Parameters
+ ----------
+ chunk_grid
+ Per-axis tuple of chunk sizes, for instance as returned by ``dask_array.chunks``.
+
+ Examples
+ --------
+ Triggers ``continue`` on the first ``if`` (single or empty axis):
+
+ >>> _is_regular_dask_chunk_grid([(4,)]) # single chunk → True
+ True
+ >>> _is_regular_dask_chunk_grid([()]) # empty axis → True
+ True
+
+ Triggers the first ``return False`` (non-uniform interior chunks):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 3, 4)]) # interior sizes differ → False
+ False
+
+ Triggers the second ``return False`` (last chunk larger than the first):
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 5)]) # last > first → False
+ False
+
+ Exits with ``return True``:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 4)]) # all equal → True
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1)]) # last < first → True
+ True
+
+ Empty grid (loop never executes) → True:
+
+ >>> _is_regular_dask_chunk_grid([])
+ True
+
+ Multi-axis: all axes regular → True; one axis irregular → False:
+
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (3, 3, 2)])
+ True
+ >>> _is_regular_dask_chunk_grid([(4, 4, 4, 1), (4, 4, 3, 4)])
+ False
+ """
+# Match Dask's private _check_regular_chunks() logic without depending on its internal API.
+foraxis_chunksinchunk_grid:
+iflen(axis_chunks) <=1:
+continue
+iflen(set(axis_chunks[:-1])) >1:
+returnFalse
+ifaxis_chunks[-1] >axis_chunks[0]:
+returnFalse
+returnTrue
+
+
+def_chunks_to_zarr_chunks(chunks: object) ->tuple[int, ...] |int|None:
+ifisinstance(chunks, int):
+returnchunks
+if_is_flat_int_sequence(chunks):
+returntuple(chunks)
+if_is_dask_chunk_grid(chunks):
+chunk_grid=tuple(tuple(axis_chunks) foraxis_chunksinchunks)
+if_is_regular_dask_chunk_grid(chunk_grid):
+returntuple(axis_chunks[0] foraxis_chunksinchunk_grid)
+returnNone
+returnNone
+
+
+def_normalize_explicit_chunks(chunks: object) ->tuple[int, ...] |int:
+normalized=_chunks_to_zarr_chunks(chunks)
+ifnormalizedisNone:
+raiseValueError(
+'storage_options["chunks"] must resolve to a Zarr chunk shape or a regular Dask chunk grid. '
+"The current raster has irregular Dask chunks, which cannot be written to Zarr. "
+"To fix this, rechunk before writing, for example by passing regular chunks=... "
+"to Image2DModel.parse(...) / Labels2DModel.parse(...)."
+ )
+returnnormalized
+
+
+def_prepare_storage_options(
+storage_options: JSONDict|list[JSONDict] |None,
+) ->JSONDict|list[JSONDict] |None:
+ifstorage_optionsisNone:
+returnNone
+ifisinstance(storage_options, dict):
+prepared=dict(storage_options)
+if"chunks"inprepared:
+prepared["chunks"] =_normalize_explicit_chunks(prepared["chunks"])
+returnprepared
+
+prepared_options= [dict(options) foroptionsinstorage_options]
+foroptionsinprepared_options:
+if"chunks"inoptions:
+options["chunks"] =_normalize_explicit_chunks(options["chunks"])
+returnprepared_options
+
+
 def_read_multiscale(
 store: str|Path, raster_type: Literal["image", "labels"], reader_format: Format
 ) ->DataArray|DataTree:
@@ -251,20 +372,18 @@ def _write_raster_dataarray(
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
 input_axes: tuple[str, ...] =tuple(raster_data.dims)
-chunks=raster_data.chunks
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-ifstorage_optionsisnotNone:
-if"chunks"notinstorage_optionsandisinstance(storage_options, dict):
-storage_options["chunks"] =chunks
-else:
-storage_options= {"chunks": chunks}
-# Scaler needs to be None since we are passing the data already downscaled for the multiscale case.
-# We need this because the argument of write_image_ngff is called image while the argument of
+storage_options=_prepare_storage_options(storage_options)
+# Explicitly disable pyramid generation for single-scale rasters. Recent ome-zarr versions default
+# write_image()/write_labels() to scale_factors=(2, 4, 8, 16), which would otherwise write s0, s1, ...
+# even when the input is a plain DataArray.
+# We need this because the argument of write_image_ngff is called image while the argument of
 # write_labels_ngff is called label.
 metadata[raster_type] =data
 ome_zarr_format=get_ome_zarr_format(raster_format)
 write_single_scale_ngff(
 group=group,
+scale_factors=[],
 scaler=None,
 fmt=ome_zarr_format,
 axes=parsed_axes,
@@ -322,10 +441,9 @@ def _write_raster_datatree(
 transformations=_get_transformations_xarray(xdata)
 iftransformationsisNone:
 raiseValueError(f"{element_name} does not have any transformations and can therefore not be written.")
-chunks=get_pyramid_levels(raster_data, "chunks")
 
 parsed_axes=_get_valid_axes(axes=list(input_axes), fmt=raster_format)
-storage_options=[{"chunks": chunk} forchunkinchunks]
+storage_options=_prepare_storage_options(storage_options)
 ome_zarr_format=get_ome_zarr_format(raster_format)
 dask_delayed=write_multi_scale_ngff(
 pyramid=data,

tests/io/test_partial_read.py

@@ -184,9 +184,9 @@ def sdata_with_corrupted_image_chunks_zarrv3(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -206,9 +206,9 @@ def sdata_with_corrupted_image_chunks_zarrv2(session_tmp_path: Path) -> PartialR
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray") # it will hide the "0" array from the Zarr reader
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
- (sdata_path/"images"/corrupted/"0").touch()
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray") # it will hide the "0" array from the Zarr reader
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
+ (sdata_path/"images"/corrupted/"s0").touch()
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
 returnPartialReadTestCase(
@@ -315,8 +315,8 @@ def sdata_with_missing_image_chunks_zarrv3(
 sdata.write(sdata_path)
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/"zarr.json")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/"zarr.json")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]
 
@@ -339,8 +339,8 @@ def sdata_with_missing_image_chunks_zarrv2(
 sdata.write(sdata_path, sdata_formats=SpatialDataContainerFormatV01())
 
 corrupted="blobs_image"
-os.unlink(sdata_path/"images"/corrupted/"0"/".zarray")
-os.rename(sdata_path/"images"/corrupted/"0", sdata_path/"images"/corrupted/"0_corrupted")
+os.unlink(sdata_path/"images"/corrupted/"s0"/".zarray")
+os.rename(sdata_path/"images"/corrupted/"s0", sdata_path/"images"/corrupted/"s0_corrupted")
 
 not_corrupted= [namefor_, name, _insdata.gen_elements() ifname!=corrupted]