`ngff_zarr.to_ngff_zarr`¶

Module Contents¶

Functions¶

`_numcodecs_to_zarr_v3_codec`	Translate a numcodecs compressor to its zarr v3 codec equivalent.
`_remove_none_values`	Recursively strip `None`-valued keys from nested dicts and lists.
`_pop_metadata_optionals`	Strip optional metadata fields that must not be serialized.
`_prep_for_to_zarr`
`_numpy_to_zarr_dtype`
`_write_with_tensorstore`	Write array using tensorstore backend
`_validate_ngff_parameters`	Validate the parameters for the NGFF Zarr generation.
`_prepare_metadata`	Prepare and convert metadata to the proper version format.
`_create_zarr_root`	Create and configure the root Zarr group with proper attributes.
`_configure_sharding`	Configure sharding parameters if sharding is enabled.
`_write_array_with_tensorstore`	Write an array using the TensorStore backend.
`_prepare_zarr_kwargs`	Prepare zarr kwargs for dask.array.to_zarr.
`_array_write_error`	Build an actionable error for failures while writing a zarr array.
`_write_array_direct`	Write an array directly using dask.array.to_zarr.
`_handle_large_array_writing`	Handle writing large arrays by splitting them into manageable pieces.
`_compute_write_regions`	Compute the regions for writing a large array in chunks.
`_compute_plane_regions`	Compute regions for a single z-slab, dividing into planes and strips if needed.
`_prepare_next_scale`	Prepare the next scale for processing if needed.
`to_ome_zarr`	Write an image pixel array and metadata to a Zarr store with the OME-NGFF standard data model.
`_to_ngff_zarr_impl`	Internal implementation of to_ngff_zarr without .ozx handling.

Data¶

`zarr_version`
`IS_ZARR_V3_PLUS`
`DASK_SUPPORTS_SHARDING`
`_DASK_USES_GROUP_CREATE`
`ScaleStrategy`
`to_ngff_zarr`

API¶

ngff_zarr.to_ngff_zarr.zarr_version¶: ‘Version(…)’

ngff_zarr.to_ngff_zarr.IS_ZARR_V3_PLUS¶: None

ngff_zarr.to_ngff_zarr.DASK_SUPPORTS_SHARDING¶: None

ngff_zarr.to_ngff_zarr._DASK_USES_GROUP_CREATE¶: False

ngff_zarr.to_ngff_zarr.ScaleStrategy¶: None

ngff_zarr.to_ngff_zarr._numcodecs_to_zarr_v3_codec(compressor)¶

Translate a numcodecs compressor to its zarr v3 codec equivalent.

Returns a zarr v3 codec object suitable for use inside a

Class:: ~zarr.codecs.sharding.ShardingCodec or as a standalone bytes-to-bytes codec. Returns None when compressor is None or the codec type is not recognised.

ngff_zarr.to_ngff_zarr._remove_none_values(obj: Any) → Any¶

Recursively strip None-valued keys from nested dicts and lists.

In the OME-Zarr spec the absence of a field carries no significance: only fields that are present are meaningful, and an explicit null is treated as equivalent to omitting the field. Culling every None therefore keeps the written metadata clean without enumerating optional fields per spec version. Only None is removed; falsy-but-valid values such as 0, 0.0, "" and empty collections are preserved.

ngff_zarr.to_ngff_zarr._pop_metadata_optionals(metadata_dict: dict) → dict¶

Strip optional metadata fields that must not be serialized.

Recursively culls all None-valued keys. Axes that carry a populated RFC 4 orientation keep it – anatomical orientation is written whenever it is present – while axes whose orientation is None have the key dropped by the None stripping below.

ngff_zarr.to_ngff_zarr._prep_for_to_zarr( store: ngff_zarr._zarr_types.StoreLike, arr: dask.array.Array, ) → dask.array.Array¶

ngff_zarr.to_ngff_zarr._numpy_to_zarr_dtype(dtype)¶

ngff_zarr.to_ngff_zarr._write_with_tensorstore(

store_path: str,

array,

region,

chunks,

zarr_format,

dimension_names=None,

internal_chunk_shape=None,

full_array_shape=None,

create_dataset=True,

compressor=None,

**kwargs,

) → None¶: Write array using tensorstore backend

