linumpy.io#

OME-Zarr and related I/O helpers for linumpy.

Submodules#

Classes#

`CustomScaler`	Custom ome_zarr.scale.Scaler class for handling downscaling up to 3D.
`OmeZarrWriter`	Write OME-Zarr files to disk in a pyramidal format, chunk by chunk.
`AnalysisOmeZarrWriter`	OmeZarrWriter subclass that supports custom analysis-friendly resolution pyramids.

Functions#

`create_tempstore`([dir, suffix])	Create a zarr store inside a temporary directory.
`create_transformation_dict`(nlevels, voxel_size[, ndims])	Create a list of coordinate transformation dicts for OME-Zarr pyramid levels.
`generate_axes_dict`([ndims, unit])	Generate the axes dictionary for up to 4 dimensions.
`create_directory`(store_path[, overwrite])	Create directory at store_path, optionally removing an existing one.
`validate_n_levels`(n_levels, shape[, downscale_factor])	Validate n_levels such that it does not go beyond the volume shape.
`save_omezarr`(data, store_path[, voxel_size, chunks, ...])	Save array to disk in OME-NGFF zarr format.
`read_omezarr`(zarr_path[, level])	Read OME-Zarr image at zarr_path and return the array and voxel size.

Package Contents#

linumpy.io.create_tempstore(dir=None, suffix=None)[source]#

Create a zarr store inside a temporary directory.

Defaults to creating the temp directory inside the current working directory (typically a Nextflow task scratch dir) rather than /tmp, so leaked temp zarrs are reclaimed when the work dir is cleaned and do not pile up on small /tmp partitions.

Parameters:

dir (str) – Directory inside which to create the temporary directory. Defaults to the current working directory.
suffix (str) – Suffix of temporary directory.

Return zarr_store:

Temporary ZarrStore.

Return type:

zarr.storage.LocalStore

class linumpy.io.CustomScaler[source]#

Bases: ome_zarr.scale.Scaler

Custom ome_zarr.scale.Scaler class for handling downscaling up to 3D.

Only resize_image method is implemented. Interpolation is ALWAYS done using 1-st order (linear) interpolation.

resize_image(image)[source]#

Resize a numpy array OR a dask array to a smaller array (not pyramid).

This method is the only method from the Scaler class called from ome_zarr.writer.write_image.

Parameters:: image (numpy.ndarray | dask.array.Array)
Return type:: numpy.ndarray | dask.array.Array

linear(base)[source]#

Downsample using skimage.transform.resize() with linear interpolation.

Parameters:: base (numpy.ndarray)
Return type:: list

linumpy.io.create_transformation_dict(nlevels, voxel_size, ndims=3)[source]#

Create a list of coordinate transformation dicts for OME-Zarr pyramid levels.

Supports images up to 4 dimensions.

Parameters:

nlevels (int) – The number of levels in the pyramid.
voxel_size (tuple) – The voxel size of the dataset.
ndims (int) – The number of dimensions of the dataset.

Return coord_transforms:

List of coordinate transformations

Return type:

list

linumpy.io.generate_axes_dict(ndims=3, unit='millimeter')[source]#

Generate the axes dictionary for up to 4 dimensions.

Dimensions are returned in order (c, z, y, x).

Parameters:

ndims (int) – Number of dimensions.
unit (str)

Return axes:

The axes dictionary.

Return type:

list

linumpy.io.create_directory(store_path, overwrite=False)[source]#

Create directory at store_path, optionally removing an existing one.

Parameters:

store_path (pathlib.Path)
overwrite (bool)

Return type:

pathlib.Path

linumpy.io.validate_n_levels(n_levels, shape, downscale_factor=2)[source]#

Validate n_levels such that it does not go beyond the volume shape.

Parameters:

n_levels (int) – Requested number of levels
shape (tuple of int) – Shape of volume to save
downscale_factor (int) – The downscale factor

Return adjusted_n_levels:

Adjusted n_levels such that we don’t exceed volume shape.

Return type:

int

linumpy.io.save_omezarr(data, store_path, voxel_size=(0.001, 0.001, 0.001), chunks=(128, 128, 128), n_levels=5, overwrite=True)[source]#

Save array to disk in OME-NGFF zarr format.

Expected ordering for axes in data and scales is (c, z, y, x).

Parameters:

data (numpy or dask array) – numpy or dask array to save as zarr.
store_path (str) – The path of the output zarr group.
voxel_size (tuple of n float, with n the number of dimensions.) – Voxel size in mm.
chunks (tuple of n int, with n the number of dimensions.) – Chunk size on disk.
n_levels (int) – Number of levels in Gaussian pyramid.
overwrite (bool) – Overwrite store_path if it already exists.

Return zarr_group:

Resulting zarr group saved to disk.

Return type:

zarr.Group

linumpy.io.read_omezarr(zarr_path, level=0)[source]#

Read OME-Zarr image at zarr_path and return the array and voxel size.

Loads image data for level in the pyramid.

Parameters:

zarr_path (str) – Path of OME-zarr file to load.
level (int >= 0) – The level of the pyramid to load (0 is full resolution data).

Return vol:

Requested zarr array.

Return res:

Voxel size of zarr array.

Return type:

tuple

class linumpy.io.OmeZarrWriter(store_path, shape, chunk_shape, shards=None, dtype=np.float32, overwrite=True, downscale_factor=2, unit='millimeter')[source]#

Write OME-Zarr files to disk in a pyramidal format, chunk by chunk.

Parameters:

store_path (pathlib.Path)
shape (tuple | collections.abc.Sequence)
chunk_shape (tuple | collections.abc.Sequence)
shards (tuple | None)
dtype (type | numpy.dtype)
overwrite (bool)
downscale_factor (int)
unit (str)

fmt: ome_zarr.format.CurrentFormat#

shape: collections.abc.Sequence#

downscale_factor: int#

root: zarr.Group#

axes: list#

zarray: zarr.Array#

property ndim: int#

Number of dimensions.

Return type:: int

property dtype: numpy.dtype#

Data type of the underlying zarr array.

Return type:: numpy.dtype

finalize(res, n_levels=5)[source]#

Finalize the OME-Zarr with traditional power-of-2 pyramid levels.

Parameters:

res (list of float) – Resolution in mm for each axis (e.g., [0.01, 0.01, 0.01] for 10 µm isotropic)
n_levels (int) – Number of pyramid levels (default: 5). Each level is 2x downsampled.

Return type:

None

class linumpy.io.AnalysisOmeZarrWriter(store_path, shape, chunk_shape, shards=None, dtype=np.float32, overwrite=True, downscale_factor=2, unit='millimeter')[source]#

Bases: OmeZarrWriter

OmeZarrWriter subclass that supports custom analysis-friendly resolution pyramids.

This class extends OmeZarrWriter to create pyramid levels at specific target resolutions (e.g., 10, 25, 50, 100 µm) instead of traditional power-of-2 downsampling. This is useful for creating output volumes optimized for downstream analysis at specific scales.

Example

>>> writer = AnalysisOmeZarrWriter("output.ome.zarr", shape, chunks, dtype=np.float32)
>>> writer[:] = data  # Write data at full resolution
>>> writer.finalize(base_res, target_resolutions_um=[10, 25, 50, 100])

Notes

Use finalize() for traditional power-of-2 pyramids (inherited from OmeZarrWriter)
Use finalize_with_resolutions() for custom analysis-friendly resolutions

Parameters:

store_path (pathlib.Path)
shape (tuple | collections.abc.Sequence)
chunk_shape (tuple | collections.abc.Sequence)
shards (tuple | None)
dtype (type | numpy.dtype)
overwrite (bool)
downscale_factor (int)
unit (str)

finalize(res, n_levels=None, *, target_resolutions_um=(10, 25, 50, 100), make_isotropic=True)[source]#

Finalize the OME-Zarr with pyramid levels.

Parameters:

res (list of float) – Base resolution in mm (e.g., [0.01, 0.01, 0.01] for 10 µm isotropic, or [0.0015, 0.01, 0.01] for anisotropic z=1.5µm, xy=10µm)
target_resolutions_um (list of float, optional) – Target resolutions in microns (default: [10, 25, 50, 100]). Ignored if n_levels is specified.
n_levels (int, optional) – If specified, uses traditional power-of-2 downsampling instead of custom resolutions (backward compatible with OmeZarrWriter).
make_isotropic (bool, optional) – If True (default), resamples anisotropic data to produce isotropic voxels at each target resolution. Each dimension is scaled independently to achieve the target resolution. If False, preserves the original aspect ratio by scaling all dimensions uniformly based on the finest (smallest) base resolution.

Return type:

None

Notes

By default, creates pyramid levels at specific analysis-friendly resolutions (e.g., 10, 25, 50, 100 µm). If n_levels is provided, falls back to traditional power-of-2 downsampling for backward compatibility.

Examples

For anisotropic data with base resolution [1.5, 10, 10] µm targeting 25 µm:

With make_isotropic=True (default):

Scale factors: [16.67, 2.5, 2.5] (per-dimension)
Output: isotropic 25 µm voxels
Shape aspect ratio changes

With make_isotropic=False:

Scale factor: 16.67 (uniform, based on finest dimension 1.5 µm)
Output: anisotropic [25, 167, 167] µm voxels
Shape aspect ratio preserved