ngff_zarr.to_ngff_zarr._validate_ngff_parameters( version: str | ngff_zarr._supported_versions.NgffVersion, chunks_per_shard: int | tuple[int, ...] | dict[str, int] | None, use_tensorstore: bool, store: ngff_zarr._zarr_types.StoreLike, ) → None¶: Validate the parameters for the NGFF Zarr generation.

ngff_zarr.to_ngff_zarr._prepare_metadata( multiscales: ngff_zarr.multiscales.NgffMultiscales, version: str, ) → tuple[ngff_zarr.v04.zarr_metadata.Metadata | ngff_zarr.v05.zarr_metadata.Metadata, tuple[str, ...], dict]¶: Prepare and convert metadata to the proper version format.

ngff_zarr.to_ngff_zarr._create_zarr_root( store: ngff_zarr._zarr_types.StoreLike, chunk_store: ngff_zarr._zarr_types.StoreLike | None, version: str, overwrite: bool, metadata_dict: dict, ) → zarr.Group¶: Create and configure the root Zarr group with proper attributes.

ngff_zarr.to_ngff_zarr._configure_sharding( arr: dask.array.Array, chunks_per_shard: int | tuple[int, ...] | dict[str, int] | None, dims: tuple[str, ...], kwargs: dict, ) → tuple[dict, tuple[int, ...] | None, dask.array.Array]¶: Configure sharding parameters if sharding is enabled.

ngff_zarr.to_ngff_zarr._write_array_with_tensorstore(

store_path: str,

path: str,

arr: dask.array.Array,

chunks: tuple[int, ...] | list[int],

shards: tuple[int, ...] | None,

internal_chunk_shape: tuple[int, ...] | None,

zarr_format: int,

dimension_names: tuple[str, ...] | None,

region: tuple[slice, ...],

full_array_shape: tuple[int, ...] | None = None,

create_dataset: bool = True,

**kwargs,

) → None¶: Write an array using the TensorStore backend.

ngff_zarr.to_ngff_zarr._prepare_zarr_kwargs(to_zarr_kwargs: dict)¶

Prepare zarr kwargs for dask.array.to_zarr.

This helper function ensures that correct kwargs are passed on based on which version of zarr and dask is being used. The different versions support different sets of arguments. The zarr_kwargs are adjusted in place and thus the original is overwritten. This is not a problem given that the arguments being adjusted are the same for the zarr store in use.

ngff_zarr.to_ngff_zarr._array_write_error(path: str, error: Exception) → OSError¶

Build an actionable error for failures while writing a zarr array.

Writing an array triggers lazy evaluation of the dask graph, which reads the source data (e.g. a TIFF/SVS file or its on-disk slab cache). A corrupt source can surface here as a cryptic OSError (such as the [Errno 22] Invalid argument reported in gh-issue-343) only after a long conversion. Wrap it with context identifying the likely cause so the failure is diagnosable rather than mysterious.

ngff_zarr.to_ngff_zarr._write_array_direct(

arr: dask.array.Array,

store: ngff_zarr._zarr_types.StoreLike,

path: str,

sharding_kwargs: dict,

zarr_kwargs: dict,

format_kwargs: dict,

dimension_names_kwargs: dict,

region: tuple[slice, ...] | None = None,

zarr_array=None,

**kwargs,

) → None¶: Write an array directly using dask.array.to_zarr.

ngff_zarr.to_ngff_zarr._handle_large_array_writing(

image,

arr: dask.array.Array,

store: ngff_zarr._zarr_types.StoreLike,

path: str,

dims: tuple[str, ...],

dim_factors: dict[str, int],

chunks: tuple[int, ...],

sharding_kwargs: dict,

zarr_kwargs: dict,

format_kwargs: dict,

dimension_names_kwargs: dict,

use_tensorstore: bool,

store_path: str | None,

zarr_format: int,

dimension_names: tuple[str, ...],

internal_chunk_shape: tuple[int, ...] | None,

shards: tuple[int, ...] | None,

progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None,

index: int,

nscales: int,

**kwargs,

) → None¶: Handle writing large arrays by splitting them into manageable pieces.

ngff_zarr.to_ngff_zarr._compute_write_regions( image, dims: tuple[str, ...], arr: dask.array.Array, shape: tuple[int, ...], x_index: int, y_index: int, chunks: tuple[int, ...], shrink_factors: list[int], ) → list[tuple[slice, ...]]¶: Compute the regions for writing a large array in chunks.

ngff_zarr.to_ngff_zarr._compute_plane_regions( image, dims: tuple[str, ...], arr: dask.array.Array, shape: tuple[int, ...], x_index: int, y_index: int, z_index: int, chunks: tuple[int, ...], shrink_factors: list[int], slab_index: int, ) → list[tuple[slice, ...]]¶: Compute regions for a single z-slab, dividing into planes and strips if needed.

ngff_zarr.to_ngff_zarr._prepare_next_scale( image, index: int, nscales: int, multiscales: ngff_zarr.multiscales.NgffMultiscales, store: ngff_zarr._zarr_types.StoreLike, path: str, progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None, scale_strategy: ngff_zarr.to_ngff_zarr.ScaleStrategy = 'pad', ) → object | None¶

Prepare the next scale for processing if needed.

Parameters:: scale_strategy – Strategy for handling non-power-of-2 scale factors. “pad” (default) always uses incremental downsampling from the previous level, which may produce slightly different sizes due to floor-division rounding. “exact” uses pre-computed images from the initial to_multiscales() call when incremental downsampling cannot achieve the exact target size.

ngff_zarr.to_ngff_zarr.to_ome_zarr(

store: ngff_zarr._zarr_types.StoreLike,

multiscales: ngff_zarr.multiscales.NgffMultiscales,

version: str = '0.5',

overwrite: bool = True,

use_tensorstore: bool = False,

chunk_store: ngff_zarr._zarr_types.StoreLike | None = None,

progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None = None,

chunks_per_shard: int | tuple[int, ...] | dict[str, int] | None = None,

scale_strategy: ngff_zarr.to_ngff_zarr.ScaleStrategy = 'pad',

**kwargs,

) → None¶

Write an image pixel array and metadata to a Zarr store with the OME-NGFF standard data model.

Parameters:

store (StoreLike) – Store or path to directory in file system. If the path ends with .ozx, writes an RFC-9 compliant zipped OME-Zarr file.
multiscales (NgffMultiscales) – NgffMultiscales OME-NGFF image pixel data and metadata. Can be generated with ngff_zarr.to_multiscales.
version (str, optional) – OME-Zarr specification version. For .ozx files, version 0.5 is required.
overwrite (bool, optional) – If True, delete any pre-existing data in store before creating groups.
use_tensorstore (bool, optional) – If True, write array using tensorstore backend.
chunk_store (StoreLike, optional) – Separate storage for chunks. If not provided, store will be used for storage of both chunks and metadata.
progress (RichDaskProgress) – Optional progress logger
chunks_per_shard (int, tuple, or dict, optional) – Number of chunks along each axis in a shard. If None, no sharding. For .ozx files, defaults to 2 if not specified. Requires OME-Zarr version >= 0.5.
scale_strategy ("pad" or "exact", optional) – Strategy for handling non-power-of-2 scale factors during multiscale writing. “pad” (default) always uses incremental downsampling from the previous level, which is memory-efficient but may produce slightly different sizes due to floor-division rounding. “exact” uses pre-computed images from the initial to_multiscales() call when incremental downsampling cannot achieve the exact target size (original_size // scale_factor).
**kwargs – Passed to the zarr.create_array() or zarr.creation.create() function, e.g., compression options.

ngff_zarr.to_ngff_zarr.to_ngff_zarr¶: None

ngff_zarr.to_ngff_zarr._to_ngff_zarr_impl(

store: ngff_zarr._zarr_types.StoreLike,

multiscales: ngff_zarr.multiscales.NgffMultiscales,

version: str = '0.4',

overwrite: bool = True,

use_tensorstore: bool = False,

chunk_store: ngff_zarr._zarr_types.StoreLike | None = None,

progress: ngff_zarr.rich_dask_progress.NgffProgress | ngff_zarr.rich_dask_progress.NgffProgressCallback | None = None,

chunks_per_shard: int | tuple[int, ...] | dict[str, int] | None = None,

scale_strategy: ngff_zarr.to_ngff_zarr.ScaleStrategy = 'pad',

**kwargs,

) → None¶: Internal implementation of to_ngff_zarr without .ozx handling.

ngff_zarr.to_ngff_zarr¶

Module Contents¶

Functions¶

Data¶

API¶

`ngff_zarr.to_ngff_zarr`¶